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