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

NAME

6       dhclient - Dynamic Host Configuration Protocol Client
7

SYNOPSIS

9       dhclient  [ -4 | -6 ] [ -S ] [ -N [ -N...  ] ] [ -T [ -T...  ] ] [ -P [
10       -P...  ] ] [ -R ] [ -i ] [ -I ] [ -4o6 port ] [ -D LL|LLT ] [ -p  port-
11       number  ] [ -d ] [ -df duid-lease-file ] [ -e VAR=value ] [ -q ] [ -1 ]
12       [ -r | -x ] [ -lf lease-file ] [ -pf pid-file ] [ --no-pid ] [ -cf con‐
13       fig-file ] [ -sf script-file ] [ -s server-addr ] [ -g relay ] [ -n ] [
14       -nw ] [ -w ] [ -nc ] [ -B ] [ -C dhcp-client-identifier ]  [  -H  host-
15       name  ] [ -F fqdn.fqdn ] [ -V vendor-class-identifier ] [ --request-op‐
16       tions request-option-list ] [ --timeout  timeout  ]  [  --dad-wait-time
17       seconds  ] [ --prefix-len-hint length ] [ --decline-wait-time seconds ]
18       [ -v ] [ --version ] [ if0 [ ...ifN ] ]
19

DESCRIPTION

21       The Internet Systems Consortium DHCP Client, dhclient, provides a means
22       for  configuring  one or more network interfaces using the Dynamic Host
23       Configuration Protocol, BOOTP protocol, or if these protocols fail,  by
24       statically assigning an address.
25

OPERATION

27       The DHCP protocol allows a host to contact a central server which main‐
28       tains a list of IP addresses which may be assigned on one or more  sub‐
29       nets.   A  DHCP  client may request an address from this pool, and then
30       use it on a temporary basis for communication  on  network.   The  DHCP
31       protocol also provides a mechanism whereby a client can learn important
32       details about the network to which it is attached, such as the location
33       of a default router, the location of a name server, and so on.
34
35       There  are  two  versions  of  the DHCP protocol DHCPv4 and DHCPv6.  At
36       startup the client may be started for one or the other via the -4 or -6
37       options.
38
39       On startup, dhclient reads the dhclient.conf for configuration instruc‐
40       tions.  It then gets a list of all the network interfaces that are con‐
41       figured in the current system.  For each interface, it attempts to con‐
42       figure the interface using the DHCP protocol.
43
44       In order to keep track of  leases  across  system  reboots  and  server
45       restarts,  dhclient  keeps a list of leases it has been assigned in the
46       dhclient.leases file.  On  startup,  after  reading  the  dhclient.conf
47       file,  dhclient  reads  the  dhclient.leases file to refresh its memory
48       about what leases it has been assigned.
49
50       When a new lease is  acquired,  it  is  appended  to  the  end  of  the
51       dhclient.leases file.  In order to prevent the file from becoming arbi‐
52       trarily large, from time to time dhclient creates a new dhclient.leases
53       file  from  its  in-core  lease  database.   The  old  version  of  the
54       dhclient.leases file is retained under the name dhclient.leases~  until
55       the next time dhclient rewrites the database.
56
57       Old  leases are kept around in case the DHCP server is unavailable when
58       dhclient is first invoked (generally during  the  initial  system  boot
59       process).   In  that  event,  old  leases from the dhclient.leases file
60       which have not yet expired are tested, and if they are determined to be
61       valid,  they  are  used until either they expire or the DHCP server be‐
62       comes available.
63
64       A mobile host which may sometimes need to access a network on which  no
65       DHCP server exists may be preloaded with a lease for a fixed address on
66       that network.  When all attempts to contact a DHCP server have  failed,
67       dhclient  will  try  to  validate the static lease, and if it succeeds,
68       will use that lease until it is restarted.
69
70       A mobile host may also travel to some networks on  which  DHCP  is  not
71       available  but  BOOTP  is.  In that case, it may be advantageous to ar‐
72       range with the network administrator for an entry on  the  BOOTP  data‐
73       base, so that the host can boot quickly on that network rather than cy‐
74       cling through the list of old leases.
75

