Add regression test infrastructure.
[dragonfly.git] / contrib / dhcp-3.0 / client / dhclient.conf.5
1 .\"     $Id: dhclient.conf.5,v 2004/09/10 21:02:30 dhankins Exp $
2 .\"
3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (c) 1996-2003 by Internet Software Consortium
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
17 .\"
18 .\"   Internet Systems Consortium, Inc.
19 .\"   950 Charter Street
20 .\"   Redwood City, CA 94063
21 .\"   <>
22 .\"
23 .\"
24 .\" This software has been written for Internet Software Consortium
25 .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
26 .\" To learn more about Internet Software Consortium, see
27 .\" ``''.  To learn more about Vixie Enterprises,
28 .\" see ``''.   To learn more about Nominum, Inc., see
29 .\" ``''.
30 .TH dhclient.conf 5
32 dhclient.conf - DHCP client configuration file
34 The dhclient.conf file contains configuration information for
35 .IR dhclient,
36 the Internet Systems Consortium DHCP Client.
37 .PP
38 The dhclient.conf file is a free-form ASCII text file.   It is parsed by
39 the recursive-descent parser built into dhclient.   The file may contain
40 extra tabs and newlines for formatting purposes.  Keywords in the file
41 are case-insensitive.   Comments may be placed anywhere within the
42 file (except within quotes).   Comments begin with the # character and
43 end at the end of the line.
44 .PP
45 The dhclient.conf file can be used to configure the behaviour of the
46 client in a wide variety of ways: protocol timing, information
47 requested from the server, information required of the server,
48 defaults to use if the server does not provide certain information,
49 values with which to override information provided by the server, or
50 values to prepend or append to information provided by the server.
51 The configuration file can also be preinitialized with addresses to
52 use on networks that don't have DHCP servers.
54 The timing behaviour of the client need not be configured by the user.
55 If no timing configuration is provided by the user, a fairly
56 reasonable timing behaviour will be used by default - one which
57 results in fairly timely updates without placing an inordinate load on
58 the server.
59 .PP
60 The following statements can be used to adjust the timing behaviour of
61 the DHCP client if required, however:
62 .PP
63 .I The
64 .B timeout
65 .I statement
66 .PP
67 .B timeout
68 .I time
69 .B ;
70 .PP
71 The
72 .I timeout
73 statement determines the amount of time that must pass between the
74 time that the client begins to try to determine its address and the
75 time that it decides that it's not going to be able to contact a
76 server.   By default, this timeout is sixty seconds.   After the
77 timeout has passed, if there are any static leases defined in the
78 configuration file, or any leases remaining in the lease database that
79 have not yet expired, the client will loop through these leases
80 attempting to validate them, and if it finds one that appears to be
81 valid, it will use that lease's address.   If there are no valid
82 static leases or unexpired leases in the lease database, the client
83 will restart the protocol after the defined retry interval.
84 .PP
85 .I The
86 .B retry
87 .I statement
88 .PP
89  \fBretry \fItime\fR\fB;\fR
90 .PP
91 The
92 .I retry
93 statement determines the time that must pass after the client has
94 determined that there is no DHCP server present before it tries again
95 to contact a DHCP server.   By default, this is five minutes.
96 .PP
97 .I The
98 .B select-timeout
99 .I statement
100 .PP
101  \fBselect-timeout \fItime\fR\fB;\fR
102 .PP
103 It is possible (some might say desirable) for there to be more than
104 one DHCP server serving any given network.   In this case, it is
105 possible that a client may be sent more than one offer in response to
106 its initial lease discovery message.   It may be that one of these
107 offers is preferable to the other (e.g., one offer may have the
108 address the client previously used, and the other may not).
109 .PP
110 The
111 .I select-timeout
112 is the time after the client sends its first lease discovery request
113 at which it stops waiting for offers from servers, assuming that it
114 has received at least one such offer.   If no offers have been
115 received by the time the
116 .I select-timeout
117 has expired, the client will accept the first offer that arrives.
118 .PP
119 By default, the select-timeout is zero seconds - that is, the client
120 will take the first offer it sees.
121 .PP
122 .I The
123 .B reboot
124 .I statement
125 .PP
126  \fBreboot \fItime\fR\fB;\fR
127 .PP
128 When the client is restarted, it first tries to reacquire the last
129 address it had.   This is called the INIT-REBOOT state.   If it is
130 still attached to the same network it was attached to when it last
131 ran, this is the quickest way to get started.   The
132 .I reboot
133 statement sets the time that must elapse after the client first tries
134 to reacquire its old address before it gives up and tries to discover
135 a new address.   By default, the reboot timeout is ten seconds.
136 .PP
137 .I The
138 .B backoff-cutoff
139 .I statement
140 .PP
141  \fBbackoff-cutoff \fItime\fR\fB;\fR
142 .PP
143 The client uses an exponential backoff algorithm with some randomness,
144 so that if many clients try to configure themselves at the same time,
145 they will not make their requests in lockstep.   The
146 .I backoff-cutoff
147 statement determines the maximum amount of time that the client is
148 allowed to back off, the actual value will be evaluated randomly between
149 1/2 to 1 1/2 times the \fItime\fR specified.   It defaults to two minutes.
150 .PP
151 .I The
152 .B initial-interval
153 .I statement
154 .PP
155  \fBinitial-interval \fItime\fR\fB;\fR
156 .PP
157 The
158 .I initial-interval
159 statement sets the amount of time between the first attempt to reach a
160 server and the second attempt to reach a server.  Each time a message
161 is sent, the interval between messages is incremented by twice the
162 current interval multiplied by a random number between zero and one.
163 If it is greater than the backoff-cutoff amount, it is set to that
164 amount.  It defaults to ten seconds.
166 The DHCP protocol allows the client to request that the server send it
167 specific information, and not send it other information that it is not
168 prepared to accept.   The protocol also allows the client to reject
169 offers from servers if they don't contain information the client
170 needs, or if the information provided is not satisfactory.
171 .PP
172 There is a variety of data contained in offers that DHCP servers send
173 to DHCP clients.  The data that can be specifically requested is what
174 are called \fIDHCP Options\fR.  DHCP Options are defined in
175  \fBdhcp-options(5)\fR.
176 .PP
177 .I The
178 .B request
179 .I statement
180 .PP
181  \fBrequest [ \fIoption\fR ] [\fB,\fI ... \fIoption\fR ]\fB;\fR
182 .PP
183 The request statement causes the client to request that any server
184 responding to the client send the client its values for the specified
185 options.   Only the option names should be specified in the request
186 statement - not option parameters.   By default, the DHCP server
187 requests the subnet-mask, broadcast-address, time-offset, routers,
188 domain-name, domain-name-servers and host-name options. 
189 .PP
190 In some cases, it may be desirable to send no parameter request list
191 at all.   To do this, simply write the request statement but specify
192 no parameters:
193 .PP
194 .nf
195         request;
196 .fi
197 .PP
198 .I The
199 .B require
200 .I statement
201 .PP
202  \fBrequire [ \fIoption\fR ] [\fB,\fI ... \fIoption ]\fB;\fR
203 .PP
204 The require statement lists options that must be sent in order for an
205 offer to be accepted.   Offers that do not contain all the listed
206 options will be ignored.
207 .PP
208 .I The
209 .B send
210 .I statement
211 .PP
212  \fBsend { [ \fIoption declaration\fR ]
213 [\fB,\fI ... \fIoption declaration\fR ]\fB}\fR
214 .PP
215 The send statement causes the client to send the specified options to
216 the server with the specified values.  These are full option
217 declarations as described in \fBdhcp-options(5)\fR.  Options that are
218 always sent in the DHCP protocol should not be specified here, except
219 that the client can specify a \fBrequested-lease-time\fR option other
220 than the default requested lease time, which is two hours.  The other
221 obvious use for this statement is to send information to the server
222 that will allow it to differentiate between this client and other
223 clients or kinds of clients.
225 The client now has some very limited support for doing DNS updates
226 when a lease is acquired.   This is prototypical, and probably doesn't
227 do what you want.   It also only works if you happen to have control
228 over your DNS server, which isn't very likely.
229 .PP
230 To make it work, you have to declare a key and zone as in the DHCP
231 server (see \fBdhcpd.conf\fR(5) for details).   You also need to
232 configure the fqdn option on the client, as follows:
233 .PP
234 .nf
235   send fqdn.fqdn "";
236   send fqdn.encoded on;
237   send fqdn.server-update off;
238 .fi
239 .PP
240 The \fIfqdn.fqdn\fR option \fBMUST\fR be a fully-qualified domain
241 name.   You \fBMUST\fR define a zone statement for the zone to be
242 updated.   The \fIfqdn.encoded\fR option may need to be set to
243 \fIon\fR or \fIoff\fR, depending on the DHCP server you are using.
244 .PP
245 .I The
246 .B do-forward-updates
247 .I statement
248 .PP
249  \fBdo-forward-updates [ \fIflag\fR ] \fB;\fR
250 .PP
251 If you want to do DNS updates in the DHCP client
252 script (see \fBdhclient-script(8)\fR) rather than having the
253 DHCP client do the update directly (for example, if you want to
254 use SIG(0) authentication, which is not supported directly by the
255 DHCP client, you can instruct the client not to do the update using
256 the \fBdo-forward-updates\fR statement.   \fIFlag\fR should be \fBtrue\fR
257 if you want the DHCP client to do the update, and \fBfalse\fR if
258 you don't want the DHCP client to do the update.   By default, the DHCP
259 client will do the DNS update.
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
263 information that it needs, and for which a useful default value
264 exists.   It may also receive information which is useful, but which
265 needs to be supplemented with local information.   To handle these
266 needs, several option modifiers are available.
267 .PP
268 .I The
269 .B default
270 .I statement
271 .PP
272  \fBdefault [ \fIoption declaration\fR ] \fB;\fR
273 .PP
274 If for some option the client should use the value supplied by
275 the server, but needs to use some default value if no value was supplied
276 by the server, these values can be defined in the
277 .B default
278 statement.
279 .PP
280 .I The
281 .B supersede
282 .I statement
283 .PP
284  \fBsupersede [ \fIoption declaration\fR ] \fB;\fR
285 .PP
286 If for some option the client should always use a locally-configured
287 value or values rather than whatever is supplied by the server, these
288 values can be defined in the 
289 .B supersede
290 statement.
291 .PP
292 .I The
293 .B prepend
294 .I statement
295 .PP
296  \fBprepend [ \fIoption declaration\fR ] \fB;\fR
297 .PP
298 If for some set of options the client should use a value you
299 supply, and then use the values supplied by
300 the server, if any, these values can be defined in the
301 .B prepend
302 statement.   The
303 .B prepend
304 statement can only be used for options which
305 allow more than one value to be given.   This restriction is not
306 enforced - if you ignore it, the behaviour will be unpredictable.
307 .PP
308 .I The
309 .B append
310 .I statement
311 .PP
312  \fBappend [ \fIoption declaration\fR ] \fB;\fR
313 .PP
314 If for some set of options the client should first use the values
315 supplied by the server, if any, and then use values you supply, these
316 values can be defined in the
317 .B append
318 statement.   The
319 .B append
320 statement can only be used for options which
321 allow more than one value to be given.   This restriction is not
322 enforced - if you ignore it, the behaviour will be unpredictable.
324 .PP
325 .I The
326 .B lease
327 .I declaration
328 .PP
329  \fBlease {\fR \fIlease-declaration\fR [ ... \fIlease-declaration ] \fB}\fR
330 .PP
331 The DHCP client may decide after some period of time (see \fBPROTOCOL
332 TIMING\fR) that it is not going to succeed in contacting a
333 server.   At that time, it consults its own database of old leases and
334 tests each one that has not yet timed out by pinging the listed router
335 for that lease to see if that lease could work.   It is possible to
336 define one or more \fIfixed\fR leases in the client configuration file
337 for networks where there is no DHCP or BOOTP service, so that the
338 client can still automatically configure its address.   This is done
339 with the
340 .B lease
341 statement.
342 .PP
343 NOTE: the lease statement is also used in the dhclient.leases file in
344 order to record leases that have been received from DHCP servers.
345 Some of the syntax for leases as described below is only needed in the
346 dhclient.leases file.   Such syntax is documented here for
347 completeness.
348 .PP
349 A lease statement consists of the lease keyword, followed by a left
350 curly brace, followed by one or more lease declaration statements,
351 followed by a right curly brace.   The following lease declarations
352 are possible:
353 .PP
354  \fBbootp;\fR
355 .PP
356 The
357 .B bootp
358 statement is used to indicate that the lease was acquired using the
359 BOOTP protocol rather than the DHCP protocol.   It is never necessary
360 to specify this in the client configuration file.   The client uses
361 this syntax in its lease database file.
362 .PP
363  \fBinterface\fR \fB"\fR\fIstring\fR\fB";\fR
364 .PP
365 The
366 .B interface
367 lease statement is used to indicate the interface on which the lease
368 is valid.   If set, this lease will only be tried on a particular
369 interface.   When the client receives a lease from a server, it always
370 records the interface number on which it received that lease.
371 If predefined leases are specified in the dhclient.conf file, the
372 interface should also be specified, although this is not required.
373 .PP
374  \fBfixed-address\fR \fIip-address\fR\fB;\fR
375 .PP
376 The
377 .B fixed-address
378 statement is used to set the ip address of a particular lease.   This
379 is required for all lease statements.   The IP address must be
380 specified as a dotted quad (e.g.,
381 .PP
382  \fBfilename "\fR\fIstring\fR\fB";\fR
383 .PP
384 The
385 .B filename
386 statement specifies the name of the boot filename to use.   This is
387 not used by the standard client configuration script, but is included
388 for completeness.
389 .PP
390  \fBserver-name "\fR\fIstring\fR\fB";\fR
391 .PP
392 The
393 .B server-name
394 statement specifies the name of the boot server name to use.   This is
395 also not used by the standard client configuration script.
396 .PP
397  \fBoption\fR \fIoption-declaration\fR\fB;\fR
398 .PP
399 The
400 .B option
401 statement is used to specify the value of an option supplied by the
402 server, or, in the case of predefined leases declared in
403 dhclient.conf, the value that the user wishes the client configuration
404 script to use if the predefined lease is used.
405 .PP
406  \fBscript "\fIscript-name\fB";\fR
407 .PP
408 The
409 .B script
410 statement is used to specify the pathname of the dhcp client
411 configuration script.  This script is used by the dhcp client to set
412 each interface's initial configuration prior to requesting an address,
413 to test the address once it has been offered, and to set the
414 interface's final configuration once a lease has been acquired.   If
415 no lease is acquired, the script is used to test predefined leases, if
416 any, and also called once if no valid lease can be identified.   For
417 more information, see
418 .B dhclient-script(8).
419 .PP
420  \fBvendor option space "\fIname\fB";\fR
421 .PP
422 The
423 .B vendor option space
424 statement is used to specify which option space should be used for
425 decoding the vendor-encapsulate-options option if one is received.
426 The \fIdhcp-vendor-identifier\fR can be used to request a specific
427 class of vendor options from the server.   See
428 .B dhcp-options(5)
429 for details.
430 .PP
431  \fBmedium "\fImedia setup\fB";\fR
432 .PP
433 The
434 .B medium
435 statement can be used on systems where network interfaces cannot
436 automatically determine the type of network to which they are
437 connected.  The media setup string is a system-dependent parameter
438 which is passed to the dhcp client configuration script when
439 initializing the interface.  On Unix and Unix-like systems, the
440 argument is passed on the ifconfig command line when configuring the
441 interface.
442 .PP
443 The dhcp client automatically declares this parameter if it uses a
444 media type (see the
445 .B media
446 statement) when configuring the interface in order to obtain a lease.
447 This statement should be used in predefined leases only if the network
448 interface requires media type configuration.
449 .PP
450  \fBrenew\fR \fIdate\fB;\fR
451 .PP
452  \fBrebind\fR \fIdate\fB;\fR
453 .PP
454  \fBexpire\fR \fIdate\fB;\fR
455 .PP
456 The \fBrenew\fR statement defines the time at which the dhcp client
457 should begin trying to contact its server to renew a lease that it is
458 using.   The \fBrebind\fR statement defines the time at which the dhcp
459 client should begin to try to contact \fIany\fR dhcp server in order
460 to renew its lease.   The \fBexpire\fR statement defines the time at
461 which the dhcp client must stop using a lease if it has not been able
462 to contact a server in order to renew it.
463 .PP
464 These declarations are automatically set in leases acquired by the
465 DHCP client, but must also be configured in predefined leases - a
466 predefined lease whose expiry time has passed will not be used by the
467 DHCP client.
468 .PP
469 Dates are specified as follows:
470 .PP
471  \fI<weekday> <year>\fB/\fI<month>\fB/\fI<day>
472 <hour>\fB:\fI<minute>\fB:\fI<second>\fR
473 .PP
474 The weekday is present to make it easy for a human to tell when a
475 lease expires - it's specified as a number from zero to six, with zero
476 being Sunday.  When declaring a predefined lease, it can always be
477 specified as zero.  The year is specified with the century, so it
478 should generally be four digits except for really long leases.  The
479 month is specified as a number starting with 1 for January.  The day
480 of the month is likewise specified starting with 1.  The hour is a
481 number between 0 and 23, the minute a number between 0 and 59, and the
482 second also a number between 0 and 59.
484  \fBalias { \fI declarations ... \fB}\fR
485 .PP
486 Some DHCP clients running TCP/IP roaming protocols may require that in
487 addition to the lease they may acquire via DHCP, their interface also
488 be configured with a predefined IP alias so that they can have a
489 permanent IP address even while roaming.   The Internet Systems
490 Consortium DHCP client doesn't support roaming with fixed addresses
491 directly, but in order to facilitate such experimentation, the dhcp
492 client can be set up to configure an IP alias using the
493 .B alias
494 declaration.
495 .PP
496 The alias declaration resembles a lease declaration, except that
497 options other than the subnet-mask option are ignored by the standard
498 client configuration script, and expiry times are ignored.  A typical
499 alias declaration includes an interface declaration, a fixed-address
500 declaration for the IP alias address, and a subnet-mask option
501 declaration.   A medium statement should never be included in an alias
502 declaration.
504  \fBreject \fIip-address\fB;\fR
505 .PP
506 The
507 .B reject
508 statement causes the DHCP client to reject offers from
509 servers who use the specified address as a server identifier.   This
510 can be used to avoid being configured by rogue or misconfigured dhcp
511 servers, although it should be a last resort - better to track down
512 the bad DHCP server and fix it.
513 .PP
514  \fBinterface "\fIname\fB" { \fIdeclarations ... \fB }
515 .PP
516 A client with more than one network interface may require different
517 behaviour depending on which interface is being configured.   All
518 timing parameters and declarations other than lease and alias
519 declarations can be enclosed in an interface declaration, and those
520 parameters will then be used only for the interface that matches the
521 specified name.   Interfaces for which there is no interface
522 declaration will use the parameters declared outside of any interface
523 declaration, or the default settings.
524 .PP
525  \fBpseudo "\fIname\fR" "\fIreal-name\fB" { \fIdeclarations ... \fB }
526 .PP
527 Under some circumstances it can be useful to declare a pseudo-interface 
528 and have the DHCP client acquire a configuration for that interface.
529 Each interface that the DHCP client is supporting normally has a DHCP
530 client state machine running on it to acquire and maintain its lease.
531 A pseudo-interface is just another state machine running on the
532 interface named \fIreal-name\fR, with its own lease and its own
533 state.   If you use this feature, you must provide a client identifier
534 for both the pseudo-interface and the actual interface, and the two
535 identifiers must be different.   You must also provide a separate
536 client script for the pseudo-interface to do what you want with the IP
537 address.   For example:
538 .PP
539 .nf
540         interface "ep0" {
541                 send dhcp-client-identifier "my-client-ep0";
542         }
543         pseudo "secondary" "ep0" {
544                 send dhcp-client-identifier "my-client-ep0-secondary";
545                 script "/etc/dhclient-secondary";
546         }
547 .fi
548 .PP
549 The client script for the pseudo-interface should not configure the
550 interface up or down - essentially, all it needs to handle are the
551 states where a lease has been acquired or renewed, and the states
552 where a lease has expired.   See \fBdhclient-script(8)\fR for more
553 information.
554 .PP
555  \fBmedia "\fImedia setup\fB"\fI [ \fB, "\fImedia setup\fB", \fI... ]\fB;\fR
556 .PP
557 The
558 .B media
559 statement defines one or more media configuration parameters which may
560 be tried while attempting to acquire an IP address.   The dhcp client
561 will cycle through each media setup string on the list, configuring
562 the interface using that setup and attempting to boot, and then trying
563 the next one.   This can be used for network interfaces which aren't
564 capable of sensing the media type unaided - whichever media type
565 succeeds in getting a request to the server and hearing the reply is
566 probably right (no guarantees).
567 .PP
568 The media setup is only used for the initial phase of address
569 acquisition (the DHCPDISCOVER and DHCPOFFER packets).   Once an
570 address has been acquired, the dhcp client will record it in its lease
571 database and will record the media type used to acquire the address.
572 Whenever the client tries to renew the lease, it will use that same
573 media type.   The lease must expire before the client will go back to
574 cycling through media types.
576 The following configuration file is used on a laptop running NetBSD
577 1.3.   The laptop has an IP alias of, and has one
578 interface, ep0 (a 3com 3C589C).   Booting intervals have been
579 shortened somewhat from the default, because the client is known to
580 spend most of its time on networks with little DHCP activity.   The
581 laptop does roam to multiple networks.
583 .nf
585 timeout 60;
586 retry 60;
587 reboot 10;
588 select-timeout 5;
589 initial-interval 2;
590 reject;
592 interface "ep0" {
593     send host-name "";
594     send dhcp-client-identifier 1:0:a0:24:ab:fb:9c;
595     send dhcp-lease-time 3600;
596     supersede domain-name "";
597     prepend domain-name-servers;
598     request subnet-mask, broadcast-address, time-offset, routers,
599             domain-name, domain-name-servers, host-name;
600     require subnet-mask, domain-name-servers;
601     script "CLIENTBINDIR/dhclient-script";
602     media "media 10baseT/UTP", "media 10base2/BNC";
603 }
605 alias {
606   interface "ep0";
607   fixed-address;
608   option subnet-mask;
609 }
610 .fi
611 This is a very complicated dhclient.conf file - in general, yours
612 should be much simpler.   In many cases, it's sufficient to just
613 create an empty dhclient.conf file - the defaults are usually fine.
615 dhcp-options(5), dhclient.leases(5), dhcpd(8), dhcpd.conf(5), RFC2132,
616 RFC2131.
618 .B dhclient(8)
619 was written by Ted Lemon
620 under a contract with Vixie Labs.   Funding
621 for this project was provided by Internet Systems Consortium.
622 Information about Internet Systems Consortium can be found at
623 .B