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 by
13 the recursive-descent parser built into dhclient. The file may contain
14 extra tabs and newlines for formatting purposes. Keywords in the file
15 are case-insensitive. Comments may be placed anywhere within the file
16 (except within quotes). Comments begin with the # character and end at
17 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 If required the following statements can be used to adjust the timing
35 behaviour of the DHCPv4 client. The DHCPv6 protocol provides values to
36 use and they are not currently configurable.
37 The timeout statement
39 timeout time;
41 The timeout statement determines the amount of time that must pass
43 between the time that the client begins to try to determine its address
44 and the time that it decides that it's not going to be able to contact
45 a server. By default, this timeout is sixty seconds. After the time‐
46 out has passed, if there are any static leases defined in the configu‐
47 ration file, or any leases remaining in the lease database that have
48 not yet expired, the client will loop through these leases attempting
49 to validate them, and if it finds one that appears to be valid, it will
50 use that lease's address. If there are no valid static leases or unex‐
51 pired leases in the lease database, the client will restart the proto‐
52 col after the defined retry interval.
53 The retry statement
55 retry time;
57 The retry statement determines the time that must pass after the client
59 has determined that there is no DHCP server present before it tries
60 again to contact a DHCP server. By default, this is five minutes.
61 The select-timeout statement
63 select-timeout time;
65 It is possible (some might say desirable) for there to be more than one
67 DHCP server serving any given network. In this case, it is possible
68 that a client may be sent more than one offer in response to its ini‐
69 tial lease discovery message. It may be that one of these offers is
70 preferable to the other (e.g., one offer may have the address the
71 client previously used, and the other may not).
72 The select-timeout is the time after the client sends its first lease
74 discovery request at which it stops waiting for offers from servers,
75 assuming that it has received at least one such offer. If no offers
76 have been received by the time the select-timeout has expired, the
77 client will accept the first offer that arrives.
78 By default, the select-timeout is zero seconds - that is, the client
80 will take the first offer it sees.
81 The reboot statement
83 reboot time;
85 When the client is restarted, it first tries to reacquire the last
87 address it had. This is called the INIT-REBOOT state. If it is still
88 attached to the same network it was attached to when it last ran, this
89 is the quickest way to get started. The reboot statement sets the time
90 that must elapse after the client first tries to reacquire its old
91 address before it gives up and tries to discover a new address. By
92 default, the reboot timeout is ten seconds.
93 The backoff-cutoff statement
95 backoff-cutoff time;
97 The client uses an exponential backoff algorithm with some randomness,
99 so that if many clients try to configure themselves at the same time,
100 they will not make their requests in lockstep. The backoff-cutoff
101 statement determines the maximum amount of time that the client is
102 allowed to back off, the actual value will be evaluated randomly
103 between 1/2 to 1 1/2 times the time specified. It defaults to fifteen
104 seconds.
105 The initial-interval statement
107 initial-interval time;
109 The initial-interval statement sets the amount of time between the
111 first attempt to reach a server and the second attempt to reach a
112 server. Each time a message is sent, the interval between messages is
113 incremented by twice the current interval multiplied by a random number
114 between zero and one. If it is greater than the backoff-cutoff amount,
115 it is set to that amount. It defaults to ten seconds.
116 The initial-delay statement
118 initial-delay time;
120 initial-delay parameter sets the maximum time client can wait after
122 start before commencing first transmission. According to RFC2131 Sec‐
123 tion 4.4.1, client should wait a random time between startup and the
124 actual first transmission. Previous versions of ISC DHCP client used to
125 wait random time up to 5 seconds, but that was unwanted due to impact
126 on startup time. As such, new versions have the default initial delay
127 set to 0. To restore old behavior, please set initial-delay to 5.
128
130 In the DHCPv6 protocol the client will wait a small amount of time to
131 allow ADVERTISE messages from multiple servers to arrive. It will then
132 need to choose from all of the messages that may have arrived before
133 proceeding to making a request of the selected server.
134 The first selection criteria is the set of options and addresses in the
136 message. Messages that don't include an option specified as required
137 will be given a score of 0 and not used. If the -R option is given on
138 the command line then messages that don't include the correct number of
139 bindings (IA-NA, IA-TA or IA-PD) will be discarded.
140 The next criteria is the preference value from the message. With the
142 highest preference value being used even if leases with better
143 addresses or options are available.
144 Finally the lease is scored and the lease with the highest score is
146 selected. A lease's score is based on the number of bindings, number
147 of addresses and number of options it contains:
148 bindings * X + addresses * Y + options
149 By default X = 10000 and Y = 100, this will cause the client to select
150 a lease with more bindings over a lease with less bindings but more
151 addresses. The weightings were changed as part of implementing RFC
152 7550. Previously they were X = 50 and Y = 100 meaning more addresses
153 were preferred over more bindings. If you wish to continue using the
154 old style you may do so by editing the file includes/site.h and uncom‐
155 menting the define for USE_ORIGINAL_CLIENT_LEASE_WEIGHTS.
156
158 The DHCP protocol allows the client to request that the server send it
159 specific information, and not send it other information that it is not
160 prepared to accept. The protocol also allows the client to reject
161 offers from servers if they don't contain information the client needs,
162 or if the information provided is not satisfactory.
163 There is a variety of data contained in offers that DHCP servers send
165 to DHCP clients. The data that can be specifically requested is what
166 are called DHCP Options. DHCP Options are defined in
167 dhcp-options(5).
168 The request statement
170 [ also ] request [ [ option-space . ] option ] [, ... ];
172 The request statement causes the client to request that any server
174 responding to the client send the client its values for the specified
175 options. Only the option names should be specified in the request
176 statement - not option parameters. By default, the DHCPv4 client
177 requests the subnet-mask, broadcast-address, time-offset, routers,
178 domain-search, domain-name, domain-name-servers, host-name, nis-domain,
179 nis-servers, ntp-servers and interface-mtu options while the DHCPv6
180 client requests the dhcp6 name-servers and domain-search options. Note
181 that if you enter a ´request´ statement, you over-ride these defaults
182 and these options will not be requested.
183 In some cases, it may be desirable to send no parameter request list at
185 all. To do this, simply write the request statement but specify no
186 parameters:
187 request;
189 In most cases, it is desirable to simply add one option to the request
191 list which is of interest to the client in question. In this case, it
192 is best to ´also request´ the additional options:
193 also request domain-search, dhcp6.sip-servers-addresses;
195 The require statement
197 [ also ] require [ [ option-space . ] option ] [, ... ];
199 The require statement lists options that must be sent in order for an
201 offer to be accepted. Offers that do not contain all the listed
202 options will be ignored. There is no default require list.
203 require name-servers;
205 interface eth0 {
207 also require domain-search;
208 }
209 The send statement
211 send [ option declaration ] ;
213 The send statement causes the client to send the specified option to
215 the server with the specified value. This is a full option declaration
216 as described in dhcp-options(5). Options that are always sent in the
217 DHCP protocol should not be specified here, except that the client can
218 specify a requested dhcp-lease-time option other than the default
219 requested lease time, which is two hours. The other obvious use for
220 this statement is to send information to the server that will allow it
221 to differentiate between this client and other clients or kinds of
222 clients.
223
225 The client now has some very limited support for doing DNS updates when
226 a lease is acquired. This is prototypical, and probably doesn't do
227 what you want. It also only works if you happen to have control over
228 your DNS server, which isn't very likely.
229 Note that everything in this section is true whether you are using
231 DHCPv4 or DHCPv6. The exact same syntax is used for both.
232 To make it work, you have to declare a key and zone as in the DHCP
234 server (see dhcpd.conf(5) for details). You also need to configure the
235 fqdn option on the client, as follows:
236 send fqdn.fqdn "grosse.example.com.";
238 send fqdn.encoded on;
239 send fqdn.server-update off;
240 also request fqdn, dhcp6.fqdn;
241 The fqdn.fqdn option MUST be a fully-qualified domain name. You MUST
243 define a zone statement for the zone to be updated. The fqdn.encoded
244 option may need to be set to on or off, depending on the DHCP server
245 you are using.
246 The do-forward-updates statement
248 do-forward-updates [ flag ] ;
250 If you want to do DNS updates in the DHCP client script (see dhclient-
252 script(8)) rather than having the DHCP client do the update directly
253 (for example, if you want to use SIG(0) authentication, which is not
254 supported directly by the DHCP client, you can instruct the client not
255 to do the update using the do-forward-updates statement. Flag should
256 be true if you want the DHCP client to do the update, and false if you
257 don't want the DHCP client to do the update. By default, the DHCP
258 client will do the DNS update.
259
261 In some cases, a client may receive option data from the server which
262 is not really appropriate for that client, or may not receive informa‐
263 tion that it needs, and for which a useful default value exists. It
264 may also receive information which is useful, but which needs to be
265 supplemented with local information. To handle these needs, several
266 option modifiers are available.
267 The default statement
269 default [ option declaration ] ;
271 If for some option the client should use the value supplied by the
273 server, but needs to use some default value if no value was supplied by
274 the server, these values can be defined in the default statement.
275 The supersede statement
277 supersede [ option declaration ] ;
279 If for some option the client should always use a locally-configured
281 value or values rather than whatever is supplied by the server, these
282 values can be defined in the supersede statement.
283 The prepend statement
285 prepend [ option declaration ] ;
287 If for some set of options the client should use a value you supply,
289 and then use the values supplied by the server, if any, these values
290 can be defined in the prepend statement. The prepend statement can
291 only be used for options which allow more than one value to be given.
292 This restriction is not enforced - if you ignore it, the behaviour will
293 be unpredictable.
294 The append statement
296 append [ option declaration ] ;
298 If for some set of options the client should first use the values sup‐
300 plied by the server, if any, and then use values you supply, these val‐
301 ues can be defined in the append statement. The append statement can
302 only be used for options which allow more than one value to be given.
303 This restriction is not enforced - if you ignore it, the behaviour will
304 be unpredictable.
305
307 The lease declaration
308 lease { lease-declaration [ ... lease-declaration ] }
310 The DHCP client may decide after some period of time (see PROTOCOL TIM‐
312 ING) that it is not going to succeed in contacting a server. At that
313 time, it consults its own database of old leases and tests each one
314 that has not yet timed out by pinging the listed router for that lease
315 to see if that lease could work. It is possible to define one or more
316 fixed leases in the client configuration file for networks where there
317 is no DHCP or BOOTP service, so that the client can still automatically
318 configure its address. This is done with the lease statement.
319 NOTE: the lease statement is also used in the dhclient.leases file in
321 order to record leases that have been received from DHCP servers. Some
322 of the syntax for leases as described below is only needed in the
323 dhclient.leases file. Such syntax is documented here for completeness.
324 A lease statement consists of the lease keyword, followed by a left
326 curly brace, followed by one or more lease declaration statements, fol‐
327 lowed by a right curly brace. The following lease declarations are
328 possible:
329 bootp;
331 The bootp statement is used to indicate that the lease was acquired
333 using the BOOTP protocol rather than the DHCP protocol. It is never
334 necessary to specify this in the client configuration file. The client
335 uses this syntax in its lease database file.
336 interface "string";
338 The interface lease statement is used to indicate the interface on
340 which the lease is valid. If set, this lease will only be tried on a
341 particular interface. When the client receives a lease from a server,
342 it always records the interface number on which it received that lease.
343 If predefined leases are specified in the dhclient.conf file, the
344 interface should also be specified, although this is not required.
345 fixed-address ip-address;
347 The fixed-address statement is used to set the ip address of a particu‐
349 lar lease. This is required for all lease statements. The IP address
350 must be specified as a dotted quad (e.g., 12.34.56.78).
351 filename "string";
353 The filename statement specifies the name of the boot filename to use.
355 This is not used by the standard client configuration script, but is
356 included for completeness.
357 server-name "string";
359 The server-name statement specifies the name of the boot server name to
361 use. This is also not used by the standard client configuration
362 script.
363 option option-declaration;
365 The option statement is used to specify the value of an option supplied
367 by the server, or, in the case of predefined leases declared in
368 dhclient.conf, the value that the user wishes the client configuration
369 script to use if the predefined lease is used.
370 script "script-name";
372 The script statement is used to specify the pathname of the dhcp client
374 configuration script. This script is used by the dhcp client to set
375 each interface's initial configuration prior to requesting an address,
376 to test the address once it has been offered, and to set the inter‐
377 face's final configuration once a lease has been acquired. If no lease
378 is acquired, the script is used to test predefined leases, if any, and
379 also called once if no valid lease can be identified. For more infor‐
380 mation, see dhclient-script(8).
381 vendor option space "name";
383 The vendor option space statement is used to specify which option space
385 should be used for decoding the vendor-encapsulate-options option if
386 one is received. The dhcp-vendor-identifier can be used to request a
387 specific class of vendor options from the server. See dhcp-options(5)
388 for details.
389 medium "media setup";
391 The medium statement can be used on systems where network interfaces
393 cannot automatically determine the type of network to which they are
394 connected. The media setup string is a system-dependent parameter
395 which is passed to the dhcp client configuration script when initializ‐
396 ing the interface. On Unix and Unix-like systems, the argument is
397 passed on the ifconfig command line when configuring the interface.
398 The dhcp client automatically declares this parameter if it uses a
400 media type (see the media statement) when configuring the interface in
401 order to obtain a lease. This statement should be used in predefined
402 leases only if the network interface requires media type configuration.
403 renew date;
405 rebind date;
407 expire date;
409 The renew statement defines the time at which the dhcp client should
411 begin trying to contact its server to renew a lease that it is using.
412 The rebind statement defines the time at which the dhcp client should
413 begin to try to contact any dhcp server in order to renew its lease.
414 The expire statement defines the time at which the dhcp client must
415 stop using a lease if it has not been able to contact a server in order
416 to renew it.
417 These declarations are automatically set in leases acquired by the DHCP
419 client, but must also be configured in predefined leases - a predefined
420 lease whose expiry time has passed will not be used by the DHCP client.
421 Dates are specified in one of two ways. The software will output times
423 in these two formats depending on if the db-time-format configuration
424 parameter has been set to default or local.
425 If it is set to default, then date values appear as follows:
427 <weekday> <year>/<month>/<day> <hour>:<minute>:<second>
429 The weekday is present to make it easy for a human to tell when a lease
431 expires - it's specified as a number from zero to six, with zero being
432 Sunday. When declaring a predefined lease, it can always be specified
433 as zero. The year is specified with the century, so it should gener‐
434 ally be four digits except for really long leases. The month is speci‐
435 fied as a number starting with 1 for January. The day of the month is
436 likewise specified starting with 1. The hour is a number between 0 and
437 23, the minute a number between 0 and 59, and the second also a number
438 between 0 and 59.
439 If the db-time-format configuration was set to local, then the date
441 values appear as follows:
442 epoch <seconds-since-epoch>; # <day-name> <month-name> <day-number>
444 <hours>:<minutes>:<seconds> <year>
445 The seconds-since-epoch is as according to the system's local clock
447 (often referred to as "unix time"). The # symbol supplies a comment
448 that describes what actual time this is as according to the system's
449 configured timezone, at the time the value was written. It is provided
450 only for human inspection, the epoch time is the only recommended value
451 for machine inspection.
452 Note that when defining a static lease, one may use either time format
454 one wishes, and need not include the comment or values after it.
455 If the time is infinite in duration, then the date is never instead of
457 an actual date.
458
460 alias { declarations ... }
461 Some DHCP clients running TCP/IP roaming protocols may require that in
463 addition to the lease they may acquire via DHCP, their interface also
464 be configured with a predefined IP alias so that they can have a perma‐
465 nent IP address even while roaming. The Internet Systems Consortium
466 DHCP client doesn't support roaming with fixed addresses directly, but
467 in order to facilitate such experimentation, the dhcp client can be set
468 up to configure an IP alias using the alias declaration.
469 The alias declaration resembles a lease declaration, except that
471 options other than the subnet-mask option are ignored by the standard
472 client configuration script, and expiry times are ignored. A typical
473 alias declaration includes an interface declaration, a fixed-address
474 declaration for the IP alias address, and a subnet-mask option declara‐
475 tion. A medium statement should never be included in an alias declara‐
476 tion.
477
479 db-time-format [ default | local ] ;
480 The db-time-format option determines which of two output methods are
482 used for printing times in leases files. The default format provides
483 day-and-time in UTC, whereas local uses a seconds-since-epoch to store
484 the time value, and helpfully places a local timezone time in a comment
485 on the same line. The formats are described in detail in this manpage,
486 within the LEASE DECLARATIONS section.
487 The lease-id-format parameter
489 lease-id-format format;
491 The format parameter must be either octal or hex. This parameter
493 governs the format used to write certain values to lease files. With
494 the default format, octal, values are written as quoted strings in
495 which non-printable characters are represented as octal escapes - a
496 backslash character followed by three octal digits. When the hex
497 format is specified, values are written as an unquoted series of
498 hexadecimal digit pairs, separated by colons.
499 Currently, the values written out based on lease-id-format are the
501 default-duid and the IAID value (DHCPv6 only). The client automati‐
502 cally reads the values in either format. Note that when the format
503 is octal, rather than as an octal string, IAID is output as hex if it
504 contains no printable characters or as a string if contains only
505 printable characters. This is done to maintain backward compatibil‐
506 ity.
507 reject cidr-ip-address [, ... cidr-ip-address ] ;
509 The reject statement causes the DHCP client to reject offers from
511 servers whose server identifier matches any of the specified hosts or
512 subnets. This can be used to avoid being configured by rogue or mis‐
513 configured dhcp servers, although it should be a last resort - better
514 to track down the bad DHCP server and fix it.
515 The cidr-ip-address configuration type is of the form ip-
517 address[/prefixlen], where ip-address is a dotted quad IP address,
518 and prefixlen is the CIDR prefix length of the subnet, counting the
519 number of significant bits in the netmask starting from the leftmost
520 end. Example configuration syntax:
521 reject 192.168.0.0/16, 10.0.0.5;
523 The above example would cause offers from any server identifier in
525 the entire RFC 1918 "Class C" network 192.168.0.0/16, or the specific
526 single address 10.0.0.5, to be rejected.
527 interface "name" { declarations ... }
529 A client with more than one network interface may require different
531 behaviour depending on which interface is being configured. All tim‐
532 ing parameters and declarations other than lease and alias declara‐
533 tions can be enclosed in an interface declaration, and those parame‐
534 ters will then be used only for the interface that matches the speci‐
535 fied name. Interfaces for which there is no interface declaration
536 will use the parameters declared outside of any interface declara‐
537 tion, or the default settings.
538 Note well: ISC dhclient only maintains one list of interfaces, which
540 is either determined at startup from command line arguments, or oth‐
541 erwise is autodetected. If you supplied the list of interfaces on
542 the command line, this configuration clause will add the named inter‐
543 face to the list in such a way that will cause it to be configured by
544 DHCP. Which may not be the result you had intended. This is an
545 undesirable side effect that will be addressed in a future release.
546 pseudo "name" "real-name" { declarations ... }
548 Under some circumstances it can be useful to declare a pseudo-inter‐
550 face and have the DHCP client acquire a configuration for that inter‐
551 face. Each interface that the DHCP client is supporting normally has
552 a DHCP client state machine running on it to acquire and maintain its
553 lease. A pseudo-interface is just another state machine running on
554 the interface named real-name, with its own lease and its own state.
555 If you use this feature, you must provide a client identifier for
556 both the pseudo-interface and the actual interface, and the two iden‐
557 tifiers must be different. You must also provide a separate client
558 script for the pseudo-interface to do what you want with the IP
559 address. For example:
560 interface "ep0" {
562 send dhcp-client-identifier "my-client-ep0";
563 }
564 pseudo "secondary" "ep0" {
565 send dhcp-client-identifier "my-client-ep0-secondary";
566 script "/etc/dhclient-secondary";
567 }
568 The client script for the pseudo-interface should not configure the
570 interface up or down - essentially, all it needs to handle are the
571 states where a lease has been acquired or renewed, and the states
572 where a lease has expired. See dhclient-script(8) for more informa‐
573 tion.
574 media "media setup" [ , "media setup", ... ];
576 The media statement defines one or more media configuration parame‐
578 ters which may be tried while attempting to acquire an IP address.
579 The dhcp client will cycle through each media setup string on the
580 list, configuring the interface using that setup and attempting to
581 boot, and then trying the next one. This can be used for network
582 interfaces which aren't capable of sensing the media type unaided -
583 whichever media type succeeds in getting a request to the server and
584 hearing the reply is probably right (no guarantees).
585 The media setup is only used for the initial phase of address acqui‐
587 sition (the DHCPDISCOVER and DHCPOFFER packets). Once an address has
588 been acquired, the dhcp client will record it in its lease database
589 and will record the media type used to acquire the address. Whenever
590 the client tries to renew the lease, it will use that same media
591 type. The lease must expire before the client will go back to
592 cycling through media types.
593 hardware link-type mac-address;
595 The hardware statement defines the hardware MAC address to use for
597 this interface, for DHCP servers or relays to direct their replies.
598 dhclient will determine the interface's MAC address automatically, so
599 use of this parameter is not recommended. The link-type corresponds
600 to the interface's link layer type (example: ´ethernet´), while the
601 mac-address is a string of colon-separated hexadecimal values for
602 octets.
603 anycast-mac link-type mac-address;
605 The anycast-mac statement over-rides the all-ones broadcast MAC
607 address dhclient will use when it is transmitting packets to the all-
608 ones limited broadcast IPv4 address. This configuration parameter is
609 useful to reduce the number of broadcast packets transmitted by DHCP
610 clients, but is only useful if you know the DHCP service(s) anycast
611 MAC address prior to configuring your client. The link-type and mac-
612 address parameters are configured in a similar manner to the hardware
613 statement.
614 bootp-broadcast-always;
616 The bootp-broadcast-always statement instructs dhclient to always set
618 the bootp broadcast flag in request packets, so that servers will
619 always broadcast replies. This is equivalent to supplying the
620 dhclient -B argument, and has the same effect as specifying 'always-
621 broadcast' in the server's dhcpd.conf. This option is provided as an
622 extension to enable dhclient to work on IBM s390 Linux guests.
623
625 The following configuration file was used on a laptop running NetBSD
626 1.3, though the domains have been modified. The laptop has an IP alias
627 of 192.5.5.213, and has one interface, ep0 (a 3com 3C589C). Booting
628 intervals have been shortened somewhat from the default, because the
629 client is known to spend most of its time on networks with little DHCP
630 activity. The laptop does roam to multiple networks.
631 timeout 60;
634 retry 60;
635 reboot 10;
636 select-timeout 5;
637 initial-interval 2;
638 reject 192.33.137.209;
639 interface "ep0" {
641 send host-name "andare.example.com";
642 hardware ethernet 00:a0:24:ab:fb:9c;
643 send dhcp-client-identifier 1:0:a0:24:ab:fb:9c;
644 send dhcp-lease-time 3600;
645 supersede domain-search "example.com", "rc.isc.org", "home.isc.org";
646 prepend domain-name-servers 127.0.0.1;
647 request subnet-mask, broadcast-address, time-offset, routers,
648 domain-name, domain-name-servers, host-name;
649 require subnet-mask, domain-name-servers;
650 script "/usr/sbin/dhclient-script";
651 media "media 10baseT/UTP", "media 10base2/BNC";
652 }
653 alias {
655 interface "ep0";
656 fixed-address 192.5.5.213;
657 option subnet-mask 255.255.255.255;
658 }
659 This is a very complicated dhclient.conf file - in general, yours
660 should be much simpler. In many cases, it's sufficient to just create
661 an empty dhclient.conf file - the defaults are usually fine.
662
664 dhcp-options(5), dhcp-eval(5), dhclient.leases(5), dhcpd(8),
665 dhcpd.conf(5), RFC2132, RFC2131.
666
668 dhclient(8) Information about Internet Systems Consortium can be found
669 at https://www.isc.org.
670 dhclient.conf(5)