DHCPD.CONF(5)

NAME
dhcpd.conf - configuration file for dhcpd (BootP and DHCP server)

SYNPOSIS
/etc/dhcpd.conf

DESCRIPTION
The file /etc/dhcpd.conf contains configuration information used by the BootP and DHCP server, dhcpd(8).

This manual page describes the dhcpd.conf file read by Carnegie Mellon University's dhcpd(8) version 3.3.7 with the Princeton patches (patchlevel 10a2) installed.

The default location of this file is /etc/dhcpd.conf, but that may be overridden via a commandline option to dhcpd(8) or a compile-time option when building dhcpd.

The file consists of a series of statements, one per line. Each statement begins with a keyword followed by zero or more arguments (depending on the keyword); keywords and arguments are separated by spaces or tabs.

Blank lines are ignored. Lines for which the first character is a '#' are treated as comments.

Throughout the discussion below, network refers to an IP network or subnet.

The keywords are as follows:

  readconfinterval
The readconfinterval statement is optional, and may be used to reduce the frequency at which dhcpd(8) checks the dhcpd.conf(5) file for changes.

Specify

    readconfinterval n

where n is an integer (n < 2^32-1)

If unspecified (or specified as 0), then before processing each received packet, the server checks the dhcpd.conf(5) file's modification time. If the file's modification time is newer than the file's modification time at the time the file was last read, the server re-reads the dhcpd.conf(5) file.

If a positive value is specified, then before processing each received packet, the server checks whether the specified number of seconds have passed since the dhcpd.conf(5) file was last read. If fewer seconds have passed, the server does not check file's modification time; the file is not re-read. If the specified number of seconds have passed, the server proceeds to examine the dhcpd.conf(5) file's modification time (as described earlier).

This feature allows you to reduce the frequency of the (relatively) expensive retrieval of the dhcpd.conf(5) file's modification time.

The dhcpd.conf(5) is still re-read when the server is signalled to do so, regardless of the use of readconfinterval. It is also re-read whenever the server re-reads the bootptab(5) file.

  readtabinterval
The readtabinterval statement is optional, and may be used to reduce the frequency at which dhcpd(8) checks the bootptab(5) file for changes.

Specify

    readtabinterval n

where n is an integer (n < 2^32-1)

If unspecified (or specified as 0), then before processing each received packet, the server checks the bootptab(5) file's modification time. If the file's modification time is newer than the file's modification time at the time the file was last read, the server re-reads the bootptab(5) file.

If a positive value is specified, then before processing each received packet, the server checks whether the specified number of seconds have passed since the bootptab(5) file was last read. If fewer seconds have passed, the server does not check file's modification time; the file is not re-read. If the specified number of seconds have passed, the server proceeds to examine the bootptab(5) file's modification time (as described earlier).

This feature allows you to reduce the frequency of the (relatively) expensive retrieval of the bootptab(5) file's modification time.

The bootptab(5) is still re-read when the server is signalled to do so, regardless of the use of readtabinterval.

  delay_reply_dhcpoffer, delay_reply_dhcpack, delay_reply_dhcpnak, delay_reply_bootpreply, delay_reply_default
These statements are optional, and may be used to cause the server to add a delay before sending BOOTPREPLY, DHCPOFFER, DHCPACK, and DHCPNAK packets.

Specify:

    delay_reply_dhcpoffer n

    delay_reply_dhcpack n

    delay_reply_dhcpnak n

    delay_reply_bootpreply n

    delay_reply_default n

where n is an integer (n < 2^32-1) specifying the number of microseconds (millionths of a second) to delay. The delay_reply_default value is used when a no value specific to the flavor of packet has been specified. All values default to 0.

  flushitems, flushinterval
The flushitems and flushinterval statements are each optional, and may be used to change the frequency at which dhcpd(8) flushes lastbinding changes from memory to disk.

By default, changes to the lastbindings data are cached in-memory, and written out to disk once 20 changes have accumulated in the cache, or 30 seconds have elapsed, whichever comes first. They are also written out whenever the server is shut down normally. By default, they are written to the /etc/bindings directory.

