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