1dhclient-script(8)          System Manager's Manual         dhclient-script(8)
2
3
4

NAME

6       dhclient-script - DHCP client network configuration script
7

DESCRIPTION

9       The  DHCP  client  network configuration script is invoked from time to
10       time by dhclient(8).  This script is used by the  dhcp  client  to  set
11       each  interface's initial configuration prior to requesting an address,
12       to test the address once it has been offered, and  to  set  the  inter‐
13       face's final configuration once a lease has been acquired.  If no lease
14       is acquired, the script is used to test predefined leases, if any,  and
15       also called once if no valid lease can be identified.
16
17       This  script  is  not meant to be customized by the end user.  If local
18       customizations are needed, they should be possible using the enter  and
19       exit  hooks  provided (see HOOKS for details).   These hooks will allow
20       the user to override the default behaviour of the client in creating  a
21       /etc/resolv.conf  file,  and  to  handle  DHCP  options  not handled by
22       default.
23
24       No standard client script  exists  for  some  operating  systems,  even
25       though  the  actual client may work, so a pioneering user may well need
26       to create a new script or modify an existing  one.   In  general,  cus‐
27       tomizations  specific  to  a  particular computer should be done in the
28       /etc/dhcp/dhclient.conf file.   If you find that you can't make such  a
29       customization  without customizing /etc/dhcp/dhclient.conf or using the
30       enter and exit hooks, please submit a bug report.
31

HOOKS

33       When it starts, the client  script  first  defines  a  shell  function,
34       make_resolv_conf  ,  which is later used to create the /etc/resolv.conf
35       file.   To override the default behaviour, redefine  this  function  in
36       the enter hook script.
37
38       On  after  defining  the  make_resolv_conf  function, the client script
39       checks for the presence of an executable /etc/dhcp/dhclient-enter-hooks
40       script,  and if present, it invokes the script inline, using the Bourne
41       shell '.' command.   The entire environment documented under  OPERATION
42       is available to this script, which may modify the environment if needed
43       to change the behaviour of the script.   If an error occurs during  the
44       execution  of  the  script,  it  can  set the exit_status variable to a
45       nonzero value, and /sbin/dhclient-script will exit with that error code
46       immediately after the client script exits.
47
48       After  all  processing  has completed, /sbin/dhclient-script checks for
49       the presence of  an  executable  /etc/dhcp/dhclient-exit-hooks  script,
50       which  if present is invoked using the '.' command.  The exit status of
51       dhclient-script will be passed to dhclient-exit-hooks in the  exit_sta‐
52       tus  shell variable, and will always be zero if the script succeeded at
53       the task for which it was invoked.   The rest  of  the  environment  as
54       described  previously  for  dhclient-enter-hooks is also present.   The
55       /etc/dhcp/dhclient-exit-hooks script can modify the valid of  exit_sta‐
56       tus to change the exit status of dhclient-script.
57
58       Immediately  after  dhclient  brings  an  interface  UP  with  a new IP
59       address, subnet mask, and routes, in the REBOOT/BOUND states,  it  will
60       check  for  the  existence of an executable /etc/dhcp/dhclient-up-hooks
61       script, and source it if found. This script can handle DHCP options  in
62       the  environment  that  are  not  handled  by default. A per-interface.
63       /etc/dhcp/dhclient-${IF}-up-hooks  script  will  override  the  generic
64       script and be sourced when interface $IF has been brought up.
65
66       Immediately  before  dhclient brings an interface DOWN, removing its IP
67       address, subnet mask, and routes, in the STOP/RELEASE  states, it  will
68       check  for the existence of an executable /etc/dhcp/dhclient-down-hooks
69       script, and source it if found. This script can handle DHCP options  in
70       the  environment  that  are  not  handled  by  default. A per-interface
71       /etc/dhcp/dhclient-${IF}-down-hooks script will  override  the  generic
72       script and be sourced when interface $IF is about to be brought down.
73

OPERATION

75       When  dhclient  needs  to  invoke  the  client configuration script, it
76       defines a set  of  variables  in  the  environment,  and  then  invokes
77       /sbin/dhclient-script.  In all cases, $reason is set to the name of the
78       reason why the script has been invoked.    The  following  reasons  are
79       currently  defined:  MEDIUM,  PREINIT,  BOUND,  RENEW,  REBIND, REBOOT,
80       EXPIRE, FAIL, STOP, RELEASE, NBI and TIMEOUT.
81

MEDIUM

83       The DHCP client is requesting that an interface's media  type  be  set.
84       The  interface  name  is  passed  in  $interface, and the media type is
85       passed in $medium.
86

PREINIT

88       The DHCP client is  requesting  that  an  interface  be  configured  as
89       required in order to send packets prior to receiving an actual address.
90       For clients which use the BSD socket library,  this  means  configuring
91       the  interface with an IP address of 0.0.0.0 and a broadcast address of
92       255.255.255.255.   For other clients, it may be possible to simply con‐
93       figure  the  interface  up  without actually giving it an IP address at
94       all.   The interface name is passed in $interface, and the  media  type
95       in $medium.
96
97       If  an IP alias has been declared in dhclient.conf, its address will be
98       passed in $alias_ip_address, and that ip alias should be  deleted  from
99       the interface, along with any routes to it.
100

BOUND

