]> CyberLeo.Net >> Repos - FreeBSD/releng/8.1.git/blob - sbin/dhclient/dhcp-options.5
Copy stable/8 to releng/8.1 in preparation for 8.1-RC1.
[FreeBSD/releng/8.1.git] / sbin / dhclient / dhcp-options.5
1 .\"     $OpenBSD: dhcp-options.5,v 1.5 2005/03/02 15:30:42 jmc Exp $
2 .\"
3 .\" Copyright (c) 1995, 1996, 1997, 1998 The Internet Software Consortium.
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\"
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of The Internet Software Consortium nor the names
16 .\"    of its contributors may be used to endorse or promote products derived
17 .\"    from this software without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE INTERNET SOFTWARE CONSORTIUM AND
20 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
21 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
22 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23 .\" DISCLAIMED.  IN NO EVENT SHALL THE INTERNET SOFTWARE CONSORTIUM OR
24 .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
27 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\"
33 .\" This software has been written for the Internet Software Consortium
34 .\" by Ted Lemon <mellon@fugue.com> in cooperation with Vixie
35 .\" Enterprises.  To learn more about the Internet Software Consortium,
36 .\" see ``http://www.isc.org/isc''.  To learn more about Vixie
37 .\" Enterprises, see ``http://www.vix.com''.
38 .\"
39 .\" $FreeBSD$
40 .\"
41 .Dd January 1, 1995
42 .Dt DHCP-OPTIONS 5
43 .Os
44 .Sh NAME
45 .Nm dhcp-options
46 .Nd Dynamic Host Configuration Protocol options
47 .Sh DESCRIPTION
48 The Dynamic Host Configuration protocol allows the client to receive
49 .Ic options
50 from the DHCP server describing the network configuration and various
51 services that are available on the network.
52 When configuring
53 .Xr dhcpd 8
54 or
55 .Xr dhclient 8 ,
56 options must often be declared.
57 The syntax for declaring options, and the names and formats of the options
58 that can be declared, are documented here.
59 .Sh REFERENCE: OPTION STATEMENTS
60 DHCP
61 .Ic option
62 statements always start with the
63 .Ic option
64 keyword, followed by an option name, followed by option data.
65 The option names and data formats are described below.
66 It is not necessary to exhaustively specify all DHCP options -
67 only those options which are needed by clients must be specified.
68 .Pp
69 Option data comes in a variety of formats, as defined below:
70 .Pp
71 The
72 .Ar ip-address
73 data type can be entered either as an explicit IP address
74 (e.g.,
75 .Li 239.254.197.10 )
76 or as a domain name (e.g.,
77 .Li haagen.isc.org ) .
78 A domain name must resolve to a single IP address.
79 .Pp
80 The
81 .Ar int32
82 data type specifies a signed 32-bit integer.
83 The
84 .Ar uint32
85 data type specifies an unsigned 32-bit integer.
86 The
87 .Ar int16
88 and
89 .Ar uint16
90 data types specify signed and unsigned 16-bit integers.
91 The
92 .Ar int8
93 and
94 .Ar uint8
95 data types specify signed and unsigned 8-bit integers.
96 Unsigned 8-bit integers are also sometimes referred to as octets.
97 .Pp
98 The
99 .Ar string
100 data type specifies an
101 .Tn NVT
102 .Pq Network Virtual Terminal
103 .Tn ASCII
104 string, which must be enclosed in double quotes - for example,
105 to specify a domain-name option, the syntax would be
106 .Pp
107 .Dl option domain-name \&"isc.org";
108 .Pp
109 The
110 .Ar flag
111 data type specifies a boolean value.
112 Booleans can be either
113 .Li true
114 or
115 .Li false
116 (or
117 .Li on
118 or
119 .Li off ,
120 if that makes more sense to you).
121 .Pp
122 The
123 .Ar data-string
124 data type specifies either an
125 .Tn NVT ASCII
126 string enclosed in double quotes, or a series of octets specified in
127 hexadecimal, separated by colons.
128 For example:
129 .Pp
130 .Dl option dhcp-client-identifier \&"CLIENT-FOO";
131 or
132 .Dl option dhcp-client-identifier 43:4c:49:45:54:2d:46:4f:4f;
133 .Pp
134 The documentation for the various options mentioned below is taken
135 from the IETF draft document on DHCP options, RFC 2132.
136 Options which are not listed by name may be defined by the name
137 .Li option- Ns Ar nnn ,
138 where
139 .Ar nnn
140 is the decimal number of the option code.
141 These options may be followed either by a string, enclosed in quotes, or by
142 a series of octets, expressed as two-digit hexadecimal numbers separated
143 by colons.
144 For example:
145 .Bd -literal -offset indent
146 option option-133 "my-option-133-text";
147 option option-129 1:54:c9:2b:47;
148 .Ed
149 .Pp
150 Because
151 .Xr dhcpd 8
152 does not know the format of these undefined option codes,
153 no checking is done to ensure the correctness of the entered data.
154 .Pp
155 The standard options are:
156 .Ss RFC 1497 Vendor Extensions
157 .Bl -tag -width indent
158 .It Ic option subnet-mask Ar ip-address ;
159 The
160 .Ic subnet-mask
161 option specifies the client's subnet mask as per RFC 950.
162 If no subnet-mask option is provided anywhere in scope, as a last resort
163 .Xr dhcpd 8
164 will use the subnet mask from the subnet declaration for the network on
165 which an address is being assigned.
166 However,
167 .Em any
168 subnet-mask option declaration that is in scope for the address being
169 assigned will override the subnet mask specified in the subnet declaration.
170 .It Ic option time-offset Ar int32 ;
171 The
172 .Ic time-offset
173 option specifies the offset of the client's subnet in seconds from
174 Coordinated Universal Time (UTC).
175 .It Xo
176 .Ic option routers Ar ip-address
177 .Oo , Ar ip-address ... Oc ;
178 .Xc
179 The
180 .Ic routers
181 option specifies a list of IP addresses for routers on the client's subnet.
182 Routers should be listed in order of preference.
183 .It Xo
184 .Ic option time-servers Ar ip-address
185 .Oo , Ar ip-address ... Oc ;
186 .Xc
187 The
188 .Ic time-server
189 option specifies a list of RFC 868 time servers available to the client.
190 Servers should be listed in order of preference.
191 .It Xo
192 .Ic option ien116-name-servers Ar ip-address
193 .Oo , Ar ip-address ... Oc ;
194 .Xc
195 The
196 .Ic ien116-name-servers
197 option specifies a list of IEN 116 name servers available to the client.
198 Servers should be listed in order of preference.
199 .It Xo
200 .Ic option domain-name-servers Ar ip-address
201 .Oo , Ar ip-address ... Oc ;
202 .Xc
203 The
204 .Ic domain-name-servers
205 option specifies a list of Domain Name System (STD 13, RFC 1035) name servers
206 available to the client.
207 Servers should be listed in order of preference.
208 .It Xo
209 .Ic option log-servers Ar ip-address
210 .Oo , Ar ip-address ... Oc ;
211 .Xc
212 The
213 .Ic log-servers
214 option specifies a list of MIT-LCS UDP log servers available to the client.
215 Servers should be listed in order of preference.
216 .It Xo
217 .Ic option cookie-servers Ar ip-address
218 .Oo , Ar ip-address ... Oc ;
219 .Xc
220 The
221 .Ic cookie-servers
222 option specifies a list of RFC 865 cookie servers available to the client.
223 Servers should be listed in order of preference.
224 .It Xo
225 .Ic option lpr-servers Ar ip-address
226 .Oo , Ar ip-address ... Oc ;
227 .Xc
228 The
229 .Ic lpr-servers
230 option specifies a list of RFC 1179 line printer servers available to the
231 client.
232 Servers should be listed in order of preference.
233 .It Xo
234 .Ic option impress-servers Ar ip-address
235 .Oo , Ar ip-address ... Oc ;
236 .Xc
237 The
238 .Ic impress-servers
239 option specifies a list of Imagen Impress servers available to the client.
240 Servers should be listed in order of preference.
241 .It Xo
242 .Ic option resource-location-servers Ar ip-address
243 .Oo , Ar ip-address ... Oc ;
244 .Xc
245 This option specifies a list of RFC 887 Resource Location servers available
246 to the client.
247 Servers should be listed in order of preference.
248 .It Ic option host-name Ar string ;
249 This option specifies the name of the client.
250 The name may or may not be qualified with the local domain name
251 (it is preferable to use the
252 .Ic domain-name
253 option to specify the domain name).
254 See RFC 1035 for character set restrictions.
255 .It Ic option boot-size Ar uint16 ;
256 This option specifies the length in 512-octet blocks of the default
257 boot image for the client.
258 .It Ic option merit-dump Ar string ;
259 This option specifies the pathname of a file to which the client's
260 core image should be dumped in the event the client crashes.
261 The path is formatted as a character string consisting of characters from
262 the
263 .Tn NVT ASCII
264 character set.
265 .It Ic option domain-name Ar string ;
266 This option specifies the domain name that the client should use when
267 resolving hostnames via the Domain Name System.
268 .It Ic option swap-server Ar ip-address ;
269 This specifies the IP address of the client's swap server.
270 .It Ic option root-path Ar string ;
271 This option specifies the pathname that contains the client's root disk.
272 The path is formatted as a character string consisting of characters from
273 the
274 .Tn NVT ASCII
275 character set.
276 .El
277 .Ss IP Layer Parameters per Host
278 .Bl -tag -width indent
279 .It Ic option ip-forwarding Ar flag ;
280 This option specifies whether the client should configure its IP layer
281 for packet forwarding.
282 A value of 0 means disable IP forwarding, and a value of 1 means enable
283 IP forwarding.
284 .It Ic option non-local-source-routing Ar flag ;
285 This option specifies whether the client should configure its IP
286 layer to allow forwarding of datagrams with non-local source routes
287 (see Section 3.3.5 of [4] for a discussion of this topic).
288 A value of 0 means disallow forwarding of such datagrams, and a value of 1
289 means allow forwarding.
290 .It Xo
291 .Ic option policy-filter Ar ip-address ip-address
292 .Oo , Ar ip-address ip-address ... Oc ;
293 .Xc
294 This option specifies policy filters for non-local source routing.
295 The filters consist of a list of IP addresses and masks which specify
296 destination/mask pairs with which to filter incoming source routes.
297 .Pp
298 Any source-routed datagram whose next-hop address does not match one
299 of the filters should be discarded by the client.
300 .Pp
301 See STD 3 (RFC 1122) for further information.
302 .It Ic option max-dgram-reassembly Ar uint16 ;
303 This option specifies the maximum size datagram that the client should be
304 prepared to reassemble.
305 The minimum legal value is 576.
306 .It Ic option default-ip-ttl Ar uint8 ;
307 This option specifies the default time-to-live that the client should
308 use on outgoing datagrams.
309 .It Ic option path-mtu-aging-timeout Ar uint32 ;
310 This option specifies the timeout (in seconds) to use when aging Path
311 MTU values discovered by the mechanism defined in RFC 1191.
312 .It Xo
313 .Ic option path-mtu-plateau-table Ar uint16
314 .Oo , Ar uint16 ... Oc ;
315 .Xc
316 This option specifies a table of MTU sizes to use when performing
317 Path MTU Discovery as defined in RFC 1191.
318 The table is formatted as a list of 16-bit unsigned integers,
319 ordered from smallest to largest.
320 The minimum MTU value cannot be smaller than 68.
321 .El
322 .Ss IP Layer Parameters per Interface
323 .Bl -tag -width indent
324 .It Ic option interface-mtu Ar uint16 ;
325 This option specifies the MTU to use on this interface.
326 The minimum legal value for the MTU is 68.
327 .It Ic option all-subnets-local Ar flag ;
328 This option specifies whether or not the client may assume that all subnets
329 of the IP network to which the client is connected use the same MTU as the
330 subnet of that network to which the client is directly connected.
331 A value of 1 indicates that all subnets share the same MTU.
332 A value of 0 means that the client should assume that some subnets of the
333 directly connected network may have smaller MTUs.
334 .It Ic option broadcast-address Ar ip-address ;
335 This option specifies the broadcast address in use on the client's subnet.
336 Legal values for broadcast addresses are specified in section 3.2.1.3 of
337 STD 3 (RFC 1122).
338 .It Ic option perform-mask-discovery Ar flag ;
339 This option specifies whether or not the client should perform subnet mask
340 discovery using ICMP.
341 A value of 0 indicates that the client should not perform mask discovery.
342 A value of 1 means that the client should perform mask discovery.
343 .It Ic option mask-supplier Ar flag ;
344 This option specifies whether or not the client should respond to subnet mask
345 requests using ICMP.
346 A value of 0 indicates that the client should not respond.
347 A value of 1 means that the client should respond.
348 .It Ic option router-discovery Ar flag ;
349 This option specifies whether or not the client should solicit routers using
350 the Router Discovery mechanism defined in RFC 1256.
351 A value of 0 indicates that the client should not perform router discovery.
352 A value of 1 means that the client should perform router discovery.
353 .It Ic option router-solicitation-address Ar ip-address ;
354 This option specifies the address to which the client should transmit
355 router solicitation requests.
356 .It Xo
357 .Ic option static-routes Ar ip-address ip-address
358 .Oo , Ar ip-address ip-address ... Oc ;
359 .Xc
360 This option specifies a list of static routes that the client should
361 install in its routing cache.
362 If multiple routes to the same destination are specified, they are listed
363 in descending order of priority.
364 .Pp
365 The routes consist of a list of IP address pairs.
366 The first address is the destination address,
367 and the second address is the router for the destination.
368 .Pp
369 The default route (0.0.0.0) is an illegal destination for a static route.
370 To specify the default route, use the
371 .Ic routers
372 option.
373 .El
374 .Ss Link Layer Parameters per Interface
375 .Bl -tag -width indent
376 .It Ic option trailer-encapsulation Ar flag ;
377 This option specifies whether or not the client should negotiate the
378 use of trailers (RFC 893 [14]) when using the ARP protocol.
379 A value of 0 indicates that the client should not attempt to use trailers.
380 A value of 1 means that the client should attempt to use trailers.
381 .It Ic option arp-cache-timeout Ar uint32 ;
382 This option specifies the timeout in seconds for ARP cache entries.
383 .It Ic option ieee802-3-encapsulation Ar flag ;
384 This option specifies whether or not the client should use Ethernet
385 Version 2 (RFC 894) or IEEE 802.3 (RFC 1042) encapsulation if the
386 interface is an Ethernet.
387 A value of 0 indicates that the client should use RFC 894 encapsulation.
388 A value of 1 means that the client should use RFC 1042 encapsulation.
389 .El
390 .Ss TCP Parameters
391 .Bl -tag -width indent
392 .It Ic option default-tcp-ttl Ar uint8 ;
393 This option specifies the default TTL that the client should use when
394 sending TCP segments.
395 The minimum value is 1.
396 .It Ic option tcp-keepalive-interval Ar uint32 ;
397 This option specifies the interval (in seconds) that the client TCP
398 should wait before sending a keepalive message on a TCP connection.
399 The time is specified as a 32-bit unsigned integer.
400 A value of zero indicates that the client should not generate keepalive
401 messages on connections unless specifically requested by an application.
402 .It Ic option tcp-keepalive-garbage Ar flag ;
403 This option specifies whether or not the client should send TCP keepalive
404 messages with an octet of garbage for compatibility with older implementations.
405 A value of 0 indicates that a garbage octet should not be sent.
406 A value of 1 indicates that a garbage octet should be sent.
407 .El
408 .Ss Application and Service Parameters
409 .Bl -tag -width indent
410 .It Ic option nis-domain Ar string ;
411 This option specifies the name of the client's NIS (Sun Network Information
412 Services) domain.
413 The domain is formatted as a character string consisting of characters
414 from the
415 .Tn NVT ASCII
416 character set.
417 .It Xo
418 .Ic option nis-servers Ar ip-address
419 .Oo , Ar ip-address ... Oc ;
420 .Xc
421 This option specifies a list of IP addresses indicating NIS servers
422 available to the client.
423 Servers should be listed in order of preference.
424 .It Xo
425 .Ic option ntp-servers Ar ip-address
426 .Oo , Ar ip-address ... Oc ;
427 .Xc
428 This option specifies a list of IP addresses indicating NTP (RFC 1305)
429 servers available to the client.
430 Servers should be listed in order of preference.
431 .It Xo
432 .Ic option netbios-name-servers Ar ip-address
433 .Oo , Ar ip-address ... Oc ;
434 .Xc
435 The NetBIOS name server (NBNS) option specifies a list of RFC 1001/1002
436 NBNS name servers listed in order of preference.
437 NetBIOS Name Service is currently more commonly referred to as WINS.
438 WINS servers can be specified using the
439 .Ic netbios-name-servers
440 option.
441 .It Xo
442 .Ic option netbios-dd-server Ar ip-address
443 .Oo , Ar ip-address ... Oc ;
444 .Xc
445 The NetBIOS datagram distribution server (NBDD) option specifies a
446 list of RFC 1001/1002 NBDD servers listed in order of preference.
447 .It Ic option netbios-node-type Ar uint8 ;
448 The NetBIOS node type option allows NetBIOS over TCP/IP clients which
449 are configurable to be configured as described in RFC 1001/1002.
450 The value is specified as a single octet which identifies the client type.
451 .Pp
452 Possible node types are:
453 .Bl -tag -width indent
454 .It 1
455 B-node: Broadcast - no WINS
456 .It 2
457 P-node: Peer - WINS only
458 .It 4
459 M-node: Mixed - broadcast, then WINS
460 .It 8
461 H-node: Hybrid - WINS, then broadcast
462 .El
463 .It Ic option netbios-scope Ar string ;
464 The NetBIOS scope option specifies the NetBIOS over TCP/IP scope
465 parameter for the client as specified in RFC 1001/1002.
466 See RFC 1001, RFC 1002, and RFC 1035 for character-set restrictions.
467 .It Xo
468 .Ic option font-servers Ar ip-address
469 .Oo , Ar ip-address ... Oc ;
470 .Xc
471 This option specifies a list of X Window System Font servers available
472 to the client.
473 Servers should be listed in order of preference.
474 .It Xo
475 .Ic option x-display-manager Ar ip-address
476 .Oo , Ar ip-address ... Oc ;
477 .Xc
478 This option specifies a list of systems that are running the X Window
479 System Display Manager and are available to the client.
480 Addresses should be listed in order of preference.
481 .It Ic option dhcp-client-identifier Ar data-string ;
482 This option can be used to specify a DHCP client identifier in a
483 host declaration, so that
484 .Xr dhcpd 8
485 can find the host record by matching against the client identifier.
486 .It Ic option nisplus-domain Ar string ;
487 This option specifies the name of the client's NIS+ domain.
488 The domain is formatted as a character string consisting of characters
489 from the
490 .Tn NVT ASCII
491 character set.
492 .It Xo
493 .Ic option nisplus-servers Ar ip-address
494 .Oo , Ar ip-address ... Oc ;
495 .Xc
496 This option specifies a list of IP addresses indicating NIS+ servers
497 available to the client.
498 Servers should be listed in order of preference.
499 .It Ic option tftp-server-name Ar string ;
500 This option is used to identify a TFTP server and, if supported by the
501 client, should have the same effect as the
502 .Ic server-name
503 declaration.
504 BOOTP clients are unlikely to support this option.
505 Some DHCP clients will support it, and others actually require it.
506 .It Ic option bootfile-name Ar string ;
507 This option is used to identify a bootstrap file.
508 If supported by the client, it should have the same effect as the
509 .Ic filename
510 declaration.
511 BOOTP clients are unlikely to support this option.
512 Some DHCP clients will support it, and others actually require it.
513 .It Xo
514 .Ic option mobile-ip-home-agent Ar ip-address
515 .Oo , Ar ip-address ... Oc ;
516 .Xc
517 This option specifies a list of IP addresses indicating mobile IP
518 home agents available to the client.
519 Agents should be listed in order of preference, although normally there
520 will be only one such agent.
521 .It Xo
522 .Ic option smtp-server Ar ip-address
523 .Oo , Ar ip-address ... Oc ;
524 .Xc
525 The
526 .Ic smtp-server
527 option specifies a list of SMTP servers available to the client.
528 Servers should be listed in order of preference.
529 .It Xo
530 .Ic option pop-server Ar ip-address
531 .Oo , Ar ip-address ... Oc ;
532 .Xc
533 The
534 .Ic pop-server
535 option specifies a list of POP3 servers available to the client.
536 Servers should be listed in order of preference.
537 .It Xo
538 .Ic option nntp-server Ar ip-address
539 .Oo , Ar ip-address ... Oc ;
540 .Xc
541 The
542 .Ic nntp-server
543 option specifies a list of NNTP servers available to the client.
544 Servers should be listed in order of preference.
545 .It Xo
546 .Ic option www-server Ar ip-address
547 .Oo , Ar ip-address ... Oc ;
548 .Xc
549 The
550 .Ic www-server
551 option specifies a list of WWW servers available to the client.
552 Servers should be listed in order of preference.
553 .It Xo
554 .Ic option finger-server Ar ip-address
555 .Oo , Ar ip-address ... Oc ;
556 .Xc
557 The
558 .Ic finger-server
559 option specifies a list of
560 .Xr finger 1
561 servers available to the client.
562 Servers should be listed in order of preference.
563 .It Xo
564 .Ic option irc-server Ar ip-address
565 .Oo , Ar ip-address ... Oc ;
566 .Xc
567 The
568 .Ic irc-server
569 option specifies a list of IRC servers available to the client.
570 Servers should be listed in order of preference.
571 .It Xo
572 .Ic option streettalk-server Ar ip-address
573 .Oo , Ar ip-address ... Oc ;
574 .Xc
575 The
576 .Ic streettalk-server
577 option specifies a list of StreetTalk servers available to the client.
578 Servers should be listed in order of preference.
579 .It Xo
580 .Ic option streettalk-directory-assistance-server Ar ip-address
581 .Oo , Ar ip-address ... Oc ;
582 .Xc
583 The StreetTalk Directory Assistance (STDA) server option specifies a
584 list of STDA servers available to the client.
585 Servers should be listed in order of preference.
586 .El
587 .Sh SEE ALSO
588 .Xr dhclient.conf 5 ,
589 .Xr dhcpd.conf 5 ,
590 .Xr dhcpd.leases 5 ,
591 .Xr dhclient 8 ,
592 .Xr dhcpd 8
593 .Rs
594 .%R "RFC 2131, RFC 2132"
595 .Re
596 .Sh AUTHORS
597 .An -nosplit
598 The
599 .Xr dhcpd 8
600 utility
601 was written by
602 .An Ted Lemon Aq mellon@vix.com
603 under a contract with Vixie Labs.
604 .Pp
605 The current implementation was reworked by
606 .An Henning Brauer Aq henning@openbsd.org .