[Previous] [Contents] [Index] [Next]


Specify DHCP configuration details




The dhcpd.conf file is a free-form ASCII text file containing a list of statements that dhcpd uses for DHCP configuration.

File format

To create a dhcpd.conf file, you enter a scope keyword first, followed by a pair of braces ({}) enclosing the parameter and declaration statements that apply within that scope. If there is no preceding scope keyword, the statement applies globally.


The following keywords define the scope for following statements:

Note: The group keyword is unusual in that it may be located anywhere under global. Thus groups may contain shared-networks and subnets, as well as hosts.

The order of precedence for parameters is in reverse hierarchical order: that is from the specific to the general. If a parameter for a machine is specified in the host section and a different parameter is specified for the same machine in the subnet section, the value in the host section applies. We'll explain the scope keywords in this order of precedence.

host keyword

The host keyword signifies that any following statements are to be applied to a unique host machine on the network.

There must be at least one host statement for every BOOTP client that is to be served. host statements may also be specified for DHCP clients, although this is not required unless booting is enabled for known hosts only.

If it is desirable to be able to boot a DHCP or BOOTP client on more than one subnet with fixed addresses, more than one address may be specified in the fixed-address parameter, or more than one host statement may be specified.

If client-specific boot parameters must change based on the network to which the client is attached, then multiple host statements should be used.

If you want to allocate a dynamic address only when it is not possible to boot with a fixed address, a host statement must be specified without a fixed-address clause.

The host declarations are matched to actual DHCP or BOOTP clients by matching the dhcp-client-identifier option specified in the host declaration to the one supplied by the client, or, if the host declaration or the client does not provide a dhcp-client-identifier option, by matching the hardware parameter in the host declaration to the network hardware address supplied by the client. BOOTP clients do not normally provide a dhcp-client-identifier, so the hardware address must be used for all clients that may boot using the BOOTP protocol.

You declare a host statement like this:

