3
.\" Copyright (c) 2004-2005 by Internet Systems Consortium, Inc. ("ISC")
4
.\" Copyright (c) 1996-2003 by Internet Software Consortium
6
.\" Permission to use, copy, modify, and distribute this software for any
7
.\" purpose with or without fee is hereby granted, provided that the above
8
.\" copyright notice and this permission notice appear in all copies.
10
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
11
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
13
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
16
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18
.\" Internet Systems Consortium, Inc.
19
.\" 950 Charter Street
20
.\" Redwood City, CA 94063
22
.\" http://www.isc.org/
24
.\" This software has been written for Internet Systems Consortium
25
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
26
.\" To learn more about Internet Systems Consortium, see
27
.\" ``http://www.isc.org/''. To learn more about Vixie Enterprises,
28
.\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
29
.\" ``http://www.nominum.com''.
31
.\" $Id: dhclient-script.8,v 1.11 2006/02/24 23:16:27 dhankins Exp $
35
dhclient-script - DHCP client network configuration script
37
The DHCP client network configuration script is invoked from time to
38
time by \fBdhclient(8)\fR. This script is used by the dhcp client to
39
set each interface's initial configuration prior to requesting an
40
address, to test the address once it has been offered, and to set the
41
interface's final configuration once a lease has been acquired. If no
42
lease is acquired, the script is used to test predefined leases, if
43
any, and also called once if no valid lease can be identified.
45
This script is not meant to be customized by the end user. If local
46
customizations are needed, they should be possible using the enter and
47
exit hooks provided (see HOOKS for details). These hooks will allow the
48
user to override the default behaviour of the client in creating a
52
No standard client script exists for some operating systems, even though
53
the actual client may work, so a pioneering user may well need to create
54
a new script or modify an existing one. In general, customizations specific
55
to a particular computer should be done in the
56
.B ETCDIR/dhclient.conf
57
file. If you find that you can't make such a customization without
59
.B ETCDIR/dhclient.conf
60
or using the enter and exit hooks, please submit a bug report.
62
When it starts, the client script first defines a shell function,
64
which is later used to create the
66
file. To override the default behaviour, redefine this function in
67
the enter hook script.
69
On after defining the make_resolv_conf function, the client script checks
70
for the presence of an executable
71
.B ETCDIR/dhclient-enter-hooks
72
script, and if present, it invokes the script inline, using the Bourne
73
shell '.' command. The entire environment documented under OPERATION
74
is available to this script, which may modify the environment if needed
75
to change the behaviour of the script. If an error occurs during the
76
execution of the script, it can set the exit_status variable to a nonzero
78
.B CLIENTBINDIR/dhclient-script
79
will exit with that error code immediately after the client script exits.
81
After all processing has completed,
82
.B CLIENTBINDIR/dhclient-script
83
checks for the presence of an executable
84
.B ETCDIR/dhclient-exit-hooks
85
script, which if present is invoked using the '.' command. The exit
86
status of dhclient-script will be passed to dhclient-exit-hooks in the
87
exit_status shell variable, and will always be zero if the script
88
succeeded at the task for which it was invoked. The rest of the
89
environment as described previously for dhclient-enter-hooks is also
91
.B ETCDIR/dhclient-exit-hooks
92
script can modify the valid of exit_status to change the exit status
95
When dhclient needs to invoke the client configuration script, it
96
defines a set of variables in the environment, and then invokes
97
.B CLIENTBINDIR/dhclient-script.
98
In all cases, $reason is set to the name of the reason why the script
99
has been invoked. The following reasons are currently defined:
100
MEDIUM, PREINIT, BOUND, RENEW, REBIND, REBOOT, EXPIRE, FAIL, STOP, RELEASE,
104
The DHCP client is requesting that an interface's media type
105
be set. The interface name is passed in $interface, and the media
106
type is passed in $medium.
108
The DHCP client is requesting that an interface be configured as
109
required in order to send packets prior to receiving an actual
110
address. For clients which use the BSD socket library, this means
111
configuring the interface with an IP address of 0.0.0.0 and a
112
broadcast address of 255.255.255.255. For other clients, it may be
113
possible to simply configure the interface up without actually giving
114
it an IP address at all. The interface name is passed in $interface,
115
and the media type in $medium.
117
If an IP alias has been declared in dhclient.conf, its address will be
118
passed in $alias_ip_address, and that ip alias should be deleted from
119
the interface, along with any routes to it.
121
The DHCP client has done an initial binding to a new address. The
122
new ip address is passed in $new_ip_address, and the interface name is
123
passed in $interface. The media type is passed in $medium. Any
124
options acquired from the server are passed using the option name
125
described in \fBdhcp-options\fR, except that dashes ('-') are replaced
126
by underscores ('_') in order to make valid shell variables, and the
127
variable names start with new_. So for example, the new subnet mask
128
would be passed in $new_subnet_mask.
130
Before actually configuring the address, dhclient-script should
131
somehow ARP for it and exit with a nonzero status if it receives a
132
reply. In this case, the client will send a DHCPDECLINE message to
133
the server and acquire a different address. This may also be done in
134
the RENEW, REBIND, or REBOOT states, but is not required, and indeed
135
may not be desirable.
137
When a binding has been completed, a lot of network parameters are
138
likely to need to be set up. A new /etc/resolv.conf needs to be
139
created, using the values of $new_domain_name and
140
$new_domain_name_servers (which may list more than one server,
141
separated by spaces). A default route should be set using
142
$new_routers, and static routes may need to be set up using
145
If an IP alias has been declared, it must be set up here. The alias
146
IP address will be written as $alias_ip_address, and other DHCP
147
options that are set for the alias (e.g., subnet mask) will be passed
148
in variables named as described previously except starting with
149
$alias_ instead of $new_. Care should be taken that the alias IP
150
address not be used if it is identical to the bound IP address
151
($new_ip_address), since the other alias parameters may be incorrect
154
When a binding has been renewed, the script is called as in BOUND,
155
except that in addition to all the variables starting with $new_,
156
there is another set of variables starting with $old_. Persistent
157
settings that may have changed need to be deleted - for example, if a
158
local route to the bound address is being configured, the old local
159
route should be deleted. If the default route has changed, the old default
160
route should be deleted. If the static routes have changed, the old
161
ones should be deleted. Otherwise, processing can be done as with
164
The DHCP client has rebound to a new DHCP server. This can be handled
165
as with RENEW, except that if the IP address has changed, the ARP
166
table should be cleared.
168
The DHCP client has successfully reacquired its old address after a
169
reboot. This can be processed as with BOUND.
171
The DHCP client has failed to renew its lease or acquire a new one,
172
and the lease has expired. The IP address must be relinquished, and
173
all related parameters should be deleted, as in RENEW and REBIND.
175
The DHCP client has been unable to contact any DHCP servers, and any
176
leases that have been tested have not proved to be valid. The
177
parameters from the last lease tested should be deconfigured. This
178
can be handled in the same way as EXPIRE.
180
The dhclient has been informed to shut down gracefully, the
181
dhclient-script should unconfigure or shutdown the interface as
184
The dhclient has been executed using the -r flag, indicating that the
185
administrator wishes it to release its lease(s). dhclient-script should
186
unconfigure or shutdown the interface.
188
No-Broadcast-Interfaces...dhclient was unable to find any interfaces
189
upon which it believed it should commence DHCP. What dhclient-script
190
should do in this situation is entirely up to the implementor.
192
The DHCP client has been unable to contact any DHCP servers.
193
However, an old lease has been identified, and its parameters have
194
been passed in as with BOUND. The client configuration script should
195
test these parameters and, if it has reason to believe they are valid,
196
should exit with a value of zero. If not, it should exit with a
199
The usual way to test a lease is to set up the network as with REBIND
200
(since this may be called to test more than one lease) and then ping
201
the first router defined in $routers. If a response is received, the
202
lease must be valid for the network to which the interface is
203
currently connected. It would be more complete to try to ping all of
204
the routers listed in $new_routers, as well as those listed in
205
$new_static_routes, but current scripts do not do this.
207
Each operating system should generally have its own script file,
208
although the script files for similar operating systems may be similar
209
or even identical. The script files included in Internet
210
Systems Consortium DHCP distribution appear in the distribution tree
211
under client/scripts, and bear the names of the operating systems on
212
which they are intended to work.
214
If more than one interface is being used, there's no obvious way to
215
avoid clashes between server-supplied configuration parameters - for
216
example, the stock dhclient-script rewrites /etc/resolv.conf. If
217
more than one interface is being configured, /etc/resolv.conf will be
218
repeatedly initialized to the values provided by one server, and then
219
the other. Assuming the information provided by both servers is
220
valid, this shouldn't cause any real problems, but it could be
223
dhclient(8), dhcpd(8), dhcrelay(8), dhclient.conf(5) and
226
.B dhclient-script(8)
227
has been written for Internet Systems Consortium
228
by Ted Lemon in cooperation with Vixie
229
Enterprises. To learn more about Internet Systems Consortium,
231
.B http://www.isc.org.
232
To learn more about Vixie
234
.B http://www.vix.com.
added
removed
client/dhclient-script.8