COMMAND LINE

77       The names of the network interfaces that  dhclient  should  attempt  to
78       configure  may be specified on the command line.  If no interface names
79       are specified on the command line dhclient will normally  identify  all
80       network  interfaces,  eliminating non-broadcast interfaces if possible,
81       and attempt to configure each interface.
82
83       It is also possible to specify interfaces by name in the  dhclient.conf
84       file.   If  interfaces  are specified in this way, then the client will
85       only configure interfaces that are either specified in  the  configura‐
86       tion file or on the command line, and will ignore all other interfaces.
87
88       The  client  normally prints no output during its startup sequence.  It
89       can be made to emit verbose messages displaying  the  startup  sequence
90       events  until  it  has  acquired an address by supplying the -v command
91       line argument.  In either case, the client logs messages using the sys‐
92       log(3) facility.
93

OPTIONS

95       -4     Use the DHCPv4 protocol to obtain an IPv4 address and configura‐
96              tion parameters.  This is the default  and  cannot  be  combined
97              with -6.
98
99       -6     Use  the  DHCPv6  protocol to obtain whatever IPv6 addresses are
100              available along with configuration  parameters.   It  cannot  be
101              combined with -4.  The -S -T -P -N and -D arguments provide more
102              control over aspects of the DHCPv6 processing.  Note: it is  not
103              recommended  to  mix queries of different types together or even
104              to share the lease file between them.
105
106       -4o6 port
107              Participate in the DHCPv4 over DHCPv6 protocol specified by  RFC
108              7341.  This associates a DHCPv4 and a DHCPv6 client to allow the
109              v4 client to send v4 requests encapsulated in a v6 packet.  Com‐
110              munication  between  the  two  clients  is done on a pair of UDP
111              sockets bound to ::1 port and port + 1.  Both  clients  must  be
112              launched using the same port argument.
113
114       -1     Try  to  get  a  lease  once.   On failure exit with code 2.  In
115              DHCPv6 this sets the maximum duration of the initial exchange to
116              timeout (from dhclient.conf with a default of sixty seconds).
117
118       -d     Force  dhclient  to  run  as a foreground process.  Normally the
119              DHCP client will run in the foreground until is  has  configured
120              an  interface  at  which  time  it will revert to running in the
121              background.  This option is useful when running the client under
122              a  debugger,  or when running it out of inittab on System V sys‐
123              tems.  This implies -v.
124
125       -nw    Become a daemon immediately (nowait) rather than  waiting  until
126              an IP address has been acquired.
127
128       -q     Be quiet at startup, this is the default.
129
130       -v     Enable verbose log messages.
131
132       -w     Continue  running  even  if  no broadcast interfaces were found.
133              Normally DHCP client will exit if it isn't able to identify  any
134              network  interfaces to configure.  On laptop computers and other
135              computers with hot-swappable I/O buses, it is  possible  that  a
136              broadcast  interface  may  be  added after system startup.  This
137              flag can be used to cause the client not to exit when it doesn't
138              find  any  such  interfaces.  The omshell(1) program can then be
139              used to notify the client when  a  network  interface  has  been
140              added or removed, so that the client can attempt to configure an
141              IP address on that interface.
142
143       -nc    Do not drop capabilities.
144
145              Normally, if  dhclient  was  compiled  with  libcap-ng  support,
146              dhclient  drops  most  capabilities  immediately  upon  startup.
147              While more secure, this greatly restricts the additional actions
148              that  hooks  in dhclient-script (8) can take.  (For example, any
149              daemons that dhclient-script (8) starts or restarts will inherit
150              the  restricted  capabilities  as well, which may interfere with
151              their correct operation.)  Thus, the -nc option can be  used  to
152              prevent dhclient from dropping capabilities.
153
154              The -nc option is ignored if dhclient was not compiled with lib‐
155              cap-ng support.
156
157
158       -n     Do not configure any interfaces.  This is most likely to be use‐
159              ful in combination with the -w flag.
160
161       -e VAR=value
162              Define  additional  environment  variables  for  the environment
163              where dhclient-script executes.  You may specify multiple -e op‐
164              tions on the command line.
165
166       -r     Release  the  current  lease and stop the running DHCP client as
167              previously recorded in the PID file.   When  shutdown  via  this
168              method dhclient-script will be executed with the specific reason
169              for calling the script set.  The client normally doesn't release
170              the  current  lease as this is not required by the DHCP protocol
171              but some cable ISPs require their clients to notify  the  server
172              if they wish to release an assigned IP address.
173
174       -x     Stop  the  running  DHCP  client  without  releasing the current
175              lease.  Kills existing dhclient process as  previously  recorded
176              in  the PID file.  When shutdown via this method dhclient-script
177              will be executed with the specific reason for calling the script
178              set.
179
180       -p port-number
181              The  UDP  port number on which the DHCP client should listen and
182              transmit.  If unspecified, dhclient uses the default port of 68.
183              This  is  mostly  useful for debugging purposes.  If a different
184              port is specified on which the client should listen  and  trans‐
185              mit, the client will also use a different destination port - one
186              less than the specified port.
187
188       -s server-addr
189              Specify the server IP address or fully qualified domain name  to
190              use  as a destination for DHCP protocol messages before dhclient
191              has acquired an IP address.  Normally, dhclient transmits  these
192              messages  to 255.255.255.255 (the IP limited broadcast address).
193              Overriding this is mostly useful for debugging  purposes.   This
194              feature is not supported in DHCPv6 (-6) mode.
195
196       -g relay
197              Set the giaddr field of all packets to the relay IP address sim‐
198              ulating a relay agent.  This is for testing  purposes  only  and
199              should not be expected to work in any consistent or useful way.
200
201       -i     Use  a DUID with DHCPv4 clients.  If no DUID is available in the
202              lease file one will be constructed and saved.  The DUID will  be
203              used  to  construct  a  RFC4361 style client id that will be in‐
204              cluded in the client's messages.  This client id can be overrid‐
205              den  by setting a client id in the configuration file.  Overrid‐
206              ing the client id in this fashion is discouraged.
207
208       -I     Use the standard DDNS scheme from RFCs 4701 & 4702.
209
210
211       --decline-wait-time seconds
212              Specify the time (in seconds) that an IPv4  client  should  wait
213              after  declining  an address before issuing a discover.  The de‐
214              fault is 10 seconds as recommended by RFC 2131,  Section  3.1.5.
215              A value of zero equates to no wait at all.
216
217       --version Print version number and exit.
218
219       Options available for DHCPv6 mode:
220
221       -S     Use  Information-request to get only stateless configuration pa‐
222              rameters (i.e., without address).  This  implies  -6.   It  also
223              doesn't rewrite the lease database.
224
225       -T     Ask for IPv6 temporary addresses, one set per -T flag.  This im‐
226              plies -6 and also disables the normal address query.  See -N  to
227              restore it.
228
229       -P     Enable  IPv6  prefix  delegation.  This implies -6 and also dis‐
230              ables the normal address query.  See -N to restore it.  Multiple
231              prefixes can be requested with multiple -P flags.  Note only one
232              requested interface is allowed.
233
234       -R     Require that responses include all of the items requested by any
235              -N,  -T,  or  -P options.  Normally even if the command line in‐
236              cludes a number of these the client will be  willing  to  accept
237              the  best  lease it can even if the lease doesn't include all of
238              the requested items.  This option causes the client to only  ac‐
239              cept leases that include all of the requested items.
240
241              Note  well:  enabling this may prevent the client from using any
242              leases it receives if the servers aren't  configured  to  supply
243              all of the items.
244
245       -D LL or LLT
246              Override the default when selecting the type of DUID to use.  By
247              default, DHCPv6 dhclient creates  an  identifier  based  on  the
248              link-layer  address (DUID-LL) if it is running in stateless mode
249              (with -S, not requesting an address), or it creates  an  identi‐
250              fier based on the link-layer address plus a timestamp (DUID-LLT)
251              if it is running in stateful mode (without -S, requesting an ad‐
252              dress).  When DHCPv4 is configured to use a DUID using -i option
253              the default is to use a DUID-LLT.  -D overrides  these  default,
254              with a value of either LL or LLT.
255
256       -N     Restore  normal  address query for IPv6. This implies -6.  It is
257              used to restore normal operation after using -T or -P.  Multiple
258              addresses can be requested with multiple -N flags.
259
260       --address-prefix-len length
261              Specify  the length of the prefix for IPv6 addresses. This value
262              is passed by dhclient into the client script via the environment
263              variable,  ip6_prefixlen,  when binding IPv6 addresses.  The de‐
264              fault value is 128.  Alternatively you may change the default at
265              compile  time  by  setting  DHCLIENT_DEFAULT_PREFIX_LEN  in  in‐
266              cludes/site.h.
267
268       --dad-wait-time seconds
269              Specify maximum time (in seconds) that the  client  should  wait
270              for  the duplicate address detection (DAD) to complete on an in‐
271              terface. This value is propagated to the dhclient  script  in  a
272              dad_wait_time environment variable. If any of the IPv6 addresses
273              on the interface are tentative (DAD is in progress), the  script
274              will  wait  for  the specified number of seconds for DAD to com‐
275              plete. If the script ignores this variable the parameter has  no
276              effect.
277
278       --prefix-len-hint length
279              When  used  in conjunction with -P, it directs the client to use
280              the given length to use a prefix hint of, "::/length", when  re‐
281              questing new prefixes.
282
283       Modifying  default file locations: The following options can be used to
284       modify the locations a client uses for its files.  They can be particu‐
285       larly  useful  if,  for example, /var/lib/dhclient or /var/run have not
286       been mounted when the DHCP client is started.
287
288       -cf config-file
289              Path to the client configuration file.  If unspecified, the  de‐
290              fault /etc/dhcp/dhclient.conf is used.  See dhclient.conf(5) for
291              a description of this file.
292
293       -df duid-lease-file
294              Path to a secondary lease  file.   If  the  primary  lease  file
295              doesn't  contain  a  DUID  this file will be searched.  The DUID
296              read from the secondary will be written to  the  primary.   This
297              option  can  be  used to allow an IPv4 instance of the client to
298              share a DUID with an IPv6 instance.  After starting one  of  the
299              instances the second can be started with this option pointing to
300              the lease file of the first instance.  There is no default.   If
301              no file is specified no search is made for a DUID should one not
302              be found in the main lease file.
303
304       -lf lease-file
305              Path to the lease database file.  If  unspecified,  the  default
306              /var/lib/dhclient/dhclient.leases       is       used.       See
307              dhclient.leases(5) for a description of this file.
308
309       -pf pid-file
310              Path to the  process  ID  file.   If  unspecified,  the  default
311              /var/run/dhclient.pid is used.
312
313       --no-pid
314              Option  to  disable  writing  pid files.  By default the program
315              will write a pid file.  If the program is invoked with this  op‐
316              tion  it  will not attempt to kill any existing client processes
317              even if invoked with -r or -x.
318
319       -sf script-file
320              Path to the network configuration  script  invoked  by  dhclient
321              when   it   gets   a   lease.    If   unspecified,  the  default
322              /usr/sbin/dhclient-script is used.  See dhclient-script(8) for a
323              description of this file.
324
325       -B     Always  set the bootp broadcast flag in request packets, so that
326              servers will always broadcast replies. This option  is  provided
327              as  an  extension  to  enable dhclient to work on IBM s390 Linux
328              guests.
329

