3 .\" Copyright (c) 1996-2001 Internet Software Consortium.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. Neither the name of The Internet Software Consortium nor the names
14 .\" of its contributors may be used to endorse or promote products derived
15 .\" from this software without specific prior written permission.
17 .\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
18 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
19 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 .\" DISCLAIMED. IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
22 .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
25 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
26 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" This software has been written for the Internet Software Consortium
32 .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
33 .\" To learn more about the Internet Software Consortium, see
34 .\" ``http://www.isc.org/''. To learn more about Vixie Enterprises,
35 .\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see
36 .\" ``http://www.nominum.com''.
39 dhclient.conf - DHCP client configuration file
41 The dhclient.conf file contains configuration information for
43 the Internet Software Consortium DHCP Client.
45 The dhclient.conf file is a free-form ASCII text file. It is parsed by
46 the recursive-descent parser built into dhclient. The file may contain
47 extra tabs and newlines for formatting purposes. Keywords in the file
48 are case-insensitive. Comments may be placed anywhere within the
49 file (except within quotes). Comments begin with the # character and
50 end at the end of the line.
52 The dhclient.conf file can be used to configure the behaviour of the
53 client in a wide variety of ways: protocol timing, information
54 requested from the server, information required of the server,
55 defaults to use if the server does not provide certain information,
56 values with which to override information provided by the server, or
57 values to prepend or append to information provided by the server.
58 The configuration file can also be preinitialized with addresses to
59 use on networks that don't have DHCP servers.
61 The timing behaviour of the client need not be configured by the user.
62 If no timing configuration is provided by the user, a fairly
63 reasonable timing behaviour will be used by default - one which
64 results in fairly timely updates without placing an inordinate load on
67 The following statements can be used to adjust the timing behaviour of
68 the DHCP client if required, however:
80 statement determines the amount of time that must pass between the
81 time that the client begins to try to determine its address and the
82 time that it decides that it's not going to be able to contact a
83 server. By default, this timeout is sixty seconds. After the
84 timeout has passed, if there are any static leases defined in the
85 configuration file, or any leases remaining in the lease database that
86 have not yet expired, the client will loop through these leases
87 attempting to validate them, and if it finds one that appears to be
88 valid, it will use that lease's address. If there are no valid
89 static leases or unexpired leases in the lease database, the client
90 will restart the protocol after the defined retry interval.
96 \fBretry \fItime\fR\fB;\fR
100 statement determines the time that must pass after the client has
101 determined that there is no DHCP server present before it tries again
102 to contact a DHCP server. By default, this is five minutes.
108 \fBselect-timeout \fItime\fR\fB;\fR
110 It is possible (some might say desirable) for there to be more than
111 one DHCP server serving any given network. In this case, it is
112 possible that a client may be sent more than one offer in response to
113 its initial lease discovery message. It may be that one of these
114 offers is preferable to the other (e.g., one offer may have the
115 address the client previously used, and the other may not).
119 is the time after the client sends its first lease discovery request
120 at which it stops waiting for offers from servers, assuming that it
121 has received at least one such offer. If no offers have been
122 received by the time the
124 has expired, the client will accept the first offer that arrives.
126 By default, the select-timeout is zero seconds - that is, the client
127 will take the first offer it sees.
133 \fBreboot \fItime\fR\fB;\fR
135 When the client is restarted, it first tries to reacquire the last
136 address it had. This is called the INIT-REBOOT state. If it is
137 still attached to the same network it was attached to when it last
138 ran, this is the quickest way to get started. The
140 statement sets the time that must elapse after the client first tries
141 to reacquire its old address before it gives up and tries to discover
142 a new address. By default, the reboot timeout is ten seconds.
148 \fBbackoff-cutoff \fItime\fR\fB;\fR
150 The client uses an exponential backoff algorithm with some randomness,
151 so that if many clients try to configure themselves at the same time,
152 they will not make their requests in lockstep. The
154 statement determines the maximum amount of time that the client is
155 allowed to back off. It defaults to two minutes.
161 \fBinitial-interval \fItime\fR\fB;\fR
165 statement sets the amount of time between the first attempt to reach a
166 server and the second attempt to reach a server. Each time a message
167 is sent, the interval between messages is incremented by twice the
168 current interval multiplied by a random number between zero and one.
169 If it is greater than the backoff-cutoff amount, it is set to that
170 amount. It defaults to ten seconds.
171 .SH LEASE REQUIREMENTS AND REQUESTS
172 The DHCP protocol allows the client to request that the server send it
173 specific information, and not send it other information that it is not
174 prepared to accept. The protocol also allows the client to reject
175 offers from servers if they don't contain information the client
176 needs, or if the information provided is not satisfactory.
178 There is a variety of data contained in offers that DHCP servers send
179 to DHCP clients. The data that can be specifically requested is what
180 are called \fIDHCP Options\fR. DHCP Options are defined in
181 \fBdhcp-options(5)\fR.
187 \fBrequest [ \fIoption\fR ] [\fB,\fI ... \fIoption\fR ]\fB;\fR
189 The request statement causes the client to request that any server
190 responding to the client send the client its values for the specified
191 options. Only the option names should be specified in the request
192 statement - not option parameters. By default, the DHCP server
193 requests the subnet-mask, broadcast-address, time-offset, routers,
194 domain-name, domain-name-servers and host-name options.
196 In some cases, it may be desirable to send no parameter request list
197 at all. To do this, simply write the request statement but specify
208 \fBrequire [ \fIoption\fR ] [\fB,\fI ... \fIoption ]\fB;\fR
210 The require statement lists options that must be sent in order for an
211 offer to be accepted. Offers that do not contain all the listed
212 options will be ignored.
218 \fBsend { [ \fIoption declaration\fR ]
219 [\fB,\fI ... \fIoption declaration\fR ]\fB}\fR
221 The send statement causes the client to send the specified options to
222 the server with the specified values. These are full option
223 declarations as described in \fBdhcp-options(5)\fR. Options that are
224 always sent in the DHCP protocol should not be specified here, except
225 that the client can specify a \fBrequested-lease-time\fR option other
226 than the default requested lease time, which is two hours. The other
227 obvious use for this statement is to send information to the server
228 that will allow it to differentiate between this client and other
229 clients or kinds of clients.
231 The client now has some very limited support for doing DNS updates
232 when a lease is acquired. This is prototypical, and probably doesn't
233 do what you want. It also only works if you happen to have control
234 over your DNS server, which isn't very likely.
236 To make it work, you have to declare a key and zone as in the DHCP
237 server (see \fBdhcpd.conf\fR(5) for details). You also need to
238 configure the fqdn option on the client, as follows:
241 send fqdn.fqdn "grosse.fugue.com.";
242 send fqdn.encoded on;
243 send fqdn.server-update off;
246 The \fIfqdn.fqdn\fR option \fBMUST\fR be a fully-qualified domain
247 name. You \fBMUST\fR define a zone statement for the zone to be
248 updated. The \fIfqdn.encoded\fR option may need to be set to
249 \fIon\fR or \fIoff\fR, depending on the DHCP server you are using.
251 In some cases, a client may receive option data from the server which
252 is not really appropriate for that client, or may not receive
253 information that it needs, and for which a useful default value
254 exists. It may also receive information which is useful, but which
255 needs to be supplemented with local information. To handle these
256 needs, several option modifiers are available.
262 \fBdefault [ \fIoption declaration\fR ] \fB;\fR
264 If for some option the client should use the value supplied by
265 the server, but needs to use some default value if no value was supplied
266 by the server, these values can be defined in the
274 \fBsupersede [ \fIoption declaration\fR ] \fB;\fR
276 If for some option the client should always use a locally-configured
277 value or values rather than whatever is supplied by the server, these
278 values can be defined in the
286 \fBprepend [ \fIoption declaration\fR ] \fB;\fR
288 If for some set of options the client should use a value you
289 supply, and then use the values supplied by
290 the server, if any, these values can be defined in the
294 statement can only be used for options which
295 allow more than one value to be given. This restriction is not
296 enforced - if you ignore it, the behaviour will be unpredictable.
302 \fBappend [ \fIoption declaration\fR ] \fB;\fR
304 If for some set of options the client should first use the values
305 supplied by the server, if any, and then use values you supply, these
306 values can be defined in the
310 statement can only be used for options which
311 allow more than one value to be given. This restriction is not
312 enforced - if you ignore it, the behaviour will be unpredictable.
313 .SH LEASE DECLARATIONS
319 \fBlease {\fR \fIlease-declaration\fR [ ... \fIlease-declaration ] \fB}\fR
321 The DHCP client may decide after some period of time (see \fBPROTOCOL
322 TIMING\fR) decide that it is not going to succeed in contacting a
323 server. At that time, it consults its own database of old leases and
324 tests each one that has not yet timed out by pinging the listed router
325 for that lease to see if that lease could work. It is possible to
326 define one or more \fIfixed\fR leases in the client configuration file
327 for networks where there is no DHCP or BOOTP service, so that the
328 client can still automatically configure its address. This is done
333 NOTE: the lease statement is also used in the dhclient.leases file in
334 order to record leases that have been received from DHCP servers.
335 Some of the syntax for leases as described below is only needed in the
336 dhclient.leases file. Such syntax is documented here for
339 A lease statement consists of the lease keyword, followed by a left
340 curly brace, followed by one or more lease declaration statements,
341 followed by a right curly brace. The following lease declarations
348 statement is used to indicate that the lease was acquired using the
349 BOOTP protocol rather than the DHCP protocol. It is never necessary
350 to specify this in the client configuration file. The client uses
351 this syntax in its lease database file.
353 \fBinterface\fR \fB"\fR\fIstring\fR\fB";\fR
357 lease statement is used to indicate the interface on which the lease
358 is valid. If set, this lease will only be tried on a particular
359 interface. When the client receives a lease from a server, it always
360 records the interface number on which it received that lease.
361 If predefined leases are specified in the dhclient.conf file, the
362 interface should also be specified, although this is not required.
364 \fBfixed-address\fR \fIip-address\fR\fB;\fR
368 statement is used to set the ip address of a particular lease. This
369 is required for all lease statements. The IP address must be
370 specified as a dotted quad (e.g., 12.34.56.78).
372 \fBfilename "\fR\fIstring\fR\fB";\fR
376 statement specifies the name of the boot filename to use. This is
377 not used by the standard client configuration script, but is included
380 \fBserver-name "\fR\fIstring\fR\fB";\fR
384 statement specifies the name of the boot server name to use. This is
385 also not used by the standard client configuration script.
387 \fBoption\fR \fIoption-declaration\fR\fB;\fR
391 statement is used to specify the value of an option supplied by the
392 server, or, in the case of predefined leases declared in
393 dhclient.conf, the value that the user wishes the client configuration
394 script to use if the predefined lease is used.
396 \fBscript "\fIscript-name\fB";\fR
400 statement is used to specify the pathname of the dhcp client
401 configuration script. This script is used by the dhcp client to set
402 each interface's initial configuration prior to requesting an address,
403 to test the address once it has been offered, and to set the
404 interface's final configuration once a lease has been acquired. If
405 no lease is acquired, the script is used to test predefined leases, if
406 any, and also called once if no valid lease can be identified. For
407 more information, see
408 .B dhclient-script(8).
410 \fBvendor option space "\fIname\fB";\fR
413 .B vendor option space
414 statement is used to specify which option space should be used for
415 decoding the vendor-encapsulate-options option if one is received.
416 The \fIdhcp-vendor-identifier\fR can be used to request a specific
417 class of vendor options from the server. See
421 \fBmedium "\fImedia setup\fB";\fR
425 statement can be used on systems where network interfaces cannot
426 automatically determine the type of network to which they are
427 connected. The media setup string is a system-dependent parameter
428 which is passed to the dhcp client configuration script when
429 initializing the interface. On Unix and Unix-like systems, the
430 argument is passed on the ifconfig command line when configuring te
433 The dhcp client automatically declares this parameter if it used a
436 statement) when configuring the interface in order to obtain a lease.
437 This statement should be used in predefined leases only if the network
438 interface requires media type configuration.
440 \fBrenew\fR \fIdate\fB;\fR
442 \fBrebind\fR \fIdate\fB;\fR
444 \fBexpire\fR \fIdate\fB;\fR
446 The \fBrenew\fR statement defines the time at which the dhcp client
447 should begin trying to contact its server to renew a lease that it is
448 using. The \fBrebind\fR statement defines the time at which the dhcp
449 client should begin to try to contact \fIany\fR dhcp server in order
450 to renew its lease. The \fBexpire\fR statement defines the time at
451 which the dhcp client must stop using a lease if it has not been able
452 to contact a server in order to renew it.
454 These declarations are automatically set in leases acquired by the
455 DHCP client, but must also be configured in predefined leases - a
456 predefined lease whose expiry time has passed will not be used by the
459 Dates are specified as follows:
461 \fI<weekday> <year>\fB/\fI<month>\fB/\fI<day>
462 <hour>\fB:\fI<minute>\fB:\fI<second>\fR
464 The weekday is present to make it easy for a human to tell when a
465 lease expires - it's specified as a number from zero to six, with zero
466 being Sunday. When declaring a predefined lease, it can always be
467 specified as zero. The year is specified with the century, so it
468 should generally be four digits except for really long leases. The
469 month is specified as a number starting with 1 for January. The day
470 of the month is likewise specified starting with 1. The hour is a
471 number between 0 and 23, the minute a number between 0 and 59, and the
472 second also a number between 0 and 59.
473 .SH ALIAS DECLARATIONS
474 \fBalias { \fI declarations ... \fB}\fR
476 Some DHCP clients running TCP/IP roaming protocols may require that in
477 addition to the lease they may acquire via DHCP, their interface also
478 be configured with a predefined IP alias so that they can have a
479 permanent IP address even while roaming. The Internet Software
480 Consortium DHCP client doesn't support roaming with fixed addresses
481 directly, but in order to facilitate such experimentation, the dhcp
482 client can be set up to configure an IP alias using the
486 The alias declaration resembles a lease declaration, except that
487 options other than the subnet-mask option are ignored by the standard
488 client configuration script, and expiry times are ignored. A typical
489 alias declaration includes an interface declaration, a fixed-address
490 declaration for the IP alias address, and a subnet-mask option
491 declaration. A medium statement should never be included in an alias
493 .SH OTHER DECLARATIONS
494 \fBreject \fIip-address\fB;\fR
496 The reject statement causes the DHCP client to reject offers from
497 servers who use the specified address as a server identifier. This
498 can be used to avoid being configured by rogue or misconfigured dhcp
499 servers, although it should be a last resort - better to track down
500 the bad DHCP server and fix it.
502 \fBinterface "\fIname\fB" { \fIdeclarations ... \fB }
504 A client with more than one network interface may require different
505 behaviour depending on which interface is being configured. All
506 timing parameters and declarations other than lease and alias
507 declarations can be enclosed in an interface declaration, and those
508 parameters will then be used only for the interface that matches the
509 specified name. Interfaces for which there is no interface
510 declaration will use the parameters declared outside of any interface
511 declaration, or the default settings.
513 \fBpseudo "\fIname\fR" "\fIreal-name\fB" { \fIdeclarations ... \fB }
515 Under some circumstances it can be useful to declare a pseudo-interface
516 and have the DHCP client acquire a configuration for that interface.
517 Each interface that the DHCP client is supporting normally has a DHCP
518 client state machine running on it to acquire and maintain its lease.
519 A pseudo-interface is just another state machine running on the
520 interface named \fIreal-name\fR, with its own lease and its own
521 state. If you use this feature, you must provide a client identifier
522 for both the pseudo-interface and the actual interface, and the two
523 identifiers must be different. You must also provide a seperate
524 client script for the pseudo-interface to do what you want with the IP
525 address. For example:
529 send dhcp-client-identifier "my-client-ep0";
531 pseudo "secondary" "ep0" {
532 send dhcp-client-identifier "my-client-ep0-secondary";
533 script "/etc/dhclient-secondary";
537 The client script for the pseudo-interface should not configure the
538 interface up or down - essentially, all it needs to handle are the
539 states where a lease has been acquired or renewed, and the states
540 where a lease has expired. See \fBdhclient-script(8)\fR for more
543 \fBmedia "\fImedia setup\fB"\fI [ \fB, "\fImedia setup\fB", \fI... ]\fB;\fR
547 statement defines one or more media configuration parameters which may
548 be tried while attempting to acquire an IP address. The dhcp client
549 will cycle through each media setup string on the list, configuring
550 the interface using that setup and attempting to boot, and then trying
551 the next one. This can be used for network interfaces which aren't
552 capable of sensing the media type unaided - whichever media type
553 succeeds in getting a request to the server and hearing the reply is
554 probably right (no guarantees).
556 The media setup is only used for the initial phase of address
557 acquisition (the DHCPDISCOVER and DHCPOFFER packtes). Once an
558 address has been acquired, the dhcp client will record it in its lease
559 database and will record the media type used to acquire the address.
560 Whenever the client tries to renew the lease, it will use that same
561 media type. The lease must expire before the client will go back to
562 cycling through media types.
564 The following configuration file is used on a laptop running NetBSD
565 1.3. The laptop has an IP alias of 192.5.5.213, and has one
566 interface, ep0 (a 3com 3C589C). Booting intervals have been
567 shortened somewhat from the default, because the client is known to
568 spend most of its time on networks with little DHCP activity. The
569 laptop does roam to multiple networks.
578 reject 192.33.137.209;
581 send host-name "andare.fugue.com";
582 send dhcp-client-identifier 1:0:a0:24:ab:fb:9c;
583 send dhcp-lease-time 3600;
584 supersede domain-name "fugue.com rc.vix.com home.vix.com";
585 prepend domain-name-servers 127.0.0.1;
586 request subnet-mask, broadcast-address, time-offset, routers,
587 domain-name, domain-name-servers, host-name;
588 require subnet-mask, domain-name-servers;
589 script "/etc/dhclient-script";
590 media "media 10baseT/UTP", "media 10base2/BNC";
595 fixed-address 192.5.5.213;
596 option subnet-mask 255.255.255.255;
599 This is a very complicated dhclient.conf file - in general, yours
600 should be much simpler. In many cases, it's sufficient to just
601 create an empty dhclient.conf file - the defaults are usually fine.
603 dhcp-options(5), dhclient.leases(5), dhcpd(8), dhcpd.conf(5), RFC2132,
607 was written by Ted Lemon
608 under a contract with Vixie Labs. Funding
609 for this project was provided by the Internet Software Consortium.
610 Information about the Internet Software Consortium can be found at
611 .B http://www.isc.org.