Appendix D. A dhcpd Reference

This appendix covers the syntax of the dhcpd command and the dhcpd.conf configuration file. It is a reference to the Internet Software Consortium (ISC) Dynamic Host Configuration Protocol (DHCP) server, dhcpd. To fully understand how to configure and use dhcpd in realistic network environments, see the tutorial and sample configuration files in Chapter 9.

The information in this appendix is based on the version of dhcpd available at this writing. As a beta release, this software is bound to be upgraded and changed. Refer to the web page http://www.isc.org/dhcp.html for the most recent information about dhcpd. And remember, a DHCP implementation from another vendor will probably be configured in a completely different manner.

Compiling dhcpd

The source code for dhcpd can be obtained through the ISC web site at http://www.isc.org or via anonymous FTP at ftp://ftp.isc.org/isc/dhcp. The name of the compressed tar file will change as new versions are released. However, the latest release should be stored as dhcp-latest.tar.gz. Download, gunzip, and untar the file:

> ftp ftp.isc.org 
Connected to pub1.bryant.vix.com. 
220 pub1.bryant.vix.com FTP server ready. 
Name (ftp.isc.org:craig): anonymous 
331 Guest login ok, send your complete email address as password. 
Password: 
230 Guest login ok, access restrictions apply. 
ftp> cd isc/dhcp 
250 CWD command successful. 
ftp> binary 
200 Type set to I. 
ftp> get dhcp-latest.tar.gz 
200 PORT command successful. 
150 Opening BINARY mode data connection for dhcp-latest.tar.gz 
226 Transfer complete. 
181892 bytes received in 17 secs (10 Kbytes/sec) 
ftp> quit 
221 Goodbye. 
> gunzip dhcp-latest.tar.gz 
> tar -xvf dhcp-latest.tar 
drwxrwxr-x mellon/engsrc     0 2001-10-05 00:22:41 dhcp-3.0/
drwxrwxr-x mellon/engsrc     0 2001-10-05 00:22:32 dhcp-3.0/doc/
...
-rw-rw-r-- mellon/engsrc 150274 2001-08-23 12:25:51 dhcp-3.0/server/failover.c
-rw-rw-r-- mellon/engsrc  67711 2001-08-23 12:30:58 dhcp-3.0/server/mdb.c
-rw-rw-r-- mellon/engsrc  62087 2001-06-21 22:28:51 dhcp-3.0/server/omapi.c
-rw-rw-r-- mellon/engsrc   7612 2001-06-21 22:31:39 dhcp-3.0/server/salloc.c
-rw-rw-r-- mellon/engsrc  34248 2001-06-21 22:35:08 dhcp-3.0/server/stables.c
drwxrwxr-x mellon/engsrc      0 2001-10-05 00:22:42 dhcp-3.0/tests/
drwxrwxr-x mellon/engsrc      0 2001-10-05 00:22:42 dhcp-3.0/tests/failover/
-rw-rw-r-- mellon/engsrc   3585 2001-05-31 16:16:05 dhcp-3.0/tests/failover/dhcp-1.cf
-rw-rw-r-- mellon/engsrc   3463 2001-05-31 16:16:06 dhcp-3.0/tests/failover/dhcp-2.cf
-rwxrwxr-x mellon/engsrc    537 2001-05-31 16:16:07 dhcp-3.0/tests/failover/new-failover

Change to the newly created directory and run configure. configure determines the type of Unix system you’re running and creates the correct Makefile for that system. If configure cannot determine what version of Unix you’re running, you must build your own Makefile by hand. Next, type make to compile the daemon. Finally, copy the daemon and the manpages to the correct directories:

# cd dhcp-3.0 
# ./configure 
System Type: linux 
# make 
cc -g      -c dhcpd.c -o dhcpd.o 
cc -g      -c dhcp.c -o dhcp.o 
cc -g      -c bootp.c -o bootp.o 
...
nroff -man dhcpd.conf.5 >dhcpd.conf.cat5 
# make install

