Merge the last year's worth of work on the branch to the HEAD.

1 files changed, 202 insertions, 36 deletions

diff --git a/common/dhcp-options.5 b/common/dhcp-options.5
index b5efb803..6ea14ef5 100644
--- a/common/dhcp-options.5
+++ b/common/dhcp-options.5
@@ -106,7 +106,7 @@ The
 .B string
 data type specifies either an NVT ASCII string
 enclosed in double quotes, or a series of octets specified in
-hexadecimal, seperated by colons.   For example:
+hexadecimal, separated by colons.   For example:
 .nf
 .sp 1
   option dhcp-client-identifier "CLIENT-FOO";
@@ -139,6 +139,16 @@ such options by defining them in the configuration file.  Please see
 the DEFINING NEW OPTIONS heading later in this document for more
 information.
 .PP
+Some of the options documented here are automatically generated by
+the DHCP server or by clients, and cannot be configured by the user.
+The value of such an option can be used in the configuration file of
+the receiving DHCP protocol agent (server or client), for example in
+conditional expressions. However, the value of the option cannot be
+used in the configuration file of the sending agent, because the value
+is determined only \fIafter\fR the configuration file has been
+processed. In the following documentation, such options will be shown
+as "not user configurable"
+.PP
 The standard options are:
 .PP
 .B option \fBall-subnets-local\fR \fIflag\fR\fB;\fR
@@ -225,6 +235,19 @@ rather than:
 .fi
 .RE
 .PP
+.B option \fBdhcp-lease-time\fR \fIuint32\fR\fB;\fR
+.RS 0.25i
+.PP
+This option is used in a client request (DHCPDISCOVER or DHCPREQUEST)
+to allow the client to request a lease time for the IP address.  In a
+server reply (DHCPOFFER), a DHCP server uses this option to specify
+the lease time it is willing to offer.                                    
+.PP
+This option is not directly user configurable in the server; refer to the
+\fImax-lease-time\fR and \fidefault-lease-time\fR server options in
+.B dhcpd.conf(5).
+.RE
+.PP
 .B option \fBdhcp-max-message-size\fR \fIuint16\fR\fB;\fR
 .RS 0.25i
 .PP
@@ -235,6 +258,62 @@ the size specified on the server is used.   This works for BOOTP as
 well as DHCP responses.
 .RE
 .PP
+.B option \fBdhcp-message\fR \fItext\fR\fB;\fR
+.RS 0.25i
+.PP
+This option is used by a DHCP server to provide an error message to a
+DHCP client in a DHCPNAK message in the event of a failure. A client
+may use this option in a DHCPDECLINE message to indicate why the
+client declined the offered parameters.
+.PP
+This option is not user configurable.
+.RE
+.PP
+.B option \fBdhcp-message-type\fR \fIuint8\fR\fB;\fR
+.RS 0.25i
+.PP
+This option, sent by both client and server, specifies the type of DHCP
+message contained in the DHCP packet. Possible values (taken directly from
+RFC2132) are:
+.PP
+.nf
+             1     DHCPDISCOVER
+             2     DHCPOFFER
+             3     DHCPREQUEST
+             4     DHCPDECLINE
+             5     DHCPACK
+             6     DHCPNAK
+             7     DHCPRELEASE
+             8     DHCPINFORM               
+.fi
+.PP
+This option is not user configurable.
+.PP
+.RE
+.B option \fBdhcp-option-overload\fR \fIuint8\fR\fB;\fR
+.RS 0.25i
+.PP
+This option is used to indicate that the DHCP 'sname' or 'file'
+fields are being overloaded by using them to carry DHCP options. A
+DHCP server inserts this option if the returned parameters will
+exceed the usual space allotted for options.
+.PP
+If this option is present, the client interprets the specified
+additional fields after it concludes interpretation of the standard
+option fields.
+.PP
+Legal values for this option are:
+.PP
+.nf
+             1     the 'file' field is used to hold options
+             2     the 'sname' field is used to hold options
+             3     both fields are used to hold options                        
+.fi
+.PP
+This option is not user configurable.
+.PP
+.RE
+.PP
 .B option \fBdhcp-parameter-request-list\fR \fIuint16\fR\fB;\fR
 .RS 0.25i
 .PP
