dhcpd-options

Section: File Formats (5)
Index Return to Main Contents

NAME

dhcp-options - Dynamic Host Configuration Protocol options

DESCRIPTION

The Dynamic Host Configuration protocol allows the client to receive options from the DHCP server describing the network configuration and various services that are available on the network. When configuring dhcpd(8) or 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.

REFERENCE: OPTION STATEMENTS

DHCP option statements always start with the option 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.

Option data comes in a variety of formats, as defined below:

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

The ip6-address data specifies an IPv6 address, like ::1 or 3ffe:bbbb:aaaa:aaaa::1.

The int32 data type specifies a signed 32-bit integer. The uint32 data type specifies an unsigned 32-bit integer. The int16 and uint16 data types specify signed and unsigned 16-bit integers. The int8 and uint8 data types specify signed and unsigned 8-bit integers. Unsigned 8-bit integers are also sometimes referred to as octets.

The 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


option root-path "10.0.1.4:/var/tmp/rootfs";

The domain-name data type specifies a domain name, which must not be 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.

The domain-list data type specifies a list of domain names, enclosed in double quotes and separated by commas ("example.com", "foo.example.com").

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

The 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:


  option dhcp-client-identifier "CLIENT-FOO";
or
  option dhcp-client-identifier 43:4c:49:45:54:2d:46:4f:4f;

The destination-descriptor describe the IP subnet number and subnet mask of a particular destination using a compact encoding. This encoding consists of one octet describing the width of the subnet mask, followed by all the significant octets of the subnet number. The following table contains some examples of how various subnet number/mask combinations can be encoded:


Subnet number   Subnet mask      Destination descriptor
0               0                0
10.0.0.0        255.0.0.0        8.10
10.0.0.0        255.255.255.0    24.10.0.0
10.17.0.0       255.255.0.0      16.10.17
10.27.129.0     255.255.255.0    24.10.27.129
10.229.0.128    255.255.255.128  25.10.229.0.128
10.198.122.47   255.255.255.255  32.10.198.122.47

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


  option my-option = expression ;

For example:


  option hostname = binary-to-ascii (16, 8, "-",
                                     substring (hardware, 1, 6));

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

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 after the configuration file has been processed. In the following documentation, such options will be shown as "not user configurable"

The standard options are:

option all-subnets-local flag;

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

option arp-cache-timeout uint32;

: This option specifies the timeout in seconds for ARP cache entries.

option bcms-controller-address ip-address [, ip-address... ];

: This option configures a list of IPv4 addresses for use as Broadcast and Multicast Controller Servers ("BCMS").

option bcms-controller-names domain-list;

: This option contains the domain names of local Broadcast and Multicast Controller Servers ("BCMS") controllers which the client may use.

option bootfile-name text;

: This option is used to identify a bootstrap file. If supported by the client, it should have the same effect as the filename declaration. BOOTP clients are unlikely to support this option. Some DHCP clients will support it, and others actually require it.

option boot-size uint16;

: This option specifies the length in 512-octet blocks of the default boot image for the client.

option broadcast-address ip-address;

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

option cookie-servers ip-address [, ip-address... ];

: The cookie server option specifies a list of RFC 865 cookie servers available to the client. Servers should be listed in order of preference.

option default-ip-ttl uint8;

: This option specifies the default time-to-live that the client should use on outgoing datagrams.

option default-tcp-ttl uint8;

: This option specifies the default TTL that the client should use when sending TCP segments. The minimum value is 1.

option default-url string;

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

option dhcp-client-identifier string;

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.

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:


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

rather than:

        option dhcp-client-identifier "foo";

option dhcp-lease-time uint32;

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.

This option is not directly user configurable in the server; refer to the max-lease-time and default-lease-time server options in dhcpd.conf(5).

option dhcp-max-message-size uint16;

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

option dhcp-message text;

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.