The dhcpd.conf Configuration File

When it starts, dhcpd reads its configuration from the /etc/dhcpd.conf file. dhcpd.conf defines the network being served by the DHCP server and the configuration information the server provides to its clients.

dhcpd.conf is an ASCII text file. Comments in the file begin with a sharp sign (#). Keywords are case-insensitive. Whitespace can be used to format the file. Related statements are enclosed in curly braces. IP addresses can be entered as numeric addresses or as hostnames that resolve to addresses.

Statements in the configuration file define the topology of the network being served. In the documentation these statements are called "declarations" because they declare something about the network topology. The statements that define the topology are shared-network, subnet, group, and host. All of these can appear multiple times in the configuration file. The statements define a hierarchical structure. The shared-network contains subnets, and subnets can contain hosts.

Parameters and options can be associated with each of these statements. Parameters define things about the server and the protocol, such as the length of time for an address lease or where the boot file is located. The options provide the clients with values for the standard DHCP configuration options defined by the RFCs, for example, whether the client should enable IP forwarding. Parameters and options specified outside of a specific topology statement apply to all networks served by this server. Those specified in the group statement apply to all of the shared networks, subnets, or hosts grouped together by the statement. The shared-network statement options and parameters apply to all subnets on the shared network. Subnet options and parameters apply to everything on the subnet. Host options and parameters apply only to the individual host. Options applied at a general level can be overridden by the same option applied at a more specific level. Subnet options override global options and host options override subnet options. This structure allows the network administrator to define configuration information for the entire network and all of its parts.

In the following sections, we examine the syntax of all of the topology statements and all the parameters and options that can be associated with them. We include many more parameters and options than you will ever use, and there is no need to study them all. Use this reference to look up the details of individual parameters and options when you need them. See "Local Network Services" for examples of how these statements, parameters, and options are actually used in a real-world configuration.

Topology Statements

• group {[parameters] [options]}
• The group statement groups together shared-network, subnet, host, or other group statements to apply a set of parameters or options to all members of the group.
• shared-network name {[parameters] [options] }
• The shared-network statement is used only if more than one IP subnet shares the same physical network. In most cases, different subnets are on different physical networks. The name, which must be provided, can be any descriptive name. It is used only in debugging messages. Parameters and options associated with the shared network are declared within the curly braces and apply to all subnets in the shared network. The subnets in a shared network must be defined within the curly braces of the shared-network statement. It is assumed that each shared-network statement contains at least two subnet statements; otherwise there is no need to use the shared-subnet statement. dhcpd cannot tell on which subnet of a shared network a client should boot. Therefore, dynamically allocated addresses are taken from the available range of all subnets on the shared network and assigned as needed.
• subnet address mask netmask { [parameters] [options] }
• The subnet statement defines the IP address and address mask of every subnet the daemon will serve. The address and mask are used to identify the clients that belong to the subnet. The parameters and options defined within the curly braces apply to every client on the subnet. Every subnet physically connected to the server must have a subnet statement even if the subnet does not have any clients.
• host hostname {[parameters] [options] }
• The host statement defines parameters and options for individual clients. Every BOOTP client must have a host statement in the dhcpd.conf file. For DHCP clients, the host statement is optional. It is matched to an actual DHCP or BOOTP client by matching the dhcp-client-identifier provided by the client or by matching the hardware parameter to the hardware address of the client. BOOTP clients do not provide a dhcp-client-identifier, so use the hardware address for BOOTP clients. DHCP clients can be identified by either the dhcp-client-identifier or the hardware address.

Configuration Parameters

The parameter statements defined in this section control the operation of the DHCP server and the DHCP protocol. The standard DHCP configuration values that are passed to clients are defined in option statements, which are covered in the next section. Some parameter statements can be associated with any of the topology statements discussed above. Others can be used only with specific statements. These are noted in the description of the parameter.

• range [dynamic-bootp] low-address [high-address] ;
• The range parameter defines the scope of addresses that are available for dynamic assignment by defining the lowest and highest IP addresses available for assignment. The range parameter must be associated with a subnet statement. All addresses in the scope of the range parameter must be in the subnet in which the range parameter is declared. The dynamic-bootp flag is specified if addresses may be automatically assigned to BOOTP clients as well as DHCP clients. The range parameter must be defined if you intend to use dynamic address assignment. If the subnet statement does not include a range parameter, dynamic address assignments are not made to clients on the subnet.
• default-lease-time seconds;
• The life of an address lease in seconds that is used if the client does not request a specific lease length.
• max-lease-time seconds;
• The maximum life of an address lease in seconds regardless of the lease length the client requests.
• hardware type address;
• Defines a client's hardware address. At present, type must be either ethernet or token-ring. address must be an appropriate physical address for the type of hardware. The hardware parameter must be associated with a host statement. It is required for a BOOTP client to be recognized. It is optional for DHCP clients, for which it is an alternative to the dhcp-client-identifier option.
• filename file;
• Identifies the boot file for diskless clients. file is an ASCII string enclosed in quotation marks.
• server-name name;
• The hostname of the DHCP server that is provided to the client. name is an ASCII string enclosed in quotation marks.
• next-server name;
• The hostname or address of the server from which the boot file is to be loaded.
• fixed-address address[, address] ;
• Assigns one or more fixed IP addresses to a host. The fixed-address parameter is valid only when associated with a host statement. If more than one address is supplied, the client is assigned the address that is valid for the subnet on which it is booting. If none of the addresses is valid for the subnet, no configuration data is sent to the client.
• dynamic-bootp-lease-cutoff date;
• Sets a termination date for addresses assigned to BOOTP clients. BOOTP clients don't have a way of renewing leases and don't know that address leases expire. By default, dhcpd assigns permanent addresses to BOOTP clients. This parameter changes that behavior. It is used only in special circumstances where the life of all systems is known in advance -- for example, on a college campus where it is known that all student systems will be removed by June.
• dynamic-bootp-lease-length seconds;
• Defines the life of an address lease in seconds for an address automatically assigned to a BOOTP client. As noted above, BOOTP clients do not understand address leases. This parameter is used only in special circumstances where clients use a BOOTP boot PROM and run an operating system that supports DHCP. During the boot the client acts as a BOOTP client, but once it boots the client runs DHCP and knows how to renew a lease. Use this parameter, and the previous one, with caution.
• get-lease-hostnames flag;
• Tells dhcpd if it should send a DNS hostname to the client when it dynamically assigns it an IP address. If flag is true, dhcpd uses DNS to look up the hostnames for all dynamically assigned addresses, which dramatically slows DHCP performance. By default the flag is false, and no lookups are done.
• use-host-decl-names flag;
• Causes the name provided on the host statement to be supplied to the client as its hostname.
• server-identifier hostname;
• Defines the value sent in the server identifier option. The default is to send the first IP address of the network interface.
• authoritative;
• not authoritative;
• Specifies whether or not the DHCP server is authoritative. The default is authoritative. not authoritative can be used if a DHCP server does not have the authority to set client addresses. It is possible to have a DHCP server that supports multiple networks and has address authority for some networks and no address authority for other networks.
• use-lease-addr-for-default-route flag;
• Causes the leased IP address to be sent to the client as the default route in order to force Windows clients to ARP for all IP addresses. This parameter is used only when the local router is the proxy ARP server. The option routers statement overrides this parameter.
• always-reply-rfc1048 flag;
• Sends responses that comply with RFC 1048 to a BOOTP client, even if that client does not send requests that comply with RFC 1048. This parameter is used when the server logs the message "(non-rfc1048)" for a BOOTP client's BOOTREQUEST. This parameter is generally used on a client-by-client basis. Upgrading the clients to DHCP is preferred.
• allow keyword;
• deny keyword;
• Determines whether or not the server responds to certain types of requests. keyword defines the type of request that is allowed or denied. There are three possible keyword values:
  • unknown-clients
  • Determines whether the server dynamically assigns addresses to unknown clients. By default, dynamic addresses are assigned to unknown clients.
  • bootp
  • Determines whether the server responds to BOOTP requests. By default, BOOTP requests are allowed.
  • booting
  • Used inside a host declaration to specify whether the server responds to a particular client. By default, the DHCP server responds to all clients.

DHCP Options

The option statements available with dhcpd cover all of the standard DHCP configuration options currently defined in the RFCs. Furthermore, the syntax of the dhcpd.conf option statement is extensible. A new option can be identified by its decimal option code. All options are assigned a decimal option code, either in the RFC that describes the option, or in the vendor documentation if it is vendor-specific. The value assigned to the new option can be expressed as a string enclosed in quotes or as a colon-separated list of hexadecimal numbers. Imagine that a new DHCP option is created and assigned an option code of 133. Further, imagine that the value carried by this option is a 16-bit binary mask and that you want your clients to "turn on" the high-order 4-bits and "turn off" all other bits in the mask. You could add the following option to your configuration:

option option-133 F0:00

All option statements begin with the keyword option. The keyword is then followed by the name of the option and the value assigned to the option, in that order. In the example above, the option name is in the form option-nnn, where nnn is the decimal option code assigned to the option. In this manner, any new option that appears can be added to dhcpd.conf file. The value assigned to this imaginary option is F000.

Looking at the huge list of standard options, you may well wonder if they will ever need to be extended. The standard options are listed in the following section. The types of values that are assigned to options are:

• Address
• An IP address written in dotted decimal notation, or a hostname that resolves to an address.
• String
• A series of characters enclosed in quotation marks.
• Number
• A numeric value.
• Flag
• A switch containing either true or false, which can also be set as or , or yes or no.

In this tutorial, the list of options is divided into "Commonly used options" and "Other options."

Commonly used options

• option subnet-mask mask;
• Specifies the subnet mask in dotted decimal notation. If the subnet mask option is not provided, dhcpd uses the network mask from the subnet statement.
• option time-offset seconds;
• Specifies the number of seconds this time zone is offset from Coordinated Universal Time (UTC).
• option routers address[, address] ;
• Lists the routers the client should use, in order of preference.
• option domain-name-servers address[, address] ;
• Lists the Domain Name System (DNS) name servers the client should use, in order of preference.
• option lpr-servers address [, address] ;
• Lists line printer (LPR) servers the client should use, in order of preference.
• option host-name host;
• Defines the hostname the client should use.
• option domain-name domain;
• Defines the domain name.
• option interface-mtu bytes;
• Defines the MTU the client should use. The minimum legal value for the MTU is 68.
• option broadcast-address address;
• Defines the broadcast address for the client's subnet.
• option static-routes destination gateway[, destination gateway] ;
• Lists the static routes the client should use. The default route cannot be specified in this manner. Use the routers option for the default route.
• option trailer-encapsulation 0 | 1;
• Specifies if the client should use trailer encapsulation. 0 means that the client shouldn't use trailer encapsulation, and 1 means that the client should use trailer encapsulation.
• option nis-domain string;
• A character string that defines the name of the Network Information Services (NIS) domain.
• option nis-servers address[, address] ;
• Lists IP addresses of the NIS servers the client should use, in order of preference.
• option dhcp-client-identifier string;
• Used in the host statement to define the DHCP client identifier. dhcpd can use the client identifier to identify DHCP clients in lieu of the hardware address.

Other options

• option time-servers address[, address] ;
• Lists the time servers the client should use, in order of preference.
• option ien116-name-servers address[, address];
• Lists the IEN 116 name servers the client should use, in order of preference. IEN 116 is an obsolete name service. Avoid this and use DNS.
• option log-servers address[, address] ;
• Lists the MIT-LCS UDP log servers the client should use, in order of preference.
• option cookie-servers address[, address] ;
• Lists the cookie servers available to the client, in order of preference.
• option impress-servers address[, address] ;
• Lists the Image Impress servers available to the client, in order of preference.
• option resource-location-servers address[, address] ;
• Lists the Resource Location servers the client should use, in order of preference.
• option boot-size blocks;
• Specifies the number of 512-octet blocks in the boot file.
• option merit-dump path;
• path is a character string that identifies the location of the file the client should dump core to in the event of a crash.
• option swap-server address;
• Specifies the IP address of the client's swap server.
• option root-path path;
• path is a character string that identifies the location of the client's root disk.
• option ip-forwarding 0 | 1;
• Specifies if the client should do IP forwarding. 0 disables IP forwarding, and 1 enables it.
• option non-local-source-routing 0 | 1;
• Specifies if the client should allow non-local source routes. Source routes are a potential security problem, as they can be used by intruders to route data off the local network in ways not intended by the local network administrator. 0 disables forwarding of non-local source-routed datagrams, and 1 enables forwarding. 0 is the more secure setting.
• option policy-filter address mask[, address mask] ;
• Lists the IP addresses and masks that specify the only valid destination/mask pairs for incoming source routes. Any source-routed datagram whose next-hop address does not match one of the filters is discarded by the client.
• option max-dgram-reassembly bytes;
• Defines, in bytes, the largest datagram the client should be prepared to reassemble. The value of bytes cannot be less than 576.
• option default-ip-ttl ttl ;
• Defines the default time-to-live (TTL) for outgoing datagrams.
• option path-mtu-aging-timeout seconds;
• Sets the number of seconds for timing out Path MTU values discovered by the mechanism defined in RFC 1191.
• option path-mtu-plateau-table bytes[, bytes] ;
• Defines a table of MTU sizes to use when performing Path MTU Discovery as defined in RFC 1191. The minimum MTU value cannot be smaller than 68.
• option all-subnets-local 0 | 1;
• Tells the client if all subnets of the local network use the same TU. 1 means that all subnets share the same MTU. 0 means that some subnets have smaller MTUs.
• option perform-mask-discovery 0 | 1;
• Specifies if the client should use ICMP to discover the subnet mask. enables ICMP mask discovery, and 1 disables it. Because the DHCP server can provide the correct subnet mask, ICMP mask discovery is rarely used on networks that have a DHCP server.
• option mask-supplier 0 | 1;
• Specifies if the client should respond to ICMP subnet mask requests. means that the client shouldn't respond, and 1 means that it should.
• option router-discovery 0 | 1;
• Specifies if the client should use the Router Discovery mechanism defined in RFC 1256 to locate routers. 0 means it shouldn't, and 1 means it should perform router discovery. Because the DHCP server provides the correct list of routers, router discovery is rarely used on networks that have a DHCP server.
• option router-solicitation-address address;
• Defines the address to which the client should transmit a router solicitation request if router discovery is enabled.
• option arp-cache-timeout seconds;
• Defines the number of seconds entries are maintained in the ARP cache.
• option ieee802-3-encapsulation 0 | 1;
• Specifies if the client should use Ethernet II (DIX) or IEEE 802.3 Ethernet encapsulation on the network. 0 tells the client to use Ethernet II and 1 tells the client to use IEEE 802.3 encapsulation.
• option default-tcp-ttl ttl;
• Defines the default TTL for TCP segments. Possible values are 1 to 255.
• option tcp-keepalive-interval seconds;
• The number of seconds TCP should wait before sending a keepalive message. 0 means that TCP should not generate keepalive messages. Keepalive messages are generally discouraged.
• option tcp-keepalive-garbage 0 | 1;
• Specifies if the client should send TCP keepalive messages with an octet of garbage for compatibility with older implementations. 0 means don't send a garbage octet and 1 means send it. Keepalives are generally discouraged.
• option ntp-servers address[, address] ;
• Lists the IP addresses of the Network Time Protocol (NTP) servers the client should use, in order of preference.
• option netbios-name-servers address[, address] ;
• Lists the NetBIOS name servers (NBNS) the client should use, in order of preference.
• option netbios-dd-server address[, address] ;
• Lists the NetBIOS datagram distribution servers (NBDD) the client should use, in order of preference.
• option netbios-node-type type;
• Defines the NetBIOS node type of the client. A type of 1 is a NetBIOS B-node; 2 is a P-node; 4 is an M-node; 8 is an H-node.
• option netbios-scope string;
• A character string that defines the NetBIOS over TCP/IP scope parameter as specified in RFC 1001/1002.
• option font-servers address[, address] ;
• Lists the X Window System Font servers the client should use, in order of preference.
• option x-display-manager address[, address] ;
• Lists the systems running the X Window System Display Manager that the client should use, in order of preference.
• option nisplus-domain string;
• Defines the NIS+ domain name.
• option nisplus-servers ip-address [, ip-address];
• Lists the NIS+ servers' IP addresses. Servers are listed in order of preference.
• option tftp-server-name string;
• Identifies a TFTP boot server.
• option bootfile-name string;
• Provides the name of the boot file found on the TFTP boot server.
• option mobile-ip-home-agent ip-address [, ip-address];
• Lists the IP addresses of Mobile IP home agents available to the client.
• option smtp-server ip-address [, ip-address];
• Lists the IP addresses of the SMTP servers in order of preference.
• option pop-server ip-address [, ip-address];
• Lists the IP addresses of POP3 servers in order of preference.
• option nntp-server ip-address [, ip-address];
• Lists the IP addresses of Network News Transport Protocol (NNTP) servers in order of preference.
• option www-server ip-address [, ip-address];
• Lists the IP addresses of web servers in order of preference.
• option finger-server ip-address [, ip-address];
• Lists the IP addresses of finger servers in order of preference.
• option irc-server ip-address [, ip-address];
• Lists the IP addresses of IRC servers in order of preference.
• option streettalk-server ip-address [, ip-address];
• Lists the IP addresses of StreetTalk servers in order of preference.
• option streettalk-directory-assistance-server ip-address [, ip-address];
• Lists the IP addresses of StreetTalk Directory Assistance (STDA) servers in order of preference.