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 46The DHCP client network configuration script is invoked from time to 47time 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. 53In general, customizations specific to a particular computer should be done 54in the 55.Pa /etc/dhclient.conf 56file. 57.Sh OPERATION 58When 59.Xr dhclient 8 60needs to invoke the client configuration script, it sets up a number of 61environment variables and runs 62.Nm . 63In all cases, 64.Va $reason 65is set to the name of the reason why the script has been invoked. 66The following reasons are currently defined: 67BOUND, RENEW, REBIND, REBOOT, EXPIRE, FAIL and TIMEOUT. 68.Bl -tag -width "ARPCHECK" 69.It BOUND 70The DHCP client has done an initial binding to a new address. 71The new IP address is passed in 72.Va $new_ip_address , 73and the interface name is passed in 74.Va $interface . 75Any options acquired from the server are passed using the option name 76described in 77.Xr dhcp-options 5 , 78except that dashes 79.Pq Sq - 80are replaced by underscores 81.Pq Sq _ 82in order to make valid shell variables, and the variable names start with new_. 83So for example, the new subnet mask would be passed in 84.Va $new_subnet_mask . 85.Pp 86When a binding has been completed, a lot of network parameters are 87likely to need to be set up. 88A new 89.Pa /etc/resolv.conf 90needs to be created, using the values of 91.Va $new_domain_name 92and 93.Va $new_domain_name_servers 94(which may list more than one server, separated by spaces). 95A default route should be set using 96.Va $new_routers , 97and static routes may need to be set up using 98.Va $new_static_routes . 99.Pp 100Note: since 101.Nm 102effectively overwrites 103.Pa /etc/resolv.conf , 104any information contained therein is lost. 105If options must be passed to the resolver, 106they may be contained in 107.Pa /etc/resolv.conf.tail , 108which is appended to the generated 109.Pa /etc/resolv.conf 110by 111.Nm . 112.\"See 113.\".Xr resolv.conf.tail 5 114.\"for further information. 115.It RENEW 116When a binding has been renewed, the script is called as in BOUND, 117except that in addition to all the variables starting with $new_, 118there is another set of variables starting with $old_. 119Persistent settings that may have changed need to be deleted \- for example, 120if a local route to the bound address is being configured, the old local 121route should be deleted. 122If the default route has changed, the old default route should be deleted. 123If the static routes have changed, the old ones should be deleted. 124Otherwise, processing can be done as with BOUND. 125.It REBIND 126The DHCP client has rebound to a new DHCP server. 127This can be handled as with RENEW, except that if the IP address has changed, 128the ARP table should be cleared. 129.It REBOOT 130The DHCP client has successfully reacquired its old address after a reboot. 131This can be processed as with BOUND. 132.It EXPIRE 133The DHCP client has failed to renew its lease or acquire a new one, 134and the lease has expired. 135The IP address must be relinquished, and all related parameters should be 136deleted, as in RENEW and REBIND. 137.It FAIL 138The DHCP client has been unable to contact any DHCP servers, and any 139leases that have been tested have not proved to be valid. 140The parameters from the last lease tested should be deconfigured. 141This can be handled in the same way as EXPIRE. 142.It TIMEOUT 143The DHCP client has been unable to contact any DHCP servers. 144However, an old lease has been identified, and its parameters have 145been passed in as with BOUND. 146The client configuration script should test these parameters and, 147if it has reason to believe they are valid, should exit with a value of zero. 148If not, it should exit with a nonzero value. 149.El 150.Pp 151The usual way to test a lease is to set up the network as with REBIND 152(since this may be called to test more than one lease) and then ping 153the first router defined in 154.Va $routers . 155If a response is received, the lease must be valid for the network to 156which the interface is currently connected. 157It would be more complete to try to ping all of the routers listed in 158.Va $new_routers , 159as well as those listed in 160.Va $new_static_routes , 161but current scripts do not do this. 162.\" .Sh FILES 163.\" Each operating system should generally have its own script file, 164.\" although the script files for similar operating systems may be similar 165.\" or even identical. 166.\" The script files included in the Internet Software Consortium DHCP 167.\" distribution appear in the distribution tree under client/scripts, 168.\" and bear the names of the operating systems on which they are intended 169.\" to work. 170.Sh SEE ALSO 171.Xr dhclient.conf 5 , 172.Xr dhclient.leases 5 , 173.\".Xr resolv.conf.tail 5 , 174.Xr dhclient 8 , 175.Xr dhcpd 8 Pq Pa net/isc-dhcp42-server , 176.Xr dhcrelay 8 Pq Pa net/isc-dhcp42-relay 177.Sh AUTHORS 178.An -nosplit 179The original version of 180.Nm 181was written for the Internet Software Consortium by 182.An Ted Lemon Aq Mt mellon@fugue.com 183in cooperation with Vixie Enterprises. 184.Pp 185The 186.Ox 187implementation of 188.Nm 189was written by 190.An Kenneth R. Westerback Aq Mt krw@openbsd.org . 191.Sh BUGS 192If more than one interface is being used, there's no obvious way to 193avoid clashes between server-supplied configuration parameters \- for 194example, the stock dhclient-script rewrites 195.Pa /etc/resolv.conf . 196If more than one interface is being configured, 197.Pa /etc/resolv.conf 198will be repeatedly initialized to the values provided by one server, and then 199the other. 200Assuming the information provided by both servers is valid, this shouldn't 201cause any real problems, but it could be confusing. 202