@@ -251,6 +330,56 @@ more limited set of options than those the server would normally
 return.
 .RE
 .PP
+.B option \fBdhcp-rebinding-time\fR \fIuint32\fR\fB;\fR
+.RS 0.25i
+.PP
+This option specifies the number of seconds from the time a client gets
+an address until the client transitions to the REBINDING state.
+.PP
+This option is not user configurable.
+.PP
+.RE
+.PP
+.B option \fBdhcp-renewal-time\fR \fIuint32\fR\fB;\fR
+.RS 0.25i
+.PP
+This option specifies the number of seconds from the time a client gets
+an address until the client transitions to the RENEWING state.
+.PP
+This option is not user configurable.
+.PP
+.RE
+.PP
+.B option \fBdhcp-requested-address\fR \fIip-address\fR\fB;\fR
+.RS 0.25i
+.PP
+This option is used by the client in a DHCPDISCOVER to
+request that a particular IP address be assigned.                 
+.PP
+This option is not user configurable.
+.PP
+.RE
+.PP
+.B option \fBdhcp-server-identifier\fR \fIip-address\fR\fB;\fR
+.RS 0.25i
+.PP
+This option is used in DHCPOFFER and DHCPREQUEST messages, and may
+optionally be included in the DHCPACK and DHCPNAK messages.  DHCP
+servers include this option in the DHCPOFFER in order to allow the
+client to distinguish between lease offers.  DHCP clients use the
+contents of the 'server identifier' field as the destination address
+for any DHCP messages unicast to the DHCP server.  DHCP clients also
+indicate which of several lease offers is being accepted by including
+this option in a DHCPREQUEST message.
+.PP
+The value of this option is the IP address of the server.
+.PP
+This option is not directly user configurable. See the 
+\fIserver-identifier\fR server option in
+.B \fIdhcpd.conf(5).
+.PP
+.RE
+.PP
 .B option \fBdomain-name\fR \fItext\fR\fB;\fR
 .RS 0.25i
 .PP
@@ -267,7 +396,7 @@ The domain-name-servers option specifies a list of Domain Name System
 should be listed in order of preference.
 .RE
 .PP
-.B option \fBextensions-path-name\fR \fItext\fR\fB;\fR
+.B option \fBextensions-path\fR \fItext\fR\fB;\fR
 .RS 0.25i
 .PP
 This option specifies the name of a file containing additional options
@@ -297,7 +426,9 @@ to the client. Servers should be listed in order of preference.
 This option specifies the name of the client.  The name may or may
 not be qualified with the local domain name (it is preferable to use
 the domain-name option to specify the domain name).  See RFC 1035 for
-character set restrictions.
+character set restrictions.  This option is only honored by
+.B dhclient-script(8)
+if the hostname for the client machine is not set.
 .RE
 .PP
 .B option \fBieee802-3-encapsulation\fR \fIflag\fR\fB;\fR
@@ -472,22 +603,6 @@ parameter for the client as specified in RFC 1001/1002. See RFC1001,
 RFC1002, and RFC1035 for character-set restrictions.
 .RE
 .PP
-.B option \fBnwip-domain\fR \fIstring\fR\fB;\fR
-.RS 0.25i
-.PP
-The name of the NetWare/IP domain that a NetWare/IP client should
-use.
-.RE
-.PP
-.B option \fBnwip-suboptions\fR \fIstring\fR\fB;\fR
-.RS 0.25i
-.PP
-A sequence of suboptions for NetWare/IP clients - see RFC2242 for
-details.   Normally this option is set by specifying specific
-NetWare/IP suboptions - see the NETWARE/IP SUBOPTIONS section for more
-information.
-.RE
-.PP
 .B option \fBnis-domain\fR \fItext\fR\fB;\fR
 .RS 0.25i
 .PP
