dhclient-script(8) - Align man page with current reality.
[dragonfly.git] / sbin / dhclient / dhclient-script.8
CommitLineData
5ba6b67a 1.\" $OpenBSD: src/sbin/dhclient/dhclient-script.8,v 1.6 2011/04/04 11:43:20 krw Exp $
846204b6
HT
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.\"
5ba6b67a 39.Dd August 4, 2012
846204b6
HT
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 .
846204b6
HT
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
68d52ec8 62.Nm .
846204b6
HT
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:
5ba6b67a 67BOUND, RENEW, REBIND, REBOOT, EXPIRE, FAIL and TIMEOUT.
846204b6 68.Bl -tag -width "ARPCHECK"
846204b6
HT
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 .
846204b6
HT
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 .
5943b4b0
SW
112.\"See
113.\".Xr resolv.conf.tail 5
114.\"for further information.
846204b6 115.Pp
846204b6
HT
116.It RENEW
117When a binding has been renewed, the script is called as in BOUND,
118except that in addition to all the variables starting with $new_,
119there is another set of variables starting with $old_.
120Persistent settings that may have changed need to be deleted \- for example,
121if a local route to the bound address is being configured, the old local
122route should be deleted.
123If the default route has changed, the old default route should be deleted.
124If the static routes have changed, the old ones should be deleted.
125Otherwise, processing can be done as with BOUND.
126.It REBIND
127The DHCP client has rebound to a new DHCP server.
128This can be handled as with RENEW, except that if the IP address has changed,
129the ARP table should be cleared.
130.It REBOOT
131The DHCP client has successfully reacquired its old address after a reboot.
132This can be processed as with BOUND.
133.It EXPIRE
134The DHCP client has failed to renew its lease or acquire a new one,
135and the lease has expired.
136The IP address must be relinquished, and all related parameters should be
137deleted, as in RENEW and REBIND.
138.It FAIL
139The DHCP client has been unable to contact any DHCP servers, and any
140leases that have been tested have not proved to be valid.
141The parameters from the last lease tested should be deconfigured.
142This can be handled in the same way as EXPIRE.
143.It TIMEOUT
144The DHCP client has been unable to contact any DHCP servers.
145However, an old lease has been identified, and its parameters have
146been passed in as with BOUND.
147The client configuration script should test these parameters and,
148if it has reason to believe they are valid, should exit with a value of zero.
149If not, it should exit with a nonzero value.
150.El
151.Pp
152The 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
154the first router defined in
155.Va $routers .
156If a response is received, the lease must be valid for the network to
157which the interface is currently connected.
158It would be more complete to try to ping all of the routers listed in
159.Va $new_routers ,
160as well as those listed in
161.Va $new_static_routes ,
162but 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 ,
5943b4b0 174.\".Xr resolv.conf.tail 5 ,
846204b6 175.Xr dhclient 8 ,
aa4e0df8
SW
176.Xr dhcpd 8 Pq Pa pkgsrc/net/isc-dhcpd4 ,
177.Xr dhcrelay 8 Pq Pa pkgsrc/net/isc-dhcrelay4
846204b6
HT
178.Sh AUTHORS
179.An -nosplit
180The original version of
181.Nm
182was written for the Internet Software Consortium by
183.An Ted Lemon Aq mellon@fugue.com
184in cooperation with Vixie Enterprises.
185.Pp
186The
187.Ox
188implementation of
189.Nm
190was written by
191.An Kenneth R. Westerback Aq krw@openbsd.org .
192.Sh BUGS
193If more than one interface is being used, there's no obvious way to
194avoid clashes between server-supplied configuration parameters \- for
195example, the stock dhclient-script rewrites
196.Pa /etc/resolv.conf .
197If more than one interface is being configured,
198.Pa /etc/resolv.conf
199will be repeatedly initialized to the values provided by one server, and then
200the other.
201Assuming the information provided by both servers is valid, this shouldn't
202cause any real problems, but it could be confusing.