dhcp-options.5

DHCP服务器源码

.\"	$Id: dhcp-options.5,v 1.19.2.11 2004/06/10 17:59:15 dhankins Exp $
.\"
.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1996-2003 by Internet Software Consortium
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"   Internet Systems Consortium, Inc.
.\"   950 Charter Street
.\"   Redwood City, CA 94063
.\"   <[e-mail]>
.\"   http://www.isc.org/
.\"
.\" This software has been written for Internet Systems Consortium
.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
.\" To learn more about Internet Systems Consortium, see
.\" ``http://www.isc.org/''.  To learn more about Vixie Enterprises,
.\" see ``http://www.vix.com''.   To learn more about Nominum, Inc., see
.\" ``http://www.nominum.com''.
.TH dhcpd-options 5
.SH NAME
dhcp-options - Dynamic Host Configuration Protocol options
.SH DESCRIPTION
The Dynamic Host Configuration protocol allows the client to receive
.B options
from the DHCP server describing the network configuration and various
services that are available on the network.   When configuring
.B dhcpd(8)
or
.B dhclient(8) ,
options must often be declared.   The syntax for declaring options,
and the names and formats of the options that can be declared, are
documented here.
.SH REFERENCE: OPTION STATEMENTS
.PP
DHCP \fIoption\fR statements always start with the \fIoption\fR
keyword, followed by an option name, followed by option data.  The
option names and data formats are described below.   It is not
necessary to exhaustively specify all DHCP options - only those
options which are needed by clients must be specified.
.PP
Option data comes in a variety of formats, as defined below:
.PP
The
.B ip-address
data type can be entered either as an explicit IP
address (e.g., 239.254.197.10) or as a domain name (e.g.,
haagen.isc.org).  When entering a domain name, be sure that that
domain name resolves to a single IP address.
.PP
The
.B int32
data type specifies a signed 32-bit integer.   The 
.B uint32
data type specifies an unsigned 32-bit integer.   The 
.B int16
and
.B uint16
data types specify signed and unsigned 16-bit integers.   The 
.B int8
and
.B uint8
data types specify signed and unsigned 8-bit integers.
Unsigned 8-bit integers are also sometimes referred to as octets.
.PP
The
.B text
data type specifies an NVT ASCII string, which must be
enclosed in double quotes - for example, to specify a root-path
option, the syntax would be
.nf
.sp 1
option root-path "10.0.1.4:/var/tmp/rootfs";
.fi
.PP
The
.B domain-name
data type specifies a domain name, which must not
enclosed in double quotes.   This data type is not used for any
existing DHCP options.   The domain name is stored just as if it were
a text option.
.PP
The
.B flag
data type specifies a boolean value.   Booleans can be either true or
false (or on or off, if that makes more sense to you).
.PP
The
.B string
data type specifies either an NVT ASCII string
enclosed in double quotes, or a series of octets specified in
hexadecimal, separated by colons.   For example:
.nf
.sp 1
  option dhcp-client-identifier "CLIENT-FOO";
or
  option dhcp-client-identifier 43:4c:49:45:54:2d:46:4f:4f;
.fi
.SH SETTING OPTION VALUES USING EXPRESSIONS
Sometimes it's helpful to be able to set the value of a DHCP option
based on some value that the client has sent.   To do this, you can
use expression evaluation.   The 
.B dhcp-eval(5)
manual page describes how to write expressions.   To assign the result
of an evaluation to an option, define the option as follows:
.nf
.sp 1
  \fBoption \fImy-option \fB= \fIexpression \fB;\fR
.fi
.PP
For example:
.nf
.sp 1
  option hostname = binary-to-ascii (16, 8, "-",
                                     substring (hardware, 1, 6));
.fi
.SH STANDARD DHCP OPTIONS
The documentation for the various options mentioned below is taken
from the latest IETF draft document on DHCP options.  Options not
listed below may not yet be implemented, but it is possible to use
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
.RS 0.25i
.PP
This option specifies whether or not the client may assume that all
subnets of the IP network to which the client is connected use the
same MTU as the subnet of that network to which the client is
directly connected.  A value of true indicates that all subnets share
the same MTU.  A value of false means that the client should assume that
some subnets of the directly connected network may have smaller MTUs.
.RE
.PP
.B option \fBarp-cache-timeout\fR \fIuint32\fR\fB;\fR
.RS 0.25i
.PP
This option specifies the timeout in seconds for ARP cache entries.
.RE
.PP
.B option \fBbootfile-name\fR \fItext\fR\fB;\fR
.RS 0.25i
.PP
This option is used to identify a bootstrap file.  If supported by the
client, it should have the same effect as the \fBfilename\fR
declaration.  BOOTP clients are unlikely to support this option.  Some
DHCP clients will support it, and others actually require it.
.RE
.PP
.B option \fBboot-size\fR \fIuint16\fR\fB;\fR
.RS 0.25i
.PP
This option specifies the length in 512-octet blocks of the default
boot image for the client.
.RE
.PP
.B option \fBbroadcast-address\fR \fIip-address\fR\fB;\fR
.RS 0.25i
.PP
This option specifies the broadcast address in use on the client's
subnet.  Legal values for broadcast addresses are specified in
section 3.2.1.3 of STD 3 (RFC1122).
.RE
.PP
.B option \fBcookie-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...
]\fB;\fR
.RS 0.25i
.PP
The cookie server option specifies a list of RFC 865 cookie
servers available to the client.  Servers should be listed in order
of preference.
.RE
.PP
.B option \fBdefault-ip-ttl\fR \fIuint8;\fR
.RS 0.25i
.PP
This option specifies the default time-to-live that the client should
use on outgoing datagrams.
.RE
.PP
.B option \fBdefault-tcp-ttl\fR \fIuint8\fR\fB;\fR
.RS 0.25i
.PP
This option specifies the default TTL that the client should use when
sending TCP segments.  The minimum value is 1.
.RE
.PP
.B option \fBdhcp-client-identifier\fR \fIstring\fR\fB;\fR
.RS 0.25i
.PP
This option can be used to specify a DHCP client identifier in a
host declaration, so that dhcpd can find the host record by matching
against the client identifier.
.PP
Please be aware that some DHCP clients, when configured with client
identifiers that are ASCII text, will prepend a zero to the ASCII
text.   So you may need to write:
.nf

	option dhcp-client-identifier "\\0foo";

rather than:

	option dhcp-client-identifier "foo";
.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
This option, when sent by the client, specifies the maximum size of
any response that the server sends to the client.   When specified on
the server, if the client did not send a dhcp-max-message-size option,
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
This option, when sent by the client, specifies which options the
client wishes the server to return.   Normally, in the ISC DHCP
client, this is done using the \fIrequest\fR statement.   If this
option is not specified by the client, the DHCP server will normally
return every option that is valid in scope and that fits into the
reply.   When this option is specified on the server, the server
returns the specified options.   This can be used to force a client to
take options that it hasn't requested, and it can also be used to
tailor the response of the DHCP server for clients that may need a
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
This option specifies the domain name that client should use when
resolving hostnames via the Domain Name System.