@@ -549,6 +664,22 @@ servers available to the client.  Servers should be listed in order
 of preference.
 .RE
 .PP
+.B option \fBnwip-domain\fR \fIstring\fR\fB;\fR
+.RS 0.25i
+.PP
+The name of the NetWare/IP domain that a NetWare/IP client should
+use.
+.RE
+.PP
+.B option \fBnwip-suboptions\fR \fIstring\fR\fB;\fR
+.RS 0.25i
+.PP
+A sequence of suboptions for NetWare/IP clients - see RFC2242 for
+details.   Normally this option is set by specifying specific
+NetWare/IP suboptions - see the NETWARE/IP SUBOPTIONS section for more
+information.
+.RE
+.PP
 .B option \fBpath-mtu-aging-timeout\fR \fIuint32\fR\fB;\fR
 .RS 0.25i
 .PP
@@ -599,7 +730,6 @@ The POP3 server option specifies a list of POP3 available to the
 client.  Servers should be listed in order of preference.
 .RE
 .PP
-.nf
 .B option \fBresource-location-servers\fR \fIip-address\fR
                               [\fB, \fR\fIip-address\fR...]\fB;\fR
 .fi
@@ -674,7 +804,7 @@ agent should only use the list of scopes provided in this option;
 otherwise, it may use its own static configuration in preference to
 the list provided in this option.
 .PP
-The text string should be a comma-seperated list of scopes that the
+The text string should be a comma-separated list of scopes that the
 SLP agent should use.   It may be omitted, in which case the SLP Agent
 will use the aggregated list of scopes of all directory agents known
 to the SLP agent.
@@ -745,6 +875,20 @@ assigned will override the subnet mask specified in the subnet
 declaration.
 .RE
 .PP
+.B option \fBsubnet-selection\fR \fIstring\fR\fB;\fR
+.RS 0.25i
+.PP
+Sent by the client if an address is required in a subnet other than the one
+that would normally be selected (based on the relaying address of the
+connected subnet the request is obtained from). See RFC3011. Note that the
+option number used by this server is 118; this has not always been the
+defined number, and some clients may use a different value. Use of this
+option should be regarded as slightly experimental!
+.RE
+.PP
+This option is not user configurable in the server.
+.PP
+.PP
 .B option \fBswap-server\fR \fIip-address\fR\fB;\fR
 .RS 0.25i
 .PP
@@ -816,7 +960,7 @@ includes a URL that does not contain a port component, the normal
 default port is assumed (i.e., port 80 for http and port 443 for
 https).  If the list includes a URL that does not contain a path
 component, the path /uap is assumed.   If more than one URL is
-specified in this list, the URLs are seperated by spaces.
+specified in this list, the URLs are separated by spaces.
 .RE
 .PP
 .B option \fBuser-class\fR \fIstring\fR\fB;\fR
@@ -876,6 +1020,14 @@ ENCAPSULATED OPTIONS section of the \fIdhcpd.conf\fI manual page for
 details.
 .RE
 .PP
+.B option \fBwww-server\fR \fIip-address\fR [\fB,\fR
+\fIip-address\fR... ]\fB;\fR
+.RS 0.25i
+.PP
+The WWW server option specifies a list of WWW available to the
+client.  Servers should be listed in order of preference.
+.RE
+.PP
 .B option \fBx-display-manager\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
 ]\fB;\fR
 .RS 0.25i
@@ -884,14 +1036,6 @@ This option specifies a list of systems that are running the X Window
 System Display Manager and are available to the client.  Addresses
 should be listed in order of preference.
 .RE
-.PP
-.B option \fBwww-server\fR \fIip-address\fR [\fB,\fR
-\fIip-address\fR... ]\fB;\fR
-.RS 0.25i
-.PP
-The WWW server option specifies a list of WWW available to the
-client.  Servers should be listed in order of preference.
-.RE
 .SH RELAY AGENT INFORMATION OPTION
 An IETF draft, draft-ietf-dhc-agent-options-11.txt, defines a series
 of encapsulated options that a relay agent can add to a DHCP packet
