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...  ] ] [ -i ] [ -I ] [ -D LL|LLT ] [ -p port-number ] [ -d ]  [  -e
11       VAR=value ] [ -q ] [ -1 ] [ -r | -x ] [ -lf lease-file ] [ -pf pid-file
12       ] [ --no-pid ] [ -cf config-file ] [ -sf script-file ] [ -s server-addr
13       ]  [  -g relay ] [ -n ] [ -nw ] [ -w ] [ -nc ] [ -B ] [ -I dhcp-client-
14       identifier ] [ -H host-name ] [ -F fqdn.fqdn ] [ -V  vendor-class-iden‐
15       tifier  ]  [  -R  request-option-list  ]  [ -timeout timeout ] [ -v ] [
16       --version ] [ if0 [ ...ifN ] ]
17

DESCRIPTION

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

OPERATION

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

COMMAND LINE

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

OPTIONS

93       -4     Use the DHCPv4 protocol to obtain an IPv4 address and configura‐
94              tion parameters.  This is the default  and  cannot  be  combined
95              with -6.
96
97       -6     Use  the  DHCPv6  protocol to obtain whatever IPv6 addresses are
98              available along with configuration  parameters.   It  cannot  be
99              combined with -4.  The -S -T -P -N and -D arguments provide more
100              control over aspects of the DHCPv6 processing.  Note: it is  not
101              recommended  to  mix queries of different types together or even
102              to share the lease file between them.
103
104       -1     Try to get a lease once.  On  failure  exit  with  code  2.   In
105              DHCPv6 this sets the maximum duration of the initial exchange to
106              timeout (from dhclient.conf with a default of sixty seconds).
107
108       -d     Force dhclient to run as a  foreground  process.   Normally  the
109              DHCP  client  will run in the foreground until is has configured
110              an interface at which time it will  revert  to  running  in  the
111              background.  This option is useful when running the client under
112              a debugger, or when running it out of inittab on System  V  sys‐
113              tems.  This implies -v.
114
115       -nw    Become  a  daemon immediately (nowait) rather than waiting until
116              an an IP address has been acquired.
117
118       -q     Be quiet at startup, this is the default.
119
120       -v     Enable verbose log messages.
121
122       -w     Continue running even if no  broadcast  interfaces  were  found.
123              Normally  DHCP client will exit if it isn't able to identify any
124              network interfaces to configure.  On laptop computers and  other
125              computers  with  hot-swappable  I/O buses, it is possible that a
126              broadcast interface may be added  after  system  startup.   This
127              flag can be used to cause the client not to exit when it doesn't
128              find any such interfaces.  The omshell(1) program  can  then  be
129              used  to  notify  the  client  when a network interface has been
130              added or removed, so that the client can attempt to configure an
131              IP address on that interface.
132
133
134       -nc    Do not drop capabilities.
135
136              Normally,  if  dhclient  was  compiled  with  libcap-ng support,
137              dhclient  drops  most  capabilities  immediately  upon  startup.
138              While more secure, this greatly restricts the additional actions
139              that hooks in dhclient-script (8) can take.  (For  example,  any
140              daemons that dhclient-script (8) starts or restarts will inherit
141              the restricted capabilities as well, which  may  interfere  with
142              their  correct  operation.)  Thus, the -nc option can be used to
143              prevent dhclient from dropping capabilities.
144
145              The -nc option is ignored if dhclient was not compiled with lib‐
146              cap-ng support.
147
148
149       -B     Set  the BOOTP broadcast flag in request packets so servers will
150              always broadcast replies.
151
152
153       -I <dhcp-client-identifier>
154              Specify the dhcp-client-identifier option to send  to  the  DHCP
155              server.
156
157
158       -H <host-name>
159              Specify  the  host-name  option to send to the DHCP server.  The
160              host-name string only contains the client's hostname prefix,  to
161              which  the server will append the ddns-domainname or domain-name
162              options, if any, to derive the fully qualified  domain  name  of
163              the client.  The -H option cannot be used with the -F option.
164
165
166       -F <fqdn.fqdn>
167              Specify  the  fqdn.fqdn option to send to the DHCP server.  This
168              option cannot be used with the -H option.  The fqdn.fqdn  option
169              must  specify the complete domain name of the client host, which
170              the server may use for dynamic DNS updates.
171
172
173       -V <vendor-class-identifier>
174              Specify the vendor-class-identifier option to send to  the  DHCP
175              server.
176
177
178       -R <option>[,<option>...]
179              Specify  the  list  of options the client is to request from the
180              server.  The option list must be a single string  consisting  of
181              option  names  separated  by  at  least one command and optional
182              space characters.  The default option list is:
183
184
185                  subnet-mask, broadcast-address, time-offset, routers,
186                  domain-search, domain-name, domain-name-servers, host-name,
187                  nis-domain, nis-servers, ntp-servers, interface-mtu
188
189
190       -R     option does not append options to the default request, it  over‐
191              rides  the  default request list.  Keep this in mind if you want
192              to request an additional  option  besides  the  default  request
193              list.   You  will  have  to  specify all option names for the -R
194              parameter.
195
196
197       -timeout <timeout>
198              Specify the time after which dhclient will decide that  no  DHCP
199              servers can be contacted when no responses have been received.
200
201
202       -n     Do not configure any interfaces.  This is most likely to be use‐
203              ful in combination with the -w flag.
204
205       -e VAR=value
206              Define additional  environment  variables  for  the  environment
207              where  dhclient-script  executes.   You  may specify multiple -e
208              options on the command line.
209
210       -r     Release the current lease and stop the running  DHCP  client  as
211              previously  recorded  in  the  PID file.  When shutdown via this
212              method dhclient-script will be executed with the specific reason
213              for calling the script set.  The client normally doesn't release
214              the current lease as this is not required by the  DHCP  protocol
215              but  some  cable ISPs require their clients to notify the server
216              if they wish to release an assigned IP address.
217
218       -x     Stop the running  DHCP  client  without  releasing  the  current
219              lease.   Kills  existing dhclient process as previously recorded
220              in the PID file.  When shutdown via this method  dhclient-script
221              will be executed with the specific reason for calling the script
222              set.
223
224       -p port-number
225              The UDP port number on which the DHCP client should  listen  and
226              transmit.  If unspecified, dhclient uses the default port of 68.
227              This is mostly useful for debugging purposes.   If  a  different
228              port  is  specified on which the client should listen and trans‐
229              mit, the client will also use a different destination port - one
230              less than the specified port.
231
232       -s server-addr
233              Specify  the server IP address or fully qualified domain name to
234              use as a destination for DHCP protocol messages before  dhclient
235              has  acquired an IP address.  Normally, dhclient transmits these
236              messages to 255.255.255.255 (the IP limited broadcast  address).
237              Overriding  this  is mostly useful for debugging purposes.  This
238              feature is not supported in DHCPv6 (-6) mode.
239
240       -g relay
241              Set the giaddr field of all packets to the relay IP address sim‐
242              ulating  a  relay  agent.  This is for testing pruposes only and
243              should not be expected to work in any consistent or useful way.
244
245       -i     Use a DUID with DHCPv4 clients.  If no DUID is available in  the
246              lease  file one will be constructed and saved.  The DUID will be
247              used to contstuct  a  RFC4361  style  client  id  that  will  be
248              included  in the client's messages.  This client id can be over‐
249              ridden by setting a client id in the configuration file.   Over‐
250              ridding the client id in this fashion is discouraged.
251
252       -I     Use the standard DDNS scheme from RFCs 4701 & 4702.
253
254       --version
255              Print version number and exit.
256
257       Options available for DHCPv6 mode:
258
259       -S     Use  Information-request  to  get  only  stateless configuration
260              parameters (i.e., without address).  This implies -6.   It  also
261              doesn't rewrite the lease database.
262
263       -T     Ask  for  IPv6  temporary  addresses, one set per -T flag.  This
264              implies -6 and also disables the normal address query.   See  -N
265              to restore it.
266
267       -P     Enable  IPv6  prefix  delegation.  This implies -6 and also dis‐
268              ables the normal address query.  See -N  to  restore  it.   Note
269              only one requested interface is allowed.
270
271       -D LL or LLT
272              Override the default when selecting the type of DUID to use.  By
273              default, DHCPv6 dhclient creates  an  identifier  based  on  the
274              link-layer  address (DUID-LL) if it is running in stateless mode
275              (with -S, not requesting an address), or it creates  an  identi‐
276              fier based on the link-layer address plus a timestamp (DUID-LLT)
277              if it is running in stateful mode  (without  -S,  requesting  an
278              address).   When  DHCPv4  is  configued  to  use a DUID using -i
279              option the default is to use a  DUID-LLT.   -D  overrides  these
280              default, with a value of either LL or LLT.
281
282       -N     Restore  normal  address query for IPv6. This implies -6.  It is
283              used to restore normal operation after using -T or -P.
284
285       Modifying default file locations: The following options can be used  to
286       modify the locations a client uses for it's files.  They can be partic‐
287       ularly useful if, for example, /var/lib/dhclient or /var/run  have  not
288       been mounted when the DHCP client is started.
289
290       -cf config-file
291              Path  to  the  client  configuration  file.  If unspecified, the
292              default /etc/dhcp/dhclient.conf is used.   See  dhclient.conf(5)
293              for a description of this file.
294
295       -lf lease-file
296              Path  to  the  lease database file.  If unspecified, the default
297              /var/lib/dhclient/dhclient.leases      is       used.        See
298              dhclient.leases(5) for a description of this file.
299
300       -pf pid-file
301              Path  to  the  process  ID  file.   If  unspecified, the default
302              /var/run/dhclient.pid is used.
303
304       --no-pid
305              Option to disable writing pid files.   By  default  the  program
306              will  write  a  pid  file.   If the program is invoked with this
307              option it will not attempt to kill any existing client processes
308              even if invoked with -r or -x.
309
310       -sf script-file
311              Path  to  the  network  configuration script invoked by dhclient
312              when  it  gets   a   lease.    If   unspecified,   the   default
313              /usr/sbin/dhclient-script is used.  See dhclient-script(8) for a
314              description of this file.
315
316
317

