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