PORTS

331       During operations the client may use multiple UDP ports to provide dif‐
332       ferent  functions.   Which ports are opened depends on both the way you
333       compiled your code and the configuration  you  supply.   The  following
334       should provide you an idea of what ports may be in use.
335
336       Normally a DHCPv4 client will open a raw UDP socket to receive and send
337       most DHCPv4 packets.  It also opens a fallback UDP socket  for  use  in
338       sending  unicast  packets.  Normally these will both use the well known
339       port number for BOOTPC.
340
341       For DHCPv6 the client opens a UDP socket on the well known client  port
342       and  a  fallback UDP socket on a random port for use in sending unicast
343       messages.  Unlike DHCPv4 the well  known  socket  doesn't  need  to  be
344       opened in raw mode.
345
346       If you have included an omapi port statement in your configuration file
347       then the client will open a TCP socket on that port to listen for OMPAI
348       connections.  When something connects another port will be used for the
349       established connection.
350
351       When DDNS is enabled at compile time (see includes/site.h)  the  client
352       will  open  both a v4 and a v6 UDP socket on random ports.  These ports
353       are not opened unless/until the client first attempts to do an  update.
354       If  the client is not configured to do updates, the ports will never be
355       opened.
356

CONFIGURATION

358       The syntax of the dhclient.conf(5) file is discussed separately.
359

