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 /usr/sbin/dhclient-script will exit with that  error
46       code immediately after the client script exits.
47
48       After  all  processing  has completed, /usr/sbin/dhclient-script checks
49       for 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       /usr/sbin/dhclient-script.  In all cases, $reason is set to the name of
78       the 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.  Options  from  a  non-default  universe
110       will  have  the universe name prepended to the option name, for example
111       $new_dhcp6_server_id.  The options that the client explicitly requested
112       via  a  PRL or ORO option are passed with the same option name as above
113       but prepended with requested_ and  with  a  value  of  1,  for  example
114       requested_subnet_mask=1.   No  such variable is defined for options not
115       requested by the client or options that don't require a request option,
116       such as the ip address (*_ip_address) or expiration time (*_expiry).
117
118       Before actually configuring the address, dhclient-script should somehow
119       ARP for it and exit with a nonzero status if it receives a reply.    In
120       this case, the client will send a DHCPDECLINE message to the server and
121       acquire a different address.   This may also  be  done  in  the  RENEW,
122       REBIND,  or  REBOOT  states, but is not required, and indeed may not be
123       desirable.
124
125       When a binding has been completed, a  lot  of  network  parameters  are
126       likely  to need to be set up.   A new /etc/resolv.conf needs to be cre‐
127       ated, using the values of $new_domain_name and $new_domain_name_servers
128       (which may list more than one server, separated by spaces).   A default
129       route should be set using $new_routers, and static routes may  need  to
130       be set up using $new_static_routes.
131
132       If  an  IP alias has been declared, it must be set up here.   The alias
133       IP address will be written as $alias_ip_address, and other DHCP options
134       that  are set for the alias (e.g., subnet mask) will be passed in vari‐
135       ables named  as  described  previously  except  starting  with  $alias_
136       instead  of $new_.   Care should be taken that the alias IP address not
137       be used if it is identical to the bound IP  address  ($new_ip_address),
138       since the other alias parameters may be incorrect in this case.
139

RENEW

141       When  a  binding  has  been  renewed, the script is called as in BOUND,
142       except that in addition to all the variables starting with  $new_,  and
143       $requested_  there  is  another  set  of variables starting with $old_.
144       Persistent settings that may have changed need  to  be  deleted  -  for
145       example, if a local route to the bound address is being configured, the
146       old local route should be deleted.  If the default route  has  changed,
147       the  old  default  route  should be deleted.  If the static routes have
148       changed, the old ones should be deleted.  Otherwise, processing can  be
149       done as with BOUND.
150

REBIND

152       The  DHCP client has rebound to a new DHCP server.  This can be handled
153       as with RENEW, except that if the IP address has changed, the ARP table
154       should be cleared.
155

REBOOT

157       The  DHCP  client  has  successfully reacquired its old address after a
158       reboot.   This can be processed as with BOUND.
159

EXPIRE

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

FAIL

166       The DHCP client has been unable to contact any DHCP  servers,  and  any
167       leases that have been tested have not proved to be valid.   The parame‐
168       ters from the last lease tested should be deconfigured.   This  can  be
169       handled in the same way as EXPIRE.
170

STOP

172       The  dhclient  has been informed to shut down gracefully, the dhclient-
173       script should unconfigure or shutdown the interface as appropriate.
174

RELEASE

176       The dhclient has been executed using the -r flag, indicating  that  the
177       administrator  wishes  it  to  release  its  lease(s).  dhclient-script
178       should unconfigure or shutdown the interface.
179

NBI

181       No-Broadcast-Interfaces...dhclient was unable to  find  any  interfaces
182       upon  which  it believed it should commence DHCP.  What dhclient-script
183       should do in this situation is entirely up to the implementor.
184

TIMEOUT

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

FILES

201       Each operating system  should  generally  have  its  own  script  file,
202       although  the script files for similar operating systems may be similar
203       or even identical.   The script files included in Internet Systems Con‐
204       sortium  DHCP  distribution  appear  in  the  distribution  tree  under
205       client/scripts, and bear the names of the operating  systems  on  which
206       they are intended to work.
207

BUGS

209       If  more  than  one  interface is being used, there's no obvious way to
210       avoid clashes between server-supplied configuration  parameters  -  for
211       example, the stock dhclient-script rewrites /etc/resolv.conf.   If more
212       than one  interface  is  being  configured,  /etc/resolv.conf  will  be
213       repeatedly  initialized  to the values provided by one server, and then
214       the other.   Assuming the  information  provided  by  both  servers  is
215       valid,  this shouldn't cause any real problems, but it could be confus‐
216       ing.
217
218       Normally, if dhclient was compiled  with  libcap-ng  support,  dhclient
219       drops  most  capabilities immediately upon startup.  While more secure,
220       this greatly restricts the additional actions that hooks  in  dhclient-
221       script  can  take. For example, any daemons that dhclient-script starts
222       or restarts will inherit the restricted capabilities as well, which may
223       interfere  with  their  correct operation.  Thus, the -nc option can be
224       used to prevent dhclient from dropping capabilities.
225

SEE ALSO

227       dhclient(8),    dhcpd(8),     dhcrelay(8),     dhclient.conf(5)     and
228       dhclient.leases(5).
229

AUTHOR

231       dhclient-script(8) To learn more about Internet Systems Consortium, see
232       https://www.isc.org.
233
234
235
236                                                            dhclient-script(8)
Impressum