dhcp-options.5

DHCP服务器源码

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,
and is just intended for reference by people who already understand the
Client FQDN option specification.
.SH THE NETWARE/IP SUBOPTIONS
RFC2242 defines a set of encapsulated options for Novell NetWare/IP
clients.  To use these options in the dhcp server, specify the option
space name, "nwip", followed by a period, followed by the option name.
The following options can be specified:
.PP
.B option \fBnwip.nsq-broadcast\fR \fIflag\fR\fB;\fR
.RS 0.25i
.PP
If true, the client should use the NetWare Nearest Server Query to
locate a NetWare/IP server.   The behaviour of the Novell client if
this suboption is false, or is not present, is not specified.
.PP
.RE
.B option \fBnwip.preferred-dss\fR \fIip-address\fR [\fB,\fR \fIip-address\fR... ]\fR\fB;\fR
.RS 0.25i
.PP
This suboption specifies a list of up to five IP addresses, each of
which should be the IP address of a NetWare Domain SAP/RIP server
(DSS).
.RE
.PP
.B option \fBnwip.nearest-nwip-server\fR \fI\fIip-address\fR
                             [\fB,\fR \fIip-address\fR...]\fR\fB;\fR
.RS 0.25i
.PP
This suboption specifies a list of up to five IP addresses, each of
which should be the IP address of a Nearest NetWare IP server.
.RE
.PP
.B option \fBnwip.autoretries\fR \fIuint8\fR\fB;\fR
.RS 0.25i
.PP
Specifies the number of times that a NetWare/IP client should attempt
to communicate with a given DSS server at startup.
.RE
.PP
.B option \fBnwip.autoretry-secs\fR \fIuint8\fR\fB;\fR
.RS 0.25i
.PP
Specifies the number of seconds that a Netware/IP client should wait
between retries when attempting to establish communications with a DSS
server at startup.
.RE
.PP
.B option \fBnwip.nwip-1-1\fR \fIuint8\fR\fB;\fR
.RS 0.25i
.PP
If true, the NetWare/IP client should support NetWare/IP version 1.1
compatibility.   This is only needed if the client will be contacting
Netware/IP version 1.1 servers.
.RE
.PP
.B option \fBnwip.primary-dss\fR \fIip-address\fR\fB;\fR
.RS 0.25i
.PP
Specifies the IP address of the Primary Domain SAP/RIP Service server
(DSS) for this NetWare/IP domain.   The NetWare/IP administration
utility uses this value as Primary DSS server when configuring a
secondary DSS server.
.RE
.SH DEFINING NEW OPTIONS
The Internet Systems Consortium DHCP client and server provide the
capability to define new options.   Each DHCP option has a name, a
code, and a structure.   The name is used by you to refer to the
option.   The code is a number, used by the DHCP server and client to
refer to an option.   The structure describes what the contents of an
option looks like.
.PP
To define a new option, you need to choose a name for it that is not
in use for some other option - for example, you can't use "host-name"
because the DHCP protocol already defines a host-name option, which is
documented earlier in this manual page.   If an option name doesn't
appear in this manual page, you can use it, but it's probably a good
idea to put some kind of unique string at the beginning so you can be
sure that future options don't take your name.   For example, you
might define an option, "local-host-name", feeling some confidence
that no official DHCP option name will ever start with "local".
.PP
Once you have chosen a name, you must choose a code.  For site-local
options, all codes between 128 and 254 are reserved for DHCP options,
so you can pick any one of these.  In practice, some vendors have
interpreted the protocol rather loosely and have used option code
values greater than 128 themselves.   There's no real way to avoid
this problem, but it's not likely to cause too much trouble in
practice.
.PP
The structure of an option is simply the format in which the option
data appears.   The ISC DHCP server currently supports a few simple
types, like integers, booleans, strings and IP addresses, and it also
supports the ability to define arrays of single types or arrays of
fixed sequences of types.
.PP
New options are declared as follows:
.PP
.B option
.I new-name
.B code
.I new-code
.B =
.I definition
.B ;
.PP
The values of
.I new-name
and
.I new-code
should be the name you have chosen for the new option and the code you
have chosen.   The
.I definition
should be the definition of the structure of the option.
.PP
The following simple option type definitions are supported:
.PP
.B BOOLEAN
.PP
.B option
.I new-name
.B code
.I new-code
.B =
.B boolean
.B ;
.PP
An option of type boolean is a flag with a value of either on or off
(or true or false).   So an example use of the boolean type would be:
.nf

option use-zephyr code 180 = boolean;
option use-zephyr on;

.fi
.B INTEGER
.PP
.B option
.I new-name
.B code
.I new-code
.B =
.I sign
.B integer
.I width
.B ;
.PP
The \fIsign\fR token should either be blank, \fIunsigned\fR
or \fIsigned\fR.   The width can be either 8, 16 or 32, and refers to
the number of bits in the integer.   So for example, the following two
lines show a definition of the sql-connection-max option and its use:
.nf

option sql-connection-max code 192 = unsigned integer 16;
option sql-connection-max 1536;

.fi
.B IP-ADDRESS
.PP
.B option
.I new-name
.B code
.I new-code
.B =
.B ip-address
.B ;
.PP
An option whose structure is an IP address can be expressed either as
a domain name or as a dotted quad.  So the following is an example use
of the ip-address type:
.nf