OMAPI

361       The DHCP client provides some ability to control it while  it  is  run‐
362       ning, without stopping it.  This capability is provided using OMAPI, an
363       API for manipulating remote objects.   OMAPI  clients  connect  to  the
364       client  using  TCP/IP,  authenticate, and can then examine the client's
365       current status and make changes to it.
366
367       Rather than implementing the underlying OMAPI protocol  directly,  user
368       programs  should  use  the  dhcpctl  API or OMAPI itself.  Dhcpctl is a
369       wrapper that handles some of the housekeeping chores  that  OMAPI  does
370       not  do  automatically.  Dhcpctl and OMAPI are documented in dhcpctl(3)
371       and omapi(3).  Most things you'd want to do with the client can be done
372       directly  using  the  omshell(1) command, rather than having to write a
373       special program.
374

THE CONTROL OBJECT

376       The control object allows you to shut the client  down,  releasing  all
377       leases  that  it  holds and deleting any DNS records it may have added.
378       It also allows you to pause the client - this unconfigures  any  inter‐
379       faces the client is using.  You can then restart it, which causes it to
380       reconfigure those interfaces.  You  would  normally  pause  the  client
381       prior  to  going  into  hibernation or sleep on a laptop computer.  You
382       would then resume it after the power comes back.  This allows PC  cards
383       to be shut down while the computer is hibernating or sleeping, and then
384       reinitialized to their previous state once the computer  comes  out  of
385       hibernation or sleep.
386
387       The  control  object  has one attribute - the state attribute.  To shut
388       the client down, set its state attribute to 2.  It  will  automatically
389       do  a  DHCPRELEASE.  To pause it, set its state attribute to 3.  To re‐
390       sume it, set its state attribute to 4.
391

