sbin/dhclient/dhclient-script.8

   1 .\" $OpenBSD: src/sbin/dhclient/dhclient-script.8,v 1.6 2011/04/04 11:43:20 krw Exp $
   2 .\"
   3 .\" Copyright (c) 1997 The Internet Software Consortium.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\"
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of The Internet Software Consortium nor the names
  16 .\"    of its contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
  20 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  21 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  22 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  23 .\" DISCLAIMED.  IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
  24 .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  27 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  28 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\" This software has been written for the Internet Software Consortium
  34 .\" by Ted Lemon <mellon@fugue.com> in cooperation with Vixie
  35 .\" Enterprises.  To learn more about the Internet Software Consortium,
  36 .\" see ``http://www.isc.org/isc''.  To learn more about Vixie
  37 .\" Enterprises, see ``http://www.vix.com''.
  38 .\"
  39 .Dd August 4, 2012
  40 .Dt DHCLIENT-SCRIPT 8
  41 .Os
  42 .Sh NAME
  43 .Nm dhclient-script
  44 .Nd DHCP client network configuration script
  45 .Sh DESCRIPTION
  46 The DHCP client network configuration script is invoked from time to
  47 time by
  48 .Xr dhclient 8 .
  49 .Pp
  50 .\" No standard client script exists for some operating systems, even though
  51 .\" the actual client may work, so a pioneering user may well need to create
  52 .\" a new script or modify an existing one.
  53 In general, customizations specific to a particular computer should be done
  54 in the
  55 .Pa /etc/dhclient.conf
  56 file.
  57 .Sh OPERATION
  58 When
  59 .Xr dhclient 8
  60 needs to invoke the client configuration script, it sets up a number of
  61 environment variables and runs
  62 .Nm .
  63 In all cases,
  64 .Va $reason
  65 is set to the name of the reason why the script has been invoked.
  66 The following reasons are currently defined:
  67 BOUND, RENEW, REBIND, REBOOT, EXPIRE, FAIL and TIMEOUT.
  68 .Bl -tag -width "ARPCHECK"
  69 .It BOUND
  70 The DHCP client has done an initial binding to a new address.
  71 The new IP address is passed in
  72 .Va $new_ip_address ,
  73 and the interface name is passed in
  74 .Va $interface .
  75 Any options acquired from the server are passed using the option name
  76 described in
  77 .Xr dhcp-options 5 ,
  78 except that dashes
  79 .Pq Sq -
  80 are replaced by underscores
  81 .Pq Sq _
  82 in order to make valid shell variables, and the variable names start with new_.
  83 So for example, the new subnet mask would be passed in
  84 .Va $new_subnet_mask .
  85 .Pp
  86 When a binding has been completed, a lot of network parameters are
  87 likely to need to be set up.
  88 A new
  89 .Pa /etc/resolv.conf
  90 needs to be created, using the values of
  91 .Va $new_domain_name
  92 and
  93 .Va $new_domain_name_servers
  94 (which may list more than one server, separated by spaces).
  95 A default route should be set using
  96 .Va $new_routers ,
  97 and static routes may need to be set up using
  98 .Va $new_static_routes .
  99 .Pp
 100 Note: since
 101 .Nm
 102 effectively overwrites
 103 .Pa /etc/resolv.conf ,
 104 any information contained therein is lost.
 105 If options must be passed to the resolver,
 106 they may be contained in
 107 .Pa /etc/resolv.conf.tail ,
 108 which is appended to the generated
 109 .Pa /etc/resolv.conf
 110 by
 111 .Nm .
 112 .\"See
 113 .\".Xr resolv.conf.tail 5
 114 .\"for further information.
 115 .Pp
 116 .It RENEW
 117 When a binding has been renewed, the script is called as in BOUND,
 118 except that in addition to all the variables starting with $new_,
 119 there is another set of variables starting with $old_.
 120 Persistent settings that may have changed need to be deleted \- for example,
 121 if a local route to the bound address is being configured, the old local
 122 route should be deleted.
 123 If the default route has changed, the old default route should be deleted.
 124 If the static routes have changed, the old ones should be deleted.
 125 Otherwise, processing can be done as with BOUND.
 126 .It REBIND
 127 The DHCP client has rebound to a new DHCP server.
 128 This can be handled as with RENEW, except that if the IP address has changed,
 129 the ARP table should be cleared.
 130 .It REBOOT
 131 The DHCP client has successfully reacquired its old address after a reboot.
 132 This can be processed as with BOUND.
 133 .It EXPIRE
 134 The DHCP client has failed to renew its lease or acquire a new one,
 135 and the lease has expired.
 136 The IP address must be relinquished, and all related parameters should be
 137 deleted, as in RENEW and REBIND.
 138 .It FAIL
 139 The DHCP client has been unable to contact any DHCP servers, and any
 140 leases that have been tested have not proved to be valid.
 141 The parameters from the last lease tested should be deconfigured.
 142 This can be handled in the same way as EXPIRE.
 143 .It TIMEOUT
 144 The DHCP client has been unable to contact any DHCP servers.
 145 However, an old lease has been identified, and its parameters have
 146 been passed in as with BOUND.
 147 The client configuration script should test these parameters and,
 148 if it has reason to believe they are valid, should exit with a value of zero.
 149 If not, it should exit with a nonzero value.
 150 .El
 151 .Pp
 152 The usual way to test a lease is to set up the network as with REBIND
 153 (since this may be called to test more than one lease) and then ping
 154 the first router defined in
 155 .Va $routers .
 156 If a response is received, the lease must be valid for the network to
 157 which the interface is currently connected.
 158 It would be more complete to try to ping all of the routers listed in
 159 .Va $new_routers ,
 160 as well as those listed in
 161 .Va $new_static_routes ,
 162 but current scripts do not do this.
 163 .\" .Sh FILES
 164 .\" Each operating system should generally have its own script file,
 165 .\" although the script files for similar operating systems may be similar
 166 .\" or even identical.
 167 .\" The script files included in the Internet Software Consortium DHCP
 168 .\" distribution appear in the distribution tree under client/scripts,
 169 .\" and bear the names of the operating systems on which they are intended
 170 .\" to work.
 171 .Sh SEE ALSO
 172 .Xr dhclient.conf 5 ,
 173 .Xr dhclient.leases 5 ,
 174 .\".Xr resolv.conf.tail 5 ,
 175 .Xr dhclient 8 ,
 176 .Xr dhcpd 8 Pq Pa net/isc-dhcp42-server ,
 177 .Xr dhcrelay 8 Pq Pa net/isc-dhcp42-relay
 178 .Sh AUTHORS
 179 .An -nosplit
 180 The original version of
 181 .Nm
 182 was written for the Internet Software Consortium by
 183 .An Ted Lemon Aq mellon@fugue.com
 184 in cooperation with Vixie Enterprises.
 185 .Pp
 186 The
 187 .Ox
 188 implementation of
 189 .Nm
 190 was written by
 191 .An Kenneth R. Westerback Aq krw@openbsd.org .
 192 .Sh BUGS
 193 If more than one interface is being used, there's no obvious way to
 194 avoid clashes between server-supplied configuration parameters \- for
 195 example, the stock dhclient-script rewrites
 196 .Pa /etc/resolv.conf .
 197 If more than one interface is being configured,
 198 .Pa /etc/resolv.conf
 199 will be repeatedly initialized to the values provided by one server, and then
 200 the other.
 201 Assuming the information provided by both servers is valid, this shouldn't
 202 cause any real problems, but it could be confusing.