Specify:

    flushitems n

where n is an integer (n < 2^32-1) specifying the number of items that should accumulate in the cache before the cache is flushed to disk.

Specify:

    flushinterval n

where n is an integer (n < 2^32-1) specifying the number of seconds that should elapse between cache flushes.

If both flushitems and flushinterval are specified, the cache will be flushed when either condition is met.

As these tunables reduce the amount of information that is not written to disk in the event of an abnormal termination, they need only be set to small values if you often experience server crashes. Otherwise, it makes sense to increase these values.

  gcinterval
The gcinterval statement is optional, and may be used to change the frequency at which dhcpd(8) examines the current bindings in memory to locate those that have expired. During garbage collection, expired bindings are deleted, and any associated dynamically-assigned IP addresses are returned to the pools of IP addresses available for dynamic assignment. By default, garbage collection is performed every 30 seconds. You may wish to increase this; a value of 300 seconds is not unreasonable.

Specify:

    gcinterval n

where n is an integer (n < 2^32-1) specifying the number of seconds that should elapse between garbage collections.

  expire_infinite_dynamics

The expire_infinite_dynamics statement is optional, and is used to enable the Expire Infinite Dynamics feature. See dhcpd(8) for information about the this feature.

Specify:

    expire_infinite_dynamics n

where n is an integer (n < 2^32-1) specifying the number of seconds that a BootP-assigned dynamic IP address assiggment should be considered valid. Such assignments are normally of infinite duration; enabling the Expire Infinite Dynamics feature causes each such assignment instead to be expired n seconds after the assignment is made.

If the expire_infinite_dynamics statement is not present, the Expire Infinite Dyamics feature is not enabled. (The feature is also not enabled if n is 0.)

  network

The network statement is used to declare each IP network for which dhcpd is to provide dynamically-assigned IP addresses. If the server is not to provide dynamically-assigned IP addresses on a given IP network (i.e. it will only be providing statically-assigned IP addresses), no network statement should be present for that network. (If the server does not provide dynamically-assigned IP addresses on any network, then the file will contain no network statements.)

If the server will provide dynamically-assigned IP addresses on several IP networks, specify a network statement for each of these networks. The statement defines the name of the "pool" of dynamic addresses for that network, the network number and netmask, the BootP Relay Agents, and which clients may obtain the dynamic addresses. It does not define the actual IP addresses that comprise the pool; those are defined in the bootptab(5) file.

The format of the network statement is:

    network poolname netnumber netmask accessflags relayagentipaddress relayagentnetmask [ relayagentipaddress relayagentnetmask ]...

where:

poolname
    The poolname is an arbitrary name you associate with this network. The name you choose is unimportant, but each poolname must be unique. The poolname will be used again in the gateway statement, later in this dhcpd.conf file.

netnumber netmask
    The netnumber is the IP network address, and the netmask is the network's IP netmask. If there are multiple network statements in your dhcpd.conf(5) file, the IP network (or subnet) they declare must not overlap. For example, you may not specify two network statements for the same IP subnet, nor two IP networks such that one contains some or all of the IP addresses in the other.

accessflags
    The accessflags is a string consisting of one or more of the following words, separated by vertical bars:

    bootp,dhcp, or both
        Exactly one of these words must be specified. Specify bootp if dynamic IP addresses on this network may be assigned only to BootP clients. Specify dhcp if dynamic IP addresses on this network may be assigned only to DHCP clients. Specify both if dynamic IP addresses on this network may be assigned to both BootP and DHCP clients.

    registered or roaming or unregistered
        Zero or one of these words may be specified.

        Specify registered if dynamic IP addresses on this network should only be assigned to clients who appear somewhere in the bootptab(5) file. If registered is specified, before assigning a dynamic IP address on this network to a client, the server looks for the Client Identifier in the bootptab(5) file; if it appears in any entry (regardless of whether that entry specifies a static IP address), the client is considered to be "registered," and may be assigned a dynamic IP address on this network. If the Client Identifier is not found in any entry, no dynamic IP address on this network will be assigned to this client.

        Specify unregistered if dynamic IP addresses on this network should only be assigned to clients who which do not appear somewhere in the bootptab(5) file. If unregistered is specified, before assigning a dynamic IP address on this network to a client, the server looks for the Client Identifier in the bootptab(5) file; if it appears in any entry (regardless of whether that entry specifies a static IP address), the client is considered to be "registered," and may not be assigned a dynamic IP address on this network.

        Specify roaming if dynamic IP addresses on this network may only be assigned to those clients who not only appear in the the bootptab(5), but also have the boolean :ro: (roaming) tag specified in the entry.

        Specify none of registered, unregistered nor roaming if dynamic IP addresses on this network may be assigned to a client regardless of whether or not the client appears in the bootptab (or contains a :ro: tag in its bootptab entry).

