]> CyberLeo.Net >> Repos - FreeBSD/releng/10.0.git/blob - sbin/dhclient/dhcp-options.5
- Copy stable/10 (r259064) to releng/10.0 as part of the
[FreeBSD/releng/10.0.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 domain-search Ar string ;
269 This option specifies a list of domain names that the client should use
270 when resolving hostnames via the Domain Name System. This option is
271 defined in RFC 3397.
272 .It Ic option swap-server Ar ip-address ;
273 This specifies the IP address of the client's swap server.
274 .It Ic option root-path Ar string ;
275 This option specifies the pathname that contains the client's root disk.
276 The path is formatted as a character string consisting of characters from
277 the
278 .Tn NVT ASCII
279 character set.
280 .El
281 .Ss IP Layer Parameters per Host
282 .Bl -tag -width indent
283 .It Ic option ip-forwarding Ar flag ;
284 This option specifies whether the client should configure its IP layer
285 for packet forwarding.
286 A value of 0 means disable IP forwarding, and a value of 1 means enable
287 IP forwarding.
288 .It Ic option non-local-source-routing Ar flag ;
289 This option specifies whether the client should configure its IP
290 layer to allow forwarding of datagrams with non-local source routes
291 (see Section 3.3.5 of [4] for a discussion of this topic).
292 A value of 0 means disallow forwarding of such datagrams, and a value of 1
293 means allow forwarding.
294 .It Xo
295 .Ic option policy-filter Ar ip-address ip-address
296 .Oo , Ar ip-address ip-address ... Oc ;
297 .Xc
298 This option specifies policy filters for non-local source routing.
299 The filters consist of a list of IP addresses and masks which specify
300 destination/mask pairs with which to filter incoming source routes.
301 .Pp
302 Any source-routed datagram whose next-hop address does not match one
303 of the filters should be discarded by the client.
304 .Pp
305 See STD 3 (RFC 1122) for further information.
306 .It Ic option max-dgram-reassembly Ar uint16 ;
307 This option specifies the maximum size datagram that the client should be
308 prepared to reassemble.
309 The minimum legal value is 576.
310 .It Ic option default-ip-ttl Ar uint8 ;
311 This option specifies the default time-to-live that the client should
312 use on outgoing datagrams.
313 .It Ic option path-mtu-aging-timeout Ar uint32 ;
314 This option specifies the timeout (in seconds) to use when aging Path
315 MTU values discovered by the mechanism defined in RFC 1191.
316 .It Xo
317 .Ic option path-mtu-plateau-table Ar uint16
318 .Oo , Ar uint16 ... Oc ;
319 .Xc
320 This option specifies a table of MTU sizes to use when performing
321 Path MTU Discovery as defined in RFC 1191.
322 The table is formatted as a list of 16-bit unsigned integers,
323 ordered from smallest to largest.
324 The minimum MTU value cannot be smaller than 68.
325 .El
326 .Ss IP Layer Parameters per Interface
327 .Bl -tag -width indent
328 .It Ic option interface-mtu Ar uint16 ;
329 This option specifies the MTU to use on this interface.
330 The minimum legal value for the MTU is 68.
331 .It Ic option all-subnets-local Ar flag ;
332 This option specifies whether or not the client may assume that all subnets
333 of the IP network to which the client is connected use the same MTU as the
334 subnet of that network to which the client is directly connected.
335 A value of 1 indicates that all subnets share the same MTU.
336 A value of 0 means that the client should assume that some subnets of the
337 directly connected network may have smaller MTUs.
338 .It Ic option broadcast-address Ar ip-address ;
339 This option specifies the broadcast address in use on the client's subnet.
340 Legal values for broadcast addresses are specified in section 3.2.1.3 of
341 STD 3 (RFC 1122).
342 .It Ic option perform-mask-discovery Ar flag ;
343 This option specifies whether or not the client should perform subnet mask
344 discovery using ICMP.
345 A value of 0 indicates that the client should not perform mask discovery.
346 A value of 1 means that the client should perform mask discovery.
347 .It Ic option mask-supplier Ar flag ;
348 This option specifies whether or not the client should respond to subnet mask
349 requests using ICMP.
350 A value of 0 indicates that the client should not respond.
351 A value of 1 means that the client should respond.
352 .It Ic option router-discovery Ar flag ;
353 This option specifies whether or not the client should solicit routers using
354 the Router Discovery mechanism defined in RFC 1256.
355 A value of 0 indicates that the client should not perform router discovery.
356 A value of 1 means that the client should perform router discovery.
357 .It Ic option router-solicitation-address Ar ip-address ;
358 This option specifies the address to which the client should transmit
359 router solicitation requests.
360 .It Xo
361 .Ic option static-routes Ar ip-address ip-address
362 .Oo , Ar ip-address ip-address ... Oc ;
363 .Xc
364 This option specifies a list of static routes that the client should
365 install in its routing cache.
366 If multiple routes to the same destination are specified, they are listed
367 in descending order of priority.
368 .Pp
369 The routes consist of a list of IP address pairs.
370 The first address is the destination address,
371 and the second address is the router for the destination.
372 .Pp
373 The default route (0.0.0.0) is an illegal destination for a static route.
374 To specify the default route, use the
375 .Ic routers
376 option.
377 .El
378 .Ss Link Layer Parameters per Interface
379 .Bl -tag -width indent
380 .It Ic option trailer-encapsulation Ar flag ;
381 This option specifies whether or not the client should negotiate the
382 use of trailers (RFC 893 [14]) when using the ARP protocol.
383 A value of 0 indicates that the client should not attempt to use trailers.
384 A value of 1 means that the client should attempt to use trailers.
385 .It Ic option arp-cache-timeout Ar uint32 ;
386 This option specifies the timeout in seconds for ARP cache entries.
387 .It Ic option ieee802-3-encapsulation Ar flag ;
388 This option specifies whether or not the client should use Ethernet
389 Version 2 (RFC 894) or IEEE 802.3 (RFC 1042) encapsulation if the
390 interface is an Ethernet.
391 A value of 0 indicates that the client should use RFC 894 encapsulation.
392 A value of 1 means that the client should use RFC 1042 encapsulation.
393 .El
394 .Ss TCP Parameters
395 .Bl -tag -width indent
396 .It Ic option default-tcp-ttl Ar uint8 ;
397 This option specifies the default TTL that the client should use when
398 sending TCP segments.
399 The minimum value is 1.
400 .It Ic option tcp-keepalive-interval Ar uint32 ;
401 This option specifies the interval (in seconds) that the client TCP
402 should wait before sending a keepalive message on a TCP connection.
403 The time is specified as a 32-bit unsigned integer.
404 A value of zero indicates that the client should not generate keepalive
405 messages on connections unless specifically requested by an application.
406 .It Ic option tcp-keepalive-garbage Ar flag ;
407 This option specifies whether or not the client should send TCP keepalive
408 messages with an octet of garbage for compatibility with older implementations.
409 A value of 0 indicates that a garbage octet should not be sent.
410 A value of 1 indicates that a garbage octet should be sent.
411 .El
412 .Ss Application and Service Parameters
413 .Bl -tag -width indent
414 .It Ic option nis-domain Ar string ;
415 This option specifies the name of the client's NIS (Sun Network Information
416 Services) domain.
417 The domain is formatted as a character string consisting of characters
418 from the
419 .Tn NVT ASCII
420 character set.
421 .It Xo
422 .Ic option nis-servers Ar ip-address
423 .Oo , Ar ip-address ... Oc ;
424 .Xc
425 This option specifies a list of IP addresses indicating NIS servers
426 available to the client.
427 Servers should be listed in order of preference.
428 .It Xo
429 .Ic option ntp-servers Ar ip-address
430 .Oo , Ar ip-address ... Oc ;
431 .Xc
432 This option specifies a list of IP addresses indicating NTP (RFC 1305)
433 servers available to the client.
434 Servers should be listed in order of preference.
435 .It Xo
436 .Ic option netbios-name-servers Ar ip-address
437 .Oo , Ar ip-address ... Oc ;
438 .Xc
439 The NetBIOS name server (NBNS) option specifies a list of RFC 1001/1002
440 NBNS name servers listed in order of preference.
441 NetBIOS Name Service is currently more commonly referred to as WINS.
442 WINS servers can be specified using the
443 .Ic netbios-name-servers
444 option.
445 .It Xo
446 .Ic option netbios-dd-server Ar ip-address
447 .Oo , Ar ip-address ... Oc ;
448 .Xc
449 The NetBIOS datagram distribution server (NBDD) option specifies a
450 list of RFC 1001/1002 NBDD servers listed in order of preference.
451 .It Ic option netbios-node-type Ar uint8 ;
452 The NetBIOS node type option allows NetBIOS over TCP/IP clients which
453 are configurable to be configured as described in RFC 1001/1002.
454 The value is specified as a single octet which identifies the client type.
455 .Pp
456 Possible node types are:
457 .Bl -tag -width indent
458 .It 1
459 B-node: Broadcast - no WINS
460 .It 2
461 P-node: Peer - WINS only
462 .It 4
463 M-node: Mixed - broadcast, then WINS
464 .It 8
465 H-node: Hybrid - WINS, then broadcast
466 .El
467 .It Ic option netbios-scope Ar string ;
468 The NetBIOS scope option specifies the NetBIOS over TCP/IP scope
469 parameter for the client as specified in RFC 1001/1002.
470 See RFC 1001, RFC 1002, and RFC 1035 for character-set restrictions.
471 .It Xo
472 .Ic option font-servers Ar ip-address
473 .Oo , Ar ip-address ... Oc ;
474 .Xc
475 This option specifies a list of X Window System Font servers available
476 to the client.
477 Servers should be listed in order of preference.
478 .It Xo
479 .Ic option x-display-manager Ar ip-address
480 .Oo , Ar ip-address ... Oc ;
481 .Xc
482 This option specifies a list of systems that are running the X Window
483 System Display Manager and are available to the client.
484 Addresses should be listed in order of preference.
485 .It Ic option dhcp-client-identifier Ar data-string ;
486 This option can be used to specify a DHCP client identifier in a
487 host declaration, so that
488 .Xr dhcpd 8
489 can find the host record by matching against the client identifier.
490 .It Ic option nisplus-domain Ar string ;
491 This option specifies the name of the client's NIS+ domain.
492 The domain is formatted as a character string consisting of characters
493 from the
494 .Tn NVT ASCII
495 character set.
496 .It Xo
497 .Ic option nisplus-servers Ar ip-address
498 .Oo , Ar ip-address ... Oc ;
499 .Xc
500 This option specifies a list of IP addresses indicating NIS+ servers
501 available to the client.
502 Servers should be listed in order of preference.
503 .It Ic option tftp-server-name Ar string ;
504 This option is used to identify a TFTP server and, if supported by the
505 client, should have the same effect as the
506 .Ic server-name
507 declaration.
508 BOOTP clients are unlikely to support this option.
509 Some DHCP clients will support it, and others actually require it.
510 .It Ic option bootfile-name Ar string ;
511 This option is used to identify a bootstrap file.
512 If supported by the client, it should have the same effect as the
513 .Ic filename
514 declaration.
515 BOOTP clients are unlikely to support this option.
516 Some DHCP clients will support it, and others actually require it.
517 .It Xo
518 .Ic option mobile-ip-home-agent Ar ip-address
519 .Oo , Ar ip-address ... Oc ;
520 .Xc
521 This option specifies a list of IP addresses indicating mobile IP
522 home agents available to the client.
523 Agents should be listed in order of preference, although normally there
524 will be only one such agent.
525 .It Xo
526 .Ic option smtp-server Ar ip-address
527 .Oo , Ar ip-address ... Oc ;
528 .Xc
529 The
530 .Ic smtp-server
531 option specifies a list of SMTP servers available to the client.
532 Servers should be listed in order of preference.
533 .It Xo
534 .Ic option pop-server Ar ip-address
535 .Oo , Ar ip-address ... Oc ;
536 .Xc
537 The
538 .Ic pop-server
539 option specifies a list of POP3 servers available to the client.
540 Servers should be listed in order of preference.
541 .It Xo
542 .Ic option nntp-server Ar ip-address
543 .Oo , Ar ip-address ... Oc ;
544 .Xc
545 The
546 .Ic nntp-server
547 option specifies a list of NNTP servers available to the client.
548 Servers should be listed in order of preference.
549 .It Xo
550 .Ic option www-server Ar ip-address
551 .Oo , Ar ip-address ... Oc ;
552 .Xc
553 The
554 .Ic www-server
555 option specifies a list of WWW servers available to the client.
556 Servers should be listed in order of preference.
557 .It Xo
558 .Ic option finger-server Ar ip-address
559 .Oo , Ar ip-address ... Oc ;
560 .Xc
561 The
562 .Ic finger-server
563 option specifies a list of
564 .Xr finger 1
565 servers available to the client.
566 Servers should be listed in order of preference.
567 .It Xo
568 .Ic option irc-server Ar ip-address
569 .Oo , Ar ip-address ... Oc ;
570 .Xc
571 The
572 .Ic irc-server
573 option specifies a list of IRC servers available to the client.
574 Servers should be listed in order of preference.
575 .It Xo
576 .Ic option streettalk-server Ar ip-address
577 .Oo , Ar ip-address ... Oc ;
578 .Xc
579 The
580 .Ic streettalk-server
581 option specifies a list of StreetTalk servers available to the client.
582 Servers should be listed in order of preference.
583 .It Xo
584 .Ic option streettalk-directory-assistance-server Ar ip-address
585 .Oo , Ar ip-address ... Oc ;
586 .Xc
587 The StreetTalk Directory Assistance (STDA) server option specifies a
588 list of STDA servers available to the client.
589 Servers should be listed in order of preference.
590 .El
591 .Sh SEE ALSO
592 .Xr dhclient.conf 5 ,
593 .Xr dhcpd.conf 5 ,
594 .Xr dhcpd.leases 5 ,
595 .Xr dhclient 8 ,
596 .Xr dhcpd 8
597 .Rs
598 .%R "RFC 2131, RFC 2132"
599 .Re
600 .Sh AUTHORS
601 .An -nosplit
602 The
603 .Xr dhcpd 8
604 utility
605 was written by
606 .An Ted Lemon Aq mellon@vix.com
607 under a contract with Vixie Labs.
608 .Pp
609 The current implementation was reworked by
610 .An Henning Brauer Aq henning@openbsd.org .