1dhclient.conf(5) File Formats Manual dhclient.conf(5)
2
6 dhclient.conf - DHCP client configuration file
7
9 The dhclient.conf file contains configuration information for dhclient,
10 the Internet Systems Consortium DHCP Client.
11 The dhclient.conf file is a free-form ASCII text file. It is parsed
13 by the recursive-descent parser built into dhclient. The file may
14 contain extra tabs and newlines for formatting purposes. Keywords in
15 the file are case-insensitive. Comments may be placed anywhere within
16 the file (except within quotes). Comments begin with the # character
17 and end at the end of the line.
18 The dhclient.conf file can be used to configure the behaviour of the
20 client in a wide variety of ways: protocol timing, information
21 requested from the server, information required of the server, defaults
22 to use if the server does not provide certain information, values with
23 which to override information provided by the server, or values to
24 prepend or append to information provided by the server. The configu‐
25 ration file can also be preinitialized with addresses to use on net‐
26 works that don't have DHCP servers.
27
29 The timing behaviour of the client need not be configured by the user.
30 If no timing configuration is provided by the user, a fairly reasonable
31 timing behaviour will be used by default - one which results in fairly
32 timely updates without placing an inordinate load on the server.
33 The following statements can be used to adjust the timing behaviour of
35 the DHCP client if required, however:
36 The timeout statement
38 timeout time ;
40 The timeout statement determines the amount of time that must pass
42 between the time that the client begins to try to determine its address
43 and the time that it decides that it's not going to be able to contact
44 a server. By default, this timeout is sixty seconds. After the
45 timeout has passed, if there are any static leases defined in the con‐
46 figuration file, or any leases remaining in the lease database that
47 have not yet expired, the client will loop through these leases
48 attempting to validate them, and if it finds one that appears to be
49 valid, it will use that lease's address. If there are no valid static
50 leases or unexpired leases in the lease database, the client will
51 restart the protocol after the defined retry interval.
52 The retry statement
54 retry time;
56 The retry statement determines the time that must pass after the client
58 has determined that there is no DHCP server present before it tries
59 again to contact a DHCP server. By default, this is five minutes.
60 The select-timeout statement
62 select-timeout time;
64 It is possible (some might say desirable) for there to be more than one
66 DHCP server serving any given network. In this case, it is possible
67 that a client may be sent more than one offer in response to its ini‐
68 tial lease discovery message. It may be that one of these offers is
69 preferable to the other (e.g., one offer may have the address the
70 client previously used, and the other may not).
71 The select-timeout is the time after the client sends its first lease
73 discovery request at which it stops waiting for offers from servers,
74 assuming that it has received at least one such offer. If no offers
75 have been received by the time the select-timeout has expired, the
76 client will accept the first offer that arrives.
77 By default, the select-timeout is zero seconds - that is, the client
79 will take the first offer it sees.
80 The reboot statement
82 reboot time;
84 When the client is restarted, it first tries to reacquire the last
86 address it had. This is called the INIT-REBOOT state. If it is
87 still attached to the same network it was attached to when it last ran,
88 this is the quickest way to get started. The reboot statement sets
89 the time that must elapse after the client first tries to reacquire its
90 old address before it gives up and tries to discover a new address.
91 By default, the reboot timeout is ten seconds.
92 The backoff-cutoff statement
94 backoff-cutoff time;
96 The client uses an exponential backoff algorithm with some randomness,
98 so that if many clients try to configure themselves at the same time,
99 they will not make their requests in lockstep. The backoff-cutoff
100 statement determines the maximum amount of time that the client is
101 allowed to back off, the actual value will be evaluated randomly
102 between 1/2 to 1 1/2 times the time specified. It defaults to two
103 minutes.
104 The initial-interval statement
106 initial-interval time;
108 The initial-interval statement sets the amount of time between the
110 first attempt to reach a server and the second attempt to reach a
111 server. Each time a message is sent, the interval between messages is
112 incremented by twice the current interval multiplied by a random number
113 between zero and one. If it is greater than the backoff-cutoff amount,
114 it is set to that amount. It defaults to ten seconds.
115
117 The DHCP protocol allows the client to request that the server send it
118 specific information, and not send it other information that it is not
119 prepared to accept. The protocol also allows the client to reject
120 offers from servers if they don't contain information the client needs,
121 or if the information provided is not satisfactory.
122 There is a variety of data contained in offers that DHCP servers send
124 to DHCP clients. The data that can be specifically requested is what
125 are called DHCP Options. DHCP Options are defined in
126 dhcp-options(5).
127 The request statement
129 [ also ] request [ [ option-space . ] option ] [, ... ];
131 The request statement causes the client to request that any server
133 responding to the client send the client its values for the specified
134 options. Only the option names should be specified in the request
135 statement - not option parameters. By default, the DHCPv4 client
136 requests the subnet-mask, broadcast-address, time-offset, routers,
137 domain-name, domain-search, domain-name-servers, host-name, nis-domain,
138 nis-servers, ntp-servers and interface-mtu options. The DHCPv6 client
139 requests by default name-servers and domain-search. Note that if you
140 enter a 'request' statement, you over-ride this default and these
141 options will not be requested.
142 In some cases, it may be desirable to send no parameter request list at
144 all. To do this, simply write the request statement but specify no
145 parameters:
146 request;
148 In most cases, it is desirable to simply add one option to the request
150 list which is of interest to the client in question. In this case, it
151 is best to 'also request' the additional options:
152 also request domain-search, dhcp6.sip-servers-addresses;
154 The require statement
156 [ also ] require [ [ option-space . ] option ] [, ... ];
158 The require statement lists options that must be sent in order for an
160 offer to be accepted. Offers that do not contain all the listed
161 options will be ignored. There is no default require list.
162 require name-servers;
164 interface eth0 {
166 also require domain-search;
167 }
168 The
170 send
171 statement
172 send { [ option declaration ]
174 [, ... option declaration ]}
175 The send statement causes the client to send the specified options to
177 the server with the specified values. These are full option
178 declarations as described in dhcp-options(5). Options that are
179 always sent in the DHCP protocol should not be specified here, except
180 that the client can specify a requested dhcp-lease-time option other
181 than the default requested lease time, which is two hours. The other
182 obvious use for this statement is to send information to the server
183 that will allow it to differentiate between this client and other
184 clients or kinds of clients.
185
187 The client now has some very limited support for doing DNS updates when
188 a lease is acquired. This is prototypical, and probably doesn't do
189 what you want. It also only works if you happen to have control over
190 your DNS server, which isn't very likely.
191 Note that everything in this section is true whether you are using
193 DHCPv4 or DHCPv6. The exact same syntax is used for both.
194 To make it work, you have to declare a key and zone as in the DHCP
196 server (see dhcpd.conf(5) for details). You also need to configure
197 the fqdn option on the client, as follows:
198 send fqdn.fqdn "grosse.fugue.com.";
200 send fqdn.encoded on;
201 send fqdn.server-update off;
202 also request fqdn, dhcp6.fqdn;
203 The fqdn.fqdn option MUST be a fully-qualified domain name. You MUST
205 define a zone statement for the zone to be updated. The fqdn.encoded
206 option may need to be set to on or off, depending on the DHCP server
207 you are using.
208 The do-forward-updates statement
210 do-forward-updates [ flag ] ;
212 If you want to do DNS updates in the DHCP client script (see dhclient-
214 script(8)) rather than having the DHCP client do the update directly
215 (for example, if you want to use SIG(0) authentication, which is not
216 supported directly by the DHCP client, you can instruct the client not
217 to do the update using the do-forward-updates statement. Flag should
218 be true if you want the DHCP client to do the update, and false if you
219 don't want the DHCP client to do the update. By default, the DHCP
220 client will do the DNS update.
221
223 In some cases, a client may receive option data from the server which
224 is not really appropriate for that client, or may not receive informa‐
225 tion that it needs, and for which a useful default value exists. It
226 may also receive information which is useful, but which needs to be
227 supplemented with local information. To handle these needs, several
228 option modifiers are available.
229 The default statement
231 default [ option declaration ] ;
233 If for some option the client should use the value supplied by the
235 server, but needs to use some default value if no value was supplied by
236 the server, these values can be defined in the default statement.
237 The supersede statement
239 supersede [ option declaration ] ;
241 If for some option the client should always use a locally-configured
243 value or values rather than whatever is supplied by the server, these
244 values can be defined in the supersede statement.
245 The prepend statement
247 prepend [ option declaration ] ;
249 If for some set of options the client should use a value you supply,
251 and then use the values supplied by the server, if any, these values
252 can be defined in the prepend statement. The prepend statement can
253 only be used for options which allow more than one value to be given.
254 This restriction is not enforced - if you ignore it, the behaviour will
255 be unpredictable.
256 The append statement
258 append [ option declaration ] ;
260 If for some set of options the client should first use the values sup‐
262 plied by the server, if any, and then use values you supply, these val‐
263 ues can be defined in the append statement. The append statement can
264 only be used for options which allow more than one value to be given.
265 This restriction is not enforced - if you ignore it, the behaviour will
266 be unpredictable.
267
269 The lease declaration
270 lease { lease-declaration [ ... lease-declaration ] }
272 The DHCP client may decide after some period of time (see PROTOCOL TIM‐
274 ING) that it is not going to succeed in contacting a server. At that
275 time, it consults its own database of old leases and tests each one
276 that has not yet timed out by pinging the listed router for that lease
277 to see if that lease could work. It is possible to define one or more
278 fixed leases in the client configuration file for networks where there
279 is no DHCP or BOOTP service, so that the client can still automatically
280 configure its address. This is done with the lease statement.
281 NOTE: the lease statement is also used in the dhclient.leases file in
283 order to record leases that have been received from DHCP servers. Some
284 of the syntax for leases as described below is only needed in the
285 dhclient.leases file. Such syntax is documented here for complete‐
286 ness.
287 A lease statement consists of the lease keyword, followed by a left
289 curly brace, followed by one or more lease declaration statements, fol‐
290 lowed by a right curly brace. The following lease declarations are
291 possible:
292 bootp;
294 The bootp statement is used to indicate that the lease was acquired
296 using the BOOTP protocol rather than the DHCP protocol. It is never
297 necessary to specify this in the client configuration file. The
298 client uses this syntax in its lease database file.
299 interface "string";
301 The interface lease statement is used to indicate the interface on
303 which the lease is valid. If set, this lease will only be tried on a
304 particular interface. When the client receives a lease from a server,
305 it always records the interface number on which it received that lease.
306 If predefined leases are specified in the dhclient.conf file, the
307 interface should also be specified, although this is not required.
308 fixed-address ip-address;
310 The fixed-address statement is used to set the ip address of a particu‐
312 lar lease. This is required for all lease statements. The IP
313 address must be specified as a dotted quad (e.g., 12.34.56.78).
314 filename "string";
316 The filename statement specifies the name of the boot filename to use.
318 This is not used by the standard client configuration script, but is
319 included for completeness.
320 server-name "string";
322 The server-name statement specifies the name of the boot server name to
324 use. This is also not used by the standard client configuration
325 script.
326 option option-declaration;
328 The option statement is used to specify the value of an option supplied
330 by the server, or, in the case of predefined leases declared in
331 dhclient.conf, the value that the user wishes the client configuration
332 script to use if the predefined lease is used.
333 script "script-name";
335 The script statement is used to specify the pathname of the dhcp client
337 configuration script. This script is used by the dhcp client to set
338 each interface's initial configuration prior to requesting an address,
339 to test the address once it has been offered, and to set the inter‐
340 face's final configuration once a lease has been acquired. If no
341 lease is acquired, the script is used to test predefined leases, if
342 any, and also called once if no valid lease can be identified. For
343 more information, see dhclient-script(8).
344 vendor option space "name";
346 The vendor option space statement is used to specify which option space
348 should be used for decoding the vendor-encapsulate-options option if
349 one is received. The dhcp-vendor-identifier can be used to request a
350 specific class of vendor options from the server. See dhcp-options(5)
351 for details.
352 medium "media setup";
354 The medium statement can be used on systems where network interfaces
356 cannot automatically determine the type of network to which they are
357 connected. The media setup string is a system-dependent parameter
358 which is passed to the dhcp client configuration script when initializ‐
359 ing the interface. On Unix and Unix-like systems, the argument is
360 passed on the ifconfig command line when configuring the interface.
361 The dhcp client automatically declares this parameter if it uses a
363 media type (see the media statement) when configuring the interface in
364 order to obtain a lease. This statement should be used in predefined
365 leases only if the network interface requires media type configuration.
366 renew date;
368 rebind date;
370 expire date;
372 The renew statement defines the time at which the dhcp client should
374 begin trying to contact its server to renew a lease that it is using.
375 The rebind statement defines the time at which the dhcp client should
376 begin to try to contact any dhcp server in order to renew its lease.
377 The expire statement defines the time at which the dhcp client must
378 stop using a lease if it has not been able to contact a server in order
379 to renew it.
380 These declarations are automatically set in leases acquired by the DHCP
382 client, but must also be configured in predefined leases - a predefined
383 lease whose expiry time has passed will not be used by the DHCP client.
384 Dates are specified in one of two ways. The software will output times
386 in these two formats depending on if the db-time-format configuration
387 parameter has been set to default or local.
388 If it is set to default, then date values appear as follows:
390 <weekday> <year>/<month>/<day> <hour>:<minute>:<second>
392 The weekday is present to make it easy for a human to tell when a lease
394 expires - it's specified as a number from zero to six, with zero being
395 Sunday. When declaring a predefined lease, it can always be specified
396 as zero. The year is specified with the century, so it should gener‐
397 ally be four digits except for really long leases. The month is speci‐
398 fied as a number starting with 1 for January. The day of the month is
399 likewise specified starting with 1. The hour is a number between 0 and
400 23, the minute a number between 0 and 59, and the second also a number
401 between 0 and 59.
402 If the db-time-format configuration was set to local, then the date
404 values appear as follows:
405 epoch <seconds-since-epoch>; # <day-name> <month-name> <day-number>
407 <hours>:<minutes>:<seconds> <year>
408 The seconds-since-epoch is as according to the system's local clock
410 (often referred to as "unix time"). The # symbol supplies a comment
411 that describes what actual time this is as according to the system's
412 configured timezone, at the time the value was written. It is provided
413 only for human inspection, the epoch time is the only recommended value
414 for machine inspection.
415 Note that when defining a static lease, one may use either time format
417 one wishes, and need not include the comment or values after it.
418 If the time is infinite in duration, then the date is never instead of
420 an actual date.
421
423 alias { declarations ... }
424 Some DHCP clients running TCP/IP roaming protocols may require that in
426 addition to the lease they may acquire via DHCP, their interface also
427 be configured with a predefined IP alias so that they can have a perma‐
428 nent IP address even while roaming. The Internet Systems Consortium
429 DHCP client doesn't support roaming with fixed addresses directly, but
430 in order to facilitate such experimentation, the dhcp client can be set
431 up to configure an IP alias using the alias declaration.
432 The alias declaration resembles a lease declaration, except that
434 options other than the subnet-mask option are ignored by the standard
435 client configuration script, and expiry times are ignored. A typical
436 alias declaration includes an interface declaration, a fixed-address
437 declaration for the IP alias address, and a subnet-mask option declara‐
438 tion. A medium statement should never be included in an alias decla‐
439 ration.
440
442 db-time-format [ default | local ] ;
443 The db-time-format option determines which of two output methods are
445 used for printing times in leases files. The default format provides
446 day-and-time in UTC, whereas local uses a seconds-since-epoch to store
447 the time value, and helpfully places a local timezone time in a comment
448 on the same line. The formats are described in detail in this manpage,
449 whithin the LEASE DECLARATIONS section.
450 reject cidr-ip-address [, ... cidr-ip-address ] ;
452 The reject statement causes the DHCP client to reject offers from
454 servers whose server identifier matches any of the specified hosts or
455 subnets. This can be used to avoid being configured by rogue or mis‐
456 configured dhcp servers, although it should be a last resort - better
457 to track down the bad DHCP server and fix it.
458 The cidr-ip-address configuration type is of the form ip-address[/pre‐
460 fixlen], where ip-address is a dotted quad IP address, and prefixlen is
461 the CIDR prefix length of the subnet, counting the number of signifi‐
462 cant bits in the netmask starting from the leftmost end. Example con‐
463 figuration syntax:
464 reject 192.168.0.0/16, 10.0.0.5;
466The above example would cause offers from any server identifier in the entire
468RFC 1918 "Class C" network 192.168.0.0/16, or the specific single address
46910.0.0.5, to be rejected.
470 interface "name" { declarations ... }
472A client with more than one network interface may require different behaviour
474depending on which interface is being configured. All timing parameters and
475declarations other than lease and alias declarations can be enclosed in an
476interface declaration, and those parameters will then be used only for the
477interface that matches the specified name. Interfaces for which there is no
478interface declaration will use the parameters declared outside of any inter‐
479face declaration, or the default settings.
480
482determined at startup from command line arguments, or otherwise is autode‐
483tected. If you supplied the list of interfaces on the command line, this con‐
484figuration clause will add the named interface to the list in such a way that
485will cause it to be configured by DHCP. Which may not be the result you had
486intended. This is an undesirable side effect that will be addressed in a
487future release.
488 pseudo "name" "real-name" { declarations ... }
490Under some circumstances it can be useful to declare a pseudo-interface and
492have the DHCP client acquire a configuration for that interface. Each inter‐
493face that the DHCP client is supporting normally has a DHCP client state
494machine running on it to acquire and maintain its lease. A pseudo-interface
495is just another state machine running on the interface named real-name, with
496its own lease and its own state. If you use this feature, you must provide a
497client identifier for both the pseudo-interface and the actual interface, and
498the two identifiers must be different. You must also provide a separate
499client script for the pseudo-interface to do what you want with the IP
500address. For example:
501 interface "ep0" {
503 send dhcp-client-identifier "my-client-ep0";
504 }
505 pseudo "secondary" "ep0" {
506 send dhcp-client-identifier "my-client-ep0-secondary";
507 script "/etc/dhclient-secondary";
508 }
509The client script for the pseudo-interface should not configure the interface
511up or down - essentially, all it needs to handle are the states where a lease
512has been acquired or renewed, and the states where a lease has expired. See
514 media "media setup" [ , "media setup", ... ];
516The media statement defines one or more media configuration parameters which
518may be tried while attempting to acquire an IP address. The dhcp client will
519cycle through each media setup string on the list, configuring the interface
520using that setup and attempting to boot, and then trying the next one. This
521can be used for network interfaces which aren't capable of sensing the media
522type unaided - whichever media type succeeds in getting a request to the
523server and hearing the reply is probably right (no guarantees).
524The media setup is only used for the initial phase of address acquisition (the
526DHCPDISCOVER and DHCPOFFER packets). Once an address has been acquired, the
527dhcp client will record it in its lease database and will record the media
528type used to acquire the address. Whenever the client tries to renew the
529lease, it will use that same media type. The lease must expire before the
530client will go back to cycling through media types.
531 bootp-broadcast-always;
533The bootp-broadcast-always statement instructs dhclient to always set the
535bootp broadcast flag in request packets, so that servers will always broadcast
536replies. This is equivalent to supplying the dhclient -B argument, and has
537the same effect as specifying 'always-broadcast' in the server's dhcpd.conf.
538This option is provided as an extension to enable dhclient to work on IBM s390
539Linux guests.
540
542 The following configuration file is used on a laptop running NetBSD
543 1.3. The laptop has an IP alias of 192.5.5.213, and has one inter‐
544 face, ep0 (a 3com 3C589C). Booting intervals have been shortened
545 somewhat from the default, because the client is known to spend most of
546 its time on networks with little DHCP activity. The laptop does roam
547 to multiple networks.
548 timeout 60;
551 retry 60;
552 reboot 10;
553 select-timeout 5;
554 initial-interval 2;
555 reject 192.33.137.209;
556 interface "ep0" {
558 send host-name "andare.fugue.com";
559 send dhcp-client-identifier 1:0:a0:24:ab:fb:9c;
560 send dhcp-lease-time 3600;
561 supersede domain-search "fugue.com", "rc.vix.com", "home.vix.com";
562 prepend domain-name-servers 127.0.0.1;
563 request subnet-mask, broadcast-address, time-offset, routers,
564 domain-search, domain-name, domain-name-servers, host-name;
565 require subnet-mask, domain-name-servers;
566 script "/sbin/dhclient-script";
567 media "media 10baseT/UTP", "media 10base2/BNC";
568 }
569 alias {
571 interface "ep0";
572 fixed-address 192.5.5.213;
573 option subnet-mask 255.255.255.255;
574 }
575 This is a very complicated dhclient.conf file - in general, yours
576 should be much simpler. In many cases, it's sufficient to just create
577 an empty dhclient.conf file - the defaults are usually fine.
578
580 dhcp-options(5), dhcp-eval(5), dhclient.leases(5), dhcpd(8),
581 dhcpd.conf(5), RFC2132, RFC2131.
582
584 dhclient(8) was written by Ted Lemon under a contract with Vixie Labs.
585 Funding for this project was provided by Internet Systems Consortium.
586 Information about Internet Systems Consortium can be found at
587 https://www.isc.org.
588 dhclient.conf(5)