relayagentipaddress relayagentnetmask
    If the network is directly attached to one of this server's interfaces (so that no client requests must traverse a BootP Relay Agent to reach the server) then specify that interface's (primary) IP address and netmask. Otherwise, if requests from clients on this network may traverse a BootP Relay Agent, specify the (primary) IP address and netmask associated with that relay agent's interface on this network. If there are multiple relay agents providing service to this network (a client's request packet may traverse any of several BootP Relay Agents) to reach this server, specify additional relayagentipaddress relayagentnetmask pairs. If the network is a secondary network, sharing the same wire with another (primary) IP network, be sure to specify the relay agent's primary IP address (its address on the primary network), not any secondary IP address.

Although the network statement declares each IP network for which the server may assign IP addresses dynamically, it does not define the specific IP addresses that may be so assigned. Those IP addresses are defined in the bootptab(5) file; what makes them dynamic addresses is that their bootptab(5) entries must contain the :dy: tag, and must not contain any :ht: (hardware type), :ha: (hardware address), or :cl: client identifier), tags. (When the server parses such a bootptab entry, it will determine in which pool of dynamic IP addresses the address belongs by comparing its IP address to the netnumber and netmask values for each network statement in the dhcpd.conf(5) file.

  gateway
The gateway statement is used to describe each BootP Relay Agent on the network, as well as the server's own interfaces. The format is:

    gateway ipaddress netmask [ poolname ]...

One gateway statement is required for each interface on the server. Specify the interface's (primary) IP address and IP netmask. If this server is to serve dynamically-allocated IP addresses on that network associated with this interface, also specify the poolname(s) associated with that network. The poolname(s) are the same arbitrary name(s) specified in network statement(s) earlier.

One gateway statement is also required for every BootP Relay Agent which may forward client requests to the server. Specify the (primary) IP address and netmask corresponding to the relay agent's interface on the network for which the agent is acting. If this server is to serve dynamically-allocated IP addresses on that IP network, also specify the poolname(s) associated with that network. A poolname is the same arbitrary name specified in a network statement earlier.

If a BootP Relay Agent is embedded in an IP router, it typically acts as a relay agent for the network on the far side of the router, from the point of view of the dhcpd(8) server. Therefore, you typically list the (primary) IP address and netmask of the IP router's far interface, not its near one. If the router has additional physical interfaces configured to provide BootP Relay Agents, specify each in its own gateway statement.

  proxy
The proxy statement is used to describe secondary IP networks that share a wire with an IP network served by a previously-defined relay agent or server interface. The format is:

    proxy ipaddress network netmask [ network netmask ]...

Specify the ipaddress of the relay agent or server interface attached to the wire; this should be the device's primary IP address, and should already appear in an earlier gateway statement. Specify the network and netmask describing the secondary IP network running on the wire. If additional IP networks run on the same wire, you may include additional network and netmask pairs, or specify each pair in its own proxy statement.

If the server is to serve dynamically-allocated IP addresses on a secondary network, specify the poolname(s) associated with the secondary network in the earlier gateway statement describing the relay agent or server interface. The poolname is the same arbitrary name specified in a network statement earlier.

  known_server_identifier
The known_server_identifier statement is optionally used to describe each DHCP Server on the network. The format is:

    known_server_identifier ipaddress

Specify the ipaddress of a DHCP server operating on your internetwork. If there are multiple DHCP servers, specify each in a separate statement.

This statement is optional; if present, the server will attempt to log each time a client specifies a Server Identifier Option containing a value that is neither my_ip_addr nor one of those specified as a known_server_identifier. This may help alert you to rogue DHCP servers.

The server checks for a Server Identifier Option in DHCPREQUEST messages (when a client is SELECTING), DHCPRELEASE messages, and DHCPDECLINE messages. When the Server Identifier Option is specified in one of these messages, but is not equal to my_ip_addr, the server checks to see if you have specified any known_server_identifier values. If so, it checks to see if the Server Identifier Option matches one of those; if it matches none of them, the server logs it as an "unknown Server Identifier."

Since the server does not examine the known_server_identifier values when the Server Identifier Option matches my_ip_addr, you need not list your server's own IP address as a known_server_identifier.

The known_server_identifier statement is optional; if you have none, the server skips the check; it will not log any "unknown Server Identifier."

This check is only used to provide you with some hint that there may be rogue DHCP servers operating on your network. It is possible for rogue DHCP servers to operate on your network and not be noticed by this check.

Note the statement does not allow you to declare a set of Server Identifier Option values that the server will consider equivalent to itself.

EXAMPLES

An example /etc/dhcpd.conf file follows:

    # Sample dhcpd.conf file
    # Only check the bootptab file's modification time (to learn if we need to re-read the file)
    # if more than 60 seconds have passed since the last time we actually read the bootptab file.
    readtabinterval 60
    # Only check the configuration file's modification time (to learn if we need to re-read the file)
    # if more than 60 seconds have passed since the last time we actually read the configuration file.
    readconfinterval 60
    # flush lastbinding changes from cache to disk every 10 changes or 60 seconds, whichever comes first.
    flushitems 10
    flushinterval 60
    # reclaim expired bindings every 300 seconds
    gcinterval 300
    # delay DHCPOFFERs by 1000 microseconds (1 millisecond)
    delay_reply_dhcpoffer 1000
    # report any Server Identifier Option values we see other than my_ip_addr and the following known DHCP servers
    known_server_identifier  192.120.245.1
    known_server_identifier  192.120.245.2
    # We serve dynamic IP addresses on four networks.
    #
    #   On plaidnet we'll serve both dhcp and bootp clients.  The clients need not be in our bootptab.
    #   The network is directly attached (no BootP Relay Agents every involved).
    network plaidnet    192.120.245.0 255.255.255.0   both
    #
    #   Clients on scramblenet must be registered use dhcp to get a dynamic address.
    #   There's one relay agent involved.
    network scramblenet 128.112.192.0 255.255.252.0   dhcp|registered    128.112.192.7 255.255.252.0
    #
    #   Clients on foobar must use bootp and not appear in bootptab to get a dynamic address.
    #   There are two bootp relay agents that may relay requests to us.
    network foobar      128.112.208.0 255.255.252.0   bootp|unregistered 128.112.208.1 255.255.252.0  128.112.210.36 255.255.252.0
    #
    #   Clients on gumby may use bootp or dhcp to get a dynamic address, but must appear in bootptab
    #   with a :ro: tag. There's just one bootp relay agent.
    network gumbynet    192.120.216.0 255.255.255.0   both|roaming       128.112.216.1 255.255.252.0
    #
    #   Clients behind 128.112.22.89 are served by several dynamic pools.
    #   They must speak dhcp to get a dynamic address.
    #   Those that do not appear in bootptab are served by both the flyers and walkers pools.
    #   Those that are appear in bootptab without a :ro: tag are served by both the floaters and walkers pools.
    #   Those that are appear in bootptab wit a :ro: tag are served by both the wanderers and walkers pools.
    #   There's only one bootp relay agent.
    network wanderers   128.112.20.0 255.255.255.0   dhcp|roaming        128.112.22.89 128.112.252.0
    network floaters    128.112.21.0 255.255.255.0   dhcp|registered     128.112.22.89 128.112.252.0
    network flyers      128.112.80.0 255.255.255.128 dhcp|unregistered   128.112.22.89 128.112.252.0
    network walkers     128.112.84.0 255.255.255.0   dhcp                128.112.22.89 128.112.252.0
    # This server has two interfaces.
    #
    # the server is directly attached to network 192.120.245.0 and serves dynamic addresses on it
    gateway 192.120.245.117 255.255.255.0 plaidnet
    #
    # the server is directly attached to network 192.120.240.0
    # network 192.120.253.0/255.255.255.128 runs on the same wire
    # we do not serve dynamic addresses on either network
    gateway 192.120.240.12  255.255.255.0
    proxy   192.120.240.12  192.120.253.0 255.255.255.128
    # Describe all the Bootp Relay Agents that may relay requests to this server.
    #
    # there is one relay agent for network 128.112.192.0 and we serve dynamic addresses for that network
    gateway 128.112.192.7 255.255.252.0 scramblenet
    #
    # there two relay agents for network 128.112.208.0, we serve dynamic addresses for that network
    gateway 128.112.208.1  255.255.252.0 foobar
    gateway 128.112.210.36 255.255.252.0 foobar
    #
    # there is one relay agent for network 128.112.112.0, we do not serve dynamic addresses on it
    gateway 128.112.112.1 255.255.252.0
    #
    # there are two relay agents for network 140.180.128.0, and we do not serve dynamic addresses on it
    gateway 140.180.128.1 255.255.192.0
    gateway 140.180.163.3 255.255.192.0
    #
    # there is one relay agent for network 128.112.216.0, and we serve dynamic addresses on it
    gateway 128.112.216.1 255.255.252.0 gumbynet
    #
    # there is one relay agent for network 128.112.16.0
    # the same wire runs three secondary IP networks (128.112.17.0, 128.112.18.0, and 140.180.128.0)
    gateway 128.112.16.32 255.255.255.0
    proxy   128.112.16.32 128.112.17.0 255.255.255.0
    proxy   128.112.16.32 128.112.18.0 255.255.255.0
    proxy   128.112.16.32 140.180.128.0 255.255.192.0
    # the three previous statements could also be written as follows:
    # proxy   128.112.16.32 128.112.17.0 255.255.255.0 128.112.18.0 255.255.255.0 140.180.128.0 255.255.192.0
    #
    # there is one relay agent for network 128.112.20.0
    # the same wire runs two secondary IP network (128.112.84.0)
    # we serve dynamic IP addresses on it
    gateway 128.112.22.89 128.112.20.0 255.255.252.0  wanderers floaters flyers walkers
    proxy   128.112.22.89 128.112.80.0 255.255.255.128
    proxy   128.112.22.89 128.112.84.0 255.255.255.0

BUGS

Each line is limited to 1024 characters, and the maximum number of tokens per line is 256.

Some of the information in the network and gateway statements is repetitious.

FILES
/etc/dhcpd.conf

SEE ALSO
dhcpd(8), bootptab(5), dhcp-bindings-tool(8).

Internet Requests for Comments:

RFC2132
    DHCP Options and BootP Vendor Extensions

RFC951
    Bootstrap Protocol

RFC1534
    Interoption Between DHCP and BootP

RFC1542
    Clarifications and Extensions for the Bootstrap Protocol

RFC1700
    Assigned Numbers

RFC2131
    Dynamic Host Configuration Protocol

RFC2241
    DHCP Options for Novell Directory Services

RFC2242
    NetWare/IP Domain Name and Information

RFC2485
    DHCP Option for The Open Group's User Authentication Protocol

RFC2610
    DHCP Options for Service Location Protocol

RFC2937
    The Name Service Search Option for DHCP

RFC2939
    Procedure and IANA Guidelines for Definition of New DHCP Options and Message Types

RFC3004
    The User Class Option for DHCP

RFC3011
    The IPv4 Subnet Selection Option for DHCP

RFC3046
    DHCP Relay Agent Information Option

RFC3942
    Reclassifying DHCPv4 Options

Internet Engineering Task Force draft documents are listed at the official IETF DHCP Working Group page: http://www.ietf.org/html.charters/dhc-charter.html

Additional DHCP resources are at: http://www.dhcp.org/