The DHCP daemon should compile without errors. If you get compile errors or if configure cannot determine your system configuration, you should consider abandoning the compile and notifying the support group. Join the support group mailing list by going to http://www.fugue.com/dhcp. Once you join, send mail to the dhcp-server@fugue.com mailing list describing your configuration and the exact problem you have. The list is read by most of the people using dhcpd. Someone may have already solved your problem.

Simply installing dhcpd may not be all that is required. Read the README file very carefully. dhcpd runs on a wide variety of systems, including OSF/1, most recent BSD derivatives, Solaris, and Linux. It runs best on OSF/1 and BSD; on other systems it may have some limitations. For example, on both Solaris and Linux, it can support only one network interface. dhcpd also may require some system-specific configuration. Old systems with the Linux 2.0.0 kernel are an excellent example of this. To successfully run dhcpd on one of these old systems, add the following entry to the /etc/hosts table:

255.255.255.255 all-ones

Next, add a specific route for the limited broadcast address, 255.255.255.255:

# route add -host all-ones dev eth0

To reinstall the limited broadcast address in the kernel routing table after each boot, add the following code to a startup script:

# Install the limited broadcast route and start DHCP 
  if [ -f /etc/dhcpd.conf ]; then 
    echo -n " dhcpd" 
    route add -host all-ones dev eth0 
    /usr/sbin/dhcpd   fi

The information needed to complete these extra configuration steps is clearly defined in the README file. Read it before you try to run dhcpd. Of course, this is not required for current versions of Linux, but it provides a good example of the type of special configuration that is sometimes required.

The dhcpd Command

The syntax of the dhcpd command is:

 dhcpd [-p port] [-f] [-d] [-cf config-file] [-lf lease-file] [if0 [ifn]]

dhcpd usually is run without any command-line arguments. Most of the arguments are used only when testing and debugging. Two of the command-line arguments handle special configuration requirements:

-f

Runs dhcpd in foreground mode. By default, dhcpd runs as a background daemon process. Use -f when dhcpd is started from inittab on a System V Unix system.

if0 [... ifn ]

Lists the interfaces on which dhcpd should listen for BOOTREQUEST packets. This is a whitespace-separated list of interface names. For example, dhcpd ec0 ec1 wd0 tells dhcpd to listen to interfaces ec0, ec1, and wd0. Normally this argument is not required. In most cases dhcpd locates all installed interfaces and eliminates the no-broadcast interfaces automatically. Use this argument only if it appears that dhcpd is failing to locate the correct interfaces.

All of the remaining command-line arguments are used for debugging or testing:

-p port

Causes dhcpd to listen to a nonstandard port. The well-known port for DHCP is 67. Changing it means that clients cannot talk to the server. On rare occasions this is done during testing.

-d

Routes error messages to stderr. Normally error messages are written via syslog with facility set to DAEMON.

-cf config-file

Causes dhcpd to read the configuration from the file identified by config-file instead of from dhcpd.conf. Use this only to test a new configuration before it is installed in dhcpd.conf. Use the standard file for production.

-lf lease-file

Causes dhcpd to write the address lease information to the file identified by lease-file instead of to dhcpd.leases. Use this only for testing. Changing the name of the lease file could cause dynamic addresses to be misallocated. Use this argument with caution.

Kill the dhcpd daemon with the SIGTERM signal. The process ID (PID) of the dhcpd daemon is found in the /var/run/dhcpd.pid file. For example:

 # kill -TERM 'cat /var/run/dhcpd.pid'

dhcpd uses three files. It writes its PID to /var/run/dhcpd.pid, maintains a record of dynamic address leases in /var/db/dhcpd.leases, and reads its configuration from /etc/dhcpd.conf. These last two files are created by you. Create an empty lease file before you run dhcpd the first time, e.g., touch /var/db/dhcpd.leases. Create a configuration and store it in dhcpd.conf.

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 Chapter 9 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 95 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 1 or 0, or yes or no.

In this book, 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 MTU. 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.