1.\" $OpenBSD: dhclient-script.8,v 1.2 2004/04/09 18:30:15 jmc 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 January 1, 1997 40.Dt DHCLIENT-SCRIPT 8 41.Os 42.Sh NAME 43.Nm dhclient-script 44.Nd DHCP client network configuration script 45.Sh DESCRIPTION 46The DHCP client network configuration script is invoked from time to 47time by 48.Xr dhclient 8 . 49This script is used by the DHCP client to set each interface's initial 50configuration prior to requesting an address, to test the address once it 51has been offered, and to set the interface's final configuration once a 52lease has been acquired. 53If no lease is acquired, the script is used to test predefined leases, if 54any, and also called once if no valid lease can be identified. 55.Pp 56.\" No standard client script exists for some operating systems, even though 57.\" the actual client may work, so a pioneering user may well need to create 58.\" a new script or modify an existing one. 59In general, customizations specific to a particular computer should be done 60in the 61.Pa /etc/dhclient.conf 62file. 63.Sh OPERATION 64When 65.Xr dhclient 8 66needs to invoke the client configuration script, it sets up a number of 67environment variables and runs 68.Nm dhclient-script . 69In all cases, 70.Va $reason 71is set to the name of the reason why the script has been invoked. 72The following reasons are currently defined: 73MEDIUM, PREINIT, ARPCHECK, ARPSEND, BOUND, RENEW, REBIND, REBOOT, 74EXPIRE, FAIL and TIMEOUT. 75.Bl -tag -width "ARPCHECK" 76.It MEDIUM 77The DHCP client is requesting that an interface's media type be set. 78The interface name is passed in 79.Va $interface , 80and the media type is passed in 81.Va $medium . 82.It PREINIT 83The DHCP client is requesting that an interface be configured as 84required in order to send packets prior to receiving an actual address. 85.\" For clients which use the BSD socket library, 86This means configuring the interface with an IP address of 0.0.0.0 87and a broadcast address of 255.255.255.255. 88.\" For other clients, it may be possible to simply configure the interface up 89.\" without actually giving it an IP address at all. 90The interface name is passed in 91.Va $interface , 92and the media type in 93.Va $medium . 94.Pp 95If an IP alias has been declared in 96.Xr dhclient.conf 5 , 97its address will be passed in 98.Va $alias_ip_address , 99and that IP alias should be deleted from the interface, 100along with any routes to it. 101.It ARPSEND 102The DHCP client is requesting that an address that has been offered to 103it be checked to see if somebody else is using it, by sending an ARP 104request for that address. 105It's not clear how to implement this, so no examples exist yet. 106The IP address to check is passed in 107.Va $new_ip_address , 108and the interface name is passed in 109.Va $interface . 110.It ARPCHECK 111The DHCP client wants to know if a response to the ARP request sent 112using ARPSEND has been received. 113If one has, the script should exit with a nonzero status, indicating that 114the offered address has already been requested and should be declined. 115.Va $new_ip_address 116and 117.Va $interface 118are set as with ARPSEND. 119.It BOUND 120The DHCP client has done an initial binding to a new address. 121The new IP address is passed in 122.Va $new_ip_address , 123and the interface name is passed in 124.Va $interface . 125The media type is passed in 126.Va $medium . 127Any options acquired from the server are passed using the option name 128described in 129.Xr dhcp-options 5 , 130except that dashes 131.Pq Sq - 132are replaced by underscores 133.Pq Sq _ 134in order to make valid shell variables, and the variable names start with new_. 135So for example, the new subnet mask would be passed in 136.Va $new_subnet_mask . 137.Pp 138When a binding has been completed, a lot of network parameters are 139likely to need to be set up. 140A new 141.Pa /etc/resolv.conf 142needs to be created, using the values of 143.Va $new_domain_name 144and 145.Va $new_domain_name_servers 146(which may list more than one server, separated by spaces). 147A default route should be set using 148.Va $new_routers , 149and static routes may need to be set up using 150.Va $new_static_routes . 151.Pp 152If an IP alias has been declared, it must be set up here. 153The alias IP address will be written as 154.Va $alias_ip_address , 155and other DHCP options that are set for the alias (e.g., subnet mask) 156will be passed in variables named as described previously except starting with 157$alias_ instead of $new_. 158Care should be taken that the alias IP address not be used if it is identical 159to the bound IP address 160.Pq Va $new_ip_address , 161since the other alias parameters may be incorrect in this case. 162.It RENEW 163When a binding has been renewed, the script is called as in BOUND, 164except that in addition to all the variables starting with $new_, 165there is another set of variables starting with $old_. 166Persistent settings that may have changed need to be deleted \- for example, 167if a local route to the bound address is being configured, the old local 168route should be deleted. 169If the default route has changed, the old default route should be deleted. 170If the static routes have changed, the old ones should be deleted. 171Otherwise, processing can be done as with BOUND. 172.It REBIND 173The DHCP client has rebound to a new DHCP server. 174This can be handled as with RENEW, except that if the IP address has changed, 175the ARP table should be cleared. 176.It REBOOT 177The DHCP client has successfully reacquired its old address after a reboot. 178This can be processed as with BOUND. 179.It EXPIRE 180The DHCP client has failed to renew its lease or acquire a new one, 181and the lease has expired. 182The IP address must be relinquished, and all related parameters should be 183deleted, as in RENEW and REBIND. 184.It FAIL 185The DHCP client has been unable to contact any DHCP servers, and any 186leases that have been tested have not proved to be valid. 187The parameters from the last lease tested should be deconfigured. 188This can be handled in the same way as EXPIRE. 189.It TIMEOUT 190The DHCP client has been unable to contact any DHCP servers. 191However, an old lease has been identified, and its parameters have 192been passed in as with BOUND. 193The client configuration script should test these parameters and, 194if it has reason to believe they are valid, should exit with a value of zero. 195If not, it should exit with a nonzero value. 196.El 197.Pp 198The usual way to test a lease is to set up the network as with REBIND 199(since this may be called to test more than one lease) and then ping 200the first router defined in 201.Va $routers . 202If a response is received, the lease must be valid for the network to 203which the interface is currently connected. 204It would be more complete to try to ping all of the routers listed in 205.Va $new_routers , 206as well as those listed in 207.Va $new_static_routes , 208but current scripts do not do this. 209.\" .Sh FILES 210.\" Each operating system should generally have its own script file, 211.\" although the script files for similar operating systems may be similar 212.\" or even identical. 213.\" The script files included in the Internet Software Consortium DHCP 214.\" distribution appear in the distribution tree under client/scripts, 215.\" and bear the names of the operating systems on which they are intended 216.\" to work. 217.Sh SEE ALSO 218.Xr dhclient.conf 5 , 219.Xr dhclient.leases 5 , 220.Xr dhclient 8 , 221.Xr dhcpd 8 , 222.Xr dhcrelay 8 223.Sh AUTHORS 224The original version of 225.Nm 226was written for the Internet Software Consortium by 227.An Ted Lemon Aq mellon@fugue.com 228in cooperation with Vixie Enterprises. 229.Pp 230The 231.Ox 232implementation of 233.Nm 234was written by 235.An Kenneth R. Westerback Aq krw@openbsd.org . 236.Sh BUGS 237If more than one interface is being used, there's no obvious way to 238avoid clashes between server-supplied configuration parameters \- for 239example, the stock dhclient-script rewrites 240.Pa /etc/resolv.conf . 241If more than one interface is being configured, 242.Pa /etc/resolv.conf 243will be repeatedly initialized to the values provided by one server, and then 244the other. 245Assuming the information provided by both servers is valid, this shouldn't 246cause any real problems, but it could be confusing. 247