.\" $Id: dhcp-options.5,v 1.1 2007/11/12 23:16:08 dcantrel Exp $

.\"

.\" Copyright (c) 2004-2007 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

.\"   <info@isc.org>

.\"   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 domain-list

data type specifies a list of domain names, a space between each name and

the entire string enclosed in double quotes.  These types of data are used

for the domain-search option for example, and encodes an RFC1035 compressed

DNS label list on the wire.

.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 \fBbcms-controller-address\fR \fIip-address\fR [\fB,\fR

\fIip-address\fR... ]\fB;\fR

.RS 0.25i

.PP

This option configures a list of IPv4 addresses for use as Broadcast and

Multicast Controller Servers ("BCMS").

.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 \fBdefault-url\fR \fIstring\fR\fB;\fR

.RS 0.25i

.PP

The format and meaning of this option is not described in any standards

document, but is claimed to be in use by Apple Computer.  It is not known

what clients may reasonably do if supplied with this option.  Use at your

own risk.

.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.

.RE

.PP

.B option \fBdomain-name-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

The domain-name-servers option specifies a list of Domain Name System

(STD 13, RFC 1035) name servers available to the client.  Servers

should be listed in order of preference.

.RE

.PP

.B option \fBdomain-search\fR \fIstring\fR\fB;\fR

.RS 0.25i

.PP

The domain-search option specifies a 'search list' of Domain Names to be

used by the client to locate not-fully-qualified domain names.  The difference

between this option and historic use of the domain-name option for the same

ends is that this option is encoded in RFC1035 compressed labels on the wire.

.RE

.PP

.B option \fBextensions-path\fR \fItext\fR\fB;\fR

.RS 0.25i

.PP

This option specifies the name of a file containing additional options

to be interpreted according to the DHCP option format as specified in

RFC2132.

.RE

.PP

.B option \fBfinger-server\fR \fIip-address\fR [\fB,\fR

\fIip-address\fR... ]\fB;\fR

.RS 0.25i

.PP

The Finger server option specifies a list of Finger servers available

to the client.  Servers should be listed in order of preference.

.RE

.PP

.B option \fBfont-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

This option specifies a list of X Window System Font servers available

to the client. Servers should be listed in order of preference.

.RE

.PP

.B option \fBhost-name\fR \fIstring\fR\fB;\fR

.RS 0.25i

.PP

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.  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

.RS 0.25i

.PP

This option specifies whether or not the client should use Ethernet

Version 2 (RFC 894) or IEEE 802.3 (RFC 1042) encapsulation if the

interface is an Ethernet.  A value of false indicates that the client

should use RFC 894 encapsulation.  A value of true means that the client

should use RFC 1042 encapsulation.

.RE

.PP

.B option \fBien116-name-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

];

.RS 0.25i

.PP

The ien116-name-servers option specifies a list of IEN 116 name servers

available to the client.  Servers should be listed in order of

preference.

.RE

.PP

.B option \fBimpress-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

The impress-server option specifies a list of Imagen Impress servers

available to the client.  Servers should be listed in order of

preference.

.RE

.PP

.B option \fBinterface-mtu\fR \fIuint16\fR\fB;\fR

.RS 0.25i

.PP

This option specifies the MTU to use on this interface.   The minimum

legal value for the MTU is 68.

.RE

.PP

.B option \fBip-forwarding\fR \fIflag\fR\fB;\fR

.RS 0.25i

.PP

This option specifies whether the client should configure its IP

layer for packet forwarding.  A value of false means disable IP

forwarding, and a value of true means enable IP forwarding.

.RE

.PP

.B option \fBirc-server\fR \fIip-address\fR [\fB,\fR

\fIip-address\fR... ]\fB;\fR

.RS 0.25i

.PP

The IRC server option specifies a list of IRC servers available

to the client.  Servers should be listed in order of preference.

.RE

.PP

.B option \fBlog-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

The log-server option specifies a list of MIT-LCS UDP log servers

available to the client.  Servers should be listed in order of

preference.

.RE

.PP

.B option \fBlpr-servers\fR \fIip-address \fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

The LPR server option specifies a list of RFC 1179 line printer

servers available to the client.  Servers should be listed in order

of preference.

.RE

.PP

.B option \fBmask-supplier\fR \fIflag\fR\fB;\fR

.RS 0.25i

.PP

This option specifies whether or not the client should respond to

subnet mask requests using ICMP.  A value of false indicates that the

client should not respond.  A value of true means that the client should

respond.

.RE

.PP

.B option \fBmax-dgram-reassembly\fR \fIuint16\fR\fB;\fR

.RS 0.25i

.PP

This option specifies the maximum size datagram that the client

should be prepared to reassemble.  The minimum legal value is

576.

.RE

.PP

.B option \fBmerit-dump\fR \fItext\fR\fB;\fR

.RS 0.25i

.PP

This option specifies the path-name of a file to which the client's

core image should be dumped in the event the client crashes.  The

path is formatted as a character string consisting of characters from

the NVT ASCII character set.

.RE

.PP