102       The DHCP client has done an initial binding to a new address.   The new
103       ip address is passed in $new_ip_address,  and  the  interface  name  is
104       passed  in  $interface.    The  media  type is passed in $medium.   Any
105       options acquired from the server  are  passed  using  the  option  name
106       described  in  dhcp-options,  except  that dashes ('-') are replaced by
107       underscores ('_') in order to make valid shell variables, and the vari‐
108       able names start with new_.   So for example, the new subnet mask would
109       be passed in $new_subnet_mask.
110
111       Before actually configuring the address, dhclient-script should somehow
112       ARP  for it and exit with a nonzero status if it receives a reply.   In
113       this case, the client will send a DHCPDECLINE message to the server and
114       acquire  a  different  address.    This  may also be done in the RENEW,
115       REBIND, or REBOOT states, but is not required, and indeed  may  not  be
116       desirable.
117
118       When  a  binding  has  been  completed, a lot of network parameters are
119       likely to need to be set up.   A new /etc/resolv.conf needs to be  cre‐
120       ated, using the values of $new_domain_name and $new_domain_name_servers
121       (which may list more than one server, separated by spaces).   A default
122       route  should  be set using $new_routers, and static routes may need to
123       be set up using $new_static_routes.
124
125       If an IP alias has been declared, it must be set up here.    The  alias
126       IP address will be written as $alias_ip_address, and other DHCP options
127       that are set for the alias (e.g., subnet mask) will be passed in  vari‐
128       ables  named  as  described  previously  except  starting  with $alias_
129       instead of $new_.   Care should be taken that the alias IP address  not
130       be  used  if it is identical to the bound IP address ($new_ip_address),
131       since the other alias parameters may be incorrect in this case.
132

RENEW

134       When a binding has been renewed, the script  is  called  as  in  BOUND,
135       except that in addition to all the variables starting with $new_, there
136       is another set of variables starting with $old_.   Persistent  settings
137       that  may  have  changed  need  to be deleted - for example, if a local
138       route to the bound address is being configured,  the  old  local  route
139       should  be  deleted.  If the default route has changed, the old default
140       route should be deleted.  If the static routes have  changed,  the  old
141       ones  should  be  deleted.   Otherwise,  processing can be done as with
142       BOUND.
143

REBIND

145       The DHCP client has rebound to a new DHCP server.  This can be  handled
146       as with RENEW, except that if the IP address has changed, the ARP table
147       should be cleared.
148

REBOOT

150       The DHCP client has successfully reacquired its  old  address  after  a
151       reboot.   This can be processed as with BOUND.
152

EXPIRE

154       The DHCP client has failed to renew its lease or acquire a new one, and
155       the lease has expired.   The IP address must be relinquished,  and  all
156       related parameters should be deleted, as in RENEW and REBIND.
157

FAIL

159       The  DHCP  client  has been unable to contact any DHCP servers, and any
160       leases that have been tested have not proved to be valid.   The parame‐
161       ters  from  the last lease tested should be deconfigured.   This can be
162       handled in the same way as EXPIRE.
163

STOP

165       The dhclient has been informed to shut down gracefully,  the  dhclient-
166       script should unconfigure or shutdown the interface as appropriate.
167

RELEASE

169       The  dhclient  has been executed using the -r flag, indicating that the
170       administrator wishes  it  to  release  its  lease(s).   dhclient-script
171       should unconfigure or shutdown the interface.
172

NBI

174       No-Broadcast-Interfaces...dhclient  was  unable  to find any interfaces
175       upon which it believed it should commence DHCP.   What  dhclient-script
176       should do in this situation is entirely up to the implementor.
177

TIMEOUT

179       The  DHCP client has been unable to contact any DHCP servers.  However,
180       an old lease has been identified, and its parameters have  been  passed
181       in  as  with BOUND.   The client configuration script should test these
182       parameters and, if it has reason to believe they are valid, should exit
183       with a value of zero.   If not, it should exit with a nonzero value.
184
185       The  usual  way to test a lease is to set up the network as with REBIND
186       (since this may be called to test more than one lease)  and  then  ping
187       the  first  router defined in $routers.  If a response is received, the
188       lease must be valid for the network to which the interface is currently
189       connected.    It  would  be  more  complete  to  try to ping all of the
190       routers  listed  in  $new_routers,  as  well   as   those   listed   in
191       $new_static_routes, but current scripts do not do this.
192

FILES

194       Each  operating  system  should  generally  have  its  own script file,
195       although the script files for similar operating systems may be  similar
196       or even identical.   The script files included in Internet Systems Con‐
197       sortium  DHCP  distribution  appear  in  the  distribution  tree  under
198       client/scripts,  and  bear  the names of the operating systems on which
199       they are intended to work.
200

BUGS

202       If more than one interface is being used, there's  no  obvious  way  to
203       avoid  clashes  between  server-supplied configuration parameters - for
204       example, the stock dhclient-script rewrites /etc/resolv.conf.   If more
205       than  one  interface  is  being  configured,  /etc/resolv.conf  will be
206       repeatedly initialized to the values provided by one server,  and  then
207       the  other.    Assuming  the  information  provided  by both servers is
208       valid, this shouldn't cause any real problems, but it could be  confus‐
209       ing.
210

SEE ALSO

212       dhclient(8),     dhcpd(8),     dhcrelay(8),     dhclient.conf(5)    and
213       dhclient.leases(5).
214

AUTHOR

216       dhclient-script(8) has been written for Internet Systems Consortium  by
217       Ted  Lemon  in cooperation with Vixie Enterprises.  To learn more about
218       Internet Systems Consortium, see https://www.isc.org.   To  learn  more
219       about Vixie Enterprises, see http://www.vix.com.
220
221
222
223                                                            dhclient-script(8)
Impressum