@@ -965,7 +1109,7 @@ encoded in DNS wire format, rather than as plain ASCII text.   The client
 normally sets this to false if it doesn't support DNS wire format in the
 FQDN option.   The server should always send back the same value that the
 client sent.   When this value is set on the configuration side, it controls
-the format in which the \fIfqdn.name\fR suboption is encoded.
+the format in which the \fIfqdn.fqdn\fR suboption is encoded.
 .RE
 .PP
 .B option fqdn.rcode1 \fIflag\fB;
@@ -978,7 +1122,7 @@ respectively, and are only sent by the DHCP server to the DHCP client.
 The values of these fields are those defined in the DNS protocol specification.
 .RE
 .PP
-.B option fqdn.name \fItext\fB;
+.B option fqdn.fqdn \fItext\fB;
 .RS 0.25i
 .PP
 Specifies the domain name that the client wishes to use.   This can be a
@@ -987,6 +1131,28 @@ fully-qualified domain name, or a single label.   If there is no trailing
 generally update that name in some locally-defined domain.
 .RE
 .PP
+.B option fqdn.hostname \fI--never set--\fB;
+.RS 0.25i
+.PP
+This option should never be set, but it can be read back using the \fBoption\fR
+and \fBconfig-option\fR operators in an expression, in which case it returns
+the first label in the \fBfqdn.fqdn\fR suboption - for example, if
+the value of \fBfqdn.fqdn\fR is "foo.example.com.", then \fBfqdn.hostname\fR
+will be "foo".
+.RE
+.PP
+.B option fqdn.domainname \fI--never set--\fB;
+.RS 0.25i
+.PP
+This option should never be set, but it can be read back using the \fBoption\fR
+and \fBconfig-option\fR operators in an expression, in which case it returns
+all labels after the first label in the \fBfqdn.fqdn\fR suboption - for
+example, if the value of \fBfqdn.fqdn\fR is "foo.example.com.",
+then \fBfqdn.hostname\fR will be "example.com.".   If this suboption value
+is not set, it means that an unqualified name was sent in the fqdn option,
+or that no fqdn option was sent at all.
+.RE
+.PP
 If you wish to use any of these suboptions, we strongly recommend that you
 refer to the Client FQDN option draft (or standard, when it becomes a
 standard) - the documentation here is sketchy and incomplete in comparison,
@@ -1197,7 +1363,7 @@ option sql-default-connection-name "PRODZA";
 .PP
 An option whose type is a data string is essentially just a collection
 of bytes, and can be specified either as quoted text, like the text
-type, or as a list of hexadecimal contents seperated by colons whose
+type, or as a list of hexadecimal contents separated by colons whose
 values must be between 0 and FF.   For example:
 .nf
 
@@ -1277,7 +1443,7 @@ length does not include itself or the option code).
 .PP
 The value of this option can be set in one of two ways.   The first
 way is to simply specify the data directly, using a text string or a
-colon-seperated list of hexadecimal values.   For example:
+colon-separated list of hexadecimal values.   For example:
 .PP
 .nf
 option vendor-encapsulated-options
@@ -1351,7 +1517,7 @@ dhcpd.conf(5), dhcpd.leases(5), dhclient.conf(5), dhcp-eval(5), dhcpd(8),
 dhclient(8), RFC2132, RFC2131, draft-ietf-dhc-agent-options-??.txt.
 .SH AUTHOR
 The Internet Software Consortium DHCP Distribution was written by Ted
-Lemon <mellon@isc.org> under a contract with Vixie Labs.  Funding for
+Lemon under a contract with Vixie Labs.  Funding for
 this project was provided through the Internet Software Consortium.
 Information about the Internet Software Consortium can be found at
-.B http://www.isc.org/isc.
+.B http://www.isc.org.