CONFIGURATION

319       The syntax of the dhclient.conf(5) file is discussed separately.
320

OMAPI

322       The DHCP client provides some ability to control it while  it  is  run‐
323       ning, without stopping it.  This capability is provided using OMAPI, an
324       API for manipulating remote objects.   OMAPI  clients  connect  to  the
325       client  using  TCP/IP,  authenticate, and can then examine the client's
326       current status and make changes to it.
327
328       Rather than implementing the underlying OMAPI protocol  directly,  user
329       programs  should  use  the  dhcpctl  API or OMAPI itself.  Dhcpctl is a
330       wrapper that handles some of the housekeeping chores  that  OMAPI  does
331       not  do  automatically.  Dhcpctl and OMAPI are documented in dhcpctl(3)
332       and omapi(3).  Most things you'd want to do with the client can be done
333       directly  using  the  omshell(1) command, rather than having to write a
334       special program.
335

THE CONTROL OBJECT

337       The control object allows you to shut the client  down,  releasing  all
338       leases  that  it  holds and deleting any DNS records it may have added.
339       It also allows you to pause the client - this unconfigures  any  inter‐
340       faces the client is using.  You can then restart it, which causes it to
341       reconfigure those interfaces.  You  would  normally  pause  the  client
342       prior  to  going  into  hibernation or sleep on a laptop computer.  You
343       would then resume it after the power comes back.  This allows PC  cards
344       to be shut down while the computer is hibernating or sleeping, and then
345       reinitialized to their previous state once the computer  comes  out  of
346       hibernation or sleep.
347
348       The  control  object  has one attribute - the state attribute.  To shut
349       the client down, set its state attribute to 2.  It  will  automatically
350       do  a  DHCPRELEASE.   To  pause  it,  set its state attribute to 3.  To
351       resume it, set its state attribute to 4.
352