host name{
[ parameters ] 
[ declarations ] 

where name is a unique host name (for an example and restrictions on use, see the entry for use-host-decl-names flag; in the section on Parameter statements, below)

Examples of parameters that might be assigned a value under a typical host scope are:

group keyword

The group scope may include individual hosts, shared networks, subnets, or even other groups.

If some machines on a subnet share common parameters but others don't, you might want to create a group scope to cover the similar machines without having to treat them as a separate subnet. You do this by using the group keyword. All of the options included within the group scope declaration apply to that group. As with subnets, this scope can also specify individual hosts with the group.

For example, you may want to provide a large set of addresses for DHCP clients that are registered to your DHCP server, while providing a smaller set of addresses, possibly with shorter lease times, for unknown clients. Or, if you have a firewall, you may be able to arrange for addresses from one group to be allowed access to the Internet, while addresses in another group are not; thus encouraging users to register their DHCP clients.

Note: Within either the group or subnet declarations, you can specify parameters for individual hosts, just as when the hosts are part of a shared network.

You can also vary the facilities afforded to members of the same group by partitioning them within the group, like this:

	default-lease-time 100000;
	option routers;
	host fantasia { hardware ethernet 08:00:07:26:c0:a5; }
	host passacaglia { hardware ethernet 0:0:c0:5d:bd:95; }
	host confusia {
		hardware ethernet 02:03:04:05:06:07;
		default-lease-time 200000;

All three machines in this group share the same router but, while leases for fantasia and passacaglia last for 100,000 seconds, confusia enjoys a 200,000-second lease.

subnet keyword

For every subnet that will be served, and for every subnet to which the DHCP server is connected, there must be subnet declarations that tell dhcpd how to recognize that an address is on that subnet. A subnet declaration is required for each subnet, even if no addresses will be dynamically allocated on that subnet.

If clients on a subnet are to be assigned addresses dynamically, a range declaration must appear within the subnet declaration. The range statement contains the pool of IP addresses that can be allocated on this subnet. For clients with statically assigned addresses, or for installations where only known clients will be served, each such client must have a host declaration.

If parameters are to be applied to a group of declarations which are not related strictly on a per-subnet basis, the group declaration can be used.

Any subnets in a shared network should be declared within a shared-network statement.

Here's what a subnet statement looks like:

subnet subnet-number netmask netmask-number{
[ parameters ] 
[ declarations ] 

The subnet-number variable should be an IP address or domain name that resolves to the subnet number of the subnet being described. The netmask-number variable should be an IP address or domain name which is applied to the subnet-number to determine the subnet address. The subnet-number and netmask-number are used together to determine whether any given IP address is on the specified subnet.

Although a netmask must be given with every subnet statement, if a site has different subnet masks, you should include a subnet-mask option statement in the declaration for each subnet to set the desired subnet mask (see Standard DHCP option statements, below). Any such subnet-mask option statement overrides the netmask declared in the top line of the subnet statement.

When a subnet becomes a shared network

Some installations have physical networks on which more than one IP subnet operates. For example, if there is a site-wide requirement that 8-bit subnet masks be used, but a department with a single physical Ethernet network expands to the point where it has more than 254 nodes, it may be necessary to run two 8-bit subnets on the same Ethernet until such time as a new physical network can be added. In this case, the subnet declarations for these two networks must be enclosed in a shared-network declaration.

For clients on more than one subnet

Some sites may have departments that have clients on more than one subnet, but you might want to offer clients in the same department a uniform set of parameters, regardless of the subnet they are on. For clients which will be declared explicitly with host declarations, these declarations can be enclosed in a group declaration along with the parameters which are common to that department.

shared-network keyword

Shared networks are separate networks that use the same physical network segment. Uses include things like restricting certain device types to specific segments or separating machines before moving them to a different network segment.

A shared-network can contain any combination of subnets, groups, and hosts.

You must declare all the subnets in a shared network within a shared-network statement. Clients on these subnets are booted using the parameters specified in the shared-network statement, unless parameters provided at the subnet or host level override them. If any subnet in a shared network has addresses available for dynamic allocation, those addresses are collected into a common pool for that shared network and assigned to clients as needed. There is no way to distinguish on which subnet of a shared network a client should boot.

The syntax for a shared-network statement is:

shared-network name { 
[ parameters ] 
[ declarations ] 

You can use a valid domain name for name, but as this variable is used only when printing debugging messages, you might want to use descriptive text (enclosed in quotes) instead.

global keyword

The global keyword may be used on its own or inside lower scope declarations, like subnet or group. It denotes that any following statements are to be applied globally, either within another scope or on the whole network. Normally, the global keyword is omitted because it is the default.


Statements cover:

Range statements

The range statement specifies the IP addresses that may be allocated to clients within a defined scope.

For any subnet on which addresses will be assigned dynamically, there must be at least one range statement. The range statement gives the lowest and highest IP addresses in a range. All IP addresses in the range should be in the subnet in which the range statement is declared. The dynamic-bootp flag may be specified if addresses in the specified range may be dynamically assigned to BOOTP clients as well as DHCP clients. Here's the syntax for the range statement:

range [ dynamic-bootp ] low-address [ high-address]; 

When specifying a single address, the high-address variable may be omitted.

Permission statements

Allow and deny statements can be used to control the response of the DHCP server to various sorts of requests. The allow and deny keywords have different meanings depending on context. In a pool context, these keywords can be used to set up access lists for address allocation pools. In other contexts, the keywords simply control general server behavior with respect to clients, based on scope.

The following declarations work in any scope, although you shouldn't use them in group declarations.

allow|deny unknown-clients;
The unknown-clients flag tells dhcpd whether or not to dynamically assign addresses to unknown clients. The default is allow. (An unknown client is simply a client that has no host declaration.)
allow|deny bootp;
The bootp flag tells dhcpd whether or not to respond to BOOTP queries. The default is allow.
allow|deny booting;
The booting flag is used to tell dhcpd whether or not to respond to queries from a particular client. This keyword only has meaning when it appears in a host declaration. By default, booting is allowed, but if it is disabled for a particular client, then that client will not be able to get an address from the DHCP server.

Parameter statements

always-reply-rfc1048 flag;
Some BOOTP clients expect RFC1048-style responses, but do not follow RFC1048 when sending their requests. You can tell that a client is having this problem if it is not getting the options you have configured for it and if you see in the server log the message "(non rfc1048)" printed with each BOOTREQUEST that is logged.

If you want to send rfc1048 options to such a client, you can set the always-reply-rfc1048 option in that client's host declaration, and the DHCP server will respond with an RFC-1048-style vendor options field. This flag can be set in any scope, and will affect all clients covered by that scope.

authoritative; or not authoritative;
The DHCP server will normally assume that the configuration information about a given network segment is not known to be correct and is not authoritative. This is so that if you install a DHCP server while not fully understanding how to configure it, the server does not send spurious DHCPNAK messages to clients that have obtained addresses from a legitimate DHCP server on the network.

When setting up authoritative DHCP servers for your networks, always write:


at the top of your configuration file to indicate that the DHCP server should send DHCPNAK messages to misconfigured clients. If you don't do this, clients who change subnets will be unable to get a correct IP address until their old lease has expired, which could take quite a long time.

If you want to set up a DHCP server so that it is aware of some networks for which it is authoritative and some networks for which it is not, you could declare authority on a per-network-segment basis.

Note: Note that the most specific scope for which the concept of authority makes any sense is the physical network segment: either a shared-network statement or a subnet statement that is not contained within a shared-network statement. It is not meaningful to specify that the server is authoritative for some subnets within a shared network, but not authoritative for others, nor is it meaningful to specify that the server is authoritative for some host declarations and not others.

boot-unknown-clients flag;
If the boot-unknown-clients statement is present and flag has a value of false or off, then clients for which there is no host declaration will not be allowed to obtain IP addresses. If this statement is not present or has a flag value of true or on, then clients without host declarations will be allowed to obtain IP addresses, as long as those addresses are not restricted by allow and deny statements within their pool declarations.
default-lease-time time;
The time variable is the length in seconds that will be assigned to a lease if the client requesting the lease does not ask for a specific expiration time.
dynamic-bootp-lease-cutoff date;
This statement sets the ending time for all leases assigned dynamically to BOOTP clients. Because BOOTP clients do not have any way of renewing leases, and don't know that their leases could expire, by default dhcpd assigns infinite leases to all BOOTP clients. However, it may make sense in some situations to set a cutoff date for all BOOTP leases for example, the end of a school term, or the time at night when a facility is closed and all machines are required to be powered off.

The date variable is the date on which all assigned BOOTP leases will end . The date is specified in the form:


Where W is the day of the week expressed as a number from zero (Sunday) to six (Saturday). YYYY is the year, including the century. MM is the month expressed as a number from 1 to 12. DD is the day of the month, counting from 1. HH is the hour, from zero to 23. MM is the minute and SS is the second. The time is always in Universal Coordinated Time (UTC), not local time.

dynamic-bootp-lease-length length;
This statement sets the duration time for leases dynamically assigned to BOOTP clients. At some sites, it may be possible to assume that a lease is no longer in use if its holder has not used BOOTP or DHCP to get its address within a certain time period. The period is specified in length as a number of seconds. If a client reboots using BOOTP during the timeout period, the lease duration is reset to length, so a BOOTP client that boots frequently enough will never lose its lease. Be very careful when adjusting length.
filename filename;
This statement can be used to specify the name of the initial boot file that is to be loaded by a client. The filename should be a filename recognizable to whatever file transfer protocol the client can be expected to use to load the file.
fixed-address address [, address ... ];
This statement assigns one or more fixed IP addresses to a client. It should only appear in a host declaration. If more than one address is supplied when the client boots, it will be assigned the address which corresponds to the network on which it is booting. If none of the addresses in the fixed-address statement are on the network on which the client is booting, that client will not match the host declaration containing that fixed-address statement. Each address should be either an IP address or a domain name which resolves to one or more IP addresses.
get-lease-hostnames flag;
The get-lease-hostnames statement tells dhcpd whether or not to look up the domain name corresponding to the IP address of each address in the lease pool and use that address for the DHCP hostname option. If flag is true, this lookup is done for all addresses in the current scope. By default, or if flag is false, no lookups are done.
hardware hardware-type hardware-address;
In order for a BOOTP client to be recognized, its network hardware address must be declared using a hardware clause in the host statement. The hardware-type variable must be the name of a physical hardware interface type. Currently, only the Ethernet type is recognized. The hardware-address variable should be a set of hexadecimal octets (numbers from 0 through ff) separated by colons. The hardware statement may also be used for DHCP clients.
max-lease-time time;
The time variable is the maximum time in seconds that will be assigned to a lease. The only exception to this is that Dynamic BOOTP lease lengths, which are not specified by the client.
next-server server-name;
This statement specifies the host address of the server from which the initial boot file (specified in the filename statement) is to be loaded. The server-name variable is a numeric IP address or a domain name. If no next-server parameter applies to a given client, the DHCP server's IP address is used.
one-lease-per-client flag;
If flag is enabled, whenever a client sends a DHCPREQUEST for a particular lease, the server will automatically free any other leases the client holds. This presumes that when the client sends a DHCPREQUEST, it has forgotten any lease not mentioned in the DHCPREQUEST: i.e. the client has only a single network interface and it does not remember leases it's holding on networks to which it is not currently attached. Neither of these assumptions are guaranteed or provable, so we urge caution in the use of this statement.
ping flag;
When the DHCP server is considering dynamically allocating an IP address to a client, it first sends an ICMP Echo request (a ping) to the address being assigned. It waits for a second, and if no ICMP Echo response has been heard, it assigns the address. If a response is heard, the lease is abandoned, and the server does not respond to the client.

This flag is always true, it can't be turned off.

server-identifier hostname;
This statement defines the value that is sent in the DHCP Server Identifier option for a given scope. The hostname value must be an IP address for the DHCP server, and must be reachable by all clients served by a particular scope.

The use of the server-identifier statement is not recommended: the only reason to use it is to force a value other than the default value to be sent on occasions where the default value would be incorrect. The default value is the first IP address associated with the physical network interface on which the request arrived.

The usual case where the server-identifier statement needs to be sent is when a physical interface has more than one IP address, and the one being sent by default isn't appropriate for some or all clients served by that interface. Another common case is when an alias is defined for the purpose of having a consistent IP address for the DHCP server, and it is desired that the clients use this IP address when contacting the server.

Supplying a value for the dhcp-server-identifier option is equivalent to using the server-identifier statement.

server-name name ;
This statement can be used to to inform the client of the name of the server from which it is booting. the name variable should be the name that will be provided to the client.
use-host-decl-names flag;
If flag is true in a given scope, for every host declaration within that scope the name provided for the host declaration will be supplied to the client as its hostname. So, for example:
group { 
	use-host-decl-names on; 
	host joe { 
	hardware ethernet 08:00:2b:4c:29:32; 
	fixed-address joe.fugue.com; 

is equivalent to:

host joe { 
	hardware ethernet 08:00:2b:4c:29:32; 
	fixed-address joe.fugue.com; 
	option host-name "joe"; 

An option host-name statement within a host declaration will override the use of the name in the host declaration.

Note: Most DHCP clients completely ignore the host-name option sent by the DHCP server, and there is no way to configure them not to do this.

use-lease-addr-for-default-route flag;
If flag is true in a given scope, instead of sending the value specified in the routers option (or sending no value at all), the IP address of the lease being assigned is sent to the client. This causes QNX DHCP clients to ARP for all IP addresses, which can be helpful if your router is configured for proxy ARP.

DHCP option statements

DHCP options contain information about a network and the various services it makes available. You direct the DHCP server to tell specified clients about some or all of this information by declaring relevant DHCP options in your dhcpd.conf file. DHCP option statements start with the option keyword, followed by an option name, followed by option data, like this:

option option-name option-data

Here are the syntax rules:

Note: See the section on Standard DHCP options for a list of allowed option names and corresponding data types.

Data types in DHCP options

The variables in DHCP option statements conform to the data types shown in the following table:

This data type: Specifies:
ip-address numerical IP address or a domain name resolving to a single IP address
int32 signed 32-bit integer
uint32 unsigned 32-bit integer
int16 signed 16-bit integer
uint16 unsigned 16-bit integer
int8 signed 8-bit integer
uint8 or octet unsigned 8-bit integer
string NVT ASCII string enclosed in double quotes
flag boolean value including true/false or on/off
data-string an NVT ASCII string enclosed in double quotes, or a series of hexadecimal octets separated by colons

Standard DHCP option statements

The standard DHCP option statements are as follows (for a sub-list of the DHCP options that are applied by the QNX DHCP client, see dhcp.client):

option subnet-mask ip-address
Client's subnet mask as per RFC 950. The default is as specified in the subnet declaration for the network on which an address is assigned.
option time-offset int32
The offset of the client's subnet in seconds from Coordinated Universal Time (UTC).
option routers ip-address [, ip-address... ]
IP addresses for routers on the client's subnet, in order of preference.
option time-servers ip-address [, ip-address... ]
Lists RFC 868 time servers available to the client, in order of preference.
option ien116-name-servers ip-address [, ip- address... ]
Lists IEN 116 name servers available to the client, in order of preference.
option domain-name-servers ip-address [, ip- address... ]
Lists Domain Name System (STD 13, RFC 1035) name servers available to the client, in order of preference.
option log-servers ip-address [, ip-address... ]
Lists MIT-LCS UDP log servers available to the client, in order of preference.
option cookie-servers ip-address [, ip-address... ]
Lists RFC 865 cookie servers available to the client, in order of preference.
option lpr-servers ip-address [, ip-address... ]
The LPR server option specifies a list of RFC 1179 line printer servers available to the client, in order of preference.
option impress-servers ip-address [, ip-address... ]
Lists Imagen Impress servers available to the client, in order of preference.
option resource-location-servers ip-address [, ip- address... ]
Lists RFC 887 Resource Location servers available to the client, in order of preference.
option host-name string
The client's name. We recommend that you don't include the local domain name; use the domain-name option to specify the domain name. See RFC 1035 for character set restrictions.
option boot-size uint16
The length (in 512-octet blocks) of the client's default boot image.
option merit-dump string
Where to dump the client's core image if the client crashes. Specify the dump-file pathname string in NVT ASCII characters.
option domain-name string
The domain name that the client should use when resolving DNS hostnames.
option swap-server ip-address
The client's swap server.
option root-path string
The pathname, in NVT ASCII characters, of the client's root disk.
option ip-forwarding flag
Whether the client should enable IP packet forwarding (1 = enable, 0 = disable).
option non-local-source-routing flag
Whether the client should configure its IP layer to allow forwarding of datagrams with non-local source routes (1 means allow this kind of forwarding, 0 means disallow it).
option policy-filter ip-address ip-address [, ip- address ip-address... ]
Specifies policy filters for non-local source routing. The filters consist of a list of IP addresses and masks which specify destination/mask pairs with which to filter incoming source routes. Any source-routed datagram whose next-hop address does not match one of the filters should be discarded by the client. See STD 3 (RFC1122) for further information.
option max-dgram-reassembly uint16
The maximum size datagram that the client should be prepared to reassemble (minimum legal value is 576).
option default-ip-ttl uint8
The default time-to-live that the client should use on outgoing datagrams.
option path-mtu-aging-timeout uint32
The timeout (in seconds) to use when aging Path MTU (maximum transmission unit) values discovered by the mechanism defined in RFC 1191.
option path-mtu-plateau-table uint16 [, uint16... ]
Lists MTU sizes to use when performing Path MTU Discovery as defined in RFC 1191, ordered from smallest to largest (minimum 68).
option interface-mtu uint16
The MTU to use on this interface (the minimum legal value is 68).
option all-subnets-local flag
If flag = 1, all subnets on the IP network to which the client is connected use the same MTU. If flag = 0, some of these subnets may have smaller MTUs.
option broadcast-address ip-address
The broadcast address in use on the client's subnet (see section of STD 3 (RFC1122) for legal values).
option perform-mask-discovery flag
If flag = 1, the client should perform subnet mask discovery using ICMP (Internet Control Message Protocol); if flag = 0, it should not.
option mask-supplier flag
If flag = 1, the client should respond to subnet mask requests using ICMP; ; if flag = 0, it should not.
option router-discovery flag
If flag = 1, the client should solicit routers using the router discovery mechanism defined in RFC 1256; if flag = 0, it should not.
option router-solicitation-address ip-address
The IP address to which the client should transmit router solicitation requests.
option static-routes ip-address ip-address [, ip- address ip-address... ]
Lists static routes that the client should install in its routing cache. If multiple routes to the same destination are specified, they are listed in descending order of priority. The list consists of IP address pairs: the first address is the destination address; the second address is the router for the destination. The default route ( is an illegal destination for a static route. To specify the default route, use the routers option.
option trailer-encapsulation flag
If flag = 1, the client should negotiate the use of trailers (RFC 893 [14]) when using the ARP protocol; if flag = 0, the client should not attempt to use trailers.
option arp-cache-timeout uint32
The timeout (in seconds) for ARP cache entries.
option ieee802-3-encapsulation flag
If flag = 1, the client should use IEEE 802.3 (RFC 1042) encapsulation for an Ethernet interface; if flag = 0, it should use Ethernet Version 2 (RFC 894).
option default-tcp-ttl uint8
The default time-to-live that the client should use when sending TCP segments. The minimum value is 1.
option tcp-keepalive-interval uint32
The interval (in seconds) that the client TCP should wait before sending a keepalive message on a TCP connection. A value of zero indicates that the client should not generate keepalive messages on connections unless specifically requested by an application.
option tcp-keepalive-garbage flag
If flag = 1, the client should send TCP keepalive messages with an octet of garbage for compatibility with older implementations; if flag = 0, the client should not.
option nis-domainstring
The name of the client's NIS (Sun Network Information Services) domain, in NVT ASCII characters.
option nis-servers ip-address [, ip-address... ]
Lists IP addresses indicating NIS servers available to the client, in order of preference.
option ntp-servers ip-address [, ip-address... ]
Lists IP addresses indicating NTP (RFC 1035) servers available to the client, in order of preference.
option netbios-name-servers ip-address [, ip- address... ]
Lists 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 this option.
option netbios-dd-server ip-address [, ip-address... ]
Lists RFC 1001/1002 NBDD servers, in order of preference.
option netbios-node-type uint8
Allows NetBIOS over TCP/IP clients that can be configured as described in RFC 1001/1002. The uint8 value is a single octet which identifies the client type as follows:
A uint8 value of: Specifies:
1 B-node: Broadcast - no WINS
2 P-node: Peer - WINS only
4 M-node: Mixed - broadcast, then WINS
8 H-node: Hybrid - WINS, then broadcast
option netbios-scope string
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.
option font-servers ip-address [, ip-address... ]
Lists X Window System Font servers available to the client, in order of preference.
option x-display-manager ip-address [, ip-address... ]
Lists systems that are running the X Window System Display Manager and are available to the client, in order of preference.
option dhcp-client-identifier data-string
Specifies the DHCP client identifier in a host declaration, so that dhcpd can find its matching host record.
option nisplus-domain string
The name (in NVT ASCII characters) of the client's NIS+ domain.
option nisplus-servers ip-address [, ip-address... ]
Lists IP addresses indicating NIS+ servers available to the client, in order of preference.
option tftp-server-name string
Identifies a TFTP server; if supported by the client, this should have the same effect as the server-name declaration. BOOTP clients are unlikely to support this option. Some DHCP clients will support it, and others actually require it.
option bootfile-name string
Identifies 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 mobile-ip-home-agent ip-address [, ip- address... ]
Lists the IP addresses of 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.
option smtp-server ip-address [, ip-address... ]
Lists the SMTP servers available to the client, in order of preference.
option pop-server ip-address [, ip-address... ]
Lists the POP3 servers available to the client, in order of preference.
option nntp-server ip-address [, ip-address... ]
Lists the NNTP servers available to the client, in order of preference.
option www-server ip-address [, ip-address... ]
Lists the WWW servers available to the client, in order of preference.
option finger-server ip-address [, ip-address... ]
Lists the Finger servers available to the client, in order of preference.
option irc-server ip-address [, ip-address... ]
Lists the IRC servers available to the client, in order of preference.
option streettalk-server ip-address [, ip-address... ]
Lists the StreetTalk servers available to the client, in order of preference.
option streetalk-directory-assistance-server ip-address [, ip- address... ]
Lists the STDA (StreetTalk Directory Assistance) servers available to the client, in order of preference.


Finding host parameters
In a complex configuration, it can be difficult to tell which parameter applies to any given host. It helps to remember two things:

When you are troubleshooting DHCP, always start at the bottom and work your way up.

Finding allocated leases
The dhcpd daemon writes information about the current state of all active leases to a text file (/var/state/dhcp/dhcp.leases). The daemon rewrites this file from time to time to keep it reasonably sized. If your server dies while dhcpd is rewriting this file, it is possible that the file will disappear. If this happens, you won't be able to restart your DHCP server because dhcpd won't start without a leases file. Fortunately, before dhcpd changes anything in the leases file, it creates a backup (dhcpd.leases~) in the same directory: just rename the backup file dhcpd.leases and you're back in business.

The contents of the dhcpd.leases file is fairly straightforward. Each lease declaration is identified with the keyword lease followed by the IP address and a block of configuration information within braces .

You might have something like this:

lease {
starts 0 2000/01/30 08:02:54;
ends 5 2000/02/04 08:02:54;
hardware ethernet
uid 01:00:50:04:53:D5:57;
client-hostname "PC0097";

The starts and ends statements tell you the period when the lease is valid. Each entry is of the form:

weekday yyyy/mm/dd hh:mm:ss;

The weekday is the numerical value for the day of the week starting with 0 on Sunday, as in this case. The date and time are UCT, not local time. The hardware entry is in the same format as in the dhcpd.conf file and lists the hardware address of the card. The uid entry is a unique identifier for the client, using either an ASCII-string client identifier supplied by the client or the hardware address preceded by hardware type (in this example 01).

Related issues

This section gives you some background information that might help explain a few related issues as you create your dhcpd.conf file.

Dynamic address allocation

Address allocation is actually only done when a client is in the INIT state and has sent a DHCPDISCOVER message. If the client thinks it has a valid lease and sends a DHCPREQUEST to initiate or renew that lease, the server has only three choices: it can ignore the DHCPREQUEST, send a DHCPNAK to tell the client it should stop using the address, or send a DHCPACK, telling the client to go ahead and use the address for a while.

If the server finds the address the client is requesting, and that address is available to the client, the server will send a DHCPACK. If the address is no longer available, or the client isn't permitted to have it, the server will send a DHCPNAK. If the server knows nothing about the address, it will remain silent, unless the address is incorrect for the network segment to which the client has been attached and the server is authoritative for that network segment, in which case the server will send a DHCPNAK even though it doesn't know about the address.

There may be a host declaration matching the client's identification, and that host declaration contains a fixed-address declaration that is valid for the network segment to which the client is connected. In this case, the DHCP server will never do dynamic address allocation. In this case, the client is required to take the address specified in the host declaration. If the client is requesting some other address, the server will respond with a DHCPNAK.

When the DHCP server allocates a new address for a client (remember, this only happens if the client has sent a DHCPDISCOVER), it first looks to see if the client already has a valid lease on an IP address, or if there is an old IP address the client had before that hasn't yet been reassigned. In that case, the server will take that address and check it to see if the client is still permitted to use it. If the client is no longer permitted to use it, the lease is freed if the server thought it was still in use: the fact that the client has sent a DHCPDISCOVER proves to the server that the client is no longer using the lease.

If no existing lease is found, or if the client is forbidden to receive the existing lease, then the server will look in the list of address pools for the network segment to which the client is attached for a lease that is not in use and that the client is permitted to have. It looks through each pool declaration in sequence (all range declarations that appear outside of pool declarations are grouped into a single pool with no permit list). If the permit list for the pool allows the client to be allocated an address from that pool, the pool is examined to see if there is an address available. If so, then the client is tentatively assigned that address. Otherwise, the next pool is tested. If no addresses are found that can be assigned to the client, no response is sent to the client.

If an address is found that the client is permitted to have, and that has never been assigned to any client before, the address is immediately allocated to the client. If the address is available for allocation but has been previously assigned to a different client, the server will keep looking in hopes of finding an address that has never before been assigned to a client.

Preventing IP address conflicts

If a lease has been specified in a range statement and has not been listed as being in use by the server or its failover peer, dhcpd checks IP addresses to see if they are in use before allocating them to clients. It does this by sending an ICMP Echo request message to the IP address being allocated.

If no ICMP Echo reply is received within a second, the address is assumed to be free. If a response is received, dhcpd assumes that there is a configuration error or the IP address is in use by a network host that is not a DHCP client. In this case, the server marks the address as abandoned, and will not assign it to clients.

If only abandoned IP addresses are available when a DHCP client makes its request, dhcpd tries to reclaim one of the abandoned IP addresses by carrying out a new ICMP Echo request check. If there is no answer to the ICMP Echo request, the address is assigned to the client and the search ends; if not, dhcpd tries the next abandoned address and so on until it finds a free one.

If the same conditions apply when the next request comes in, dhcpd starts the same search starting at a different IP address to avoid cycling through the same sequence as before.


At first glance, there may not seem to be much to talk about in terms of security and DHCP. However, considering the importance of DHCP, a few precautions are in order.

The first consideration is the machine itself. Although an outage of a couple of hours might be something you can deal with, any long outage means that there may be a number of machines without a valid configuration or even a valid IP address. Therefore, you need to look at what other services the machine with your DHCP server provides. Since there is very little computer power required to support DHCP, you can easily get away with smaller machines. This might be preferable to having dhcpd running alongside some other machines.

Another issue to consider is a denial-of-service attack. If your DHCP server were accessible from the Internet, it would be possible for someone to gobble up all of your IP addresses, leaving nothing for your own machines. So make sure that you stop DHCP traffic getting through your firewall by blocking port 67 (the DHCP listen port) and port 68 (the DHCP transmit port) on the machine running your firewall.


An easy way to create you own dhcpd.conf file is to backup the file in /etc/dhcpd.conf file and then change it to suit your own needs. Here is the file we provide in /etc/dhcpd.conf:

# dhcpd.conf
# Sample configuration file for ISC dhcpd

# option definitions common to all supported networks...
option domain-name "fugue.com";
option domain-name-servers toccata.fugue.com;

option subnet-mask;
default-lease-time 600;
max-lease-time 7200;

subnet netmask {
  option broadcast-address;
  option routers prelude.fugue.com;

# The other subnet that shares this physical network
subnet netmask {
  range dynamic-bootp;
  option broadcast-address;
  option routers snarg.fugue.com;

subnet netmask {
  option name-servers bb.home.vix.com, gw.home.vix.com;
  option domain-name "vix.com";
  option routers;
  option subnet-mask;
  option broadcast-address;
  default-lease-time 600;
  max-lease-time 7200;

# Hosts which require special configuration options can be listed in
# host statements.   If no address is specified, the address will be
# allocated dynamically (if possible), but the host-specific information
# will still come from the host declaration.

host passacaglia {
  hardware ethernet 0:0:c0:5d:bd:95;
  filename "vmunix.passacaglia";
  server-name "toccata.fugue.com";

# Fixed IP addresses can also be specified for hosts.   These addresses
# should not also be listed as being available for dynamic assignment.
# Hosts for which fixed IP addresses have been specified can boot using
# BOOTP or DHCP.   Hosts for which no fixed address is specified can only
# be booted with DHCP, unless there is an address range on the subnet
# to which a BOOTP client is connected which has the dynamic-bootp flag
# set.
host fantasia {
  hardware ethernet 08:00:07:26:c0:a5;
  fixed-address fantasia.fugue.com;

# If a DHCP or BOOTP client is mobile and might be connected to a variety
# of networks, more than one fixed address for that host can be specified.
# Hosts can have fixed addresses on some networks, but receive dynamically
# allocated address on other subnets; in order to support this, a host
# declaration for that client must be given which does not have a fixed
# address.   If a client should get different parameters depending on
# what subnet it boots on, host declarations for each such network should
# be given.   Finally, if a domain name is given for a host's fixed address
# and that domain name evaluates to more than one address, the address
# corresponding to the network to which the client is attached, if any,
# will be assigned.
host confusia {
  hardware ethernet 02:03:04:05:06:07;
  fixed-address confusia-1.fugue.com, confusia-2.fugue.com;
  filename "vmunix.confusia";
  server-name "toccata.fugue.com";

host confusia {
  hardware ethernet 02:03:04:05:06:07;
  fixed-address confusia-3.fugue.com;
  filename "vmunix.confusia";
  server-name "snarg.fugue.com";

host confusia {
  hardware ethernet 02:03:04:05:06:07;
  filename "vmunix.confusia";
  server-name "bb.home.vix.com";

See also:

dhcp.client, dhcpd, /var/state/dhcp/dhcpd.leases, dhcprelay, syslogd.

RFC2131, RFC2132.

[Previous] [Contents] [Index] [Next]