ENVIRONMENT VARIABLES

393       The following environment variables may  be  defined  to  override  the
394       builtin defaults for file locations.  Note that use of the related com‐
395       mand-line options will ignore the  corresponding  environment  variable
396       settings.
397
398       PATH_DHCLIENT_CONF
399              The dhclient.conf configuration file.
400
401       PATH_DHCLIENT_DB
402              The dhclient.leases database.
403
404       PATH_DHCLIENT_PID
405              The dhclient PID file.
406
407       PATH_DHCLIENT_SCRIPT
408              The dhclient-script file.
409

FILES

411       /usr/sbin/dhclient-script,                     /etc/dhcp/dhclient.conf,
412       /var/lib/dhclient/dhclient.leases,               /var/run/dhclient.pid,
413       /var/lib/dhclient/dhclient.leases~.
414

SEE ALSO

416       dhcpd(8),     dhcrelay(8),     dhclient-script(8),    dhclient.conf(5),
417       dhclient.leases(5), dhcp-eval(5).
418

AUTHOR

420       dhclient(8) To  learn  more  about  Internet  Systems  Consortium,  see
421       https://www.isc.org
422
423       This client was substantially modified and enhanced by Elliot Poger for
424       use on Linux while he was working on the MosquitoNet project  at  Stan‐
425       ford.
426
427       The  current  version owes much to Elliot's Linux enhancements, but was
428       substantially reorganized and partially rewritten by Ted Lemon so as to
429       use  the same networking framework that the Internet Systems Consortium
430       DHCP server uses.  Much system-specific configuration  code  was  moved
431       into  a  shell  script so that as support for more operating systems is
432       added, it will not be necessary to port  and  maintain  system-specific
433       configuration  code  to  these  operating  systems - instead, the shell
434       script can invoke the native tools to accomplish the same purpose.
435
436                                                                   dhclient(8)
Impressum