ENVIRONMENT VARIABLES

354       The following environment variables may  be  defined  to  override  the
355       builtin defaults for file locations.  Note that use of the related com‐
356       mand-line options will ignore the  corresponding  environment  variable
357       settings.
358
359       PATH_DHCLIENT_CONF
360              The dhclient.conf configuration file.
361
362       PATH_DHCLIENT_DB
363              The dhclient.leases database.
364
365       PATH_DHCLIENT_PID
366              The dhclient PID file.
367
368       PATH_DHCLIENT_SCRIPT
369              The dhclient-script file.
370

FILES

372       /usr/sbin/dhclient-script,                     /etc/dhcp/dhclient.conf,
373       /var/lib/dhclient/dhclient.leases,               /var/run/dhclient.pid,
374       /var/lib/dhclient/dhclient.leases~.
375

SEE ALSO

377       dhcpd(8),     dhcrelay(8),     dhclient-script(8),    dhclient.conf(5),
378       dhclient.leases(5), dhcp-eval(5).
379

AUTHOR

381       dhclient(8) has been written for Internet  Systems  Consortium  by  Ted
382       Lemon  in  cooperation  with  Vixie  Enterprises.   To learn more about
383       Internet Systems Consortium,  see  https://www.isc.org  To  learn  more
384       about Vixie Enterprises, see http://www.vix.com.
385
386       This client was substantially modified and enhanced by Elliot Poger for
387       use on Linux while he was working on the MosquitoNet project  at  Stan‐
388       ford.
389
390       The  current  version owes much to Elliot's Linux enhancements, but was
391       substantially reorganized and partially rewritten by Ted Lemon so as to
392       use  the same networking framework that the Internet Systems Consortium
393       DHCP server uses.  Much system-specific configuration  code  was  moved
394       into  a  shell  script so that as support for more operating systems is
395       added, it will not be necessary to port  and  maintain  system-specific
396       configuration  code  to  these  operating  systems - instead, the shell
397       script can invoke the native tools to accomplish the same purpose.
398
399                                                                   dhclient(8)
Impressum