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