1: .\" $Id: dhcp-options.5,v 1.1.1.1 2012/10/09 09:06:54 misho Exp $
2: .\"
3: .\" Copyright (c) 2012 by Internet Systems Consortium, Inc. ("ISC")
4: .\" Copyright (c) 2004-2010 by Internet Systems Consortium, Inc. ("ISC")
5: .\" Copyright (c) 1996-2003 by Internet Software Consortium
6: .\"
7: .\" Permission to use, copy, modify, and distribute this software for any
8: .\" purpose with or without fee is hereby granted, provided that the above
9: .\" copyright notice and this permission notice appear in all copies.
10: .\"
11: .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
12: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
14: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
17: .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18: .\"
19: .\" Internet Systems Consortium, Inc.
20: .\" 950 Charter Street
21: .\" Redwood City, CA 94063
22: .\" <info@isc.org>
23: .\" https://www.isc.org/
24: .\"
25: .\" This software has been written for Internet Systems Consortium
26: .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
27: .\"
28: .\" Support and other services are available for ISC products - see
29: .\" https://www.isc.org for more information or to learn more about ISC.
30: .\"
31: .TH dhcp-options 5
32: .SH NAME
33: dhcp-options - Dynamic Host Configuration Protocol options
34: .SH DESCRIPTION
35: The Dynamic Host Configuration protocol allows the client to receive
36: .B options
37: from the DHCP server describing the network configuration and various
38: services that are available on the network. When configuring
39: .B dhcpd(8)
40: or
41: .B dhclient(8) ,
42: options must often be declared. The syntax for declaring options,
43: and the names and formats of the options that can be declared, are
44: documented here.
45: .SH REFERENCE: OPTION STATEMENTS
46: .PP
47: DHCP \fIoption\fR statements always start with the \fIoption\fR
48: keyword, followed by an option name, followed by option data. The
49: option names and data formats are described below. It is not
50: necessary to exhaustively specify all DHCP options - only those
51: options which are needed by clients must be specified.
52: .PP
53: Option data comes in a variety of formats, as defined below:
54: .PP
55: The
56: .B ip-address
57: data type can be entered either as an explicit IP
58: address (e.g., 239.254.197.10) or as a domain name (e.g.,
59: haagen.isc.org). When entering a domain name, be sure that that
60: domain name resolves to a single IP address.
61: .PP
62: The
63: .B ip6-address
64: data specifies an IPv6 address, like ::1 or 3ffe:bbbb:aaaa:aaaa::1.
65: .PP
66: The
67: .B int32
68: data type specifies a signed 32-bit integer. The
69: .B uint32
70: data type specifies an unsigned 32-bit integer. The
71: .B int16
72: and
73: .B uint16
74: data types specify signed and unsigned 16-bit integers. The
75: .B int8
76: and
77: .B uint8
78: data types specify signed and unsigned 8-bit integers.
79: Unsigned 8-bit integers are also sometimes referred to as octets.
80: .PP
81: The
82: .B text
83: data type specifies an NVT ASCII string, which must be
84: enclosed in double quotes - for example, to specify a root-path
85: option, the syntax would be
86: .nf
87: .sp 1
88: option root-path "10.0.1.4:/var/tmp/rootfs";
89: .fi
90: .PP
91: The
92: .B domain-name
93: data type specifies a domain name, which must not be
94: enclosed in double quotes. This data type is not used for any
95: existing DHCP options. The domain name is stored just as if it were
96: a text option.
97: .PP
98: The
99: .B domain-list
100: data type specifies a list of domain names, enclosed in double quotes and
101: separated by commas ("example.com", "foo.example.com").
102: .PP
103: The
104: .B flag
105: data type specifies a boolean value. Booleans can be either true or
106: false (or on or off, if that makes more sense to you).
107: .PP
108: The
109: .B string
110: data type specifies either an NVT ASCII string
111: enclosed in double quotes, or a series of octets specified in
112: hexadecimal, separated by colons. For example:
113: .nf
114: .sp 1
115: option dhcp-client-identifier "CLIENT-FOO";
116: or
117: option dhcp-client-identifier 43:4c:49:45:54:2d:46:4f:4f;
118: .fi
119: .SH SETTING OPTION VALUES USING EXPRESSIONS
120: Sometimes it's helpful to be able to set the value of a DHCP option
121: based on some value that the client has sent. To do this, you can
122: use expression evaluation. The
123: .B dhcp-eval(5)
124: manual page describes how to write expressions. To assign the result
125: of an evaluation to an option, define the option as follows:
126: .nf
127: .sp 1
128: \fBoption \fImy-option \fB= \fIexpression \fB;\fR
129: .fi
130: .PP
131: For example:
132: .nf
133: .sp 1
134: option hostname = binary-to-ascii (16, 8, "-",
135: substring (hardware, 1, 6));
136: .fi
137: .SH STANDARD DHCPV4 OPTIONS
138: The documentation for the various options mentioned below is taken
139: from the latest IETF draft document on DHCP options. Options not
140: listed below may not yet be implemented, but it is possible to use
141: such options by defining them in the configuration file. Please see
142: the DEFINING NEW OPTIONS heading later in this document for more
143: information.
144: .PP
145: Some of the options documented here are automatically generated by
146: the DHCP server or by clients, and cannot be configured by the user.
147: The value of such an option can be used in the configuration file of
148: the receiving DHCP protocol agent (server or client), for example in
149: conditional expressions. However, the value of the option cannot be
150: used in the configuration file of the sending agent, because the value
151: is determined only \fIafter\fR the configuration file has been
152: processed. In the following documentation, such options will be shown
153: as "not user configurable"
154: .PP
155: The standard options are:
156: .PP
157: .B option \fBall-subnets-local\fR \fIflag\fR\fB;\fR
158: .RS 0.25i
159: .PP
160: This option specifies whether or not the client may assume that all
161: subnets of the IP network to which the client is connected use the
162: same MTU as the subnet of that network to which the client is
163: directly connected. A value of true indicates that all subnets share
164: the same MTU. A value of false means that the client should assume that
165: some subnets of the directly connected network may have smaller MTUs.
166: .RE
167: .PP
168: .B option \fBarp-cache-timeout\fR \fIuint32\fR\fB;\fR
169: .RS 0.25i
170: .PP
171: This option specifies the timeout in seconds for ARP cache entries.
172: .RE
173: .PP
174: .B option \fBbcms-controller-address\fR \fIip-address\fR [\fB,\fR
175: \fIip-address\fR... ]\fB;\fR
176: .RS 0.25i
177: .PP
178: This option configures a list of IPv4 addresses for use as Broadcast and
179: Multicast Controller Servers ("BCMS").
180: .RE
181: .PP
182: .B option \fBbcms-controller-names\fR \fIdomain-list\fR\fB;\fR
183: .RS 0.25i
184: .PP
185: This option contains the domain names of local Broadcast and
186: Multicast Controller Servers ("BCMS") controllers which the client
187: may use.
188: .RE
189: .PP
190: .B option \fBbootfile-name\fR \fItext\fR\fB;\fR
191: .RS 0.25i
192: .PP
193: This option is used to identify a bootstrap file. If supported by the
194: client, it should have the same effect as the \fBfilename\fR
195: declaration. BOOTP clients are unlikely to support this option. Some
196: DHCP clients will support it, and others actually require it.
197: .RE
198: .PP
199: .B option \fBboot-size\fR \fIuint16\fR\fB;\fR
200: .RS 0.25i
201: .PP
202: This option specifies the length in 512-octet blocks of the default
203: boot image for the client.
204: .RE
205: .PP
206: .B option \fBbroadcast-address\fR \fIip-address\fR\fB;\fR
207: .RS 0.25i
208: .PP
209: This option specifies the broadcast address in use on the client's
210: subnet. Legal values for broadcast addresses are specified in
211: section 3.2.1.3 of STD 3 (RFC1122).
212: .RE
213: .PP
214: .B option \fBcookie-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
215: ]\fB;\fR
216: .RS 0.25i
217: .PP
218: The cookie server option specifies a list of RFC 865 cookie
219: servers available to the client. Servers should be listed in order
220: of preference.
221: .RE
222: .PP
223: .B option \fBdefault-ip-ttl\fR \fIuint8;\fR
224: .RS 0.25i
225: .PP
226: This option specifies the default time-to-live that the client should
227: use on outgoing datagrams.
228: .RE
229: .PP
230: .B option \fBdefault-tcp-ttl\fR \fIuint8\fR\fB;\fR
231: .RS 0.25i
232: .PP
233: This option specifies the default TTL that the client should use when
234: sending TCP segments. The minimum value is 1.
235: .RE
236: .PP
237: .B option \fBdefault-url\fR \fIstring\fR\fB;\fR
238: .RS 0.25i
239: .PP
240: The format and meaning of this option is not described in any standards
241: document, but is claimed to be in use by Apple Computer. It is not known
242: what clients may reasonably do if supplied with this option. Use at your
243: own risk.
244: .RE
245: .PP
246: .B option \fBdhcp-client-identifier\fR \fIstring\fR\fB;\fR
247: .RS 0.25i
248: .PP
249: This option can be used to specify a DHCP client identifier in a
250: host declaration, so that dhcpd can find the host record by matching
251: against the client identifier.
252: .PP
253: Please be aware that some DHCP clients, when configured with client
254: identifiers that are ASCII text, will prepend a zero to the ASCII
255: text. So you may need to write:
256: .nf
257:
258: option dhcp-client-identifier "\\0foo";
259:
260: rather than:
261:
262: option dhcp-client-identifier "foo";
263: .fi
264: .RE
265: .PP
266: .B option \fBdhcp-lease-time\fR \fIuint32\fR\fB;\fR
267: .RS 0.25i
268: .PP
269: This option is used in a client request (DHCPDISCOVER or DHCPREQUEST)
270: to allow the client to request a lease time for the IP address. In a
271: server reply (DHCPOFFER), a DHCP server uses this option to specify
272: the lease time it is willing to offer.
273: .PP
274: This option is not directly user configurable in the server; refer to the
275: \fImax-lease-time\fR and \fIdefault-lease-time\fR server options in
276: .B dhcpd.conf(5).
277: .RE
278: .PP
279: .B option \fBdhcp-max-message-size\fR \fIuint16\fR\fB;\fR
280: .RS 0.25i
281: .PP
282: This option, when sent by the client, specifies the maximum size of
283: any response that the server sends to the client. When specified on
284: the server, if the client did not send a dhcp-max-message-size option,
285: the size specified on the server is used. This works for BOOTP as
286: well as DHCP responses.
287: .RE
288: .PP
289: .B option \fBdhcp-message\fR \fItext\fR\fB;\fR
290: .RS 0.25i
291: .PP
292: This option is used by a DHCP server to provide an error message to a
293: DHCP client in a DHCPNAK message in the event of a failure. A client
294: may use this option in a DHCPDECLINE message to indicate why the
295: client declined the offered parameters.
296: .PP
297: This option is not user configurable.
298: .RE
299: .PP
300: .B option \fBdhcp-message-type\fR \fIuint8\fR\fB;\fR
301: .RS 0.25i
302: .PP
303: This option, sent by both client and server, specifies the type of DHCP
304: message contained in the DHCP packet. Possible values (taken directly from
305: RFC2132) are:
306: .PP
307: .nf
308: 1 DHCPDISCOVER
309: 2 DHCPOFFER
310: 3 DHCPREQUEST
311: 4 DHCPDECLINE
312: 5 DHCPACK
313: 6 DHCPNAK
314: 7 DHCPRELEASE
315: 8 DHCPINFORM
316: .fi
317: .PP
318: This option is not user configurable.
319: .PP
320: .RE
321: .B option \fBdhcp-option-overload\fR \fIuint8\fR\fB;\fR
322: .RS 0.25i
323: .PP
324: This option is used to indicate that the DHCP \'sname\' or \'file\'
325: fields are being overloaded by using them to carry DHCP options. A
326: DHCP server inserts this option if the returned parameters will
327: exceed the usual space allotted for options.
328: .PP
329: If this option is present, the client interprets the specified
330: additional fields after it concludes interpretation of the standard
331: option fields.
332: .PP
333: Legal values for this option are:
334: .PP
335: .nf
336: 1 the \'file\' field is used to hold options
337: 2 the \'sname\' field is used to hold options
338: 3 both fields are used to hold options
339: .fi
340: .PP
341: This option is not user configurable.
342: .PP
343: .RE
344: .PP
345: .B option \fBdhcp-parameter-request-list\fR \fIuint16\fR [\fB,\fR
346: \fIuint16\fR... ]\fB;\fR
347: .RS 0.25i
348: .PP
349: This option, when sent by the client, specifies which options the
350: client wishes the server to return. Normally, in the ISC DHCP
351: client, this is done using the \fIrequest\fR statement. If this
352: option is not specified by the client, the DHCP server will normally
353: return every option that is valid in scope and that fits into the
354: reply. When this option is specified on the server, the server
355: returns the specified options. This can be used to force a client to
356: take options that it hasn't requested, and it can also be used to
357: tailor the response of the DHCP server for clients that may need a
358: more limited set of options than those the server would normally
359: return.
360: .RE
361: .PP
362: .B option \fBdhcp-rebinding-time\fR \fIuint32\fR\fB;\fR
363: .RS 0.25i
364: .PP
365: This option specifies the number of seconds from the time a client gets
366: an address until the client transitions to the REBINDING state.
367: .PP
368: This option is not user configurable.
369: .PP
370: .RE
371: .PP
372: .B option \fBdhcp-renewal-time\fR \fIuint32\fR\fB;\fR
373: .RS 0.25i
374: .PP
375: This option specifies the number of seconds from the time a client gets
376: an address until the client transitions to the RENEWING state.
377: .PP
378: This option is not user configurable.
379: .PP
380: .RE
381: .PP
382: .B option \fBdhcp-requested-address\fR \fIip-address\fR\fB;\fR
383: .RS 0.25i
384: .PP
385: This option is used by the client in a DHCPDISCOVER to
386: request that a particular IP address be assigned.
387: .PP
388: This option is not user configurable.
389: .PP
390: .RE
391: .PP
392: .B option \fBdhcp-server-identifier\fR \fIip-address\fR\fB;\fR
393: .RS 0.25i
394: .PP
395: This option is used in DHCPOFFER and DHCPREQUEST messages, and may
396: optionally be included in the DHCPACK and DHCPNAK messages. DHCP
397: servers include this option in the DHCPOFFER in order to allow the
398: client to distinguish between lease offers. DHCP clients use the
399: contents of the \'server identifier\' field as the destination address
400: for any DHCP messages unicast to the DHCP server. DHCP clients also
401: indicate which of several lease offers is being accepted by including
402: this option in a DHCPREQUEST message.
403: .PP
404: The value of this option is the IP address of the server.
405: .PP
406: This option is not directly user configurable. See the
407: \fIserver-identifier\fR server option in
408: .B \fIdhcpd.conf(5).
409: .PP
410: .RE
411: .PP
412: .B option \fBdomain-name\fR \fItext\fR\fB;\fR
413: .RS 0.25i
414: .PP
415: This option specifies the domain name that client should use when
416: resolving hostnames via the Domain Name System.
417: .RE
418: .PP
419: .B option \fBdomain-name-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
420: ]\fB;\fR
421: .RS 0.25i
422: .PP
423: The domain-name-servers option specifies a list of Domain Name System
424: (STD 13, RFC 1035) name servers available to the client. Servers
425: should be listed in order of preference.
426: .RE
427: .PP
428: .B option \fBdomain-search\fR \fIdomain-list\fR\fB;\fR
429: .RS 0.25i
430: .PP
431: The domain-search option specifies a \'search list\' of Domain Names to be
432: used by the client to locate not-fully-qualified domain names. The difference
433: between this option and historic use of the domain-name option for the same
434: ends is that this option is encoded in RFC1035 compressed labels on the wire.
435: For example:
436: .nf
437: .sp 1
438: option domain-search "example.com", "sales.example.com",
439: "eng.example.com";
440: .fi
441: .RE
442: .PP
443: .B option \fBextensions-path\fR \fItext\fR\fB;\fR
444: .RS 0.25i
445: .PP
446: This option specifies the name of a file containing additional options
447: to be interpreted according to the DHCP option format as specified in
448: RFC2132.
449: .RE
450: .PP
451: .B option \fBfinger-server\fR \fIip-address\fR [\fB,\fR
452: \fIip-address\fR... ]\fB;\fR
453: .RS 0.25i
454: .PP
455: The Finger server option specifies a list of Finger servers available
456: to the client. Servers should be listed in order of preference.
457: .RE
458: .PP
459: .B option \fBfont-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
460: ]\fB;\fR
461: .RS 0.25i
462: .PP
463: This option specifies a list of X Window System Font servers available
464: to the client. Servers should be listed in order of preference.
465: .RE
466: .PP
467: .B option \fBhost-name\fR \fIstring\fR\fB;\fR
468: .RS 0.25i
469: .PP
470: This option specifies the name of the client. The name may or may
471: not be qualified with the local domain name (it is preferable to use
472: the domain-name option to specify the domain name). See RFC 1035 for
473: character set restrictions. This option is only honored by
474: .B dhclient-script(8)
475: if the hostname for the client machine is not set.
476: .RE
477: .PP
478: .B option \fBieee802-3-encapsulation\fR \fIflag\fR\fB;\fR
479: .RS 0.25i
480: .PP
481: This option specifies whether or not the client should use Ethernet
482: Version 2 (RFC 894) or IEEE 802.3 (RFC 1042) encapsulation if the
483: interface is an Ethernet. A value of false indicates that the client
484: should use RFC 894 encapsulation. A value of true means that the client
485: should use RFC 1042 encapsulation.
486: .RE
487: .PP
488: .B option \fBien116-name-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
489: ];
490: .RS 0.25i
491: .PP
492: The ien116-name-servers option specifies a list of IEN 116 name servers
493: available to the client. Servers should be listed in order of
494: preference.
495: .RE
496: .PP
497: .B option \fBimpress-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
498: ]\fB;\fR
499: .RS 0.25i
500: .PP
501: The impress-server option specifies a list of Imagen Impress servers
502: available to the client. Servers should be listed in order of
503: preference.
504: .RE
505: .PP
506: .B option \fBinterface-mtu\fR \fIuint16\fR\fB;\fR
507: .RS 0.25i
508: .PP
509: This option specifies the MTU to use on this interface. The minimum
510: legal value for the MTU is 68.
511: .RE
512: .PP
513: .B option \fBip-forwarding\fR \fIflag\fR\fB;\fR
514: .RS 0.25i
515: .PP
516: This option specifies whether the client should configure its IP
517: layer for packet forwarding. A value of false means disable IP
518: forwarding, and a value of true means enable IP forwarding.
519: .RE
520: .PP
521: .B option \fBirc-server\fR \fIip-address\fR [\fB,\fR
522: \fIip-address\fR... ]\fB;\fR
523: .RS 0.25i
524: .PP
525: The IRC server option specifies a list of IRC servers available
526: to the client. Servers should be listed in order of preference.
527: .RE
528: .PP
529: .B option \fBlog-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
530: ]\fB;\fR
531: .RS 0.25i
532: .PP
533: The log-server option specifies a list of MIT-LCS UDP log servers
534: available to the client. Servers should be listed in order of
535: preference.
536: .RE
537: .PP
538: .B option \fBlpr-servers\fR \fIip-address \fR [\fB,\fR \fIip-address\fR...
539: ]\fB;\fR
540: .RS 0.25i
541: .PP
542: The LPR server option specifies a list of RFC 1179 line printer
543: servers available to the client. Servers should be listed in order
544: of preference.
545: .RE
546: .PP
547: .B option \fBmask-supplier\fR \fIflag\fR\fB;\fR
548: .RS 0.25i
549: .PP
550: This option specifies whether or not the client should respond to
551: subnet mask requests using ICMP. A value of false indicates that the
552: client should not respond. A value of true means that the client should
553: respond.
554: .RE
555: .PP
556: .B option \fBmax-dgram-reassembly\fR \fIuint16\fR\fB;\fR
557: .RS 0.25i
558: .PP
559: This option specifies the maximum size datagram that the client
560: should be prepared to reassemble. The minimum legal value is
561: 576.
562: .RE
563: .PP
564: .B option \fBmerit-dump\fR \fItext\fR\fB;\fR
565: .RS 0.25i
566: .PP
567: This option specifies the path-name of a file to which the client's
568: core image should be dumped in the event the client crashes. The
569: path is formatted as a character string consisting of characters from
570: the NVT ASCII character set.
571: .RE
572: .PP
573: .B option \fBmobile-ip-home-agent\fR \fIip-address\fR [\fB,\fR \fIip-address\fR... ]\fB;\fR
574: .RS 0.25i
575: .PP
576: This option specifies a list of IP addresses indicating mobile IP
577: home agents available to the client. Agents should be listed in
578: order of preference, although normally there will be only one such
579: agent.
580: .RE
581: .PP
582: .B option \fBnds-context\fR \fIstring\fR\fB;\fR
583: .RS 0.25i
584: .PP
585: The nds-context option specifies the name of the initial Netware
586: Directory Service for an NDS client.
587: .RE
588: .PP
589: .B option \fBnds-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR... ]\fB;\fR
590: .RS 0.25i
591: .PP
592: The nds-servers option specifies a list of IP addresses of NDS servers.
593: .RE
594: .PP
595: .B option \fBnds-tree-name\fR \fIstring\fR\fB;\fR
596: .RS 0.25i
597: .PP
598: The nds-tree-name option specifies NDS tree name that the NDS client
599: should use.
600: .RE
601: .PP
602: .B option \fBnetbios-dd-server\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
603: ]\fB;\fR
604: .RS 0.25i
605: .PP
606: The NetBIOS datagram distribution server (NBDD) option specifies a
607: list of RFC 1001/1002 NBDD servers listed in order of preference.
608: .RE
609: .PP
610: .B option \fBnetbios-name-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...]\fB;\fR
611: .RS 0.25i
612: .PP
613: The NetBIOS name server (NBNS) option specifies a list of RFC
614: 1001/1002 NBNS name servers listed in order of preference. NetBIOS
615: Name Service is currently more commonly referred to as WINS. WINS
616: servers can be specified using the netbios-name-servers option.
617: .RE
618: .PP
619: .B option \fBnetbios-node-type\fR \fIuint8\fR\fB;\fR
620: .RS 0.25i
621: .PP
622: The NetBIOS node type option allows NetBIOS over TCP/IP clients which
623: are configurable to be configured as described in RFC 1001/1002. The
624: value is specified as a single octet which identifies the client type.
625: .PP
626: Possible node types are:
627: .PP
628: .TP 5
629: .I 1
630: B-node: Broadcast - no WINS
631: .TP
632: .I 2
633: P-node: Peer - WINS only
634: .TP
635: .I 4
636: M-node: Mixed - broadcast, then WINS
637: .TP
638: .I 8
639: H-node: Hybrid - WINS, then broadcast
640: .RE
641: .PP
642: .B option \fBnetbios-scope\fR \fIstring\fR\fB;\fR
643: .RS 0.25i
644: .PP
645: The NetBIOS scope option specifies the NetBIOS over TCP/IP scope
646: parameter for the client as specified in RFC 1001/1002. See RFC1001,
647: RFC1002, and RFC1035 for character-set restrictions.
648: .RE
649: .PP
650: .B option \fBnetinfo-server-address\fR \fIip-address\fR [\fB,\fR
651: \fIip-address\fR... ]\fB;\fR
652: .RS 0.25i
653: .PP
654: The \fBnetinfo-server-address\fR option has not been described in any
655: RFC, but has been allocated (and is claimed to be in use) by Apple
656: Computers. It's hard to say if the above is the correct format, or
657: what clients might be expected to do if values were configured. Use
658: at your own risk.
659: .RE
660: .PP
661: .B option \fBnetinfo-server-tag\fR \fItext\fR\fB;\fR
662: .RS 0.25i
663: .PP
664: The \fBnetinfo-server-tag\fR option has not been described in any
665: RFC, but has been allocated (and is claimed to be in use) by Apple
666: Computers. It's hard to say if the above is the correct format,
667: or what clients might be expected to do if values were configured. Use
668: at your own risk.
669: .RE
670: .PP
671: .B option \fBnis-domain\fR \fItext\fR\fB;\fR
672: .RS 0.25i
673: .PP
674: This option specifies the name of the client's NIS (Sun Network
675: Information Services) domain. The domain is formatted as a character
676: string consisting of characters from the NVT ASCII character set.
677: .RE
678: .PP
679: .B option \fBnis-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
680: ]\fB;\fR
681: .RS 0.25i
682: .PP
683: This option specifies a list of IP addresses indicating NIS servers
684: available to the client. Servers should be listed in order of
685: preference.
686: .RE
687: .PP
688: .B option \fBnisplus-domain\fR \fItext\fR\fB;\fR
689: .RS 0.25i
690: .PP
691: This option specifies the name of the client's NIS+ domain. The
692: domain is formatted as a character string consisting of characters
693: from the NVT ASCII character set.
694: .RE
695: .PP
696: .B option \fBnisplus-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
697: ]\fB;\fR
698: .RS 0.25i
699: .PP
700: This option specifies a list of IP addresses indicating NIS+ servers
701: available to the client. Servers should be listed in order of
702: preference.
703: .RE
704: .PP
705: .B option \fBnntp-server\fR \fIip-address\fR [\fB,\fR
706: \fIip-address\fR... ]\fB;\fR
707: .RS 0.25i
708: .PP
709: The NNTP server option specifies a list of NNTP servesr available
710: to the client. Servers should be listed in order of preference.
711: .RE
712: .PP
713: .B option \fBnon-local-source-routing\fR \fIflag\fR\fB;\fR
714: .RS 0.25i
715: .PP
716: This option specifies whether the client should configure its IP
717: layer to allow forwarding of datagrams with non-local source routes
718: (see Section 3.3.5 of [4] for a discussion of this topic). A value
719: of false means disallow forwarding of such datagrams, and a value of true
720: means allow forwarding.
721: .RE
722: .PP
723: .B option \fBntp-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
724: ]\fB;\fR
725: .RS 0.25i
726: .PP
727: This option specifies a list of IP addresses indicating NTP (RFC 1035)
728: servers available to the client. Servers should be listed in order
729: of preference.
730: .RE
731: .PP
732: .B option \fBnwip-domain\fR \fIstring\fR\fB;\fR
733: .RS 0.25i
734: .PP
735: The name of the NetWare/IP domain that a NetWare/IP client should
736: use.
737: .RE
738: .PP
739: .B option \fBnwip-suboptions\fR \fIstring\fR\fB;\fR
740: .RS 0.25i
741: .PP
742: A sequence of suboptions for NetWare/IP clients - see RFC2242 for
743: details. Normally this option is set by specifying specific
744: NetWare/IP suboptions - see the NETWARE/IP SUBOPTIONS section for more
745: information.
746: .RE
747: .PP
748: .B option \fBpath-mtu-aging-timeout\fR \fIuint32\fR\fB;\fR
749: .RS 0.25i
750: .PP
751: This option specifies the timeout (in seconds) to use when aging Path
752: MTU values discovered by the mechanism defined in RFC 1191.
753: .RE
754: .PP
755: .B option \fBpath-mtu-plateau-table\fR \fIuint16\fR [\fB,\fR \fIuint16\fR...
756: ]\fB;\fR
757: .RS 0.25i
758: .PP
759: This option specifies a table of MTU sizes to use when performing
760: Path MTU Discovery as defined in RFC 1191. The table is formatted as
761: a list of 16-bit unsigned integers, ordered from smallest to largest.
762: The minimum MTU value cannot be smaller than 68.
763: .RE
764: .PP
765: .B option \fBperform-mask-discovery\fR \fIflag\fR\fB;\fR
766: .RS 0.25i
767: .PP
768: This option specifies whether or not the client should perform subnet
769: mask discovery using ICMP. A value of false indicates that the client
770: should not perform mask discovery. A value of true means that the
771: client should perform mask discovery.
772: .RE
773: .PP
774: .nf
775: .B option \fBpolicy-filter\fR \fIip-address ip-address\fR
776: [\fB,\fR \fIip-address ip-address\fR...]\fB;\fR
777: .RE
778: .fi
779: .RS 0.25i
780: .PP
781: This option specifies policy filters for non-local source routing.
782: The filters consist of a list of IP addresses and masks which specify
783: destination/mask pairs with which to filter incoming source routes.
784: .PP
785: Any source routed datagram whose next-hop address does not match one
786: of the filters should be discarded by the client.
787: .PP
788: See STD 3 (RFC1122) for further information.
789: .RE
790: .PP
791: .B option \fBpop-server\fR \fIip-address\fR [\fB,\fR \fIip-address\fR... ]\fB;\fR
792: .RS 0.25i
793: .PP
794: The POP3 server option specifies a list of POP3 servers available
795: to the client. Servers should be listed in order of preference.
796: .RE
797: .PP
798: .B option \fBresource-location-servers\fR \fIip-address\fR
799: [\fB, \fR\fIip-address\fR...]\fB;\fR
800: .fi
801: .RS 0.25i
802: .PP
803: This option specifies a list of RFC 887 Resource Location
804: servers available to the client. Servers should be listed in order
805: of preference.
806: .RE
807: .PP
808: .B option \fBroot-path\fR \fItext\fB;\fR\fR
809: .RS 0.25i
810: .PP
811: This option specifies the path-name that contains the client's root
812: disk. The path is formatted as a character string consisting of
813: characters from the NVT ASCII character set.
814: .RE
815: .PP
816: .B option \fBrouter-discovery\fR \fIflag\fR\fB;\fR
817: .RS 0.25i
818: .PP
819: This option specifies whether or not the client should solicit
820: routers using the Router Discovery mechanism defined in RFC 1256.
821: A value of false indicates that the client should not perform
822: router discovery. A value of true means that the client should perform
823: router discovery.
824: .RE
825: .PP
826: .B option \fBrouter-solicitation-address\fR \fIip-address\fR\fB;\fR
827: .RS 0.25i
828: .PP
829: This option specifies the address to which the client should transmit
830: router solicitation requests.
831: .RE
832: .PP
833: .B option routers \fIip-address\fR [\fB,\fR \fIip-address\fR...
834: ]\fB;\fR
835: .RS 0.25i
836: .PP
837: The routers option specifies a list of IP addresses for routers on the
838: client's subnet. Routers should be listed in order of preference.
839: .RE
840: .PP
841: .B option slp-directory-agent \fIboolean ip-address
842: [\fB,\fR \fIip-address\fR... ]\fB;\fR
843: .RS 0.25i
844: .PP
845: This option specifies two things: the IP addresses of one or more
846: Service Location Protocol Directory Agents, and whether the use of
847: these addresses is mandatory. If the initial boolean value is true,
848: the SLP agent should just use the IP addresses given. If the value
849: is false, the SLP agent may additionally do active or passive
850: multicast discovery of SLP agents (see RFC2165 for details).
851: .PP
852: Please note that in this option and the slp-service-scope option, the
853: term "SLP Agent" is being used to refer to a Service Location Protocol
854: agent running on a machine that is being configured using the DHCP
855: protocol.
856: .PP
857: Also, please be aware that some companies may refer to SLP as NDS.
858: If you have an NDS directory agent whose address you need to
859: configure, the slp-directory-agent option should work.
860: .RE
861: .PP
862: .B option slp-service-scope \fIboolean text\fR\fB;\fR
863: .RS 0.25i
864: .PP
865: The Service Location Protocol Service Scope Option specifies two
866: things: a list of service scopes for SLP, and whether the use of this
867: list is mandatory. If the initial boolean value is true, the SLP
868: agent should only use the list of scopes provided in this option;
869: otherwise, it may use its own static configuration in preference to
870: the list provided in this option.
871: .PP
872: The text string should be a comma-separated list of scopes that the
873: SLP agent should use. It may be omitted, in which case the SLP Agent
874: will use the aggregated list of scopes of all directory agents known
875: to the SLP agent.
876: .RE
877: .PP
878: .B option \fBsmtp-server\fR \fIip-address\fR [\fB,\fR
879: \fIip-address\fR... ]\fB;\fR
880: .RS 0.25i
881: .PP
882: The SMTP server option specifies a list of SMTP servers available to
883: the client. Servers should be listed in order of preference.
884: .RE
885: .PP
886: .nf
887: .B option \fBstatic-routes\fR \fIip-address ip-address\fR
888: [\fB,\fR \fIip-address ip-address\fR...]\fB;\fR
889: .fi
890: .RS 0.25i
891: .PP
892: This option specifies a list of static routes that the client should
893: install in its routing cache. If multiple routes to the same
894: destination are specified, they are listed in descending order of
895: priority.
896: .PP
897: The routes consist of a list of IP address pairs. The first address
898: is the destination address, and the second address is the router for
899: the destination.
900: .PP
901: The default route (0.0.0.0) is an illegal destination for a static
902: route. To specify the default route, use the
903: .B routers
904: option. Also, please note that this option is not intended for
905: classless IP routing - it does not include a subnet mask. Since
906: classless IP routing is now the most widely deployed routing standard,
907: this option is virtually useless, and is not implemented by any of the
908: popular DHCP clients, for example the Microsoft DHCP client.
909: .RE
910: .PP
911: .nf
912: .B option \fBstreettalk-directory-assistance-server\fR \fIip-address\fR
913: [\fB,\fR \fIip-address\fR...]\fB;\fR
914: .fi
915: .RS 0.25i
916: .PP
917: The StreetTalk Directory Assistance (STDA) server option specifies a
918: list of STDA servers available to the client. Servers should be
919: listed in order of preference.
920: .RE
921: .PP
922: .B option \fBstreettalk-server\fR \fIip-address\fR [\fB,\fR \fIip-address\fR... ]\fB;\fR
923: .RS 0.25i
924: .PP
925: The StreetTalk server option specifies a list of StreetTalk servers
926: available to the client. Servers should be listed in order of
927: preference.
928: .RE
929: .PP
930: .B option subnet-mask \fIip-address\fR\fB;\fR
931: .RS 0.25i
932: .PP
933: The subnet mask option specifies the client's subnet mask as per RFC
934: 950. If no subnet mask option is provided anywhere in scope, as a
935: last resort dhcpd will use the subnet mask from the subnet declaration
936: for the network on which an address is being assigned. However,
937: .I any
938: subnet-mask option declaration that is in scope for the address being
939: assigned will override the subnet mask specified in the subnet
940: declaration.
941: .RE
942: .PP
943: .B option \fBsubnet-selection\fR \fIstring\fR\fB;\fR
944: .RS 0.25i
945: .PP
946: Sent by the client if an address is required in a subnet other than the one
947: that would normally be selected (based on the relaying address of the
948: connected subnet the request is obtained from). See RFC3011. Note that the
949: option number used by this server is 118; this has not always been the
950: defined number, and some clients may use a different value. Use of this
951: option should be regarded as slightly experimental!
952: .RE
953: .PP
954: This option is not user configurable in the server.
955: .PP
956: .PP
957: .B option \fBswap-server\fR \fIip-address\fR\fB;\fR
958: .RS 0.25i
959: .PP
960: This specifies the IP address of the client's swap server.
961: .RE
962: .PP
963: .B option \fBtcp-keepalive-garbage\fR \fIflag\fR\fB;\fR
964: .RS 0.25i
965: .PP
966: This option specifies whether or not the client should send TCP
967: keepalive messages with an octet of garbage for compatibility with
968: older implementations. A value of false indicates that a garbage octet
969: should not be sent. A value of true indicates that a garbage octet
970: should be sent.
971: .RE
972: .PP
973: .B option \fBtcp-keepalive-interval\fR \fIuint32\fR\fB;\fR
974: .RS 0.25i
975: .PP
976: This option specifies the interval (in seconds) that the client TCP
977: should wait before sending a keepalive message on a TCP connection.
978: The time is specified as a 32-bit unsigned integer. A value of zero
979: indicates that the client should not generate keepalive messages on
980: connections unless specifically requested by an application.
981: .RE
982: .PP
983: .B option \fBtftp-server-name\fR \fItext\fR\fB;\fR
984: .RS 0.25i
985: .PP
986: This option is used to identify a TFTP server and, if supported by the
987: client, should have the same effect as the \fBserver-name\fR
988: declaration. BOOTP clients are unlikely to support this option.
989: Some DHCP clients will support it, and others actually require it.
990: .RE
991: .PP
992: .B option time-offset \fIint32\fR\fB;\fR
993: .RS 0.25i
994: .PP
995: The time-offset option specifies the offset of the client's subnet in
996: seconds from Coordinated Universal Time (UTC).
997: .RE
998: .PP
999: .B option time-servers \fIip-address\fR [, \fIip-address\fR...
1000: ]\fB;\fR
1001: .RS 0.25i
1002: .PP
1003: The time-server option specifies a list of RFC 868 time servers
1004: available to the client. Servers should be listed in order of
1005: preference.
1006: .RE
1007: .PP
1008: .B option \fBtrailer-encapsulation\fR \fIflag\fR\fB;\fR
1009: .RS 0.25i
1010: .PP
1011: This option specifies whether or not the client should negotiate the
1012: use of trailers (RFC 893 [14]) when using the ARP protocol. A value
1013: of false indicates that the client should not attempt to use trailers. A
1014: value of true means that the client should attempt to use trailers.
1015: .RE
1016: .PP
1017: .B option \fBuap-servers\fR \fItext\fR\fB;\fR
1018: .RS 0.25i
1019: .PP
1020: This option specifies a list of URLs, each pointing to a user
1021: authentication service that is capable of processing authentication
1022: requests encapsulated in the User Authentication Protocol (UAP). UAP
1023: servers can accept either HTTP 1.1 or SSLv3 connections. If the list
1024: includes a URL that does not contain a port component, the normal
1025: default port is assumed (i.e., port 80 for http and port 443 for
1026: https). If the list includes a URL that does not contain a path
1027: component, the path /uap is assumed. If more than one URL is
1028: specified in this list, the URLs are separated by spaces.
1029: .RE
1030: .PP
1031: .B option \fBuser-class\fR \fIstring\fR\fB;\fR
1032: .RS 0.25i
1033: .PP
1034: This option is used by some DHCP clients as a way for users to
1035: specify identifying information to the client. This can be used in a
1036: similar way to the vendor-class-identifier option, but the value of
1037: the option is specified by the user, not the vendor. Most recent
1038: DHCP clients have a way in the user interface to specify the value for
1039: this identifier, usually as a text string.
1040: .RE
1041: .PP
1042: .B option \fBvendor-class-identifier\fR \fIstring\fR\fB;\fR
1043: .RS 0.25i
1044: .PP
1045: This option is used by some DHCP clients to identify the vendor
1046: type and possibly the configuration of a DHCP client. The information
1047: is a string of bytes whose contents are specific to the vendor and are
1048: not specified in a standard. To see what vendor class identifier
1049: clients are sending, you can write the following in your DHCP server
1050: configuration file:
1051: .nf
1052: .PP
1053: set vendor-string = option vendor-class-identifier;
1054: .fi
1055: .PP
1056: This will result in all entries in the DHCP server lease database file
1057: for clients that sent vendor-class-identifier options having a set
1058: statement that looks something like this:
1059: .nf
1060: .PP
1061: set vendor-string = "SUNW.Ultra-5_10";
1062: .fi
1063: .PP
1064: The vendor-class-identifier option is normally used by the DHCP server
1065: to determine the options that are returned in the
1066: .B vendor-encapsulated-options
1067: option. Please see the VENDOR ENCAPSULATED OPTIONS section later in this
1068: manual page for further information.
1069: .RE
1070: .PP
1071: .B option \fBvendor-encapsulated-options\fR \fIstring\fR\fB;\fR
1072: .RS 0.25i
1073: .PP
1074: The \fBvendor-encapsulated-options\fR option can contain either a
1075: single vendor-specific value or one or more vendor-specific
1076: suboptions. This option is not normally specified in the DHCP server
1077: configuration file - instead, a vendor class is defined for each
1078: vendor, vendor class suboptions are defined, values for those
1079: suboptions are defined, and the DHCP server makes up a response on
1080: that basis.
1081: .PP
1082: Some default behaviours for well-known DHCP client vendors (currently,
1083: the Microsoft Windows 2000 DHCP client) are configured automatically,
1084: but otherwise this must be configured manually - see the VENDOR
1085: ENCAPSULATED OPTIONS section later in this manual page for details.
1086: .RE
1087: .PP
1088: .B option \fBvivso\fR \fIstring\fR\fB;\fR
1089: .RS 0.25i
1090: .PP
1091: The \fBvivso\fR option can contain multiple separate options, one for
1092: each 32-bit Enterprise ID. Each Enterprise-ID discriminated option then
1093: contains additional options whose format is defined by the vendor who
1094: holds that ID. This option is usually not configured manually, but
1095: rather is configured via intervening option definitions. Please also
1096: see the VENDOR ENCAPSULATED OPTIONS section later in this manual page
1097: for details.
1098: .RE
1099: .PP
1100: .B option \fBwww-server\fR \fIip-address\fR [\fB,\fR
1101: \fIip-address\fR... ]\fB;\fR
1102: .RS 0.25i
1103: .PP
1104: The WWW server option specifies a list of WWW servers available
1105: to the client. Servers should be listed in order of preference.
1106: .RE
1107: .PP
1108: .B option \fBx-display-manager\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
1109: ]\fB;\fR
1110: .RS 0.25i
1111: .PP
1112: This option specifies a list of systems that are running the X Window
1113: System Display Manager and are available to the client. Addresses
1114: should be listed in order of preference.
1115: .RE
1116: .SH RELAY AGENT INFORMATION OPTION
1117: An IETF draft, draft-ietf-dhc-agent-options-11.txt, defines a series
1118: of encapsulated options that a relay agent can add to a DHCP packet
1119: when relaying it to the DHCP server. The server can then make
1120: address allocation decisions (or whatever other decisions it wants)
1121: based on these options. The server also returns these options in any
1122: replies it sends through the relay agent, so that the relay agent can
1123: use the information in these options for delivery or accounting
1124: purposes.
1125: .PP
1126: The current draft defines two options. To reference
1127: these options in the dhcp server, specify the option space name,
1128: "agent", followed by a period, followed by the option name. It is
1129: not normally useful to define values for these options in the server,
1130: although it is permissible. These options are not supported in the
1131: client.
1132: .PP
1133: .B option \fBagent.circuit-id\fR \fIstring\fR\fB;\fR
1134: .RS 0.25i
1135: .PP
1136: The circuit-id suboption encodes an agent-local identifier of the
1137: circuit from which a DHCP client-to-server packet was received. It is
1138: intended for use by agents in relaying DHCP responses back to the
1139: proper circuit. The format of this option is currently defined to be
1140: vendor-dependent, and will probably remain that way, although the
1141: current draft allows for for the possibility of standardizing the
1142: format in the future.
1143: .RE
1144: .PP
1145: .B option \fBagent.remote-id\fR \fIstring\fR\fB;\fR
1146: .RS 0.25i
1147: .PP
1148: The remote-id suboption encodes information about the remote host end
1149: of a circuit. Examples of what it might contain include caller ID
1150: information, username information, remote ATM address, cable modem ID,
1151: and similar things. In principal, the meaning is not well-specified,
1152: and it should generally be assumed to be an opaque object that is
1153: administratively guaranteed to be unique to a particular remote end of
1154: a circuit.
1155: .RE
1156: .PP
1157: .B option \fBagent.DOCSIS-device-class\fR \fIuint32\fR\fB;\fR
1158: .RS 0.25i
1159: .PP
1160: The DOCSIS-device-class suboption is intended to convey information about
1161: the host endpoint, hardware, and software, that either the host operating
1162: system or the DHCP server may not otherwise be aware of (but the relay is
1163: able to distinguish). This is implemented as a 32-bit field (4 octets),
1164: each bit representing a flag describing the host in one of these ways.
1165: So far, only bit zero (being the least significant bit) is defined in
1166: RFC3256. If this bit is set to one, the host is considered a CPE
1167: Controlled Cable Modem (CCCM). All other bits are reserved.
1168: .RE
1169: .PP
1170: .B option \fBagent.link-selection\fR \fIip-address\fR\fB;\fR
1171: .RS 0.25i
1172: .PP
1173: The link-selection suboption is provided by relay agents to inform servers
1174: what subnet the client is actually attached to. This is useful in those
1175: cases where the giaddr (where responses must be sent to the relay agent)
1176: is not on the same subnet as the client. When this option is present in
1177: a packet from a relay agent, the DHCP server will use its contents to find
1178: a subnet declared in configuration, and from here take one step further
1179: backwards to any shared-network the subnet may be defined within...the
1180: client may be given any address within that shared network, as normally
1181: appropriate.
1182: .RE
1183: .SH THE CLIENT FQDN SUBOPTIONS
1184: The Client FQDN option, currently defined in the Internet Draft
1185: draft-ietf-dhc-fqdn-option-00.txt is not a standard yet, but is in
1186: sufficiently wide use already that we have implemented it. Due to
1187: the complexity of the option format, we have implemented it as a
1188: suboption space rather than a single option. In general this
1189: option should not be configured by the user - instead it should be
1190: used as part of an automatic DNS update system.
1191: .PP
1192: .B option fqdn.no-client-update \fIflag\fB;
1193: .RS 0.25i
1194: .PP
1195: When the client sends this, if it is true, it means the client will not
1196: attempt to update its A record. When sent by the server to the client,
1197: it means that the client \fIshould not\fR update its own A record.
1198: .RE
1199: .PP
1200: .B option fqdn.server-update \fIflag\fB;
1201: .RS 0.25i
1202: .PP
1203: When the client sends this to the server, it is requesting that the server
1204: update its A record. When sent by the server, it means that the server
1205: has updated (or is about to update) the client's A record.
1206: .RE
1207: .PP
1208: .B option fqdn.encoded \fIflag\fB;
1209: .RS 0.25i
1210: .PP
1211: If true, this indicates that the domain name included in the option is
1212: encoded in DNS wire format, rather than as plain ASCII text. The client
1213: normally sets this to false if it doesn't support DNS wire format in the
1214: FQDN option. The server should always send back the same value that the
1215: client sent. When this value is set on the configuration side, it controls
1216: the format in which the \fIfqdn.fqdn\fR suboption is encoded.
1217: .RE
1218: .PP
1219: .B option fqdn.rcode1 \fIflag\fB;
1220: .PP
1221: .B option fqdn.rcode2 \fIflag\fB;
1222: .RS 0.25i
1223: .PP
1224: These options specify the result of the updates of the A and PTR records,
1225: respectively, and are only sent by the DHCP server to the DHCP client.
1226: The values of these fields are those defined in the DNS protocol specification.
1227: .RE
1228: .PP
1229: .B option fqdn.fqdn \fItext\fB;
1230: .RS 0.25i
1231: .PP
1232: Specifies the domain name that the client wishes to use. This can be a
1233: fully-qualified domain name, or a single label. If there is no trailing
1234: \'.\' character in the name, it is not fully-qualified, and the server will
1235: generally update that name in some locally-defined domain.
1236: .RE
1237: .PP
1238: .B option fqdn.hostname \fI--never set--\fB;
1239: .RS 0.25i
1240: .PP
1241: This option should never be set, but it can be read back using the \fBoption\fR
1242: and \fBconfig-option\fR operators in an expression, in which case it returns
1243: the first label in the \fBfqdn.fqdn\fR suboption - for example, if
1244: the value of \fBfqdn.fqdn\fR is "foo.example.com.", then \fBfqdn.hostname\fR
1245: will be "foo".
1246: .RE
1247: .PP
1248: .B option fqdn.domainname \fI--never set--\fB;
1249: .RS 0.25i
1250: .PP
1251: This option should never be set, but it can be read back using the \fBoption\fR
1252: and \fBconfig-option\fR operators in an expression, in which case it returns
1253: all labels after the first label in the \fBfqdn.fqdn\fR suboption - for
1254: example, if the value of \fBfqdn.fqdn\fR is "foo.example.com.",
1255: then \fBfqdn.hostname\fR will be "example.com.". If this suboption value
1256: is not set, it means that an unqualified name was sent in the fqdn option,
1257: or that no fqdn option was sent at all.
1258: .RE
1259: .PP
1260: If you wish to use any of these suboptions, we strongly recommend that you
1261: refer to the Client FQDN option draft (or standard, when it becomes a
1262: standard) - the documentation here is sketchy and incomplete in comparison,
1263: and is just intended for reference by people who already understand the
1264: Client FQDN option specification.
1265: .SH THE NETWARE/IP SUBOPTIONS
1266: RFC2242 defines a set of encapsulated options for Novell NetWare/IP
1267: clients. To use these options in the dhcp server, specify the option
1268: space name, "nwip", followed by a period, followed by the option name.
1269: The following options can be specified:
1270: .PP
1271: .B option \fBnwip.nsq-broadcast\fR \fIflag\fR\fB;\fR
1272: .RS 0.25i
1273: .PP
1274: If true, the client should use the NetWare Nearest Server Query to
1275: locate a NetWare/IP server. The behaviour of the Novell client if
1276: this suboption is false, or is not present, is not specified.
1277: .PP
1278: .RE
1279: .B option \fBnwip.preferred-dss\fR \fIip-address\fR [\fB,\fR \fIip-address\fR... ]\fR\fB;\fR
1280: .RS 0.25i
1281: .PP
1282: This suboption specifies a list of up to five IP addresses, each of
1283: which should be the IP address of a NetWare Domain SAP/RIP server
1284: (DSS).
1285: .RE
1286: .PP
1287: .B option \fBnwip.nearest-nwip-server\fR \fI\fIip-address\fR
1288: [\fB,\fR \fIip-address\fR...]\fR\fB;\fR
1289: .RS 0.25i
1290: .PP
1291: This suboption specifies a list of up to five IP addresses, each of
1292: which should be the IP address of a Nearest NetWare IP server.
1293: .RE
1294: .PP
1295: .B option \fBnwip.autoretries\fR \fIuint8\fR\fB;\fR
1296: .RS 0.25i
1297: .PP
1298: Specifies the number of times that a NetWare/IP client should attempt
1299: to communicate with a given DSS server at startup.
1300: .RE
1301: .PP
1302: .B option \fBnwip.autoretry-secs\fR \fIuint8\fR\fB;\fR
1303: .RS 0.25i
1304: .PP
1305: Specifies the number of seconds that a Netware/IP client should wait
1306: between retries when attempting to establish communications with a DSS
1307: server at startup.
1308: .RE
1309: .PP
1310: .B option \fBnwip.nwip-1-1\fR \fIuint8\fR\fB;\fR
1311: .RS 0.25i
1312: .PP
1313: If true, the NetWare/IP client should support NetWare/IP version 1.1
1314: compatibility. This is only needed if the client will be contacting
1315: Netware/IP version 1.1 servers.
1316: .RE
1317: .PP
1318: .B option \fBnwip.primary-dss\fR \fIip-address\fR\fB;\fR
1319: .RS 0.25i
1320: .PP
1321: Specifies the IP address of the Primary Domain SAP/RIP Service server
1322: (DSS) for this NetWare/IP domain. The NetWare/IP administration
1323: utility uses this value as Primary DSS server when configuring a
1324: secondary DSS server.
1325: .RE
1326: .SH STANDARD DHCPV6 OPTIONS
1327: DHCPv6 options differ from DHCPv4 options partially due to using
1328: 16-bit code and length tags, but semantically zero-length options
1329: are legal in DHCPv6, and multiple options are treated differently.
1330: Whereas in DHCPv4 multiple options would be concatenated to form one
1331: option, in DHCPv6 they are expected to be individual instantiations.
1332: Understandably, many options are not "allowed" to have multiple
1333: instances in a packet - normally these are options which are digested
1334: by the DHCP protocol software, and not by users or applications.
1335: .PP
1336: .B option \fBdhcp6.client-id\fR \fIstring\fR\fB;\fR
1337: .RS 0.25i
1338: .PP
1339: This option specifies the client's DUID identifier. DUIDs are similar
1340: but different from DHCPv4 client identifiers - there are documented duid
1341: types:
1342: .PP
1343: .I duid-llt
1344: .PP
1345: .I duid-en
1346: .PP
1347: .I duid-ll
1348: .PP
1349: This value should not be configured, but rather is provided by clients
1350: and treated as an opaque identifier key blob by servers.
1351: .RE
1352: .PP
1353: .B option \fBdhcp6.server-id\fR \fIstring\fR\fB;\fR
1354: .RS 0.25i
1355: .PP
1356: This option specifies the server's DUID identifier. One may use this
1357: option to configure an opaque binary blob for your server's identifier.
1358: .RE
1359: .PP
1360: .B option \fBdhcp6.ia-na\fR \fIstring\fR\fB;\fR
1361: .RS 0.25i
1362: .PP
1363: The Identity Association for Non-temporary Addresses (ia-na) carries
1364: assigned addresses that are not temporary addresses for use by the
1365: DHCPv6 client. This option is produced by the DHCPv6 server software,
1366: and should not be configured.
1367: .RE
1368: .PP
1369: .B option \fBdhcp6.ia-ta\fR \fIstring\fR\fB;\fR
1370: .RS 0.25i
1371: .PP
1372: The Identity Association for Temporary Addresses (ia-ta) carries
1373: temporary addresses, which may change upon every renewal. There is
1374: no support for this in the current DHCPv6 software.
1375: .RE
1376: .PP
1377: .B option \fBdhcp6.ia-addr\fR \fIstring\fR\fB;\fR
1378: .RS 0.25i
1379: .PP
1380: The Identity Association Address option is encapsulated inside ia-na
1381: or ia-ta options in order to represent addresses associated with those
1382: IA's. These options are manufactured by the software, so should not
1383: be configured.
1384: .RE
1385: .PP
1386: .B option \fBdhcp6.oro\fR \fIuint16\fR [ \fB,\fR \fIuint16\fR\fB,\fR ... ]\fB;\fR
1387: .RS 0.25i
1388: .PP
1389: The Option Request Option ("ORO") is the DHCPv6 equivalent of the
1390: parameter-request-list. Clients supply this option to ask servers
1391: to reply with options relevant to their needs and use. This option
1392: must not be directly configured, the request syntax in dhclient.conf (5)
1393: should be used instead.
1394: .RE
1395: .PP
1396: .B option \fBdhcp6.preference\fR \fIuint8\fR\fB;\fR
1397: .RS 0.25i
1398: .PP
1399: The \fBpreference\fR option informs a DHCPv6 client which server is
1400: \'preferred\' for use on a given subnet. This preference is only
1401: applied during the initial stages of configuration - once a client
1402: is bound to an IA, it will remain bound to that IA until it is no
1403: longer valid or has expired. This value may be configured on the
1404: server, and is digested by the client software.
1405: .RE
1406: .PP
1407: .B option \fBdhcp6.elapsed-time\fR \fIuint16\fR\fB;\fR
1408: .RS 0.25i
1409: .PP
1410: The \fBelapsed-time\fR option is constructed by the DHCPv6 client
1411: software, and is potentially consumed by intermediaries. This
1412: option should not be configured.
1413: .RE
1414: .PP
1415: .B option \fBdhcp6.relay-msg\fR \fIstring\fR\fB;\fR
1416: .RS 0.25i
1417: .PP
1418: The \fBrelay-msg\fR option is constructed by intervening DHCPv6
1419: relay agent software. This option is entirely used by protocol
1420: software, and is not meant for user configuration.
1421: .RE
1422: .PP
1423: .B option \fBdhcp6.unicast\fR \fIip6-address\fR\fB;\fR
1424: .RS 0.25i
1425: .PP
1426: The \fBunicast\fR option is provided by DHCPv6 servers which are
1427: willing (or prefer) to receive Renew packets from their clients
1428: by exchanging UDP unicasts with them. Normally, DHCPv6 clients
1429: will multicast their Renew messages. This may be configured on
1430: the server, and should be configured as an address the server
1431: is ready to reply to.
1432: .RE
1433: .PP
1434: .B option \fBdhcp6.status-code\fR \fIstatus-code\fR [ \fIstring\fR ] \fB;\fR
1435: .RS 0.25i
1436: .PP
1437: The \fBstatus-code\fR option is provided by DHCPv6 servers to inform
1438: clients of error conditions during protocol communication. This option
1439: is manufactured and digested by protocol software, and should not be
1440: configured.
1441: .RE
1442: .PP
1443: .B option \fBdhcp6.rapid-commit\fR \fB;\fR
1444: .RS 0.25i
1445: .PP
1446: The \fBrapid-commit\fR option is a zero-length option that clients use
1447: to indicate their desire to enter into rapid-commit with the server. This
1448: option is not supported by the client at this time, and is digested by
1449: the server when present, so should not be configured.
1450: .RE
1451: .PP
1452: .B option \fBdhcp6.vendor-opts\fR \fIstring\fR\fB;\fR
1453: .RS 0.25i
1454: .PP
1455: The \fBvendor-opts\fR option is actually an encapsulated sub-option space,
1456: in which each Vendor-specific Information Option (VSIO) is identified by
1457: a 32-bit Enterprise-ID number. The encapsulated option spaces within these
1458: options are defined by the vendors.
1459: .PP
1460: To make use of this option, the best way is to examine the section
1461: titled VENDOR ENCAPSULATED OPTIONS below, in particular the bits about
1462: the "vsio" option space.
1463: .RE
1464: .PP
1465: .B option \fBdhcp6.interface-id\fR \fIstring\fR\fB;\fR
1466: .RS 0.25i
1467: .PP
1468: The \fBinterface-id\fR option is manufactured by relay agents, and may
1469: be used to guide configuration differentiating clients by the interface
1470: they are remotely attached to. It does not make sense to configure a
1471: value for this option, but it may make sense to inspect its contents.
1472: .RE
1473: .PP
1474: .B option \fBdhcp6.reconf-msg\fR \fIdhcpv6-message\fR\fB;\fR
1475: .RS 0.25i
1476: .PP
1477: The \fBreconf-msg\fR option is manufactured by servers, and sent to
1478: clients in Reconfigure messages to inform them of what message
1479: the client should Reconfigure using. There is no support for
1480: DHCPv6 Reconfigure extensions, and this option is documented
1481: informationally only.
1482: .RE
1483: .PP
1484: .B option \fBdhcp6.reconf-accept ;\fR
1485: .RS 0.25i
1486: .PP
1487: The \fBreconf-accept\fR option is included by DHCPv6 clients that
1488: support the Reconfigure extentions, advertising that they will
1489: respond if the server were to ask them to Reconfigure. There is
1490: no support for DHCPv6 Reconfigure extensions, and this option is
1491: documented informationally only.
1492: .RE
1493: .PP
1494: .B option \fBdhcp6.sip-servers-names\fR \fIdomain-list\fR\fB;\fR
1495: .RS 0.25i
1496: .PP
1497: The \fBsip-servers-names\fR option allows SIP clients to locate a
1498: local SIP server that is to be used for all outbound SIP requests, a
1499: so-called"outbound proxy server." If you wish to use manually entered
1500: IPv6 addresses instead, please see the \fBsip-servers-addresses\fR option
1501: below.
1502: .RE
1503: .PP
1504: .B option
1505: .B dhcp6.sip-servers-addresses
1506: .I ip6-address \fR[\fB,\fR
1507: .I ip6-address \fR... ]
1508: .B ;
1509: .RS 0.25i
1510: .PP
1511: The \fBsip-servers-addresses\fR option allows SIP clients to locate
1512: a local SIP server that is to be used for all outbound SIP requests,
1513: a so-called "outbound proxy servers." If you wish to use domain names
1514: rather than IPv6 addresses, please see the \fBsip-servers-names\fR option
1515: above.
1516: .RE
1517: .PP
1518: .B option
1519: .B dhcp6.name-servers
1520: .I ip6-address \fR[\fB,\fR
1521: .I ip6-address \fR... ]
1522: .B ;
1523: .RS 0.25i
1524: .PP
1525: The \fBname-servers\fR option instructs clients about locally available
1526: recursive DNS servers. It is easiest to describe this as the "nameserver"
1527: line in /etc/resolv.conf.
1528: .RE
1529: .PP
1530: .B option \fBdhcp6.domain-search\fR \fIdomain-list\fR\fB;\fR
1531: .RS 0.25i
1532: .PP
1533: The \fBdomain-search\fR option specifies the client's domain search path
1534: to be applied to recursive DNS queries. It is easiest to describe this as
1535: the "search" line in /etc/resolv.conf.
1536: .RE
1537: .PP
1538: .B option \fBdhcp6.ia-pd\fR \fIstring\fR\fB;\fR
1539: .RS 0.25i
1540: .PP
1541: The \fBia-pd\fR option is manufactured by clients and servers to create a
1542: Prefix Delegation binding - to delegate an IPv6 prefix to the client. It is
1543: not directly edited in dhcpd.conf(5) or dhclient.conf(5), but rather is
1544: manufactured and consumed by the software.
1545: .RE
1546: .PP
1547: .B option \fBdhcp6.ia-prefix\fR \fIstring\fR\fB;\fR
1548: .RS 0.25i
1549: .PP
1550: The \fBia-prefix\fR option is placed inside \fBia-pd\fR options in order
1551: to identify the prefix(es) allocated to the client. It is not directly
1552: edited in dhcpd.conf(5) or dhclient.conf(5), but rather is
1553: manufactured and consumed by the software.
1554: .RE
1555: .PP
1556: .B option
1557: .B dhcp6.nis-servers
1558: .I ip6-address \fR[\fB,
1559: .I ip6-address \fR... ]
1560: .B ;
1561: .RS 0.25i
1562: .PP
1563: The \fBnis-servers\fR option identifies, in order, NIS servers available
1564: to the client.
1565: .RE
1566: .PP
1567: .B option
1568: .B dhcp6.nisp-servers
1569: .I ip6-address \fR[\fB,
1570: .I ip6-address \fR... ]
1571: .B ;
1572: .RS 0.25i
1573: .PP
1574: The \fBnisp-servers\fR option identifies, in order, NIS+ servers available
1575: to the client.
1576: .RE
1577: .PP
1578: .B option \fBnis-domain-name\fR \fIdomain-list\fR\fB;\fR
1579: .RS 0.25i
1580: .PP
1581: The \fBnis-domain-name\fR option specifies the NIS domain name the client is
1582: expected to use, and is related to the \fBnis-servers\fR option.
1583: .RE
1584: .PP
1585: .B option \fBnisp-domain-name\fR \fIdomain-list\fR\fB;\fR
1586: .RS 0.25i
1587: .PP
1588: The \fBnisp-domain-name\fR option specifies the NIS+ domain name the client
1589: is expected to use, and is related to the \fBnisp-servers\fR option.
1590: .RE
1591: .PP
1592: .B option
1593: .B dhcp6.sntp-servers
1594: .I ip6-address \fR[\fB,
1595: .I ip6-address \fR... ]
1596: .B ;
1597: .RS 0.25i
1598: .PP
1599: The \fBsntp-servers\fR option specifies a list of local SNTP servers
1600: available for the client to synchronize their clocks.
1601: .RE
1602: .PP
1603: .B option \fBdhcp6.info-refresh-time\fR \fIuint32\fR\fB;\fR
1604: .RS 0.25i
1605: .PP
1606: The \fBinfo-refresh-time\fR option gives DHCPv6 clients using
1607: Information-request messages a hint as to how long they should between
1608: refreshing the information they were given. Note that this option will
1609: only be delivered to the client, and be likely to affect the client's
1610: behaviour, if the client requested the option.
1611: .RE
1612: .PP
1613: .B option \fBdhcp6.bcms-server-d\fR \fIdomain-list\fR\fB;\fR
1614: .RS 0.25i
1615: .PP
1616: The \fBbcms-server-d\fR option contains the domain names of local BCMS
1617: (Broadcast and Multicast Control Services) controllers which the client
1618: may use.
1619: .RE
1620: .PP
1621: .B option
1622: .B dhcp6.bcms-server-a
1623: .I ip6-address \fR[\fB,
1624: .I ip6-address \fR... ]
1625: .B ;
1626: .RS 0.25i
1627: .PP
1628: The \fBbcms-server-a\fR option contains the IPv6 addresses of local BCMS
1629: (Broadcast and Multicast Control Services) controllers which the client
1630: may use.
1631: .RE
1632: .PP
1633: .B option \fBdhcp6.remote-id\fR \fIstring\fR\fB;\fR
1634: .RS 0.25i
1635: .PP
1636: The \fBremote-id\fR option is constructed by relay agents, to inform the
1637: server of details pertaining to what the relay knows about the client (such
1638: as what port it is attached to, and so forth). The contents of this option
1639: have some vendor-specific structure (similar to VSIO), but we have chosen
1640: to treat this option as an opaque field.
1641: .RE
1642: .PP
1643: .B option \fBdhcp6.subscriber-id\fR\fB;\fR
1644: .RS 0.25i
1645: .PP
1646: The \fBsubscriber-id\fR option is an opaque field provided by the relay agent,
1647: which provides additional information about the subscriber in question. The
1648: exact contents of this option depend upon the vendor and/or the operator's
1649: configuration of the remote device, and as such is an opaque field.
1650: .RE
1651: .PP
1652: .B option \fBdhcp6.fqdn\fR \fIstring\fR\fB;\fR
1653: .RS 0.25i
1654: .PP
1655: The \fBfqdn\fR option is normally constructed by the client or server,
1656: and negotiates the client's Fully Qualified Domain Name, as well as which
1657: party is responsible for Dynamic DNS Updates. See the section on the
1658: Client FQDN SubOptions for full details (the DHCPv4 and DHCPv6 FQDN options
1659: use the same "fqdn." encapsulated space, so are in all ways identical).
1660: .RE
1661: .PP
1662: .B option \fBdhcp6.lq-query\fR \fIstring\fR\fB;\fR
1663: .RS 0.25i
1664: .PP
1665: The \fBlq-query\fR option is used internally by for lease query.
1666: .RE
1667: .PP
1668: .B option \fBdhcp6.client-data\fR \fIstring\fR\fB;\fR
1669: .RS 0.25i
1670: .PP
1671: The \fBclient-data\fR option is used internally by for lease query.
1672: .RE
1673: .PP
1674: .B option \fBdhcp6.clt-time\fR \fIuint32\fR\fB;\fR
1675: .RS 0.25i
1676: .PP
1677: The \fBclt-time\fR option is used internally by for lease query.
1678: .RE
1679: .PP
1680: .B option \fBdhcp6.lq-relay-data\fR \fIip6-address string\fR\fB;\fR
1681: .RS 0.25i
1682: .PP
1683: The \fBlq-relay-data\fR option is used internally by for lease query.
1684: .RE
1685: .PP
1686: .B option
1687: .B dhcp6.lq-client-link
1688: .I ip6-address \fR[\fB,\fR
1689: .I ip6-address \fR... ]
1690: .B ;
1691: .RS 0.25i
1692: .PP
1693: The \fBlq-client-link\fR option is used internally by for lease query.
1694: .RE
1695: .PP
1696: .RE
1697: .SH DEFINING NEW OPTIONS
1698: The Internet Systems Consortium DHCP client and server provide the
1699: capability to define new options. Each DHCP option has a name, a
1700: code, and a structure. The name is used by you to refer to the
1701: option. The code is a number, used by the DHCP server and client to
1702: refer to an option. The structure describes what the contents of an
1703: option looks like.
1704: .PP
1705: To define a new option, you need to choose a name for it that is not
1706: in use for some other option - for example, you can't use "host-name"
1707: because the DHCP protocol already defines a host-name option, which is
1708: documented earlier in this manual page. If an option name doesn't
1709: appear in this manual page, you can use it, but it's probably a good
1710: idea to put some kind of unique string at the beginning so you can be
1711: sure that future options don't take your name. For example, you
1712: might define an option, "local-host-name", feeling some confidence
1713: that no official DHCP option name will ever start with "local".
1714: .PP
1715: Once you have chosen a name, you must choose a code. All codes between
1716: 224 and 254 are reserved as \'site-local\' DHCP options, so you can pick
1717: any one of these for your site (not for your product/application). In
1718: RFC3942, site-local space was moved from starting at 128 to starting at
1719: 224. In practice, some vendors have interpreted the protocol rather
1720: loosely and have used option code values greater than 128 themselves.
1721: There's no real way to avoid this problem, and it was thought to be
1722: unlikely to cause too much trouble in practice. If you come across
1723: a vendor-documented option code in either the new or old site-local
1724: spaces, please contact your vendor and inform them about rfc3942.
1725: .PP
1726: The structure of an option is simply the format in which the option
1727: data appears. The ISC DHCP server currently supports a few simple
1728: types, like integers, booleans, strings and IP addresses, and it also
1729: supports the ability to define arrays of single types or arrays of
1730: fixed sequences of types.
1731: .PP
1732: New options are declared as follows:
1733: .PP
1734: .B option
1735: .I new-name
1736: .B code
1737: .I new-code
1738: .B =
1739: .I definition
1740: .B ;
1741: .PP
1742: The values of
1743: .I new-name
1744: and
1745: .I new-code
1746: should be the name you have chosen for the new option and the code you
1747: have chosen. The
1748: .I definition
1749: should be the definition of the structure of the option.
1750: .PP
1751: The following simple option type definitions are supported:
1752: .PP
1753: .B BOOLEAN
1754: .PP
1755: .B option
1756: .I new-name
1757: .B code
1758: .I new-code
1759: .B =
1760: .B boolean
1761: .B ;
1762: .PP
1763: An option of type boolean is a flag with a value of either on or off
1764: (or true or false). So an example use of the boolean type would be:
1765: .nf
1766:
1767: option use-zephyr code 180 = boolean;
1768: option use-zephyr on;
1769:
1770: .fi
1771: .B INTEGER
1772: .PP
1773: .B option
1774: .I new-name
1775: .B code
1776: .I new-code
1777: .B =
1778: .I sign
1779: .B integer
1780: .I width
1781: .B ;
1782: .PP
1783: The \fIsign\fR token should either be blank, \fIunsigned\fR
1784: or \fIsigned\fR. The width can be either 8, 16 or 32, and refers to
1785: the number of bits in the integer. So for example, the following two
1786: lines show a definition of the sql-connection-max option and its use:
1787: .nf
1788:
1789: option sql-connection-max code 192 = unsigned integer 16;
1790: option sql-connection-max 1536;
1791:
1792: .fi
1793: .B IP-ADDRESS
1794: .PP
1795: .B option
1796: .I new-name
1797: .B code
1798: .I new-code
1799: .B =
1800: .B ip-address
1801: .B ;
1802: .PP
1803: An option whose structure is an IP address can be expressed either as
1804: a domain name or as a dotted quad. So the following is an example use
1805: of the ip-address type:
1806: .nf
1807:
1808: option sql-server-address code 193 = ip-address;
1809: option sql-server-address sql.example.com;
1810:
1811: .fi
1812: .B IP6-ADDRESS
1813: .PP
1814: .B option
1815: .I new-name
1816: .B code
1817: .I new-code
1818: .B =
1819: .B ip6-address
1820: .B ;
1821: .PP
1822: An option whose structure is an IPv6 address must be expressed as
1823: a valid IPv6 address. The following is an example use of the
1824: ip6-address type:
1825: .nf
1826:
1827: option dhcp6.some-server code 1234 = array of ip6-address;
1828: option dhcp6.some-server 3ffe:bbbb:aaaa:aaaa::1, 3ffe:bbbb:aaaa:aaaa::2;
1829:
1830: .fi
1831: .PP
1832: .B TEXT
1833: .PP
1834: .B option
1835: .I new-name
1836: .B code
1837: .I new-code
1838: .B =
1839: .B text
1840: .B ;
1841: .PP
1842: An option whose type is text will encode an ASCII text string. For
1843: example:
1844: .nf
1845:
1846: option sql-default-connection-name code 194 = text;
1847: option sql-default-connection-name "PRODZA";
1848:
1849: .fi
1850: .PP
1851: .B DATA STRING
1852: .PP
1853: .B option
1854: .I new-name
1855: .B code
1856: .I new-code
1857: .B =
1858: .B string
1859: .B ;
1860: .PP
1861: An option whose type is a data string is essentially just a collection
1862: of bytes, and can be specified either as quoted text, like the text
1863: type, or as a list of hexadecimal contents separated by colons whose
1864: values must be between 0 and FF. For example:
1865: .nf
1866:
1867: option sql-identification-token code 195 = string;
1868: option sql-identification-token 17:23:19:a6:42:ea:99:7c:22;
1869:
1870: .fi
1871: .PP
1872: .B DOMAIN-LIST
1873: .PP
1874: .B option
1875: .I new-name
1876: .B code
1877: .I new-code
1878: .B =
1879: .B domain-list
1880: .B [compressed]
1881: .B ;
1882: .PP
1883: An option whose type is \fBdomain-list\fR is an RFC1035 formatted (on the
1884: wire, "DNS Format") list of domain names, separated by root labels. The
1885: optional \fBcompressed\fR keyword indicates if the option should be
1886: compressed relative to the start of the option contents (not the packet
1887: contents).
1888: .PP
1889: When in doubt, omit the \fBcompressed\fR keyword. When the software recieves
1890: an option that is compressed and the \fBcompressed\fR keyword is omitted, it
1891: will still decompress the option (relative to the option contents field). The
1892: keyword only controls whether or not transmitted packets are compressed.
1893: .PP
1894: Note that when
1895: .B domain-list
1896: formatted options are output as environment variables to
1897: .B dhclient-script(8),
1898: the standard DNS \-escape mechanism is used: they are decimal. This is
1899: appropriate for direct use in eg /etc/resolv.conf.
1900: .nf
1901:
1902: .fi
1903: .PP
1904: .B ENCAPSULATION
1905: .PP
1906: .B option
1907: .I new-name
1908: .B code
1909: .I new-code
1910: .B =
1911: .B encapsulate
1912: .I identifier
1913: .B ;
1914: .PP
1915: An option whose type is \fBencapsulate\fR will encapsulate the
1916: contents of the option space specified in \fIidentifier\fR. Examples
1917: of encapsulated options in the DHCP protocol as it currently exists
1918: include the vendor-encapsulated-options option, the netware-suboptions
1919: option and the relay-agent-information option.
1920: .nf
1921:
1922: option space local;
1923: option local.demo code 1 = text;
1924: option local-encapsulation code 197 = encapsulate local;
1925: option local.demo "demo";
1926:
1927: .fi
1928: .PP
1929: .B ARRAYS
1930: .PP
1931: Options can contain arrays of any of the above types except for the
1932: text and data string types, which aren't currently supported in
1933: arrays. An example of an array definition is as follows:
1934: .nf
1935:
1936: option kerberos-servers code 200 = array of ip-address;
1937: option kerberos-servers 10.20.10.1, 10.20.11.1;
1938:
1939: .fi
1940: .B RECORDS
1941: .PP
1942: Options can also contain data structures consisting of a sequence of
1943: data types, which is sometimes called a record type. For example:
1944: .nf
1945:
1946: option contrived-001 code 201 = { boolean, integer 32, text };
1947: option contrived-001 on 1772 "contrivance";
1948:
1949: .fi
1950: It's also possible to have options that are arrays of records, for
1951: example:
1952: .nf
1953:
1954: option new-static-routes code 201 = array of {
1955: ip-address, ip-address, ip-address, integer 8 };
1956: option static-routes
1957: 10.0.0.0 255.255.255.0 net-0-rtr.example.com 1,
1958: 10.0.1.0 255.255.255.0 net-1-rtr.example.com 1,
1959: 10.2.0.0 255.255.224.0 net-2-0-rtr.example.com 3;
1960:
1961: .fi
1962: .SH VENDOR ENCAPSULATED OPTIONS
1963: The DHCP protocol defines the \fBvendor-encapsulated-options\fR
1964: option, which allows vendors to define their own options that will be
1965: sent encapsulated in a standard DHCP option. It also defines
1966: the \fBVendor Identified Vendor Sub Options\fR option ("VIVSO"), and the
1967: DHCPv6 protocol defines the \fBVendor-specific Information Option\fR
1968: ("VSIO"). The format of all of these options is usually internally a
1969: string of options, similarly to other normal DHCP options. The VIVSO
1970: and VSIO options differ in that that they contain options that correspond
1971: to vendor Enterprise-ID numbers (assigned by IANA), which then contain
1972: options according to each Vendor's specifications. You will need to refer
1973: to your vendor's documentation in order to form options to their
1974: specification.
1975: .PP
1976: The value of these options can be set in one of two ways. The first
1977: way is to simply specify the data directly, using a text string or a
1978: colon-separated list of hexadecimal values. For help in forming these
1979: strings, please refer to \fBRFC2132\fR for the DHCPv4 \fBVendor Specific
1980: Information Option\fR, \fBRFC3925\fR for the DHCPv4 \fBVendor Identified Vendor
1981: Sub Options\fR, or \fBRFC3315\fR for the DHCPv6 \fBVendor-specific Information
1982: Option\fR. For example:
1983: .PP
1984: .nf
1985: option vendor-encapsulated-options
1986: 2:4:
1987: AC:11:41:1:
1988: 3:12:
1989: 73:75:6e:64:68:63:70:2d:73:65:72:76:65:72:31:37:2d:31:
1990: 4:12:
1991: 2f:65:78:70:6f:72:74:2f:72:6f:6f:74:2f:69:38:36:70:63;
1992: option vivso
1993: 00:00:09:bf:0E:
1994: 01:0c:
1995: 48:65:6c:6c:6f:20:77:6f:72:6c:64:21;
1996: option dhcp6.vendor-opts
1997: 00:00:09:bf:
1998: 00:01:00:0c:
1999: 48:65:6c:6c:6f:20:77:6f:72:6c:64:21;
2000: .fi
2001: .PP
2002: The second way of setting the value of these options is to have the DHCP
2003: server generate a vendor-specific option buffer. To do this, you
2004: must do four things: define an option space, define some options in
2005: that option space, provide values for them, and specify that that
2006: option space should be used to generate the relevant option.
2007: .PP
2008: To define a new option space in which vendor options can be stored,
2009: use the \fRoption space\fP statement:
2010: .PP
2011: .B option
2012: .B space
2013: .I name
2014: .B [ [ code width
2015: .I number
2016: .B ] [ length width
2017: .I number
2018: .B ] [ hash size
2019: .I number
2020: .B ] ] ;
2021: .PP
2022: Where the numbers following \fBcode width\fR, \fBlength width\fR,
2023: and \fBhash size\fR respectively identify the number of bytes used to
2024: describe option codes, option lengths, and the size in buckets of the
2025: hash tables to hold options in this space (most DHCPv4 option spaces
2026: use 1 byte codes and lengths, which is the default, whereas most
2027: DHCPv6 option spaces use 2 byte codes and lengths).
2028: .PP
2029: The code and length widths are used in DHCP protocol - you must configure
2030: these numbers to match the applicable option space you are configuring.
2031: They each default to 1. Valid values for code widths are 1, 2 or 4.
2032: Valid values for length widths are 0, 1 or 2. Most DHCPv4 option spaces
2033: use 1 byte codes and lengths, which is the default, whereas most DHCPv6
2034: option spaces use 2 byte codes and lengths. A zero-byte length produces
2035: options similar to the DHCPv6 Vendor-specific Information Option - but
2036: not their contents!
2037: .PP
2038: The hash size defaults depend upon the \fBcode width\fR selected, and
2039: may be 254 or 1009. Valid values range between 1 and 65535. Note
2040: that the higher you configure this value, the more memory will be used. It
2041: is considered good practice to configure a value that is slightly larger
2042: than the estimated number of options you plan to configure within the
2043: space. Previous versions of ISC DHCP (up to and including DHCP 3.0.*),
2044: this value was fixed at 9973.
2045: .PP
2046: The name can then be used in option definitions, as described earlier in
2047: this document. For example:
2048: .nf
2049:
2050: option space SUNW code width 1 length width 1 hash size 3;
2051: option SUNW.server-address code 2 = ip-address;
2052: option SUNW.server-name code 3 = text;
2053: option SUNW.root-path code 4 = text;
2054:
2055: option space ISC code width 1 length width 1 hash size 3;
2056: option ISC.sample code 1 = text;
2057: option vendor.ISC code 2495 = encapsulate vivso-sample;
2058: option vendor-class.ISC code 2495 = text;
2059:
2060: option ISC.sample "configuration text here";
2061: option vendor-class.ISC "vendor class here";
2062:
2063: option space docsis code width 2 length width 2 hash size 17;
2064: option docsis.tftp-servers code 32 = array of ip6-address;
2065: option docsis.cablelabs-configuration-file code 33 = text;
2066: option docsis.cablelabs-syslog-servers code 34 = array of ip6-address;
2067: option docsis.device-id code 36 = string;
2068: option docsis.time-servers code 37 = array of ip6-address;
2069: option docsis.time-offset code 38 = signed integer 32;
2070: option vsio.docsis code 4491 = encapsulate docsis;
2071:
2072: .fi
2073: Once you have defined an option space and the format of some options,
2074: you can set up scopes that define values for those options, and you
2075: can say when to use them. For example, suppose you want to handle
2076: two different classes of clients. Using the option space definition
2077: shown in the previous example, you can send different option values to
2078: different clients based on the vendor-class-identifier option that the
2079: clients send, as follows:
2080: .PP
2081: .nf
2082: class "vendor-classes" {
2083: match option vendor-class-identifier;
2084: }
2085:
2086: subclass "vendor-classes" "SUNW.Ultra-5_10" {
2087: vendor-option-space SUNW;
2088: option SUNW.root-path "/export/root/sparc";
2089: }
2090:
2091: subclass "vendor-classes" "SUNW.i86pc" {
2092: vendor-option-space SUNW;
2093: option SUNW.root-path "/export/root/i86pc";
2094: }
2095:
2096: option SUNW.server-address 172.17.65.1;
2097: option SUNW.server-name "sundhcp-server17-1";
2098:
2099: option vivso-sample.sample "Hello world!";
2100:
2101: option docsis.tftp-servers ::1;
2102:
2103: .fi
2104: .PP
2105: As you can see in the preceding example, regular scoping rules apply,
2106: so you can define values that are global in the global scope, and only
2107: define values that are specific to a particular class in the local
2108: scope. The \fBvendor-option-space\fR declaration tells the DHCP
2109: server to use options in the SUNW option space to construct the DHCPv4
2110: .B vendor-encapsulated-options
2111: option. This is a limitation of that option - the DHCPv4 VIVSO and the
2112: DHCPv6 VSIO options can have multiple vendor definitions all at once (even
2113: transmitted to the same client), so it is not necessary to configure this.
2114: .SH SEE ALSO
2115: dhcpd.conf(5), dhcpd.leases(5), dhclient.conf(5), dhcp-eval(5), dhcpd(8),
2116: dhclient(8), RFC2132, RFC2131, RFC3046, RFC3315.
2117: .SH AUTHOR
2118: The Internet Systems Consortium DHCP Distribution was written by Ted
2119: Lemon under a contract with Vixie Labs. Funding for
2120: this project was provided through Internet Systems Consortium.
2121: Information about Internet Systems Consortium can be found at
2122: .B https://www.isc.org.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dhcp-options.5 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / dhcp / common