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

DESCRIPTION

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

OPERATION

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

COMMAND LINE

70       The  names  of  the  network interfaces that dhclient should attempt to
71       configure may be specified on the command line.  If no interface  names
72       are  specified  on the command line dhclient will normally identify all
73       network interfaces, eliminating non-broadcast interfaces  if  possible,
74       and attempt to configure each interface.
75
76       It   is   also   possible   to   specify  interfaces  by  name  in  the
77       dhclient.conf(5) file.   If interfaces are specified in this way,  then
78       the  client will only configure interfaces that are either specified in
79       the configuration file or on the command  line,  and  will  ignore  all
80       other interfaces.
81

OPTIONS

83       -4     Use the DHCPv4 protocol to obtain an IPv4 address and configura‐
84              tion parameters (default).
85
86
87       -6     Use the DHCPv6 protocol to obtain whatever  IPv6  addresses  are
88              available  along with configuration parameters.  The functional‐
89              ity of DHCPv6 mode may be modified with the -S ,  -T  ,  and  -N
90              options.
91
92
93       -S     Perform an information-only request over DHCPv6 to get stateless
94              configuration parameters.  It is not recommended to combine this
95              option  with the -N , -P , or -T options or to share lease files
96              between different modes of operation.  Only valid  with  the  -6
97              option.
98
99
100       -N     Perform  a  normal (IA_NA) address query over DHCPv6.  It is not
101              recommended to combine this option with the -P  ,  -S  ,  or  -T
102              options or to share lease files between different modes of oper‐
103              ation.  Only valid with the -6 option.
104
105
106       -T     Perform a temporary (IA_TA) address query over DHCPv6  (disables
107              normal  address  query).   It is not recommended to combine this
108              option with the -N , -P , or -S options or to share lease  files
109              between  different  modes  of operation.  Only valid with the -6
110              option.
111
112
113       -P     Enable IPv6 prefix delegation (disables normal  address  query).
114              It  is  not not recommended to combine this option with the -N ,
115              -S , or -T options or to share  lease  files  between  different
116              modes of operation.  Only valid with the -6 option.
117
118
119       -p <port number>
120              The  UDP  port number the DHCP client should listen and transmit
121              on.  If unspecified, dhclient uses the default  port  68.   This
122              option  is mostly useful for debugging purposes.  If a different
123              port is specified for the client to listen and transmit on,  the
124              client  will  also  use  a different destination port - one less
125              than the specified port.
126
127
128       -d     Force dhclient to run as a foreground process.  This  is  useful
129              when running the client under a debugger, or when running it out
130              of inittab on System V systems.
131
132
133       -e VAR=value
134              Define additional  environment  variables  for  the  environment
135              where  dhclient-script  executes.  You may specify multiplate -e
136              options on the command line.  For example: -e IF_METRIC=1
137
138
139       -q     Suppress all terminal and log output except error messages.
140
141
142       -1     Try once to get a lease.  One failure, exit with code 2.
143
144
145       -r     Tell dhclient to release the  current  lease  it  has  from  the
146              server.   This  is  not  required by the DHCP protocol, but some
147              ISPs require their clients to notify the server if they wish  to
148              release an assigned IP address.
149
150
151       -lf <lease-file>
152              Path  to  the  lease database file.  If unspecified, the default
153              /var/lib/dhclient/dhclient.leases is used.
154
155
156       -pf <pid-file>
157              Path to the  process  ID  file.   If  unspecified,  the  default
158              /var/run/dhclient.pid is used.
159
160
161       -cf <config-file>
162              Path  to  the  client  configuration  file.  If unspecified, the
163              default /etc/dhcp/dhclient.conf is used.
164
165
166       -sf <script-file>
167              Path to the network configuration  script  invoked  by  dhclient
168              when   it   gets   a   lease.    If   unspecified,  the  default
169              /sbin/dhclient-script is used.
170
171
172       -s <server>
173              Specifiy the server IP address or fully qualified domain name to
174              transmit  DHCP  protocol messages to.  Normally, dhclient trans‐
175              mits these messages to 255.255.255.255 (the IP limited broadcast
176              address).   Overriding  this is mostly useful for debugging pur‐
177              poses.
178
179
180       -g <relay>
181              Only for debugging.  Set the giaddr field  of  all  packets  the
182              client  sends  to  the IP address specified.  This should not be
183              expected to work in any consistent or useful way.
184
185
186       -n     Do not configure any interfaces.  Most useful combined with  the
187              -w option.
188
189
190       -nc    Do not drop capabilities.
191
192              Normally,  if  dhclient  was  compiled  with  libcap-ng support,
193              dhclient  drops  most  capabilities  immediately  upon  startup.
194              While more secure, this greatly restricts the additional actions
195              that hooks in dhclient-script (8) can take.  (For  example,  any
196              daemons that dhclient-script (8) starts or restarts will inherit
197              the restricted capabilities as well, which  may  interfere  with
198              their  correct  operation.)  Thus, the -nc option can be used to
199              prevent dhclient from dropping capabilities.
200
201              The -nc option is ignored if dhclient was not compiled with lib‐
202              cap-ng support.
203
204
205       -nw    Become a daemon process immediately (nowait) rather than waiting
206              until an IP address has been acquired.
207
208
209       -w     Keep running even if  no  network  interfaces  are  found.   The
210              omshell  program can be used to notify the client when a network
211              interface has been added or removed so it can attempt to config‐
212              ure an IP address on that interface.
213
214
215       -B     Set  the BOOTP broadcast flag in request packets so servers will
216              always broadcast replies.
217
218
219       -I <dhcp-client-identifier>
220              Specify the dhcp-client-identifier option to send  to  the  DHCP
221              server.
222
223
224       -H <host-name>
225              Specify  the  host-name  option to send to the DHCP server.  The
226              host-name string only contains the client's hostname prefix,  to
227              which  the server will append the ddns-domainname or domain-name
228              options, if any, to derive the fully qualified  domain  name  of
229              the client.  The -H option cannot be used with the -F option.
230
231
232       -F <fqdn.fqdn>
233              Specify  the  fqdn.fqdn option to send to the DHCP server.  This
234              option cannot be used with the -H option.  The fqdn.fqdn  option
235              must  specify the complete domain name of the client host, which
236              the server may use for dynamic DNS updates.
237
238
239       -V <vendor-class-identifier>
240              Specify the vendor-class-identifier option to send to  the  DHCP
241              server.
242
243
244       -R <option>[,<option>...]
245              Specify  the  list  of options the client is to request from the
246              server.  The option list must be a single string  consisting  of
247              option  names  separated  by  at  least one command and optional
248              space characters.  The default option list is:
249
250
251                  subnet-mask, broadcast-address, time-offset, routers,
252                  domain-name, domain-name-servers, host-name,
253                  nis-domain, nis-servers, ntp-servers, interface-mtu
254
255              The -R option does not append options to the default request, it
256              overrides  the  default  request list.  Keep this in mind if you
257              want to request an additional option besides the default request
258              list.   You  will  have  to  specify all option names for the -R
259              parameter.
260
261
262       -timeout <timeout>
263              Specify the time after which dhclient will decide that  no  DHCP
264              servers can be contacted when no responses have been received.
265
266
267       -v     Enable verbose log messages.
268
269
270       If  the  client  is  killed  by  a  signale (for example at shutdown or
271       reboot), it will not execute the dhclient-script (8) at exit.  However,
272       if  you  shut  the client down gracefully with -r or -x it will execute
273       dhclient-script (8) at shutdown with the specific  reason  for  calling
274       the script set in the environment table.
275