option sql-server-address code 193 = ip-address;
option sql-server-address sql.example.com;

.fi
.PP
.B TEXT
.PP
.B option
.I new-name
.B code
.I new-code
.B =
.B text
.B ;
.PP
An option whose type is text will encode an ASCII text string.   For
example:
.nf

option sql-default-connection-name code 194 = text;
option sql-default-connection-name "PRODZA";

.fi
.PP
.B DATA STRING
.PP
.B option
.I new-name
.B code
.I new-code
.B =
.B string
.B ;
.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 separated by colons whose
values must be between 0 and FF.   For example:
.nf

option sql-identification-token code 195 = string;
option sql-identification-token 17:23:19:a6:42:ea:99:7c:22;

.fi
.PP
.B ENCAPSULATION
.PP
.B option
.I new-name
.B code
.I new-code
.B =
.B encapsulate
.I identifier
.B ;
.PP
An option whose type is \fBencapsulate\fR will encapsulate the
contents of the option space specified in \fIidentifier\fR.   Examples
of encapsulated options in the DHCP protocol as it currently exists
include the vendor-encapsulated-options option, the netware-suboptions
option and the relay-agent-information option.
.nf

option space local;
option local.demo code 1 = text;
option local-encapsulation code 197 = encapsulate local;
option local.demo "demo";

.fi
.PP
.B ARRAYS
.PP
Options can contain arrays of any of the above types except for the
text and data string types, which aren't currently supported in
arrays.   An example of an array definition is as follows:
.nf

option kerberos-servers code 200 = array of ip-address;
option kerberos-servers 10.20.10.1, 10.20.11.1;

.fi
.B RECORDS
.PP
Options can also contain data structures consisting of a sequence of
data types, which is sometimes called a record type.   For example:
.nf

option contrived-001 code 201 = { boolean, integer 32, text };
option contrived-001 on 1772 "contrivance";

.fi
It's also possible to have options that are arrays of records, for
example:
.nf

option new-static-routes code 201 = array of {
	ip-address, ip-address, ip-address, integer 8 };
option static-routes
	10.0.0.0 255.255.255.0 net-0-rtr.example.com 1,
	10.0.1.0 255.255.255.0 net-1-rtr.example.com 1,
	10.2.0.0 255.255.224.0 net-2-0-rtr.example.com 3;

.fi	
.SH VENDOR ENCAPSULATED OPTIONS
The DHCP protocol defines the \fB vendor-encapsulated-options\fR
option, which allows vendors to define their own options that will be
sent encapsulated in a standard DHCP option.   The format of the
.B vendor-encapsulated-options
option is either a series of bytes whose format is not specified, or
a sequence of options, each of which consists of a single-byte
vendor-specific option code, followed by a single-byte length,
followed by as many bytes of data as are specified in the length (the
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-separated list of hexadecimal values.   For example:
.PP
.nf
option vendor-encapsulated-options
    2:4:AC:11:41:1:
    3:12:73:75:6e:64:68:63:70:2d:73:65:72:76:65:72:31:37:2d:31:
    4:12:2f:65:78:70:6f:72:74:2f:72:6f:6f:74:2f:69:38:36:70:63;
.fi
.PP
The second way of setting the value of this option is to have the DHCP
server generate a vendor-specific option buffer.   To do this, you
must do four things: define an option space, define some options in
that option space, provide values for them, and specify that that 
option space should be used to generate the
.B vendor-encapsulated-options
option.
.PP
To define a new option space in which vendor options can be stored,
use the \fRoption space\fP statement:
.PP
.B option
.B space
.I name
.B ;
.PP
The name can then be used in option definitions, as described earlier in
this document.   For example:
.nf

option space SUNW;
option SUNW.server-address code 2 = ip-address;
option SUNW.server-name code 3 = text;
option SUNW.root-path code 4 = text;

.fi
Once you have defined an option space and the format of some options,
you can set up scopes that define values for those options, and you
can say when to use them.   For example, suppose you want to handle
two different classes of clients.   Using the option space definition
shown in the previous example, you can send different option values to
different clients based on the vendor-class-identifier option that the
clients send, as follows:
.PP
.nf
class "vendor-classes" {
  match option vendor-class-identifier;
}

option SUNW.server-address 172.17.65.1;
option SUNW.server-name "sundhcp-server17-1";

subclass "vendor-classes" "SUNW.Ultra-5_10" {
  vendor-option-space SUNW;
  option SUNW.root-path "/export/root/sparc";
}

subclass "vendor-classes" "SUNW.i86pc" {
  vendor-option-space SUNW;
  option SUNW.root-path "/export/root/i86pc";
}
.fi
.PP
As you can see in the preceding example, regular scoping rules apply,
so you can define values that are global in the global scope, and only
define values that are specific to a particular class in the local
scope.   The \fBvendor-option-space\fR declaration tells the DHCP
server to use options in the SUNW option space to construct the
.B vendor-encapsulated-options
option.
.SH SEE ALSO
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 Systems Consortium DHCP Distribution was written by Ted
Lemon under a contract with Vixie Labs.  Funding for
this project was provided through Internet Systems Consortium.
Information about Internet Systems Consortium can be found at
.B http://www.isc.org.