.B option \fBmobile-ip-home-agent\fR \fIip-address\fR [\fB,\fR \fIip-address\fR... ]\fB;\fR

.RS 0.25i

.PP

This option specifies a list of IP addresses indicating mobile IP

home agents available to the client.  Agents should be listed in

order of preference, although normally there will be only one such

agent.

.RE

.PP

.B option \fBnds-context\fR \fIstring\fR\fB;\fR

.RS 0.25i

.PP

The nds-context option specifies the name of the initial Netware

Directory Service for an NDS client.

.RE

.PP

.B option \fBnds-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR... ]\fB;\fR

.RS 0.25i

.PP

The nds-servers option specifies a list of IP addresses of NDS servers.

.RE

.PP

.B option \fBnds-tree-name\fR \fIstring\fR\fB;\fR

.RS 0.25i

.PP

The nds-tree-name option specifies NDS tree name that the NDS client

should use.

.RE

.PP

.B option \fBnetbios-dd-server\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

The NetBIOS datagram distribution server (NBDD) option specifies a

list of RFC 1001/1002 NBDD servers listed in order of preference.

.RE

.PP

.B option \fBnetbios-name-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...]\fB;\fR

.RS 0.25i

.PP

The NetBIOS name server (NBNS) option specifies a list of RFC

1001/1002 NBNS name servers listed in order of preference.   NetBIOS

Name Service is currently more commonly referred to as WINS.   WINS

servers can be specified using the netbios-name-servers option.

.RE

.PP

.B option \fBnetbios-node-type\fR \fIuint8\fR\fB;\fR

.RS 0.25i

.PP

The NetBIOS node type option allows NetBIOS over TCP/IP clients which

are configurable to be configured as described in RFC 1001/1002.  The

value is specified as a single octet which identifies the client type.

.PP

Possible node types are:

.PP

.TP 5

.I 1

B-node: Broadcast - no WINS

.TP

.I 2

P-node: Peer - WINS only

.TP

.I 4

M-node: Mixed - broadcast, then WINS

.TP

.I 8

H-node: Hybrid - WINS, then broadcast

.RE

.PP

.B option \fBnetbios-scope\fR \fIstring\fR\fB;\fR

.RS 0.25i

.PP

The NetBIOS scope option specifies the NetBIOS over TCP/IP scope

parameter for the client as specified in RFC 1001/1002. See RFC1001,

RFC1002, and RFC1035 for character-set restrictions.

.RE

.PP

.B option \fBnetinfo-server-address\fR \fIip-address\fR [\fB,\fR

\fIip-address\fR... ]\fB;\fR

.RS 0.25i

.PP

The \fBnetinfo-server-address\fR option has not been described in any

RFC, but has been allocated (and is claimed to be in use) by Apple

Computers.  It's hard to say if the above is the correct format, or

what clients might be expected to do if values were configured.  Use

at your own risk.

.RE

.PP

.B option \fBnetinfo-server-tag\fR \fItext\fR\fB;\fR

.RS 0.25i

.PP

The \fBnetinfo-server-tag\fR option has not been described in any

RFC, but has been allocated (and is claimed to be in use) by Apple

Computers.  It's hard to say if the above is the correct format,

or what clients might be expected to do if values were configured.  Use

at your own risk.

.RE

.PP

.B option \fBnis-domain\fR \fItext\fR\fB;\fR

.RS 0.25i

.PP

This option specifies the name of the client's NIS (Sun Network

Information Services) domain.  The domain is formatted as a character

string consisting of characters from the NVT ASCII character set.

.RE

.PP

.B option \fBnis-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

This option specifies a list of IP addresses indicating NIS servers

available to the client.  Servers should be listed in order of

preference.

.RE

.PP

.B option \fBnisplus-domain\fR \fItext\fR\fB;\fR

.RS 0.25i

.PP

This option specifies the name of the client's NIS+ domain.  The

domain is formatted as a character string consisting of characters

from the NVT ASCII character set.

.RE

.PP

.B option \fBnisplus-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

This option specifies a list of IP addresses indicating NIS+ servers

available to the client.  Servers should be listed in order of

preference.

.RE

.PP

.B option \fBnntp-server\fR \fIip-address\fR [\fB,\fR

\fIip-address\fR... ]\fB;\fR

.RS 0.25i

.PP

The NNTP server option specifies a list of NNTP servesr available

to the client.  Servers should be listed in order of preference.

.RE

.PP

.B option \fBnon-local-source-routing\fR \fIflag\fR\fB;\fR

.RS 0.25i

.PP

This option specifies whether the client should configure its IP

layer to allow forwarding of datagrams with non-local source routes

(see Section 3.3.5 of [4] for a discussion of this topic).  A value

of false means disallow forwarding of such datagrams, and a value of true

means allow forwarding.

.RE

.PP

.B option \fBntp-servers\fR \fIip-address\fR [\fB,\fR \fIip-address\fR...

]\fB;\fR

.RS 0.25i

.PP

This option specifies a list of IP addresses indicating NTP (RFC 1035)

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