CONFIGURATION

277       The syntax of the dhclient.conf(5) file is discussed separately.
278

OMAPI

280       The  DHCP  client  provides some ability to control it while it is run‐
281       ning, without stopping it.  This capability is provided using OMAPI, an
282       API  for  manipulating  remote  objects.   OMAPI clients connect to the
283       client using TCP/IP, authenticate, and can then  examine  the  client's
284       current status and make changes to it.
285
286       Rather  than  implementing the underlying OMAPI protocol directly, user
287       programs should use the dhcpctl API or OMAPI  itself.    Dhcpctl  is  a
288       wrapper  that  handles  some of the housekeeping chores that OMAPI does
289       not do automatically.   Dhcpctl and OMAPI are documented in  dhcpctl(3)
290       and  omapi(3).    Most  things  you'd want to do with the client can be
291       done directly using the omshell(1) command, rather than having to write
292       a special program.
293

THE CONTROL OBJECT

295       The  control  object  allows you to shut the client down, releasing all
296       leases that it holds and deleting any DNS records it  may  have  added.
297       It  also  allows you to pause the client - this unconfigures any inter‐
298       faces the client is using.   You can then restart it, which  causes  it
299       to  reconfigure those interfaces.   You would normally pause the client
300       prior to going into hibernation or sleep on a  laptop  computer.    You
301       would  then resume it after the power comes back.  This allows PC cards
302       to be shut down while the computer is hibernating or sleeping, and then
303       reinitialized  to  their  previous state once the computer comes out of
304       hibernation or sleep.
305
306       The control object has one attribute - the state attribute.    To  shut
307       the  client down, set its state attribute to 2.   It will automatically
308       do a DHCPRELEASE.   To pause it, set its state  attribute  to  3.    To
309       resume it, set its state attribute to 4.
310

FILES

312       /sbin/dhclient-script,                         /etc/dhcp/dhclient.conf,
313       /var/lib/dhclient/dhclient.leases,               /var/run/dhclient.pid,
314       /var/lib/dhclient/dhclient.leases~.
315

SEE ALSO

317       dhcpd(8),     dhcrelay(8),     dhclient-script(8),    dhclient.conf(5),
318       dhclient.leases(5), dhcp-eval(5).
319

AUTHOR

321       dhclient(8) has been written for Internet  Systems  Consortium  by  Ted
322       Lemon  in  cooperation  with  Vixie  Enterprises.   To learn more about
323       Internet Systems Consortium,  see  https://www.isc.org  To  learn  more
324       about Vixie Enterprises, see http://www.vix.com.
325
326       This client was substantially modified and enhanced by Elliot Poger for
327       use on Linux while he was working on the MosquitoNet project  at  Stan‐
328       ford.
329
330       The  current  version owes much to Elliot's Linux enhancements, but was
331       substantially reorganized and partially rewritten by Ted Lemon so as to
332       use  the same networking framework that the Internet Systems Consortium
333       DHCP server uses.   Much system-specific configuration code  was  moved
334       into  a  shell  script so that as support for more operating systems is
335       added, it will not be necessary to port  and  maintain  system-specific
336       configuration  code  to  these  operating  systems - instead, the shell
337       script can invoke the native tools to accomplish the same purpose.
338
339                                                                   dhclient(8)
Impressum