4. DHCP/BOOTP Server

Introduction

This chapter describes the DHCP/BOOTP Server. It combines the Dynamic Host Configuration Protocol (DHCP) server with the Bootstrap Protocol (BOOTP). DHCP allows hosts on a TCP/IP network to request and be assigned IP addresses, and also to discover information about the network to which they are attached.  BOOTP provides similar functionality, with certain restrictions.

TCPware V6.0 and later supplies two different DHCP servers: ISC DHCP V3 and ISC DHCP V4. A given system can only run one of these servers. Information about both servers is included in this chapter.

Note!     DHCP uses DNS for host names and IP addresses; thus, a malfunction in your DNS server can affect the DHCP server.

DHCP and BOOTP

In TCPware, the DHCP Server (DHCPD) is combined with the BOOTP Server (BOOTPD) to form the DHCP/BOOTP Server (DHCPD/BOOTPD).

DHCP

DHCP is the Dynamic Host Configuration Protocol. It centralizes and automates TCP/IP network configuration. The DHCP Server dynamically allocates IP addresses for hosts on the network from an available pool of addresses. In this way, new hosts or hosts that are frequently relocated can automatically get new IP addresses for a certain lease period. In order for this to work, the network administrator allocates address pools in each subnet and enters them into the DHCP configuration file (DHCPD.CONF).

DHCP is an extension of the Internet Bootstrap Protocol (BOOTP). DHCP offers a network host a temporary lease rather than an ownership of an IP address. The lease identifies the duration for which the client can safely use its dynamically assigned IP address. Lease lengths generally depend on the number of network users (crowding of the network) and the number of available IP addresses the DHCP server can assign. The network manager sets the lease length through parameters in the DHCPD.CONF file.

BOOTP

BOOTP support is also provided by this server.  BOOTP uses UDP/IP to allow diskless systems to find their IP addresses, addresses of boot servers, and names of boot files. BOOTP can supply other client information, such as the addresses of name servers, gateways, and LPD servers.

Unlike DHCP, the BOOTP protocol does not provide a protocol for recovering dynamically-assigned addresses once they are no longer needed.  It is still possible to dynamically assign addresses to BOOTP           clients, but some administrative process for reclaiming addresses is required.  By default, leases are granted to BOOTP clients in perpetuity, although the network administrator may set an earlier cutoff date or a shorter lease length for BOOTP leases. BOOTP clients may also be served in the old standard way, which is to simply provide a declaration in the DHCPD.CONF file for each BOOTP client, permanently assigning an address to each client.

 

Dynamic Host Configuration Process

On startup, the DHCP server reads the DHCPD.CONF file and stores a list of available addresses on each subnet in memory.  When a client requests an address using the DHCP protocol, the server allocates an address for it.  Each client is assigned a lease, which expires after an amount of time chosen by the administrator (by default, one day).  Before leases expire, the clients to which leases are assigned are expected to renew them in order to continue to use the addresses.  Once a lease has expired, the client to which that lease was assigned is no longer permitted to use the leased IP address.

In order to keep track of leases across system reboots and server restarts, the DHCP server keeps a list of leases it has assigned in a lease file (DHCPD.LEASES).  Before the server grants a lease to a host, it records the lease in this file and makes sure that the contents of the file are flushed to disk.  This ensures that even in the event of a system crash, the server will not forget about a lease that it has assigned.  On startup, after reading the configuration file, the server reads the leases file to refresh its memory about what leases have been assigned.

DHCP Protocol

With respect to the DHCP protocol, the DHCP server goes through an initializing, selecting, requesting, binding, renewal, rebinding, and expiration cycle when negotiating for an IP address, as shown in Figure 4-1. The process is basically as follows:

1   The client just added or relocated on the network requests an IP address by broadcasting a DHCPDISCOVER message to the local subnet over the well-known BOOTP server port. (The client can also go through a BOOTP router or relay agent to forward the DHCPDISCOVER to additional remote DHCP servers.) This is the initializing state.

2   The participating DHCP servers respond with a DHCPOFFER message if they have a valid configuration for the client. The client may get many of these messages, which contain the IP address and configuration data. (The servers make sure to reserve the addresses so as not to accidentally offer them to another client.) At this point the client enters the selecting state.

3   After selecting an address, the client broadcasts the selected address and name of the "winning" server (DHCP Server 1 in Figure 4-1) using a DHCPREQUEST message. This is the requesting state. All the other servers can now safely unreserve their addresses.

4   Server 1 sends the client a DHCPACK (acknowledgment) message with the negotiated IP address, the lease, and the network configuration parameters. The client now enters the binding state and can fully use the assigned IP address.

5   About halfway through the lease, the client sends Server 1 another DHCPREQUEST for a lease renewal, and enters the renewal state. If the server deems the lease renewable, it sends back another DHCPACK to update the lease (including any new parameters). The client now returns to the binding state, as in Step 4.

6   If the client cannot renew the lease (such as if Server 1 is down), the client waits until about 87.5% of the way through the lease and broadcasts another DHCPREQUEST to all DHCP servers. Any server can now return a DHCPACK containing the extended lease and updated parameters. This is the rebinding state.

7   When the lease reaches 100% expired, or a server sends back a DHCPNAK negative acknowledgment message, the client must give up the IP address. It then returns to the initializing state and has to start the address negotiation over again.

DHCP is defined in RFC 2131 and RFC 2132. Refer to them for more information.

Two DHCP servers are recommended for a network. The benefit of having more than one server is if one fails another is available to continue processing requests, ensuring that all hosts (old and new) are serviced continuously.

 

DHCP Administration

You can administer the DHCP server using the following TCPware Network Control Utility (NETCU) commands. For DHCP V3, use the component name “DHCP”. For DHCP V4, use the component name “DHCP4”.

Command	Description
RELEASE DHCP ip-address RELEASE DHCP4 ip-address	Forces the DHCP server to act as if it heard a DHCPRELEASE message from the client for the given IP address.
REMOVE DHCP ip-address REMOVE DHCP4 ip-address	Synonym for RELEASE DHCP/DHCP4.
SET DHCP/DEBUG=value SET DHCP4/DEBUG=value	Sets the debug logging level to the given value.
SET DHCP/NEWLOG SET DHCP4/NEWLOG	Starts a new debug log file.
SET DHCP/PARTNERDOWN SET DHCP4/PARTNERDOWN	For Failover DHCP: causes the DHCP server to transition into Partner Down state.
STOP/DHCP STOP/DHCP4	Causes the server to shut down.
SHOW DHCP/ALL SHOW DHCP4/ALL	Displays SHOW DHCP/SUBNET output for all subnets, plus information about static assignments.
SHOW DHCP/CLIENT_IDENTIFIER=client-id SHOW DHCP4/CLIENT_IDENTIFIER=client-id	Displays all lease binding and static assignment details for the given client ID.
SHOW DHCP/CONFIGURATION SHOW DHCP4/CONFIGURATION	Writes all configuration and lease information to a dump file.
SHOW DHCP/HARDWARE_ADDRESS= hardware-address SHOW DHCP4/HARDWARE_ADDRESS= hardware-address	Displays all lease binding and static assignment details for the given hardware address.
SHOW DHCP/IP_ADDRESS=ip-address SHOW DHCP4/IP_ADDRESS=ip-address	Displays lease binding details for the given IP address. Static assignments are not supported.
SHOW DHCP/ISKNOWN host, subclass SHOW DHCP4/ISKNOWN host, subclass	If host is specified, shows whether the given hardware address or client identifier is "known", that is if there is a host declaration for that hardware address or client identifier. If subclass is specified, shows whether the given subclass data exists as a subclass within the given class.
SHOW DHCP/LEASES SHOW DHCP4/LEASES	Displays brief information about each lease.
SHOW DHCP/POOLS SHOW DHCP4/POOLS	Displays address pool availability.
SHOW DHCP/STATUS SHOW DHCP4/STATUS	Checks if the DHCP server is running.
SHOW DHCP/SUBNET=ip-address SHOW DHCP4/SUBNET=ip-address	Displays brief information about each IP address in the same shared network as the given IP address.
SHOW DHCP/VERIFY SHOW DHCP4/VERIFY	Checks the syntax of the configuration file and optionally the lease file and the update file.
SHOW DHCP/VERSION SHOW DHCP4/VERSION	Displays the version of the DHCP server.
UPDATE DHCP UPDATE DHCP4	Instructs the Dynamic Host Configuration Protocol (DHCP) server to process the update file and add or remove the specified host and subclass declarations.

 

See the NETCU Command Reference for details about these commands.

DHCP Service Configuration

You can configure the DHCP server using CNFNET, by typing @TCPWARE:CNFNET DHCP for the DHCP V3 server and @TCPWARE:CNFNET DHCP4 for the DHCP V4 server.

You can configure the following items:

•   Enable or disable the DHCP server.

•   Set the debug logging level.

•   Set the debug log file name.

•   Include the date in the log file or not.

•   Log debug messages to OPCOM or not.

See the DHCP configuration description in the Installation and Configuration Guide.

Verifying the DHCP Configuration

Whenever you modify the configuration file, it is good practice to verify the syntax by entering the following NETCU command:

$ NETCU SHOW DHCP /VERIFY[=(config=<config-file>)] -
_$ [/OUTPUT=<output-file>]

For DHCP V4, specify “DHCP4” instead of “DHCP” in the above command.

This command causes the DHCP server to run enough to read and parse the configuration file. The DHCP server displays a copyright notice and a message for each syntax error encountered. If the DHCP server displays only the copyright notice, the configuration file has no syntax errors.

The CONFIG option optionally specifies where the configuration file is. If you do not specify the CONFIG option, the DHCP server reads the default configuration file TCPWARE:DHCPD.CONF. Note that both the DHCP V3 server and the DHCP V4 server use this as the configuration file name.

The /OUTPUT qualifier optionally sends command output to the specified file.

Reloading the DHCP Configuration

If you modify TCPWARE:DHCPD.CONF after starting the DHCP server, reload the DHCP configuration by restarting the DHCP server by using @TCPWARE:RESTART DHCP (V3) or @TCPWARE:RESTART DHCP4 (V4). When the DHCP server restarts, it rereads the configuration file.

Upgrading to DHCP V4

There are no conversion tools to upgrade to the ISC DHCP V4 server, either from the pre-ISC DHCP server that was in TCPware v5.3 and earlier, or from the ISC DHCP V3 server.  If you are upgrading from TCPware v5.3 or earlier and want to use the ISC DHCP V4 server, you can use the conversion tool described below to upgrade to ISC DHCP V3 and then use the following procedure to upgrade from there to ISC DHCP V4.

The DHCP V3 and V4 configuration files are substantially similar. Any changes that are needed can be made by hand. The biggest changes between the DHCP V3 server configuration file and the DHCP V4 server configuration file are in the areas of Dynamic DNS Updates (DDNS) and Failover. This is due to the fact that in DHCP V3, DDNS and Failover are Process Software implementations, and in DHCP V4, they are the ISC implementations. Other changes in DHCP V4 are:

·         Process Software's Host Name Generation function is no longer available. In DHCP V4, various evaluation functions can be used in the configuration file to ask the server to create a host name.

·         The configuration file statement allow/deny ras-servers has been removed. This statement was deprecated in a previous release and has been removed altogether in DHCP V4.

The DHCP V3 server lease file is most likely not going to be able to be read by the DHCP V4 server. It may be able to be read if you are using a simple configuration. It will definitely not be able to be read if you are using DDNS or Failover. In most cases, you should expect that when you upgrade to DHCP V4, you will lose the entire database of leases. In that case, all DHCP clients will have to obtain new leases. To avoid conflicts, it is recommended that prior to the upgrade, the length of leases being given out by the DHCP server be made very short, so that all leases expire during the changeover. You may also want to consider initially using a different range of addresses after the upgrade to doubly ensure that the DHCP V4 server does not attempt to give out leases for IP addresses that are still in use.

DHCP Conversion Tool

The DHCP_CONVERSION_TOOL assists in changing from the pre-ISC DHCP server that was in TCPware v5.3 and earlier to the ISC DHCP V3 server. This tool converts the configuration file and lease file from the v5.3 DHCP server to the format of the configuration and lease files of the ISC DHCP V3 server. It is run automatically if necessary by the command procedure that starts the DHCP server, TCPWARE:DHCP_CONTROL.COM. However, it is recommended that you run the conversion tool and verify the output ahead of time.

Note that if you are upgrading from TCPware v5.3 or earlier and want to use the ISC DHCP V4 server, you need to convert the v5.3 configuration file to the ISC DHCP V3 format, and then perform any necessary changes for DHCP V4 by hand.

The DHCP conversion tool reads the v5.3 DHCP configuration file or BOOTP configuration file and writes out a configuration file in the ISC DHCP V3 format. All information from the v5.3 configuration file is in the generated file. Information that does not have an equivalent is represented with comment lines.

The conversion tool then reads the v5.3 lease file and writes out a lease file in the ISC DHCP V3 format.

The v5.3 configuration and lease files are retained in their original location so you can use them to validate the new configuration and lease files.

You can also run the conversion tool directly by specifying the names of the input and output files at the command prompt. If they are not specified, the tool prompts you for them. Enter “NONE” for the file name if you do not have the input file. For example: if you do not have a lease file, then enter:

$ dhcpconvert :== $tcpware:dhcp_conversion_tool.exe
$ dhcpconvert dhcptab. none dhcpd.conf dhcpd.leases

Enter a question mark (?) to get help for the tool. The default file names are:

TCPWARE:DHCPTAB.	The v5.3 DHCP configuration file.
TCPWARE:BOOTPTAB.	The v5.3 BOOTP configuration file. Read only if the DHCPTAB file does not exist.
TCPWARE:DHCPD.CONF	The ISC DHCP V3 configuration file.
TCPWARE:DHCP_LEASE.DAT	The v5.3 DHCP lease file containing the lease status.
TCPWARE:DHCPD.LEASES	The ISC DHCP V3 lease file.

 

Note!       Review the output lease file carefully. The v5.3 TCPware lease file does not contain the hardware type, so the conversion tool usually uses ethernet. If you are using a token ring network, change the 'hardware ethernet' statements to 'hardware token-ring' statements. The v5.3 TCPware lease file also does not contain whether the ID was a hardware address or client identifier, so review carefully all 'uid' and 'hardware' statements.

Introducing the Configuration File

TCPware supplies template DHCP configuration files for both DHCP V3 and DHCP V4 that contain comments and a number of examples to help you enter information for your hosts. The template DHCP configuration files are:

·         TCPWARE:DHCPD_CONF.TEMPLATE for DHCP V3

·         TCPWARE:DHCPD4_CONF.TEMPLATE for DHCP V4

Using this template as a guide, create a DHCP configuration file at TCPWARE:DHCPD.CONF (with any text editor) containing the entries you need for your network and hosts. The dhcpd.conf file is a free-form ASCII text file. The file may contain extra tabs and new lines for formatting purposes and comments may be placed anywhere within the file (except within quotation marks). Comments begin with the # character and end at the end of the line. Keywords in the file are case-insensitive.

Note!             Whenever changes are made to the dhcpd.conf file, the DHCP server must be restarted.

The file consists of a list of statements specify which fall into two categories: parameters and declarations.

Parameters

Parameter statements always specify one of the following:

•   How to do something (for example, how long a lease to offer)

•   Whether to do something (for example, should the DHCP server provide addresses to unknown clients)

•   What parameters to provide to the client (for example, use gateway 220.177.244.7)

Global parameters are at the beginning of the file. Some examples of global parameters are the organization's domain name and the addresses of the name servers (if they are common to the entire organization).

It is legal to specify host addresses in parameters as domain names rather than as numeric IP addresses. If a given hostname resolves to more than one IP address (for example, if that host has two ethernet interfaces), then where possible both addresses are supplied to the client.

Both the shared-network statement and the subnet statement can have parameters.

The most obvious reason for having subnet-specific parameters is that each subnet, of necessity, has its own router; for example:

option routers 204.254.239.1;

Note that the address is specified numerically; this is not required. If you have a different domain name for each interface on your router, it is appropriate to use the domain name for that interface instead of the numeric address. However, there may be only one domain name for all a router's IP addresses, and it would not be appropriate to use that name here.

Parameters starting with the option keyword correspond to actual DHCP options. Parameters that do not start with the option keyword either control the behavior of the DHCP server (for example, how long a lease the DHCP server will give out), or specify client parameters that are not optional in the DHCP protocol (for example, server-name and filename).

Each host can have host-specific parameters. These could include such things as the:

•   Hostname option

•   Name of a file to upload (the filename parameter)

•   Address of the server from which to upload the file (the next-server parameter)

In general, any parameter can appear wherever parameters are allowed, and will be applied according to the scope in which the parameter appears.

All parameters must be specified first before you can specify any declarations that depend on those parameters. Parameters should be set inside declarations so they can be set on a per-subnet or a per-host basis.

Declarations

Declarations are used to:

•   Describe the topology of the network.

•   Describe clients on the network.

•   Provide addresses that can be assigned to clients.

•   Apply a group of parameters to a group of declarations.

Declarations about network topology include the subnet and the shared-network declarations.

For every subnet to be served, and for every subnet connected to the DHCP server, there must be one subnet declaration. This declaration tells the DHCP server how to recognize that an address is on that particular subnet. A subnet declaration is required for each subnet even if no addresses are dynamically allocated on that subnet.

There are different declarations required for different situations. The following are the basic declarations in a configuration file.

•   For clients with dynamically assigned addresses, a range declaration must appear within the subnet declaration, or within a pool declaration.

•   For clients with statically assigned addresses, or for installations where only known clients will be served, each client must have a host declaration.

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

Some installations have physical networks allowing more than one IP subnet to operate. For example, if your site has a requirement that 8-bit subnet masks be used, but a department with a single physical ethernet network expands beyond 254 nodes, you may have to run two 8-bit subnets on the same ethernet until a new physical network is added. In this case, you can enclose the subnet declarations for the two networks in a shared-network declaration.

Note that even when the shared-network declaration is absent, an empty one is created by the server to contain the subnet (and any scoped parameters included in the subnet). For practical purposes, this means that "stateless" DHCP clients, which are not tied to addresses (and therefore subnets) will receive the same configuration as stateful ones.

Some sites may have departments that have clients on more than one subnet. It may be desirable to offer those clients a uniform set of parameters that are different than what would be offered to clients from other departments on the same subnet.

•   For clients declared explicitly with host declarations, enclose the declarations in a group declaration using the parameters that are common to that department.

•   For clients with dynamically assigned addresses, group parameter assignments by network topology. Alternately, host declarations can provide parameters and if they have no fixed-address parameter, the clients get an address dynamically assigned. See the example below.

•   In DHCP V4, class declarations and conditional declarations may be used may be used to group parameter assignments based on information the client sends.

When a client is to be booted, its boot parameters are determined by consulting the following scopes in this order:

1   Client’s host declaration (if any).

2   Group declaration (if any) that enclosed the host declaration.

3   Subclass declaration for the subclass the client belongs to (if any).

4   Class declaration for the class the client belongs to (if any).

5   Pool declaration that the assigned IP address comes from (if any).

6   Subnet declaration for the subnet on which the client is booting.

7   Shared-network declaration (if any) containing that subnet.

8   Top-level parameters that may be specified outside of any declaration.

Each of these declarations itself appears within a lexical scope, and all declarations at less specific lexical scopes are also consulted for client option declarations.   Scopes are never considered twice, and if parameters are declared in more than one scope, the parameter declared in the most specific scope is the one that is used.

When searching for a host declaration, the DHCP server looks for one with a fixed-address parameter that matches the subnet or shared network on which the client is booting. If no such entry is found, it looks for an entry with no fixed-address parameter.

Example

Imagine that you have a site with a lot of NCD X-Terminals. These terminals come in a variety of models, and you want to specify the boot files for each model. You could have host declarations for each server and group them by model:

group {
      filename "Xncd19r";
      next-server ncd-booter;
      host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; }
      host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; }
      host ncd8 { hardware ethernet 0:c0:c3:22:46:81; }
}
group {
      filename "Xncd19c";
      next-server ncd-booter;
      host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; }
      host ncd3 { hardware ethernet 0:c0:c3:00:14:11; }
}
group {
      filename "XncdHMX";
      next-server ncd-booter;
      host ncd1 { hardware ethernet 0:c0:c3:11:90:23; }
      host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; }
      host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; }
}

Dynamic Address Allocation

Address allocation is done when a client is in the INIT state and has sent a DHCPDISCOVER message.  When the DHCP server is looking for an IP address to allocate to a client, it checks first

•   if the client has an active lease on an IP address, or

•   if the client has an expired lease on an IP address that has not been reassigned.

It then follows these rules:

–      If a lease was found but the client is not permitted to use it, then the lease is freed (if it was not expired already).

–      If no lease is found or a lease was found and the client is not permitted to use the address, then the server looks for an address that is not in use and that the client is permitted to have among the list of address pools on the client’s subnet.

–      If no addresses are found that can be assigned to the client, then no response is sent to the client.

–      If an address is found that the client is permitted to have, then the address is allocated to the client.

Note that IP addresses that have never been assigned are chosen over those that have previously been assigned to other clients. 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.

Note also that the DHCP server generates the list of available IP addresses from a hash table.  This means that the addresses are not sorted in any particular order.  It is not possible to predict or control the order in which the DHCP server allocates IP addresses.

Renewing

If the client thinks it has a valid lease and sends a DHCPREQUEST to initiate or renew that lease, the server has three choices. It can

•   Ignore the DHCPREQUEST.

•   Send a DHCPNAK, telling the client to stop using the address.

•   Send a DHCPACK, telling the client to use the address.

If the server finds the requested address and that address is available to the client, the server sends a DHCPACK.

If the address is no longer available or the client is not permitted to have it, the server sends a DHCPNAK.

If the server knows nothing about the address, the server remains silent. However, if the address is incorrect for the network segment to which the client is attached and the server is authoritative for that segment, the server sends a DHCPNAK.

Fixed Addresses

There may be a host declaration matching the client's identification.   If that host declaration contains a fixed-address declaration that lists an IP address 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 sends a DHCPREQUEST for some other address, the server will respond with a DHCPNAK.

Address Pools

Pool declarations let you have different allocation policies for different address allocation pools. A client may be denied access to one pool, but allowed access to another pool on the same network segment.

A pool declaration is used to specify how a group of addresses should be treated differently than another group of addresses, even if they are on the same network segment or subnet.

For example, you can provide a large set of addresses assigned to DHCP clients that are known to your DHCP server, while at the same time providing a small set of addresses that are available for unknown clients. If you have a firewall, you can arrange for addresses from one pool to have access to the Internet, while addresses in another pool do not have access to the Internet. The following example illustrates how you could set up a pair of pool declarations.

subnet 10.0.0.0 netmask 255.255.255.0 {
  option routers 10.0.0.254;

  # Unknown clients get this pool.
  pool {
    option domain-name-servers bogus.example.com;
    max-lease-time 300;
    range 10.0.0.200 10.0.0.253;
    allow unknown-clients;
  }

  # Known clients get this pool.
  pool {
    option domain-name-servers ns1.example.com, ns2.example.com;
    max-lease-time 28800;
    range 10.0.0.5 10.0.0.199;
    deny unknown-clients;
  }
}

You can also set up entirely different subnets for known and unknown clients. This is possible because address pools exist at the level of shared networks, so address ranges within pool declarations can be on different subnets, as long as they are on the same shared network.

Pool Permit Lists

The above example shows that address pools can have permit lists. A permit list controls which clients are allowed access to the address pool and which clients are not allowed access. Each entry in a permit list is introduced with the allow or deny keyword. The following table describes the four possibilities for eligibility to addresses from the address pool.

If a pool has...	Then...
a permit list	Only those clients that match specific entries on the permit list are eligible for addresses from the pool.
a deny list	Only those clients that do not match any entries on the deny list are eligible for addresses from the pool.
both a permit list and a deny list	Only clients that match the permit list and do not match the deny list are eligible for addresses from the pool.
neither a permit list nor a deny list	All clients are eligible for addresses from the pool.

 

Range declarations that appear outside of pool declarations in the same shared-network are grouped into two pools: one which allows all clients for range statements with the “dynamic-bootp” keyword and one which denies dynamic-bootp clients for range statements without the “dynamic-bootp” keyword.

As described in the Dynamic Address Allocation section, the DHCP server checks each IP address pool in sequence to see if the client is permitted to use it, in response to both DHCPDISCOVER and DHCPREQUEST messages. The DHCP server checks both the address pool permit lists and the relevant in-scope allow and deny statements. If the client is allowed to use the pool, the server chooses an available address from that pool (if any) and tentatively assigns that address to the client.

See below for the recognized allow and deny statements. They can be used to permit or refuse access to known or unknown clients, members of a class, dynamic bootp clients, or all clients.

IP Address Conflict Prevention

The DHCP server 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 (ping) to the IP address being allocated.   If no ICMP Echo reply is received within a second, the address is assumed to be free.  This is only done for leases that have been specified in range statements, and only when the lease is thought by the DHCP server to be free – that is, the DHCP server or its failover peer has not listed the lease as in use.

If a response is received to an ICMP Echo request, the DHCP server assumes that there is a configuration error – that the IP address is in use by some host on the network that is not a DHCP client.  It marks the address as abandoned, and will not assign it to clients.

If a DHCP client tries to get an IP address, but none are available, but there are abandoned IP addresses, then the DHCP server will attempt to reclaim an abandoned IP address.  It marks one IP address as free, and then does the same ICMP Echo request check described previously.   If there is no answer to the ICMP Echo request, the address is assigned to the client.

The DHCP server does not cycle through abandoned IP addresses if the first IP address it tries to reclaim is free.   Rather, when the next DHCPDISCOVER comes in from the client, it will attempt a new allocation using the same method described here, and will typically try a new IP address.

Lease Lengths

DHCP leases can be assigned almost any length from zero seconds to infinity. What lease length makes sense for any given subnet, or for any given installation, will vary depending on the kinds of hosts being served.

For example, in an office environment where systems are added from time to time and removed from time to time, but move relatively infrequently, it might make sense to allow lease times of a month or more.  In a final test environment on a manufacturing floor, it may make more sense to assign a maximum lease length of 30 minutes – enough time to go through a simple test procedure on a network appliance before packaging it up for delivery.

It is possible to specify two lease lengths: the default length that will be assigned if a client doesn't ask for any particular lease length, and a maximum lease length.  These are specified as clauses to the subnet command, for example:

subnet 10.252.197.0 netmask 255.255.255.0 {
     range 10.252.197.10 10.252.197.107;
     default-lease-time 600;
     max-lease-time 7200;
}

This particular subnet declaration specifies a default lease time of 600 seconds (ten minutes), and a maximum lease time of 7200 seconds (two hours).  Other common values would be 86400 (one day), 604800 (one week) and 2592000 (30 days). Note that each subnet need not have the same lease.

Reserved Leases (DHCP V4)

(DHCP V4 only) It's often useful to allocate a single address to a single client, in approximate perpetuity.   Host statements with fixed-address clauses exist to a certain extent to serve this purpose, but because host statements are intended to approximate 'static configuration', they suffer from not being referenced in a litany of other server services, such as dynamic DNS, failover, 'on events' and so forth.

In DCHP V4, if a standard dynamic lease, as from any range statement, is marked reserved, then the server will only allocate this lease to the client it is identified by (by client identifier or hardware address). In practice, this means that the lease follows the normal state engine, enters ACTIVE state when the client is bound to it, expires, or is released, and any events or services that would normally be supplied during these events are processed normally, as with any other dynamic lease.  The only difference is that failover servers treat reserved leases as special when they enter the FREE or BACKUP states – each server applies the lease into the state it may allocate from – and the leases are not placed on the queue for allocation to other clients.  Instead they may only be 'found' by client identity.  The result is that the lease is only offered to the returning client.

Note!     Care should be taken to ensure that the client only has one lease within a given subnet that it is identified by.

Leases may be set 'reserved' through the infinite-is-reserved configuration option. Leases marked 'reserved' are effectively treated the same as leases marked 'bootp'.

Client Classing

You can separate clients into classes, treating each client differently depending on what class it is in. To separate clients into classes, use conditional statements (see the Conditional Behavior section) or a match statement within a class declaration. You can specify a limit on the total number of clients within a particular class or subclass that may hold leases at one time using the lease limit statement. You can specify automatic subclassing based on the contents of the client packet using the spawn with statement.

To add clients to classes based on conditional evaluation, write a conditional statement to match the clients you want in the class. Then, put an add statement in the conditional's list of statements. For example, to identify requests coming from Microsoft^(R) NT RAS servers:

if substring (option dhcp-client-identifier, 1, 3) = "RAS" {
  add "ras-clients";
}

An equivalent way to do this is to specify the conditional expression as a matching expression in the class statement. For example:

class "ras-clients" {
  match if substring (option dhcp-client-identifier, 1, 3) = "RAS";
}

Note!     Whether you use matching expressions or add statements (or both) to classify clients, you must write a class declaration for any class that you use.

If you want no match statement and no in-scope statements for a class, the declaration looks like this, for example:

class "ras-clients" {
}

Important!   The add statement adds the client to the class after the address assignment has been completed. This means the client will not be affected by pool permits related to that class if the client is a member of a class due to an add statement.

Subclasses

In addition to classes, you can declare subclasses. A subclass is a class having the same name as a regular class but with a specific submatch expression that is hashed for quick matching. It is quicker to find five subclasses within one class than it is to find five classes with match expressions. The following example illustrates how to code for subclasses:

class "allocation-class-1" {
  match pick-first-value (option dhcp-client-identifier, hardware);
}

class "allocation-class-2" {
  match pick-first-value (option dhcp-client-identifier, hardware);
}

subclass "allocation-class-1" 1:0:0:c4:aa:29:44;
subclass "allocation-class-1" 1:8:0:2b:4c:39:ad;
subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3;

subnet 10.0.0.0 netmask 255.255.255.0 {
  pool {
    allow members of "allocation-class-1";
    range 10.0.0.11 10.0.0.50;
  }
  pool {
    allow members of "allocation-class-2";
    range 10.0.0.51 10.0.0.100;
  }
}

The data following the class name in the subclass declaration is a constant value used in matching the match expression for the class. During class matching, the server evaluates the match expression and looks up the result in the hash table. If a match is found, the client is considered a member of both the class and the subclass.

You can specify subclasses with or without scope (i.e., statements). In the above example, the sole purpose of the subclass is to allow some clients access to one address pool, while other clients are given access to the other pool. Thus, these subclasses are declared without any statements (scope). If you wanted to define different parameter values for some clients, you would declare those subclasses with scopes.

For example: if you had a single client needing some configuration parameters, while most did not, you might write the following subclass declaration for that client:

subclass "allocation-class-2" 1:08:00:2b:a1:11:31 {
  option root-path "samsara:tcpware:alphapc";
  filename "tcpware:netbsd.alphapc-diskless";
}

In these examples, subclassing is being used as a way to control address allocation on a per-client basis. However, it is possible to use subclassing in ways that are not specific to clients. For example, you can use the value of the vendor-class-identifier option to determine what values to send in the vendor-encapsulated-options option. See the Vendor Encapsulated Options section.

Note!     If you are using match hardware, the hardware address is preceded by the hardware type. In this example, the “1:” indicates Ethernet.

Per-Class Limits on Dynamic Address Allocation

The number of clients in a class that can be assigned leases can be limited. This limiting makes it difficult for a new client in a class to get an address. Once a class has reached its limit, the only way a new client in that class can get a lease is for an existing client to relinquish its lease, either by

•   letting it expire, or

•   sending a DHCPRELEASE packet.

The following example illustrates how to specify classes with lease limits.

class "limited-1" {
  lease limit 4;
}

This produces a class in which a maximum of four members may hold leases at one time.

Spawning Classes

It is possible to declare a spawning class. A spawning class is a class that automatically produces subclasses based on what the client sends.   The reason that spawning classes were created was to make it possible to create lease-limited classes on the fly. For example, if you want to provide clients at a particular site with more than one IP address, but do not want to provide these clients with their own subnet, nor give them an unlimited number of IP addresses from the network segment to which they are connected, you can create a spawning class and use lease limits.

Many cable modem head-end systems can be configured to add a Relay Agent Information option to DHCP packets when relaying them to the DHCP server. These systems typically add a circuit ID or remote ID option that uniquely identifies the customer site. The following example illustrates how to write a class declaration to take advantage of these relay agent options to create lease limited classes on the fly:

class "customer" {
  match if exists agent.circuit-id;
  spawn with option agent.circuit-id;
  lease limit 4;
}

With this class declaration, whenever a request comes in from a customer site, the circuit ID option is checked against the class's hash table.

•   If a subclass matches the circuit ID, the client is classified in that subclass.

•   If no subclass matches the circuit ID, a new subclass is created and logged in the dhcpd.leases file and the client is classified in the new subclass.

Once a client is classified, it is treated according to the rules of the class; as in the example above, being subjected to the per-site limit of four leases.

Note!     The use of the subclass spawning mechanism is not restricted to relay agent options. This particular example is given only because it is a straightforward one.

Combining Match, Match-If, and Spawn

In some cases, it may be useful to use one expression to assign a client to a particular class, and a second expression to put it into a subclass of that class.   This can be done by combining the match if and spawn with statements, or the match if and match statements.   For example:

class "jr-cable-modems" {
  match if option dhcp-vendor-identifier = "jrcm";
  spawn with option agent.circuit-id;
  lease limit 4;
}

class "dv-dsl-modems" {
  match if option dhcp-vendor-identifier = "dvdsl";
  spawn with option agent.circuit-id;
  lease limit 16;
}

This allows you to have two classes that both have the same spawn with expression without getting the clients in the two classes confused with each other.

Events (DHCP V4)

(DHCP V4 only) There are three kinds of events that can happen regarding a lease, and it is possible to declare statements that occur when any of these events happen.   These events are:

·         the commit event, when the server has made a commitment of a certain lease to a client

·         the release event, when  the client has released the server from its commitment

·         the expiry event, when the commitment expires

To declare a set of statements to execute when an event happens, you must use the on statement, followed by the name of the event, followed by a series of statements to execute when the event happens, enclosed in braces.

Conditional Behavior

The DHCP server can be configured to perform conditional behavior depending on the packets it receives.

Conditional behavior is specified using the if statement and the else or elsif statements. A conditional statement can appear anywhere that a regular statement can appear, and can enclose one or more such statements. The following is an example of a conditional statement.

if option dhcp-user-class = "accounting" {
  max-lease-time 17600;
  option domain-name "accounting.example.org";
  option domain-name-servers ns1.accounting.example.org,
                                   ns2.accounting.example.org;
} elsif option dhcp-user-class = "engineering" {
  max-lease-time 17600;
  option domain-name "engineering.example.org";
  option domain-name-servers ns1.engineering.example.org,
                                   ns2.engineering.example.org;
} else {
  max-lease-time 600;
  option domain-name "misc.example.org";
  option domain-name-servers ns1.misc.example.org,
                                   ns2.misc.example.org;
}

Both the if statement and the elsif continuation statement take expressions that, when evaluated, produce a boolean result. See the Expressions section for more information.

•   If the expression evaluates to true, then the statements enclosed in braces following the if statement are executed. All subsequent elsif and else clauses are skipped.

•   If the expression evaluates to false, then the statements enclosed in braces following the if statement are not executed and each subsequent elsif clause is checked until an elsif clause is encountered that evaluates to true.

•   If such an elsif clause is found, then the statements in braces following it are executed. Any subsequent elsif and else clauses are skipped.

•   If all the if and elsif clauses are checked but none of their expressions evaluate to true, then if there is an else clause, then the statements enclosed in braces following the else clause are evaluated.

Note!     Boolean expressions that evaluate to null are treated as false in conditionals.

Dynamic DNS Updates (DDNS)

The DHCP server has the ability to perform dynamic updates to DNS using DNS's dynamic updating functionality (DDNS). Within the configuration files, you can define how you want the updates to be done.

Note!     Be sure to configure your name server to allow updates from the DHCP server, see Chapter 3, Domain Name Services.

DDNS in DHCP V3

This section describes how DDNS is implemented in the DHCP V3 server.

The following statements in the DHCP V3 server configuration file are related to dynamic updating:

•   allow/deny dynamic-update;

•   allow/deny update-A-record;

•   allow/deny name-by-client;

•   invalid-ddns-chars {fail | discard | replace [“chars”]};

See the  Failover Configuration File Statements section).

Allow and Deny Statements and DHCP Statements sections for a description of these statements.

Dynamic updates can be enabled or disabled by using the allow/deny dynamic-update statement in the configuration file. The default is to not perform dynamic updates. Dynamic updates can be turned on or off on a per subnet basis. Note that dynamic updates are not done at all for static assignments to BOOTP clients, and the support for static assignments to DHCP clients is to add DNS entries only.

When dynamic updating is enabled, the DHCP server determines the client's Fully Qualified Domain Name (FQDN) and assigns it an IP address. The FQDN is determined either by what the client sends or by what is in the configuration file. This behavior is controlled by the allow/deny name-by-client statement in the configuration file.

If you use the deny name-by-client statement or if the client does not send a name, you must specify the host name in the configuration file using one of the following methods:

•   Using option host-name “name” (see the Host Name Generation section)

•   Specifying use-host-decl-names on in conjunction with host declarations.

If the hostname specified by the client contains invalid characters for DNS, the DHCP server can handle them one of three ways:

•   Consider it a failure and not do the dynamic update.

•   Throw away the invalid characters.

•   Replace the invalid characters with specified valid characters.

This behavior is controlled by the invalid-ddns-chars statement in the configuration file.

The FQDN and IP address are used in the dynamic update to create a PTR resource record (RR). The DHCP server also optionally creates an A RR. This option is enabled or disabled by using the allow/deny update-A-record statement in the configuration file. The default is to not create the A RR. This can be set on a per subnet basis. See Chapter 3, Domain Name Services for information about PTR resource records and A resource records.

When dynamic updating is allowed, the DHCP server adds the resource records whenever an IP address is leased to a client. The RRs are deleted if the IP address is released or if the IP address is leased to a different client. Also, the RRs are deleted for expired leases periodically.

DDNS in DHCP V4

This section describes how DDNS is implemented in the DHCP V4 server.

The following statements in the DHCP V4 server configuration file are related to dynamic updating:

•   ddns-updates flag;

•   ddns-update-style { interim | none };

•   do-forward-updates flag;

•   ddns-hostname name;

•   ddns-domainname name;

•   ddns-rev-domainname name;

•   update-static-leases flag;

•   allow/deny/ignore client-updates;

•   update-conflict-detection flag;

•   update-optimization flag;

The use of these statements is described in this section. These statements are also listed in the  Failover Configuration File Statements section).

Allow and Deny Statements and DHCP Statements sections.

The DNS update scheme implemented by DHCP V4 is called the interim DHCP-DNS interaction draft update mode. In future versions of ISC DHCP, an update mode will be implemented based on the standardized RFCs which came from these drafts.

Use the ddns-update-style interim statement to enable the interim update mode. To turn on DDNS updates, use the statement ddns-updates on. The ddns-updates statement can be at the top of the dhcpd.conf file or inside a shared-network or subnet declaration or other scope.

DHCP V4 Interim Update Mode

Updating A and PTR Records

With the interim update mode, the DHCP server does not necessarily always update both the A and the PTR records. By default, forward (A record) updates are enabled. They can be disabled by setting the do-forward-updates parameter to off or false. In this case, the DHCP server never attempts to update the client’s A record, and only attempts to update the PTR record if the client supplies an FQDN that should be placed in the PTR record using the FQDN option. If forward updates are enabled, then the DHCP server honors the client-updates flag.

The FQDN option sent by the client may include a flag which indicates that the client wishes to update its own A record. In that case, the server can be configured either to honor the client's intentions or ignore them. This is done with the statement allow/deny/ignore client-updates. By default, client updates are allowed.

If the server is configured to allow client updates, then if the client sends a fully-qualified domain name in the FQDN option, the server will use that name to update the PTR record. For example, let us say that the client is a visitor from the "radish.org" domain, whose hostname is "jschmoe". The server is for the "example.org" domain. The DHCP client indicates in the FQDN option that its FQDN is "jschmoe.radish.org.". It also indicates that it wants to update its own A record. The DHCP server therefore does not attempt to set up an A record for the client, but does set up a PTR record for the IP address that it assigns the client, pointing at jschmoe.radish.org. Once the DHCP client has an IP address, it can update its own A record, assuming that the "radish.org" DNS server will allow it to do so.

If the server is configured not to allow client updates or if the client doesn't want to do its own update, the server performs the update of the A record.

The server must determine a host name for the client. It first looks for a ddns-hostname configuration option, and using that if it is present.  If no such option is present, the server looks for a valid hostname in the FQDN option sent by the client.  If one is found, it is used. Otherwise, if the client sent a host-name option, that is used.  Otherwise, if there is a host declaration that applies to the client, the name from that declaration is used (the name can be specified via the host-name option, or by enabling the use-host-decl-names parameter).  If none of these applies, the server will not have a hostname for the client, and will not be able to do a DNS update.

Note that in the configuration file, ddns-hostname or the host-name option can be defined such that the server will generate a host name. See the Expressions section for more information.

The server then chooses a domain name for the client. By default, the server uses its own domain name. If desired, the domain name may be specified in the configuration file by using the option domain-name statement, or the ddns-domainname parameter. For the PTR record, the domain name is by default “in-addr.arpa”. If desired, this domain name may be specified in the configuration file by using the ddns-rev-domainname parameter.

The domain name is appended to the host name that it chose for the client. The server then updates both the A and PTR record.

After doing the DDNS updates, if the ignore client-updates directive is used, then the server sends a response in the DHCP packet, using the FQDN option, that implies to the client that it should perform its own updates if it chooses to do so. With deny client-updates, a response is sent which indicates the client may not perform updates.

Conflict Detection

With the interim scheme, a method is used that allows more than one DHCP server to update the DNS database without accidentally deleting A records that shouldn't be deleted nor failing to add A records that should be added. The scheme works as follows:

When the DHCP server issues a client a new lease, it creates a text string that is an MD5 hash over the DHCP client's identification. The update adds an A record with the name the server chose and a TXT record containing the hashed identifier string. If this update succeeds, the server is done.

If the update fails because the A record already exists, then the DHCP server attempts to add the A record with the prerequisite that there must be a TXT record in the same name as the new A record, and that TXT record's contents must be equal to the hashed identifier. If this update succeeds, then the client has its A record and PTR record. If it fails, then the name the client has been assigned (or requested) is in use, and can't be used by the client. At this point the DHCP server gives up trying to do a DNS update for the client until the client chooses a new name.

This conflict detection can be disabled by setting the update-conflict-detection parameter to off or false in the configuration file. In this case, the server skips the TXT file check and instead simply tears down any previous binding to install the new binding without question.

Update Optimization

Because each DNS update involves a round trip to the DNS server, there is a cost associated with doing updates even if they do not actually modify the DNS database. So the DHCP server tracks whether or not it has updated the record in the past (this information is stored on the lease) and does not attempt to update records that it thinks it has already updated.

This optimization can be disabled by setting the update-optimization parameter to off or false in the configuration file. If the update-optimization parameter is false for a given client, the server will attempt a DNS update for that client each time the client renews its lease.  This will allow the DNS to heal from database inconsistencies more easily, but the cost is that the DHCP server must do many more DNS updates. We recommend leaving this optimization enabled, which is the default.  If this parameter is not specified, or is set to true, the DHCP server will only update when the client information changes, the client gets a different lease, or the client's lease expires.

Static Leases

By default, the server does not do DDNS updates for static assignments – that is, if the IP address is specified in a fixed-address statement in a host declaration. The update-static-leases flag, if enabled, causes the DHCP server to do DNS updates for a client even if it is being given a static assignment.  It is not recommended because the DHCP server has no way to tell that the update has been done, and therefore will not delete the record when it is not in use.  Also, the server must attempt the update each time the client renews its lease, which could have a significant performance impact in environments that place heavy demands on the DHCP server.

DNSSEC (DHCP V4 only)

This section describes how DDNS security (DNSSEC) is implemented in the DHCP V4 server.

The following statements in the DHCP V4 server configuration file are related to DNSSEC:

•   key

•   zone

The use of these statements is described here. They are also listed in the DHCP Statements section.

When you set your name server up to allow updates from the DHCP server, you may be exposing it to unauthorized updates. To avoid this, you should use TSIG signatures – a method of cryptographically signing updates using a shared secret key. As long as you protect the secrecy of this key, your updates should also be secure.  Note, however, that the DHCP protocol itself provides no security, and that clients can therefore provide information to the DHCP server which the DHCP server will then use in its updates, with the constraints described previously.

Name Server Configuration

The name server must be configured to allow updates for any zone that the DHCP server will be updating.  For example, let us say that clients in the example.org domain are assigned addresses on the 10.10.17.0/24 subnet.  In that case, you need a key declaration for the TSIG key you will be using, and also two zone declarations – one for the zone containing A records that are updated and one for the zone containing PTR records. For the TCPware DNS server, you can use something like the following. Note that you may also wish to enable logging of DNS updates in your name server (not shown here).

     key DHCP_UPDATER {
       algorithm HMAC-MD5.SIG-ALG.REG.INT;
       secret pRP5FapFoJ95JEL06sv4PQ==;
     };

     zone "example.org" {
          type master;
          file "example_org.hosts";
          allow-update { key DHCP_UPDATER; };
     };

     zone "17.10.10.in-addr.arpa" {
          type master;
          file "17_10_10_inaddr_arpa.hosts";
          allow-update { key DHCP_UPDATER; };
     };

DHCP Server Configuration

You also have to configure your DHCP server to do updates to these zones.  To do so, you need to add something like the following to your dhcpd.conf file:

     key DHCP_UPDATER {
       algorithm HMAC-MD5.SIG-ALG.REG.INT;
       secret pRP5FapFoJ95JEL06sv4PQ==;
     };

     zone EXAMPLE.ORG. {
       primary 127.0.0.1;
       key DHCP_UPDATER;
     }

     zone 17.127.10.in-addr.arpa. {
       primary 127.0.0.1;
       key DHCP_UPDATER;
     }

The primary statement specifies the IP address of the name server whose zone information is to be updated.  In addition to the primary statement, you may also specify secondary statements.  The secondaries provide for additional addresses for name servers to be used if the primary does not respond.  The number of name servers the DDNS code will attempt to use before giving up is limited and is currently set to three.

Note that the zone declarations have to correspond to authority records in your name server – in the above example, there must be SOA records for "example.org." and for "17.10.10.in-addr.arpa.".  For example, if there were a subdomain "foo.example.org" with no separate SOA, you could not write a zone declaration for "foo.example.org." Also keep in mind that zone names in your DHCP configuration should end in a dot ("."); this is the preferred syntax but not required.  (If you do not end your zone name in a dot, the DHCP server will figure it out.)  Also note that in the DHCP configuration, zone names are not encapsulated in quotes the way they are in the name server configuration.

Using dnssec-keygen

You should use your own secret key, of course.  TCPware comes with a program for generating secret keys called dnssec-keygen.  To use dnssec-keygen, for example:

$ keygen :== $tcpware:dnssec-keygen.exe
$ keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER
You must use the keyboard to create entropy, since your system is lacking
/dev/random (or equivalent)

start typing:
........................

At this point, start typing at the keyboard to generate a random input.  dnssec-keygen will display dots until it is done, at which point it will display the following:

stop typing.
Kdhcp_updater-157-27654

The last line is the name of the files that it created in your current directory which contain the generated key:

$ type KDHCP_UPDATER-157-27654.*

DISK:[DEV]KDHCP_UPDATER-157-27654.KEY;1

dhcp_updater. IN KEY 0 3 157 8k+pa57JEGylQUXkOv33VA==

DISK:[DEV]KDHCP_UPDATER-157-27654.PRIVATE;1

Private-key-format: v1.3
Algorithm: 157 (HMAC_MD5)
Key: 8k+pa57JEGylQUXkOv33VA==
Bits: AAA=
Created: 20140220172314
Publish: 20140220172314
Activate: 20140220172314

Take the key in the “Key:” line and use it in your named.conf and dhcpd.conf files as the value for the secret in the key statement.

Upgrading DDNS from DHCP V3 to DHCP V4

If you have a DHCP V3 server that is configured to do Dynamic DNS updates and you are upgrading to DHCP V4, the mapping from DHCP V3 DDNS statements to DHCP V4 DDNS statements is as follows.

Note that in DHCP V3 the default is to not do DDNS updates, while in DHCP V4 the default is to do them. Similarly, the DHCP V3 default is to not create the A record, while the DHCP V4 default is to create it.

DHCP V3	DHCP V4
allow/deny dynamic-update;	ddns-updates flag; ddns-update-style {interim|none};
allow/deny update-A-record;	do-forward-updates flag; allow/deny/ignore client-updates;
allow/deny name-by-client; invalid-ddns-chars {fail | discard | replace [“chars”]};	see above for how host names are determined

 

Host Name Generation

Some DHCP clients require that the server send them a host name. The DHCP server can generate a host name if it cannot get the host name in another way. This host name is sent to the client and is combined with the domain name to create the Fully Qualified Domain Name (FQDN) required for dynamic DNS updates. See the Dynamic DNS Updates (DDNS) section.

To enable the DHCP server to generate host names, specify in the configuration file an option host-name statement with a value formatted in a certain way, as described here. The option host-name statement can be specified for example at the top level in a subnet statement, or in a host statement.

DHCP V4

In DHCP V4, you can specify the host name to generate either in the option host-name statement or the ddns-hostname statement.  You can use a combination of evaluation functions to tell the server how to generate the name. See the Expressions section for more information on available evaluation functions.

See the DHCP V4 Interim Update Mode section for a description of when it looks at ddns-hostname statement and when it looks at the option host-name statement to determine the host name. If it does execute either statement, it will generate a host name as specified by the expressions in the value.

For example:

option host-name = concat(“DHCP-“, binary-to-ascii(10,8,””,leased-address);
ddns-hostname = concat(“DHCP-“, binary-to-ascii(10,8,””,leased-address);

These statements in dhcpd.conf generate a host name consisting of the string “DHCP-” followed by the ASCII version of the IP address that was leased out to the client by the DHCP server. It uses the data expressions concat, binary-to-ascii, and leased-address.

DHCP V3

As described in the DNS updates section for DHCP V3, the allow/deny name-by-client statement in the configuration file controls whether the DHCP server uses information from the client to determine the host name and FQDN.

The DHCP server generates a host name if it is enabled to do so and either of the following is specified:

•   allow name-by-client and the client does not send a host name

•   deny name-by-client and the DHCP server does not find a host name in the configuration file or in DNS (if get-lease-hostnames is set)

You can use the following keys to specify what you want the generated host name to look like.  The generated host name can contain parts of the host's IP address, client ID, and/or MAC address, plus any characters that are valid for the host-name option. The key values are as follows. You can include more than one in the same host-name value.

Note!     Some of these do not by themselves generate a unique identifier.

Key	Meaning
%A	First byte of the host's IP address.
%B	Second byte of the host's IP address.
%C	Third byte of the host's IP address.
%D	Fourth byte of the host's IP address.
%H	Host part of the host's IP address. Example: for address 10.24.25.201 with subnet mask 255.255.0.0, the key would return 6601.
%I	Client Identifier sent by the host.
%-I	Client ID as above, except that hyphens (-) are used to separate each byte.
%M	MAC address of the host.
%-M	MAC address of the host, as above, except that hyphens (-) are used to separate each byte.
%N	Host name sent by the client, if any. If none, “Host”.
%P	Printable characters from the client ID. For example: if the client ID was 0174657374, the 01 is thrown away and the resulting hostname is “test”.
%S	Subnet part of the host's IP address. Example: for address 10.24.25.201 with subnet mask 255.255.0.0, the key would return 102400.
%-S	Subnet part of the host's IP address, as above, except that hyphens (-) are used to separate each byte.  For example: 10-24-0-0.

 

You can intersperse string constants such as hyphens between key definitions. However, if the generated host name exceeds 63 characters, it is truncated. Here is an example host-name statement:

option host-name "Host%H-%-S";

For a lease pool defined with an address range of 192.168.11.7 through 192.168.11.10 and a subnet mask of 255.255.255.0, the DHCP server generates the following host names:

Host7-192-168-11-0
Host8-192-168-11-0
Host9-192-168-11-0
Host10-192-168-11-0

The %N key allows you to use the host name as sent by the client (option 12) and then add something unique to it to generate a unique name. For example, if multiple clients all send the name "dilbert" you can make them unique by appending the MAC (hardware) address, as follows:

deny name-by-client;
option host-name "%N-%M";

This would generate the host name "dilbert-010203040506" for a client with hardware address 01:02:03:04:05:06.

Configuration File Declarations and Parameters

This section lists and describes the declarations and parameters you can use in a configuration file.

This section does not include DHCP Failover related configuration file statements. (See the Failover Configuration File Statements section).

Allow and Deny Statements

Use the allow and deny and ignore statements to control the behavior of the DHCP server. The ignore keyword is available in DHCP V4 only.

The allow and deny keywords have different meanings depending on the context.

·         In a pool context, use allow and deny to set up access lists for address allocation pools.

·         (V4 only) In a non-pool context, the ignore keyword can be used in place of the deny keyword to prevent logging of denied requests.

·         In other contexts, use these keywords to control general server behavior with respect to clients based on scope.

Allow and Deny Outside of Pool Declarations

These allow, deny, and ignore statements work the same way whether the client is sending a DHCPDISCOVER or a DHCPREQUEST message: an address is allocated to the client (either the old requested address or a new address), and then, that address is tested to see if it is okay for the client to have it.

If the client requested it, and it is not okay, the server sends a DHCPNAK message. Otherwise, the server does not respond to the client. If it is okay to give the address to the client, the server sends a DHCPACK message.

These are not recommended for use inside pool declarations. See the Pool Permit Lists section for an important note.

The following table lists the available allow and deny statements.

Statement	Description
allow unknown-clients; deny unknown-clients; (V4 only) ignore unknown-clients;	Use the unknown-clients flag to tell the DHCP server whether or not to dynamically assign addresses to unknown clients. An unknown client is one that does not have a host declaration. The default is to allow dynamic address assignments to unknown clients. The use of this option outside of pool declarations is now deprecated.  If you are trying to restrict access on your network to known clients, you should deny unknown clients inside of your address pool.
allow bootp; deny bootp; (V4 only) ignore bootp;	Use the bootp flag to tell the DHCP server to respond to bootp queries or to not respond to bootp queries. The default is to allow bootp queries.
allow booting; deny booting; (V4 only) ignore booting;	Use the booting flag to tell the DHCP server whether or not to respond to queries from a particular client. This keyword only has meaning inside of a host declaration. The default is to allow booting. If it is disabled for a particular client, that client will not be able to get an address from the DHCP server.
allow dynamic-bootp; deny dynamic-bootp;	Use the dynamic-bootp flag to tell the DHCP server to dynamically assign addresses to bootp clients or to not do so. The default is to allow dynamic bootp for IP addresses declared in pool declarations. The default for range statements outside of pool declarations is set by the presence or absence of the dynamic-bootp keyword. Deny dynamic-bootp overrides the dynamic-bootp range keyword.  (V4) This statement is deprecated in DHCP V4 in favor of the dynamic-bootp keyword on the range statement, or the allow/deny dynamic bootp clients statement in the pool declaration.
(V4 only) allow declines; deny declines; ignore declines;	(V4 only) The DHCPDECLINE message is used by DHCP clients to indicate that the lease the server has offered is not valid.  When the server receives a DHCPDECLINE for a particular address, it normally abandons that address, assuming that some unauthorized system is using it.  Unfortunately, a malicious or buggy client can, using DHCPDECLINE messages, completely exhaust the DHCP server's allocation pool.  The server will reclaim these leases, but while the client is running through the pool, it may cause serious thrashing in DNS, and it will also cause the DHCP server to forget old DHCP client address allocations. The declines flag tells the DHCP server whether or not to honor DHCPDECLINE messages.  If it is set to deny or ignore in a particular scope, the DHCP server will not respond to DHCPDECLINE messages.
(V4 only) allow duplicates; deny duplicates;	(V4 only) Host declarations can match client messages based on the DHCP Client Identifier option or based on the client's network hardware type and MAC address.  If the MAC address is used, the host declaration will match any client with that MAC address – even clients with different client identifiers.  This doesn't normally happen, but is possible when one computer has more than one operating system installed on it – for example, Microsoft Windows and Linux. The duplicates flag tells the DHCP server that if a request is received from a client that matches the MAC address of a host declaration, any other leases matching that MAC address should be discarded by the server, even if the UID is not the same.  This is a violation of the DHCP protocol, but can prevent clients whose client identifiers change regularly from holding many leases at the same time.  By default, duplicates are allowed.
(V4 only) allow leasequery; deny leasequery;	(V4 only) The leasequery flag tells the DHCP server whether or not to answer DHCPLEASEQUERY packets.  The answer to a DHCPLEASEQUERY packet includes information about a specific lease, such as when it was issued and when it will expire. By default, the server will not respond to these packets.
allow dhcpinform; deny dhcpinform	Use the dhcpinform flag to tell the DHCP server to respond to DHCPINFORM messages or to not respond. The default is to allow DHCPINFORM messages for authoritative subnets, and to deny DHCPINFORM messages for non-authoritative subnets.
(V4 only) allow client-updates; deny client-updates;	(V4 only) The client-updates flag tells the DHCP server whether or not to honor the client's intention to do its own update of its A record.  This is only relevant when doing interim DNS updates.
(V3 only) allow dynamic-update; deny dynamic-update;	(V3 only) Use the dynamic-update flag to tell the DHCP server to perform dynamic DNS updates or to not perform them. The default is to deny dynamic DNS updates.
(V3 only) allow name-by-client; deny name-by-client;	( V3 only) Use the name-by-client flag to tell the DHCP server to determine the hostname and Fully Qualified Domain Name (FQDN) for dynamic DNS updates from information sent by the client or from information in the configuration file. The default is to deny use of client-specified information.
(V3 only) allow update-A-record; deny update-A-record;	(V3 only) Use the update-A-record flag to tell the DHCP server to update the A resource record or not when performing DNS updates (the PTR resource record is always updated). The default is to deny updating the A resource record.

Allow and Deny in Pool Declarations

This section lists and describes the available allow and deny statements that can be used in pool declarations.

See the Pool Permit Lists section for discussion, defaults, and important notes.

 

Statement	Description
allow unknown-clients; deny unknown-clients;	Use unknown clients to allow or prevent allocation from this pool to any client that has no host declaration.
allow members of “class-name”; deny members of “class-name”;	Use members of “class” to allow or prevent allocation from this pool to any client that is a member of the named class.
allow dynamic bootp clients; deny dynamic bootp clients;	Use dynamic bootp clients to allow or prevent allocation from this pool to any BOOTP client.
allow all clients; deny all clients;	Use all clients to allow or prevent allocation from this pool to all clients. You can use this, for example, when you want to write a pool declaration but you want to hold it in reserve; or when you want to renumber your network quickly, and thus want the server to force all clients that have been allocated addresses from this pool to obtain new addresses immediately when they next renew their leases.
(V4 only) allow after time; deny after time;	(V4 only) If specified, this statement either allows or prevents allocation from this pool after a given date. This can be used when you want to move clients from one pool to another.  The server adjusts the regular lease time so that the latest expiry time is at the given time plus min-lease-time.  A short min-lease-time enforces a step change, whereas a longer min-lease-time allows for a gradual change. time is either seconds since epoch, or a UTC time string e.g. 4 2007/08/24 09:14:32 or a string with time zone offset in seconds e.g. 4 2007/08/24 11:14:32 -7200

 

DHCP Statements

This section lists and describes the remaining declarations and parameters that can be specified in the DHCP server configuration file.

 

Statement	Description
(V4 only) adaptive-lease-time-threshold	(V4 only) When the number of allocated leases within a pool rises above the percentage given in this parameter, the DHCP server decreases the lease length for new clients within this pool to min-lease-time seconds. Clients renewing already valid (long) leases get at least the remaining time from the current lease. Since the leases expire faster, the server may either recover more quickly or avoid pool exhaustion entirely.  Once the number of allocated leases drop below the threshold, the server reverts back to normal lease times.  Valid percentages are between 1 and 99. adaptive-lease-time-threshold percentage;
add	Use the add statement to add a client to the class whose name is specified in class-name. Important!   Because this statement executes after IP address allocation is completed, class membership caused by this statement cannot be used in the address allocation process. add “class-name”;
always-broadcast	Use the always-broadcast parameter to cause the DHCP server to always broadcast its responses. This feature is to handle clients who do not set the broadcast flag in their requests and yet require a broadcast response. We recommend you restrict the use of this feature to as few clients as possible. always-broadcast flag;
always-reply-rfc1048	Some BOOTP clients expect RFC 1048-style responses, but do not follow RFC 1048 rules when sending their requests. You can determine if 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 RFC 1048 options to this kind of client, set the always-reply-rfc1048 parameter in that client's host declaration. The DHCP server responds with an RFC 1048-style vendor options field. This flag can be set in any scope, and affects all clients covered by that scope. always-reply-rfc1048 flag;
authoritative	When the DHCP server receives a DHCPREQUEST message from a DHCP client requesting a specific IP address, the DHCP protocol requires that the server determine whether the IP address is valid for the network to which the client is attached. If the address is not valid, the DHCP server should respond with a DHCPNAK message, forcing the client to acquire a new IP address. To make this determination for IP addresses on a particular network segment, the DHCP server must have complete configuration information for that network segment. Unfortunately, it is not safe to assume that DHCP servers are configured with complete information. Therefore, the DHCP server normally assumes that it does not have complete information, and thus is not sufficiently authoritative to safely send DHCPNAK messages as required by the protocol. This default assumption should not be true for any network segment that is in the same administrative domain as the DHCP server. For such network segments, the authoritative statement should be specified, so that the server sends DHCPNAK messages as required by the protocol. If the DHCP server receives requests only from network segments in the same administrative domain, you can specify the authoritative statement at the top of the configuration file (in the global scope). Note!     Version 2.0 (TCPware v5.4) of the DCHP server makes the opposite assumption: that the DCHP server is configured with all configuration information for all network segments of which it is aware. If this assumption is not valid for your configuration, you must write not authoritative statements for all network segments where this assumption is not true (or at the top of the configuration file). authoritative; not authoritative;
(V4 only) boot-unknown-clients	(V4 only) If the boot-unknown-clients parameter is present and 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 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. boot-unknown-clients flag;
class	This declaration groups clients together based on information they send. A client can become a member of a class in the following ways: •      through an add statement •      based on the class’s matching rules •      because the client matches a subclass of that class Class-name is the name of the class and is used in: •      add statements •      members of permit statements •      subclass declarations for subclasses of the named class When a packet is received from a client, every class declaration is examined for a match, match if, or spawn statement. That statement is checked to see if the client is a member of the class. The class declaration statements are lease limit, match, match if, and spawn with. class “class-name” {[ statements ][ declarations ]}
(V4 only) ddns-domainname	(V4 only) Use the ddns-domainname parameter to specify the domain name to be appended to the client’s host name to form a fully qualified domain name (FQDN) for DDNS. See Dynamic DNS Updates (DDNS). ddns-domainname name;
(V4 only) ddns-hostname	(V4 only) Use the ddns-hostname parameter to specify the hostname to be used in setting up the client's A and PTR records for DDNS.   If no ddns-hostname is specified in scope, then the server derives the hostname automatically. See Dynamic DNS Updates (DDNS). ddns-hostname name;
(V4 only) ddns-rev-domainname	(V4 only) Use the ddns-rev-domainname parameter to specify the domain name that will be appended to the client's reversed IP address to produce a name for use in the client's PTR record.  By default, this is "in-addr.arpa.", but the default can be overridden here. The reversed IP address to which this domain name is appended is always the IP address of the client, in dotted quad notation, reversed – for example, if the IP address assigned to the client is 10.17.92.74, then the reversed IP address is 74.92.17.10.  So a client with that IP address would, by default, be given a PTR record of 10.17.92.74.in-addr.arpa. ddns-rev-domainname name;
(V4 only) ddns-update-style	(V4 only) Use the ddns-update-style parameter to turn on DDNS updates and specify the update style. The only supported update style is interim. To turn off DDNS updates, set ddns-update-style to none (the default). This parameter is only meaningful in the outer scope – at the top of the DHCPD.CONF file. There is no way to set ddns-update-style to different values for different clients. ddns-update-style [ interim | none ];
(V4 only) ddns-updates	(V4 only) The ddns-updates parameter controls whether or not the server will attempt to do a DNS update when a lease is confirmed.  Set this to off if the server should not attempt to do updates within a certain scope.  The ddns-updates parameter is on by default.  To disable DNS updates in all scopes, it is preferable to use the ddns-update-style statement, setting the style to none. ddns-updates flag;
(V4 only) db-time-format	(V4 only) The DHCP server software outputs several timestamps when writing leases to persistent storage.  The db-time-format parameter selects one of two output formats: default or local. The default format prints the day, date, and time in UTC, while the local format prints the system seconds-since-epoch, and provides the day and time in the system timezone in a comment dhcp-time-format [ default | local ];
default-lease-time	Time is the length (in seconds) that the DHCP server assigns to a lease if the requesting client did not ask for a specific amount of time for the lease to be active. The infinite lease value is “infinite”. The default is 43200 seconds (12 hours). You should set the value of default-lease-time no larger than the value of max-lease-time. default-lease-time time;
(V4 only) delayed-ack	(V4 only) The delayed-ack parameter works with the max-ack-delay parameter. Use the delayed-ack parameter to specify an integer value from 0 to 65535 (default 28) representing the maximum number of replies that the server can queue up pending transmission until after a database commit event. If this number is reached, a database commit is done (representing a performance penalty), and the replies are transmitted in a batch. This preserves the RFC2131 direction that "stable storage" be updated prior to replying to clients.  If it happens at any point that there are no incoming requests into the DHCP server (and so the server is temporarily idle), the commit is made at that time and any queued replies are transmitted. delayed-ack count; Note that the V3 equivalent of this parameter is max-delayed-acks.
(V4 only) do-forward-updates	(V4 only) The do-forward-updates parameter instructs the DHCP server as to whether it should attempt to update a DHCP client's A record when the client acquires or renews a lease. This statement has no effect unless DNS updates are enabled and ddns-update-style is set to interim.  Forward updates are enabled by default.  If this statement is used to disable forward updates, the DHCP server will never attempt to update the client's A record, and will only ever attempt to update the client's PTR record if the client supplies an FQDN (fully qualified domain name) that should be placed in the PTR record, using the fqdn option.  If forward updates are enabled, the DHCP server will still honor the setting of the client-updates flag. do-forward-updates flag;
dynamic-bootp-lease-cutoff	Use the dynamic-bootp-lease-cutoff parameter to set the ending time for all leases dynamically assigned to BOOTP clients. By default, the DHCP server assigns infinite leases to all BOOTP clients because they do not have any way of renewing leases, and do not know that their leases could expire. However, it may make sense 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. Date should be the date all assigned BOOTP leases will end. The date is specified in the form: W YYYY/MM/DD HH:MM:SS W is the day of the week, from zero (Sunday) to six (Saturday). YYYY is the year, including the century. MM is the number of the month, from 01 to 12. DD is the day of the month, counting from 01. HH is the hour, from 00 to 23. MM is the minute, from 00 to 59. SS is the second, from 00 to 59. The time is always in Greenwich Mean Time, not local time. dynamic-bootp-lease-cutoff date;
dynamic-bootp-lease-length	Use the dynamic-bootp-lease-length parameter to set the length of leases dynamically assigned to BOOTP clients. You may be able 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 length of the time period is your judgment call. Specify length in seconds. The infinite lease value is 0. If a BOOTP client reboots during a timeout period, the lease duration is reset to length so a BOOTP client that boots frequently never loses its lease. This parameter should be adjusted with extreme caution. The default is an infinite lease. dynamic-boot-lease-length length;
filename	Use the filename parameter to specify the name of the initial boot file that is to be loaded by a client. The filename should be recognizable to whatever file transfer protocol the client can be expected to use. filename “file-name”;
fixed-address	To make a static IP address assignment for a client, the client must match a host declaration, as described later. In addition, the host declaration must contain a fixed-address statement. A fixed-address statement specifies one or more IP addresses or domain names that resolve to IP addresses. If a client matches a host declaration, and one of the IP addresses specified in the host declaration is valid for the network segment to which the client is connected, the client is assigned that IP address. A static IP address assignment overrides a dynamically assigned IP address that is valid on that network segment. That is, if a new static mapping for a client is added after the client has a dynamic mapping, the client cannot use the dynamic mapping the next time it tries to renew its lease. The DHCP server will not assign an IP address that is not correct for the network segment to which the client is attached and will not override a valid dynamic mapping for one network segment based on a static mapping that is valid on a different network segment. You can specify a domain name instead of an IP address in a fixed-address statement. However, you should do this only for long-lived domain name records — the DHCP server only looks up the record on startup. So, if the record changes while the server is running, the server continues to use the record’s former value. fixed-address address [,...,address];
get-lease-hostnames	Use the get-lease-hostnames parameter to tell the DHCP server to look up the domain name corresponding to each address in the lease pool and use that address for the DHCP hostname option. If flag is true, the lookup is done for all addresses in the current scope. If flag is false (the default), lookups are not done. get-lease-hostnames flag;
group	Use the group declaration to apply one or more parameters to a group of declarations. You can use it to group hosts, shared networks, subnets, or other groups. group {[parameters] [declarations]}
hardware	Use the hardware parameter inside a host statement to specify the network hardware address of a BOOTP or DHCP client. hardware-type must be the name of a physical hardware interface type. Ethernet, Token-Ring, and FDDI are the only recognized types. The hardware-address should be a set of hexadecimal octets (numbers from 0 through ff) separated by colons (:). hardware hardware-type hardware-address;
host	The host declaration provides information about a particular client. Name should be a unique name, but a specific meaning is not required. If the use-host-decl-names flag is enabled, name is sent in the host-name option if no host-name option is specified. Host declarations match DHCP or BOOTP clients based on either the client's hardware address or the dhcp-client-identifier option that the client sends. BOOTP clients do not normally send a dhcp-client-identifier option. So, you must use the hardware address for all clients that might send BOOTP protocol requests. The host declaration has three purposes: to assign a static IP address to a client, to declare a client as "known", and to specify a scope in which statements can be executed for a specific client. You can make the DHCP server treat some DHCP clients differently from others if host declarations exist for those clients. Any request coming from a client that matches a host declaration is considered to be from a "known" client. Requests that do not match any host declaration are considered to be from "unknown" clients. You can use this knowledge to control how addresses are allocated. It is possible to write more than one host declaration for a client. If you want to assign more than one static address to a given client, you can either specify more than one address in the fixed-address statement or you can write multiple host declarations. Multiple host declarations are needed if the client has different requirements (scopes) on different subnets. For each IP address that requires a different scope, one host declaration should exist. A client can be in the scope of only one host declaration at a time. Host declarations with static address assignments are in scope for a client only if one of the address assignments is valid for the network segment to which the client is connected. If you want to boot a client using static addresses on some subnets, and using dynamically assigned addresses on other subnets, you need to write a host declaration with no fixed-address statement. There can be only one such host declaration per client.  Its scope is used whenever that client receives a dynamically assigned address. host name { [ parameters ] [ declarations ] }
if	The if statement conditionally executes statements based on the values the client sends or other information. See the Conditional Behavior section for more information. if boolean-expression { [statements] } [elsif boolean-expression { [statements] }] [else { [statements] } ]
(V4 only) include	(V4 only) The include statement is used to read in the specified file, and process the contents of the included file as if they were in the configuration file directly. include “filename”;
(V4 only) infinite-is-reserved	(V4 only) If the infinite-is-reserved parameter is set to on the server automatically marks as reserved leases which are allocated to clients who requested an infinite lease time. The default is off. infinite-is-reserved flag;
(V3 only) invalid-ddns-chars	(V3 only) This parameter specifies how DHCP should handle invalid characters in the hostname for Dynamic DNS updates (DDNS). fail tells DHCP to display a message and not perform any DNS updates if there are any invalid characters in the hostname. This is the same as the behavior of the DHCP server in TCPware V5.4. This is the default. invalid-ddns-chars fail; discard tells DHCP to throw away the invalid characters in the hostname. invalid-ddns-chars discard; replace tells DHCP to replace the invalid characters with the specified character(s). If none are specified, the default replacement character is the hyphen ('-'). invalid-ddns-chars replace ["characters"];
(V4 only) key	(V4 only) DDNS: The key statement specifies the secret key and algorithm to use for DNSSEC. key key-name {     algorithm algorithm;     secret key; };
(V4 only) lease-file-name	(V4 only) The lease-file-name parameter in the configuration file can be used to specify the name of the lease file. The default is TCPWARE:DHCPD.LEASES. This parameter must appear at the outer scope – at the top of the configuration file. lease-file-name name;
lease limit	This statement causes the DHCP server to limit the number of members of a class that can hold a lease at any one time. This limit applies to all addresses the DHCP server allocates in the class, not just addresses on a particular network segment. •      If a client is a member of more than one class with lease limits, the server assigns the client an address based on either class. •      If a client is a member of one or more classes with limits and one or more classes without limits, the classes without limits are not considered. lease limit limit;
(V3 only) lease-scan-interval	(V3 only) This parameter specifies how frequently to scan for expired leases. The default is 60 seconds. lease-scan-interval seconds;
(V4 only) local-port	(V4 only) The local-port parameter can be used to specify a different port for the DHCP server to listen on, other than the default port of 67. local-port port;
match	data-expression is evaluated using the contents of a client’s request. If it returns a value that matches a subclass of the class in which the match statement appears, the client is considered a member of both the subclass and the class. match data-expression;
match if	boolean-expression is evaluated when the server receives a packet from the client. If it is true, the client is considered a member of the class. The boolean-expression may depend on the contents of the packet the client sends. match if boolean-expression;
(V4 only) max-ack-delay	(V4 only) The max-ack-delay parameter works with the delayed-ack parameter (see description above). Use the max-ack-delay parameter to specify the length of time that replies are allowed to queue up awaiting a database commit event. The value is in microseconds, from 0 to 4,294,967,295, with a default of 250,000 (1/4 of a second). max-ack-delay microseconds;
max-delayed-acks	Use the max-delayed-acks statement to specify the maximum number of DHCPACKs to batch up. The default is 8. To disable the delaying of DHCPACKs, specify a value of 1. To improve performance under very heavy loads, the DHCP server delays sending DHCPACK messages by up to 2 seconds. All DHCPACKs accumulated in that time are sent in a batch. max-delayed-acks count; (V4) In DHCP V4, this statement is superseded by delayed-ack.
max-lease-time	Use the max-lease-time parameter to assign the maximum amount of time (in seconds) to a lease. The only exception to this is Dynamic BOOTP lease lengths because they are not specified by the client and are not limited by this maximum. The infinite lease value is “infinite”. The default is 86,400 seconds (24 hours). Note!     You should set the value of max-lease-time at least as large as default-lease-time. max-lease-time time;
min-lease-time	Use the min-lease-time parameter to assign the minimum length in seconds to a lease. The infinite lease value is “infinite”. The default is the smaller of 300 seconds or the value of max-lease-time. min-lease-time should be less than or equal to default-lease-time and max-lease-time. min-lease-time time;
min-secs	Use the min-secs parameter to assign the minimum amount of time (in seconds) it takes for the DHCP server to respond to a client’s request for a new lease. The number of seconds is based on what the client reports in the secs field of the requests it sends. The maximum value is 255 seconds. Usually, setting this to one second results in the DHCP server not responding to the client's first request, but always responding to the client’s second request. You can use the min-secs statement to set up a secondary DHCP server to never offer an address to a client until the primary server has been given a chance to do so. If the primary server is down, the client binds to the secondary server; otherwise, clients should always bind to the primary. Note that this does not, by itself, permit a primary server and a secondary server to share a pool of dynamically-allocatable addresses. min-secs seconds;
next-server	Use the next-server parameter to specify the host address of the server from where the client will load the initial boot file (specified in the filename statement). name should be a numeric IP address or a domain name. The DHCP server’s IP address is used if no next-server parameter applies to a given client. next-server name;
one-lease-per-client	Use the one-lease-per-client parameter to have the server free any other leases the client holds when the client sends a DHCPREQUEST for a particular lease. This presumes the client has forgotten any lease not mentioned in the DHCPREQUEST. For example, the client has only a single network interface and it does not remember leases it is holding on networks to which it is not currently attached. Neither of these assumptions is guaranteed or provable, so use caution in the use of this statement. one-lease-per-client flag;
option	This statement specifies actual DHCP protocol options to send to the client. The option statement is described in the next section.
option definition	This statement assigns a name and a type to an option code. See the Defining New Options section for more information. option name code code = definition;
option space	This statement specifies a new option space. This declaration must precede all definitions for options in the space being specified. Space-name should be the name of the option space. Option space names include: dhcp (the default), agent, and server. If an option name is specified without an option space, it is assumed the name refers to an option in the dhcp option space. For example, the option names dhcp.routers and routers are equivalent. option space space-name [ options ];
ping (V4 only) ping-check	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 ping check introduces a default one-second delay in responding to DHCPDISCOVER messages, which can be a problem for some clients.  The length of delay may be configured using the ping-timeout parameter. A value of false or off turns pinging off. ping flag; (V3) ping-check flag; (V4 only)
ping-retries	This parameter defines the number of times the DHCP server pings an IP address before it concludes that the address is not in use. The default is 1. ping-retries count;
ping-timeout	This parameter defines the time (in seconds) that ping should wait for a response. The default is 1 second. ping-timeout time;
pool	This statement specifies an address pool from which IP addresses can be allocated. This pool can be customized to have its own permit list to control client access and its own scope to declare pool-specific parameters. You can put pool declarations within subnet declarations or within shared-network declarations. You can use the range declaration to specify the addresses in a particular pool. For subnet declarations: specified addresses must be correct within the pool declaration within which it is made. For shared-network declarations: specified addresses must be on subnets that were previously specified within the same shared-network declaration. pool {[permit list][range declaration][statements]}
range	For any subnet on which addresses are assigned dynamically, there must be at least one range declaration. The range declaration specifies that the server may allocate to DHCP clients every address, from low-address to high-address. You can specify a single IP address by omitting high-address. All IP addresses in the range should be on the same subnet. If the range declaration appears within a subnet declaration, all addresses should be on the declared subnet. If the range declaration appears within a shared-network declaration, all addresses should be on subnets already declared within the shared-network declaration. You may specify the dynamic-bootp flag if addresses in the specified range can be dynamically assigned to both BOOTP and DHCP clients. range [dynamic-bootp] low-address [high-address];
(V4 only) remote-port	(V4 only) The remote-port parameter can be used to specify a different port for the DHCP server to send to clients at, other than the default port of 68. Changing the remote port is not recommended. remote-port port;
requested-options-only	Use the requested-options-only parameter to send just the options requested by the client. To send a specific set of options, set requested-options-only to true and specify the dhcp-parameter-request-list option. The following sends only the subnet-mask, routers, and domain-name-servers options to the client (assuming they are defined in the configuration file): host restricted {     hardware ethernet 01:02:03:04:05:06;     option dhcp-parameter-request-list 1, 3, 6;     requested-options-only true; } We recommend you restrict the use of this feature to as few clients as possible. requested-options-only flag;
server-identifier	The server-identifier parameter is equivalent to the dhcp-server-identifier option. See the dhcp-server-identifier option for more information. server-identifier hostname;
server-name	Use the server-name parameter to inform the client of the server’s name from which it is booting. name should be the name provided to the client. server-name name;
shared-network	Use this declaration to inform the DHCP server that some IP subnets share the same physical network. Declare all subnets in the same shared network within a shared-network declaration. Parameters specified in the shared-network declaration will be used when booting clients on those subnets unless parameters provided at the subnet or host level override them. If more than one subnet in a shared network has addresses available for dynamic allocation, those addresses are collected into a common pool. There is no way to specify which subnet of a shared network a client should boot on. Name should be the name of the shared network. Make the name descriptive as it will be used when printing debugging messages. It can have the syntax of a valid domain name (although it will never be used as such), or can be any arbitrary name enclosed in quotation marks. shared-network name {[parameters] [declarations]}
site-option-space	The site-option-space parameter can be used to determine from what option space site-local options will be taken.  This can be used in much the same way as the vendor-option-space parameter.  Site-local options in DHCP are those options whose numeric codes are greater than 224.  These options are intended for site-specific uses, but are frequently used by vendors of embedded hardware that contains DHCP clients.  Because site-specific options are allocated on an ad-hoc basis, it is quite possible that one vendor's DHCP client might use the same option code that another vendor's client uses, for different purposes.  The site-option-space parameter can be used to assign a different set of site-specific options for each such vendor, using conditional evaluation. site-option-space option-space;
spawn with	data-expression must evaluate to a non-null value for the server to look for a subclass of the class that matches the evaluation. •      If such a subclass exists, the client is considered a member of both the subclass and the class. •      If no such subclass exists, one is created and recorded in the lease database, and the client is considered a member of the new subclass as well as the class. spawn with data-expression;
(V4 only) stash-agent-options	(V4 only) If the stash-agent-options parameter is true for a given client, the server will record the relay agent information options sent during the client's initial DHCPREQUEST message when the client was in the SELECTING state and behave as if those options are included in all subsequent DHCPREQUEST messages sent in the RENEWING state.  This works around a problem with relay agent information options, which is that they usually not appear in DHCPREQUEST messages sent by the client in the RENEWING state, because such messages are unicast directly to the server and not sent through a relay agent. stash-agent-options flag;
subclass	This statement specifies a subclass of the class named by class-name. Class-data should be either •      a text string enclosed in quotes, or •      a list of bytes expressed in hexadecimal, separated by colons. Clients match subclasses after evaluating the match or spawn with statements in the class declaration for class-name. If the evaluation matches class-data, the client is a member of the subclass and the class. subclass “class-name” class-data; subclass “class-name” class-data {    [statements] }
subnet	This declaration contains information specific to a subnet. The information communicates the following to DHCP: •      Enough information for DHCP to determine if an IP address is on that subnet. •      What the subnet-specific parameters are. •      What addresses may be dynamically allocated to clients booting on that subnet. Use the range declaration to specify what addresses are available to be dynamically allocated to clients booting on the subnet. Two things are required to define a subnet: •      The subnet-number •      The netmask The subnet-number and the netmask entry is an IP address or domain name that resolves to the subnet-number or the netmask of the subnet being described. The subnet-number and the netmask are enough to determine if any given IP address is on the specified subnet. Note!     A netmask must be given with every subnet declaration. If there is any variance in subnet masks at a site, use a subnet-mask option statement in each subnet declaration to set the desired subnet mask. The subnet-mask option statement overrides the subnet mask declared in the subnet statement. subnet subnet-number netmask netmask {[parameters][declarations]}
(V4 only) update-conflict-detection	(V4 only) DDNS: If the update-conflict-detection parameter is true, the server will perform standard DHCID multiple-client, one-name conflict detection.  If the parameter has been set to false, the server will skip this check and instead simply tear down any previous bindings to install the new binding without question.  The default is true. update-conflict-detection flag;
(V4 only) update-optimization	(V4 only) DDNS: If the update-optimization parameter is false for a given client, the server will attempt a DNS update for that client each time the client renews its lease, rather than only attempting an update when it appears to be necessary.  This will allow the DNS to heal from database inconsistencies more easily, but the cost is that the DHCP server must do many more DNS updates. We recommend leaving this option enabled, which is the default.  If this parameter is not specified, or is true, the DHCP server will only update when the client information changes, the client gets a different lease, or the client's lease expires. update-optimization flag;
(V4 only) update-static-leases	(V4 only) DDNS: The update-static-leases parameter, if enabled, causes the DHCP server to do DNS updates for clients even if those clients are being assigned their IP address using a fixed-address statement – that is, the client is being given a static assignment.  It is not recommended because the DHCP server has no way to tell that the update has been done, and therefore will not delete the record when it is not in use.  Also, the server must attempt the update each time the client renews its lease, which could have a significant performance impact in environments that place heavy demands on the DHCP server. update-static-leases flag;
use-host-decl-names	If the use-host-decl-names parameter is true, the name provided for each host declaration is given to the client as its hostname. The default is false. 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 overrides the use of the name in the host declaration. use-host-decl-names flag;
use-lease-addr-for-default-route	If the use-lease-addr-for-default-route parameter is true in a given scope, the IP address of the lease being assigned is sent to the client instead of the value specified in the routers option (or sending no value at all). This causes some clients to ARP for all IP addresses, which can be helpful if your router is configured for proxy ARP. The use of this feature is not recommended. If use-lease-addr-for-default-route is enabled and an option routers statement are both in scope, use-lease-addr-for-default-route is preferred. use-lease-addr-for-default-route flag;
vendor-option-space	Use the vendor-option-space statement to instruct the server to construct a vendor-encapsulated-options option using all the defined options in the option space. If no vendor-encapsulated-options option is defined, the server sends this option to the client, if appropriate. vendor-option-space option-space;
(V4 only) zone	(V4 only) DDNS: The zone statement provides information to the server about the DNS zones that it might be updating via DDNS. This statement is required if you are using DNSSEC (using DNSSEC is recommended). zone zone-name {     primary ip-address;     [ secondary ip-address; ]     [ key key-name; ] }; The zone-name must correspond to the name of the actual zone to be updated, for example “example.org.” or “17.10.10.in-addr.arpa.” (without the quotes). Note that the zone specified must have an SOA record. The primary and secondary keywords specify the IP addresses of the primary and secondary name servers for the zone. Up to three name servers may be specified. The key keyword is used to provide the secret key to be used by DNSSEC. The key-name is the name of a key statement in the configuration file which contains that information.

 

Expressions

The DHCP server can evaluate expressions while executing statements. The DHCP server’s expression evaluator returns the following types:

•   A boolean, a true or false (on or off) value.

•   An integer, a 32-bit quantity that may be treated as signed or unsigned, depending on the context.

•   A string of data, a collection of zero or more bytes. Any byte value is valid in a data string — the DHCP server maintains a length rather than depending on a NUL termination.

Expression evaluation is performed when a request is received from a DHCP client. Values in the packet sent by the client can be extracted and used to determine what to send back to the client. If the expression refers to a field or option in the packet for which there is no value, the result is null. Null values are treated specially in expression evaluation. A Boolean expression that returns a null value is considered false. A data expression that returns a null value generally results in the statement using the value not having any effect.

Expressions can be used to set the value of a DHCP server parameter or an option, for example based on some value that the client has sent. To do this, you can use expression evaluation. To assign the result of an evaluation to a parameter or option, use the following syntax in your configuration file:

parameter-or-option = expression;

The following example asks the DHCP server to create a host name for the client:

option host-name = concat(“DHCP-“, binary-to-ascii(10,8,””,leased-address);
ddns-hostname = concat(“DHCP-“, binary-to-ascii(10,8,””,leased-address);

These statements in dhcpd.conf generate a host name consisting of the string “DHCP-” followed by the ASCII version of the IP address that was leased out to the client by the DHCP server. It uses the data expressions concat, binary-to-ascii, and leased-address, described below.

Boolean Expressions

The following are the boolean expressions supported by DHCP.

boolean-expression-1 and boolean-expression-2	The and operator evaluates to true if both boolean expressions evaluate to true. The and operator evaluates to false if either boolean expression does not evaluate to true. If either of the boolean expressions is null, the result is null.
boolean-expression-1 or boolean-expression-2	The or operator evaluates to true if either of the boolean expressions evaluate to true. The or operator evaluates to false if both of the boolean expressions evaluate to false. If either of the boolean expressions is null, the result is null.
data-expression-1 = data-expression-2	The equals (=) operator compares the results of evaluating two data expressions, evaluating to true if they are the same; evaluating to false if they are not. If one of the expressions is null, the result is null.
data-expression-1 != data-expression-2 (V4 only)	(V4) The not-equals (!=) operator compares the results of evaluating two data expressions, evaluating to true if they are not the same; evaluating to false if they are. If one of the expressions is null, the result is null.
exists option-name	The exists expression evaluates to true if the specified option exists in the incoming DHCP packet.
known	The known expression evaluates to true if the client whose request is being processed is known; that is, if the client has a host declaration.
not boolean-expression	The not operator evaluates to true if the boolean expression evaluates to false. The not operator evaluates to false if the boolean expression evaluates to true. If the boolean expression evaluates to null, the result is null.
static (V4 only)	(V4 only) The static expression evaluates to true if the lease assigned to the client whose request is being processed is derived from a static address assignment.

 

Data Expressions

The following are the expressions supported by DHCP that return a data string.

binary-to-ascii (numeric-expr1, numeric-expr2, data-expr1, data-expr2)	numeric-expr1, numeric-expr2, data-expr1, and data-expr2 are all evaluated as expressions and the results of those evaluations are used as follows. The binary-to-ascii operator converts the binary data in data-expr2 into an ASCII string, using data-expr1 as a separator. How the conversion is done is controlled by numeric-expr1 and numeric-expr2. •      numeric-expr1 specifies the base to convert into. Any value 2 through 16 is supported. For example, a value of 10 would produce decimal numbers in the result. •      numeric-expr2 specifies the number of bits in data-expr2 to treat as a single unit. The value can be 8, 16, or 32. This example converts the binary value of an IP address into its dotted decimal equivalent: binary-to-ascii(10, 8, ".", 168364039) The result would be the string "10.9.8.7".
colon-separated hexadecimal list	A list of hexadecimal octet values, separated by colons, may be specified as a data expression. A single hexadecimal number, appearing in a context where a data string is expected, is interpreted as a data string containing a single byte.
concat (data-expr1, …, data-exprN)	The data expressions data-expr1 through data-exprN are evaluated and the results of each evaluation are concatenated in the sequence that the subexpressions are listed. If any subexpression evaluates to null, the result of the concatenation is null. (V3) Note that for DHCP V3, only two data expressions are allowed.
config-option option-name (V4 only)	(V4 only) The config-option operator returns the value for the specified option that the server has been configured to send.
encode-int (numeric-expr, width)	numeric-expr is evaluated and encoded as a data string of the specified width, in network byte order (with the most significant byte first). If numeric-expr evaluates to null, the result is null.
gethostname() (V4 only)	(V4 only) The gethostname() function returns a data string whose contents are a character string, the results of calling gethostname() on the local system with a size limit of 255 bytes  (not  including NULL terminator).
hardware	The hardware operator returns a data string whose first element is the type of the network interface indicated in the packet being processed, and whose subsequent elements are the client’s link-layer address. If there is no packet, or if the RFC 2131 hlen field is invalid, the result is null. Supported hardware types are: ethernet (1), token-ring (6), fddi (8)
host-decl-name (V4 only)	(V4 only) The host-decl-name function returns the name of the host declaration that matched the client whose request is being processed, if any.  If no host declaration matched, the result is the null value.
pick-first-value (data-expr1 [,… data-exprN ] (V4 only)	(V4 only) The pick-first-value function takes any number of data expressions as its arguments.  Each expression is evaluated, starting with the first in the list, until an expression is found that does not evaluate to a null value.  That expression is returned, and none of the subsequent expressions are evaluated.  If all expressions evaluate to a null value, the null value is returned.
lcase (data-expr) (V4 only)	(V4 only) The lcase function returns the result of evaluating data-expr converted to lower case. If data-expr evaluates to null, then the result is also null.
leased-address	In any context where the client has been assigned an IP address, this data expression returns that IP address.
option option-name	The option operator returns the contents of the specified option in the packet to which the server is responding.
packet (offset, length)	The packet operator returns the specified portion of the packet being considered. The packet operator returns a value of null where no packet is being considered. Offset and length are applied to the contents of the packet as in the substring operator. The link-layer, IP, and UDP headers are not available.
reverse (numeric-expr1, data-expr2)	numeric-expr1 and data-expr2 are evaluated. The result of data-expr2 is reversed in place, using chunks of the size specified in numeric-expr1. For example, if numeric-expr1 evaluates to 4 and data-expr2 evaluates to 12 bytes of data, the reverse expression evaluates to 12 bytes of data constructed in the following way: •      the last 4 bytes of the input data, •      followed by the middle 4 bytes, •      followed by the first 4 bytes.
substring (data-expr, offset, length)	The substring operator evaluates the data expression and returns the substring of the result of that evaluation that starts offset bytes from the beginning and continues for length bytes. Offset and length are numeric expressions. •      If data-expr, offset, or length evaluates to null, the result is null. •      If offset is greater than or equal to the length of the evaluated data, a zero-length data string is returned. •      If length is greater than the remaining length of the evaluated data after offset, a data string containing all data from offset to the end of the evaluated data is returned.
suffix (data-expr, length)	The suffix operator evaluates data-expr and returns the last length bytes of that evaluation. Length is a numeric expression. •      If data-expr or length evaluates to null, the result is null. •      If length evaluates to a number greater than the length of the evaluated data, the evaluated data is returned.
“text”	A text string, enclosed in quotes, may be specified as a data expression. The string returns the text between the quotes, encoded in ASCII. The backslash ('\') character is treated specially,  as in C programming: ·         '\t' means TAB, ·         '\r' means carriage return ·         '\n' means newline ·         '\b' means bell ·         any octal value can be specified with '\nnn', where nnn is any positive octal number less than 0400 ·         any hexadecimal value can be specified with '\xnn', where nn is any positive hexadecimal number less than or equal to 0xff
ucase (data-expr) (V4 only)	(V4 only) The ucase function returns the result of evaluating data-expr converted to upper case. If data-expr evaluates to null, then the result is also null.

 

Numeric Expressions

Numeric expressions evaluate to an integer. In general, the precision of numeric expressions is at least 32 bits. However, the precision of such integers may be more than 32 bits.

extract-int (data-expr, width)	The extract-int operator extracts an integer value in network byte order after evaluating data-expr. Width is the width in bits (8, 16, or 32) of the integer to extract. If the evaluation of data-expr does not provide an integer of the specified size, a value of null is returned.
number	Number can be any numeric value between zero and the maximum representable size.

 

Action Expressions

log ([priority,] data-expr) (V4 only)

(V4 only) The log expression may be used to write a message (specified via data-expr) to the DHCP server debug log file and/or OPCOM (depending on how the server was configured via TCPWARE:CNFNET). The optional priority can be: fatal, error, info, or debug.

DHCP Options

The Dynamic Host Configuration protocol allows the client to receive options from the DHCP server describing the network configuration and various services that are available on the network. When configuring the DHCP server, options must often be declared. The syntax for declaring options, and the names and formats of the options in the default dhcp option space that can be declared, are below.

DHCP option statements always start with the keyword option, followed by an option name, followed by option data. Only options needed by clients must be specified.

An option name is an optional option space name followed by a period (“.”) followed by the option name. The default option space is dhcp. There are other predefined option spaces, for example, agent and server. You can also define option spaces of your own. See the sections Relay Agent Information Option and Defining New Options in this chapter.

Option data comes in these formats:

•   The ip-address data type can be entered either as an explicit IP address (e.g., 239.254.197.10) or as a domain name (e.g., haagen.isc.org). When entering a domain name, be sure that the domain name resolves to the single IP address.

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

•   The domain-name data type specifies a domain name, which must not be enclosed in double quotes.  This data type is not used for any existing DHCP options.  The domain name is stored just as if it were a text option.

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

•   The string data type specifies an NVT ASCII string. It must be enclosed in quotation marks. For example, option domain-name “isc.org”;

•   The flag data type specifies a boolean value. Booleans can be either true (ON) or false (OFF). You can use TRUE and FALSE, or ON and OFF.

•   The data-string data type specifies either an NVT ASCII string enclosed in quotation marks, or a series of octets specified in hexadecimal, separated by colons. For example, option dhcp-client-identifier “CLIENT-FOO”; or option dhcp-client-identifier 43:4c:49:54:2d:46:4f:4f;

Strings and data-strings when enclosed in quotation marks can contain normal C-type characters such as “\t” for a tab.

If the option value is a list (such as for the routes option), you must list them in the configuration file in the order you want the client to use the values. The DHCP server does not re-order them.

Also, option data may be specified using an expression that returns a data string (see the Expressions section). The syntax is

option option-name = data-expression;

Standard DHCP Options

This section describes the standard DHCP options. Underlined items indicate user input items.

Note!     All of these options could be specified with the dhcp option space listed explicitly. For example:

option dhcp.bootfile-name “bootfile.lis”;

Option	Description
option all-subnets-local flag;	Use this option to indicate whether or not to assume all subnets of the client’s IP network use the same MTU as the client’s subnet. ON means assume all subnets share the same MTU. OFF means assume some subnets have smaller MTUs.
option arp-cache-timeout uint32;	Use this option to identify the timeout (in seconds) for ARP cache entries.
option bcms-controller-address ip-address [, ip-address …];	(V4) This option configures a list of IPv4 addresses for use as Broadcast and Multicast Controller Servers ("BCMS").
option bcms-controller-names domain-list;	(V4) This option contains the domain names of local Broadcast and Multicast Controller Servers ("BCMS") controllers which the client may use.
option bootfile-name string;	Use this option to identify a bootstrap file. If this option is 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 support it; others require it.
option boot-size uint16;	Use this option to specify the length in 512-octet blocks of the client’s default boot image.
option broadcast-address ip-address;	Use this option to identify the broadcast address in use on the client’s subnet. See STD 3 (RFC 1122), section 3.2.1.3 for legal values for broadcast addresses.
option cookie-servers ip-address [, ip-address ...];	Use this option to list RFC 865 cookie servers in order of preference.
option default-ip-ttl uint8;	Use this option to identify the default time-to-live the client should use on outgoing datagrams.
option default-tcp-ttl uint8;	Use this option to identify the default TTL to use when sending TCP segments. The minimum value is 1.
option default-url data-string;	(V4) The format and meaning of this option is not described in any standards document, but is claimed to be in use by Apple Computer.  It is not known what clients may reasonably do if supplied with this option.  Use at your own risk.
option dhcp-client-identifier data-string;	Use this option to specify a DHCP client identifier only in a host declaration. The DHCP server uses it to locate the host record by matching against the client identifier.
option dhcp-max-message-size uint16;	Use this option to specify the maximum length DHCP message that the client is able to accept. Use this option in the DHCP configuration file to supply a value when the client does not. Note!     Use this option with caution. Make sure that the client can accept a message of the specified size.
option dhcp-parameter-request-list uint8[,uint8...];	The client uses this option to request that the server return certain options. Use this option in the DHCP configuration file to override the client's list, or to supply a list when the client does not. The value is a list of valid DHCP option codes as listed in RFC 2132.
option domain-name-servers ip-address [, ip-address ...];	Use this option to list Domain Name System (STD 12, RFC 1035) name servers in order of preference.
option domain-name string;	Use this option to identify the domain name the client should use when resolving hostnames via the Domain Name System.
option domain-search domain-list;	(V4) The domain-search option specifies a 'search list' of Domain Names to be used by the client to locate not-fully-qualified domain names.  The difference between this option and historic use of the domain-name option for the same ends is that this option is encoded in RFC1035 compressed labels on the wire.
option extensions-path string;	Use this option to indicate the path-name of a file the client should load containing more options.
option finger-server ip-address [, ip-address ...];	Use this option to list the Finger servers in order of preference.
option font-servers ip-address [, ip-address ...];	Use this option to list X Window System Font servers in order of preference.
option host-name string;	Use this option to name the client. The name may or may not be qualified with the local domain name. It is preferable to use the domain-name option to specify the domain name. See RFC 1035 for character set restrictions.
option ieee802-3-encapsulation flag;	If the interface is an Ethernet, use this option to indicate whether the client uses Ethernet Version 2 (RFC 894) or IEEE 802.3 (RFC 1042) encapsulation. OFF means use RFC 894 encapsulation. ON means use RFC 1042 encapsulation.
option ien116-name-servers ip-address [, ip-address ...];	Use this option to list IEN 116 name servers in order of preference.
option impress-servers ip-address [, ip-address ...];	Use this option to list Imagen Impress servers in order of preference.
option interface-mtu uint16;	Use this option to identify what MTU value to use on this interface. The minimum legal value is 68.
option ip-forwarding flag;	Use this option to indicate if the client should configure its IP layer for packet forwarding. ON means disable forwarding. OFF means enable forwarding.
option irc-server ip-address [, ip-address ...];	Use this option to list the IRC servers in order of preference.
option log-servers ip-address [, ip-address ...];	Use this option to list MIT-LCS UDP log servers in order of preference.
option lpr-servers ip-address [, ip-address ...];	Use this option to list RFC 1179 line printer servers in order of preference.
option mask-supplier flag;	Use this option to indicate whether or not the client should respond to subnet mask requests using ICMP. ON means do not respond to subnet mask requests. OFF means respond to subnet mask requests.
option max-dgram-reassembly uint16;	Use this option to indicate the maximum size datagram the client should be prepared to reassemble. The minimum legal value is 576.
option merit-dump string;	Use this option to indicate the path-name of a file to which the client’s core image should be dumped in the event of a client crash. The path is formatted as a character string using the NVT ASCII character set.
option mobile-ip-home-agent ip-address [, ip-address ...];	Use this option to list mobile IP home agents in order of preference. Usually there will be only one agent.
option nds-context string;	Use this option to identify the initial NDS context the client should use.
option nds-servers ip-address [, ip-address...];	Use this option to list Novell Directory Services servers in order of preference.
option nds-tree-name data-string;	Use this option to name the NDS tree the client will be contacting.
option netbios-dd-server ip-address [, ip-address ...];	Use this option to list RFC 1001/1002 NetBIOS Datagram Distribution servers in order of preference.
option netbios-name-servers ip-address [, ip-address ...];	Use this option to list RFC 1001/1002 NetBIOS Name Server name servers in order of preference. Note!     NetBIOS is the same as WINS.
option netbios-node-type uint8;	Use this option to configure configurable NetBIOS over TCP/IP clients as described in RFC 1001/1002. The value is a single octet identifying the client type. Possible node types are 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 data-string;	Use this option to specify 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 netinfo-server-address ip-address [, ip-address …];	(V4) The netinfo-server-address option has not been described in any RFC, but has been allocated (and is claimed to be in use) by Apple Computers.  It's hard to say if this is the correct format, or what clients might be expected to do if values were configured. Use at your own risk.
option netinfo-server-tag string;	(V4) The netinfo-server-tag option has not been described in any RFC, but has been allocated (and is claimed to be in use) by Apple Computers.  It's hard to say if this is the correct format, or what clients might be expected to do if values were configured.  Use at your own risk.
option nis-domain string;	Use this option to specify the client’s NIS (Sun Network Information Services) domain. Use the NVT ASCII character set to define the domain character string.
option nis-servers ip-address [, ip-address ...];	Use this option to list NIS servers in order of preference.
option nisplus-domain string;	Use this option to specify the client's NIS+ domain. Use the NVT ASCII character set to define the domain character string.
option nisplus-servers ip-address [, ip-address ...];	Use this option to list NIS+ servers in order of preference.
option non-local-source-routing flag;	Use this option to indicate if the client should configure its IP layer to allow forwarding of datagrams with non-local source routes. ON means disable forwarding. OFF means enable forwarding.
option nntp-server ip-address [, ip-address ...];	Use this option to list NNTP servers in order of preference.
option ntp-servers ip-address [, ip-address ...];	Use this option to list NTP (RFC 1035) servers in order of preference.
option nwip-domain data-string;	(V4) The name of the NetWare/IP domain that a NetWare/IP client should use.
option nwip-suboptions data-string;	(V4) A sequence of suboptions for  NetWare/IP clients – see RFC2242 for details.  Normally this option is set by specifying specific NetWare/IP suboptions – see the The NetWare/IP Suboptions  section for more information.
option path-mtu-aging-timeout uint32;	Use this option to specify the timeout to use (in seconds) when aging Path MTU values that were discovered by the mechanism defined in RFC 1191.
option path-mtu-plateau-table uint16 [, uint16 ...];	Use this option to specify a table of MTU sizes to use when performing Path MTU Discovery as defined in RFC 1191. The table is a list of 16-bit unsigned integers. You must list them in order from smallest to largest. The minimum MTU value cannot be smaller than 68.
option perform-mask-discovery flag;	Use this option to indicate whether or not the client should perform subnet mask discovery using ICMP. ON means do not perform mask discovery. OFF means perform mask discovery.
option policy-filter ip-address ip-address [, ip-address ip-address ...];	Use this option to indicate the policy filters for non-local source routing. The filters consist of IP addresses and masks that indicate which destination/mask pairs to use when filtering incoming source routes. The client should discard any source routed datagram whose next-hop address does not match one of the filters. See STD 3 (RFC 1122) for more information.
option pop-server ip-address [, ip-address ...];	Use this option to list POP3 servers in order of preference.
option resource-location-servers ip-address [, ip-address ...];	Use this option to list RFC 887 Resource Location servers in order of preference.
option root-path string;	Use this option to specify the path-name that contains the client’s root disk. The path is formatted as a character string using the NVT ASCII character set.
option router-discovery flag;	Use this option to indicate whether or not the client should solicit routers using the Router Discovery mechanism defined in RFC 1256. ON means do not perform router discovery. OFF means perform router discovery.
option routers ip-address [, ip-address ...];	Use this option to list IP addresses for routers on the client’s subnet, listing the routers in order of preference.
option router-solicitation-address ip-address;	Use this option to identify the address where the client transmits router solicitation requests.
option slp-directory-agent flag ip-address [, ip-address …];	(V4) This option specifies two things: the IP addresses of one or more Service Location Protocol Directory Agents, and whether the use of these addresses is mandatory.  If the flag is true, the SLP agent should just use the IP addresses given.  If the value is false, the SLP agent may additionally do active or passive multicast discovery of SLP agents (see RFC2165 for details). Please note that in this option and the slp-service-scope option, the term "SLP Agent" is being used to refer to a Service Location Protocol agent running on a machine that is being configured using the DHCP protocol. Note that some companies may refer to SLP as NDS.  If you have an NDS directory agent whose address you need to configure, the slp-directory-agent option should work.
option slp-service-scope flag [ string ];	(V4) The Service Location Protocol Service Scope Option specifies two things: a list of service scopes for SLP, and whether the use of this list is mandatory.  If the flag is true, the SLP agent should only use the list of scopes provided in this option; otherwise, it may use its own static configuration in preference to the list provided in this option. The text string should be a comma-separated list of scopes that the SLP agent should use.  It may be omitted, in which case the SLP Agent will use the aggregated list of scopes of all directory agents known to the SLP agent.
option smtp-server ip-address [, ip-address ...];	Use this option to list SMTP servers in order of preference.
option static-routes ip-address ip-address [, ip-address ip-address ...];	Use this option to specify a list of static routes that the client should install in its routing cache. If there are multiple routes to the same destination, you should list them in descending order of priority. The routes are made up of IP address pairs. The first address is the destination address; the second address is the router for the destination. The default route (0.0.0.0) is an illegal destination for a static route. Use the routers option to specify the default route. Note!     This option cannot be used with classless IP routing since it does not include a subnet mask.
option streettalk-directory-assistance-server ip-address [, ip-address ...];	Use this option to list the StreetTalk Directory Assistance (STDA) servers in order of preference.
option streettalk-server ip-address [, ip-address ...];	Use this option to list the StreetTalk servers in order of preference.
option subnet-mask ip-address;	Use this option indicate the client’s subnet mask as per RFC 950. If no subnet mask option is in scope, the DHCP server uses the subnet mask from the subnet declaration on which the address is being assigned. If a subnet mask option is in scope for the address being assigned, it overrides the subnet mask specified in the subnet declaration.
option swap-server ip-address;	Use this option to identify the IP address of the client’s swap server.
option tcp-keepalive-garbage flag;	Use this option to indicate whether the client sends TCP keep-alive messages with an octet of garbage for compatibility with older implementations. ON means do not send a garbage octet. OFF means send a garbage octet.
option tcp-keepalive-interval uint32;	Use this option to indicate the interval (in seconds) the client TCP waits before sending a keep-alive message on a TCP connection. The time is specified as a 32-bit unsigned integer. 0 (zero) means do not generate keep-alive messages unless requested by an application.
option tftp-server-name string;	Use this option to identify a TFTP server. If this option is supported by the client, it should have the same effect as the server-name declaration. BOOTP clients are unlikely to support this option. Some DHCP clients support it; others require it.
option time-offset int32;	Use this option to specify the offset of the client’s subnet (in seconds) from Coordinated Universal Time (UTC). Use negative numbers for West of UTC and positive numbers for East of UTC.
option time-servers ip-address [, ip-address ...];	Use this option to list RFC 868 time servers in order of preference.
option trailer-encapsulation flag;	Use this option to indicate if the client negotiates the use of trailers (RFC 893) when using the ARP protocol. ON means do not use trailers. OFF means use trailers.
option uap-servers string;	(V4) This option specifies a list of URLs, each pointing to a user authentication service that is capable of processing authentication requests encapsulated in the User Authentication Protocol (UAP).  UAP servers can accept either HTTP 1.1 or SSLv3 connections.  If the list includes a URL that does not contain a port component, the normal default port is assumed (i.e., port  80  for http and port 443 for https).  If the list includes a URL that does not contain a path component, the path /uap is assumed.  If more than one URL is specified in this list, the URLs are separated by spaces.
option vendor-encapsulated-options data-string;	Use this option to specify vendor-specific information. See the Vendor Encapsulated Options section.
option vivso data-string;	(V4) The vivso option can contain multiple separate options, one for each 32-bit Enterprise ID.  Each Enterprise-ID discriminated option then contains additional options whose format is defined by the vendor who holds that ID. This option is usually not configured manually, but rather is configured via intervening option definitions.  See the Vendor Encapsulated Options section.
option www-server ip-address [, ip-address ...];	Use this option to list WWW servers in order of preference.
option x-display-manager ip-address [, ip-address ...];	Use this option to list the systems running X Window System Display Manager in order of preference.

 

Relay Agent Information Option

A relay agent can add a series of encapsulated options to a DHCP packet when relaying that packet to the DHCP server. The server can make address allocation decisions (or whatever decisions it wants) based on these options. The server returns these options in any replies it sends through the relay agent. The relay agent can use the information in these options for delivery or accounting purposes.

The relay agent option has the following sub-options. To reference these options in the DHCP server, specify the option space name "agent", followed by a period, followed by the option name.

Note!     It is not useful to specify these options to be sent.

option agent.circuit-id data-string;	The circuit-id sub-option encodes an agent-local identifier of the circuit from which a DHCP client-to-server packet was received. It is intended for agents who will use it in relaying DHCP responses back to the proper circuit. The format of this option is defined to be vendor-dependent.
option agent.remote-id data-string;	The remote-id sub-option encodes information about the remote host end of a circuit. Examples include the following: caller ID information, username information, remote ATM address, and cable modem ID. This is an opaque object that is administratively guaranteed to be unique to a particular remote end of a circuit.
option agent.DOCSIS-device-class uint32;	(V4) The DOCSIS-device-class suboption is intended to convey information about the host endpoint, hardware, and software, that either the host operating system or the DHCP server may not otherwise be aware of (but the relay is able to distinguish).  This is implemented as a 32-bit field (4 octets), each bit representing a flag describing the host in one of these ways.  So far, only bit zero (being the least significant bit) is defined in RFC3256. If this bit is set to one, the host is considered a CPE Controlled Cable Modem (CCCM).  All other bits are reserved.
option agent.link-selection ip-address;	(V4) The link-selection suboption is provided by relay agents to inform servers what subnet the client is actually attached to.  This is useful in those cases where the giaddr (where responses must be sent to the relay agent) is not on the same subnet as the client.  When this option is present in a packet from a relay agent, the DHCP server will use its contents to find a subnet declared in the configuration, and from here take one step further backwards to any shared-network the subnet may be defined within.  The client may be given any address within that shared network, as normally appropriate.

The Client FQDN Suboptions (DHCP V4)

The Client FQDN option is sent from the client to the server. Then in the response, the server constructs a reply FQDN option. Due to the complexity of the Client FQDN option format, it has been implemented as a suboption space rather than a single option.  Its components should not be specified in the server configuration file. It is constructed by the server itself based on information it has when it formats a reply to send to the client.

The configuration file can reference these options by specifing the option space name "fqdn", followed by a period, followed by the option name.

option fqdn.no-client-update flag;	When the client sends this, if it is true, it means the client will not attempt to update its A record.  When sent by the server to the client, the server is telling the client that the client should not update its own A record.
option fqdn.server-update flag;	When the client sends this to the server, it is requesting that the server update its A record.  When sent by the server, it is telling the client that the server has updated (or is about to update) the client's A record.
option fqdn.encoded flag;	If true, this indicates that the domain name included in the option is encoded in DNS wire format, rather than as plain ASCII text.  The client normally sets this to false if it doesn't support DNS wire format in the FQDN option. The server should always send back the same value that the client sent.
option fqdn.rcode1 uint8; option fqdn.rcode2 uint8;	These options specify the result of the updates of the A and PTR records, respectively, and are only sent by the DHCP server to the DHCP client.  The values of these fields are those defined in the DNS protocol specification.
option fqdn.fqdn string;	Specifies the domain name that the client wishes to use. This can be a fully-qualified domain name, or a single label.  If there is no trailing dot in the name, it is not fully-qualified, and the server will generally update that name in some locally-defined domain.
option fqdn.hostname (never set)	This option should never be set, but it can be read back using the option and config-option operators in an expression, in which case it returns the first label in the fqdn.fqdn suboption – for example, if the value of fqdn.fqdn is "foo.example.com.", then fqdn.hostname will be "foo".
option fqdn.domainname (never set)	This option should never be set, but it can be read back using the option and config-option operators in an expression, in which case it returns all labels after the first label in the fqdn.fqdn suboption – for example, if the value of fqdn.fqdn is "foo.example.com.", then fqdn.domainname will be "example.com.".  If this suboption value is not set, it means that an unqualified name was sent in the fqdn option, or that no fqdn option was sent at all.

 

The NetWare/IP Suboptions (DHCP V4)

RFC2242 defines a set of encapsulated options for Novell NetWare/IP clients.  To use these options in the DHCP server, specify the option space name, "nwip", followed by a period, followed by the option name.  The following options can be specified:

option nwip.nsq-broadcast flag;	If true, the client should use the NetWare Nearest Server Query to locate a NetWare/IP server.  The behavior of the Novell client if this suboption is false, or is not present, is not specified.
option nwip.preferred-dss ip-address [, ip-address…];	This suboption specifies a list of up to five IP addresses, each of which should be the IP address of a NetWare Domain SAP/RIP server (DSS).
option nwip.nearest-nwip-server ip-address [, ip-address …]	This suboption specifies a list of up to five IP addresses, each of which should be the IP address of a Nearest NetWare IP server.
option nwip.autoretries uint8;	Specifies the number of times that a NetWare/IP client should attempt to communicate with a given DSS server at startup.
option nwip.autoretry-secs uint8;	Specifies the number of seconds that a Netware/IP client should wait between retries when attempting to establish communications with a DSS server at startup.
option nwip.nwip-1-1 uint8;	If true, the NetWare/IP client should support NetWare/IP version 1.1 compatibility.  This is only needed if the client will be contacting Netware/IP version 1.1 servers.
option nwip.primary-dss ip-address;	Specifies the IP address of the Primary Domain SAP/RIP Service server (DSS) for this NetWare/IP domain.  The NetWare/IP administration utility uses this value as Primary DSS server when configuring a secondary DSS server.

 

Defining New Options

You can define new options with the DHCP server. Each DHCP option has the following:

•   A name, used by you to refer to the option.

•   A code, a number used by the DHCP server to refer to the option.

•   A structure, describing what the contents of the option look like.

To define a new option, choose a name that is not in use for any other option. For example, you cannot use "host-name" because the DHCP protocol already defines a host-name option. You should refer to the options listed in this chapter as these are all the DHCP options in use by TCPware. If an option name doesn't appear here, you can use it, but it's probably a good idea to put some kind of unique string at the beginning so you can be sure that future options don't take your name.

After choosing a name, choose a code. For site-local options, all codes between 224 and 254 are reserved for “site-local” DHCP options, so you can use any one of these.

The structure of an option is the format in which the option data appears. The DHCP server supports a few simple types: for example, integers, booleans, strings, and IP addresses. The server also supports the ability to define arrays of single types or arrays of fixed sequences of types. The syntax for declaring new options is:

option new-name code new-code = definition ;

The values of new-name and new-code are the name and the code you have chosen for the new option. The definition is one of the following simple option type definitions.

BOOLEAN	option new-name code new-code = boolean ; An option of type boolean is a flag with a value of either ON (true) or OFF (false). For example: option use-zephyr code 224 = boolean; option use-zephyr on;
INTEGER	option new-name code new-code = sign integer width ; The sign token should either be blank, unsigned, or signed. The width can be 8, 16 or 32, referring to the number of bits in the integer. For example, a definition of the sql-connection-max option and its use: option sql-connection-max code 192 = unsigned integer 16; option sql-connection-max 1536;
IP-ADDRESS	option new-name code new-code = ip-address ; An option of type IP address can be expressed either as a domain name or as an explicit IP address. For example: option sql-server-address code 193 = ip-address; option sql-server-address sql.example.com;
TEXT	option new-name code new-code = text ; An option of type text encodes an ASCII text string (this is called “string” above). For example: option sql-default-connection-name code 194 = text; option sql-default-connection-name "PRODZA";
DATA STRING	option new-name code new-code = string ; An option of type data string is a collection of bytes. It can be specified either as quoted text, like the text type, or as a list of hexadecimal octets separated by colons whose values must be between 0 and FF. For example: option sql-identification-token code 195 = string; option sql-identification-token        17:23:19:a6:42:ea:99:7c:22;
DOMAIN-LIST (V4)	option new-name code new-code = domain-list [compressed]; An option whose type is domain-list is an RFC1035-formatted (on the wire, "DNS Format") list of domain names, separated by root labels.  The optional compressed keyword indicates if the option should be compressed relative to the start of the option contents (not the packet contents). When in doubt, omit the compressed keyword.  When the software receives an option that is compressed and the compressed keyword is omitted, it will still decompress the option (relative to the option contents field).  The keyword only controls whether or not transmitted packets are compressed.
ENCAPSUL- ATION (V4)	option new-name code new-code = encapsulate identifier; An option whose type is encapsulate will encapsulate the contents of the option space specified in identifier. Examples of encapsulated options in the DHCP protocol include the vendor-encapsulated-options option, the netware-suboptions option and the relay-agent-information option.  For example: option space local; option local.demo code 1 = text; option local-encapsulation code 225 = encapsulate local; option local.demo "demo";
ARRAYS	Options can contain arrays of any of the above types except for the text and the data string types. For example: option kerberos-servers code 200 = array of ip-address; option kerberos-servers 10.20.10.1, 10.20.11.1;
RECORDS	Options can contain data structures consisting of a sequence of data types, sometimes called a record type. For example: option contrived-001 code 231 =        { boolean, integer 32, text }; option contrived-001 on 1772 "contrivance"; It is also possible to have options that are arrays of records. For example: option new-static-routes code 201 = array of {      ip-address, ip-address, ip-address, integer 8 }; option static-routes      10.0.0.0 255.255.255.0 net-0-rtr.example.com 1,      10.0.1.0 255.255.255.0 net-1-rtr.example.com 1,      10.2.0.0 255.255.224.0 net-2-0-rtr.example.com 3;

 

Vendor Encapsulated Options

The DHCP protocol defines the vendor-encapsulated-options option. This allows vendors to define their own options that will be sent encapsulated in a standard DHCP option.

(DHCP V4) It also defines the Vendor Identified Vendor Sub Options option (“VIVSO”).

The format of all of these options is either a chunk of opaque data, or an actual option buffer just like a standard DHCP option buffer.

(DHCP V4) The VIVSO option differs in that it contains options that correspond to vendor Enterprise-ID numbers (assigned by IANA), which then contain options according to each Vendor’s specifications. You will need to refer to your vendor’s documentation in order to form options to their specification.

You can send one of these options to clients in one of two ways.

The first way is to define the data directly, using a text string or a colon-separated list of hexadecimal values. To send a simple chunk of data, provide a value for the option in the right scope. For example:

option vendor-encapsulated-options
     2:4:AC:11:41:1:
     3:12:73:75:6e:64:68:63:70:2d:73:65:72:76:65:72:31:37:2d:31:
     4:12:2f:65:78:70:6f:72:74:2f:72:6f:6f:74:2f:69:38:36:70:63;

The second way of setting the value of these options is to have the DHCP server generate a vendor-specific options buffer. To do this, you must do four things: define an option space, define some options in that option space, provide values for them, and specify that this option space should be used to generate the relevant option.

To define a new option space to store vendor options, use the option space statement. The syntax of the statement is:

(DHCP V3) option space name;

(DHCP V4) option space name
    [ [ code width number ] [ length width number ] [ hash size number ] ];

Where the numbers following code width, length width, and hash size respectively identify the number of bytes used to describe option codes, option lengths, and the size in buckets of the hash tables to hold options in this space (most DHCP v4 option spaces use 1 byte codes and lengths, which is the default).

The code and length widths are used in the DHCP protocol – you must configure these numbers to match the applicable option space you are configuring.  They each default to 1.  Valid values for code widths are 1, 2 or 4.  Valid values for length widths are 0, 1 or 2. The hash size defaults depend upon the code width selected, and may be 254 or 1009.  Valid values range between 1 and 65535.  Note that the higher you configure this value, the more memory will be used.     It is considered good practice to configure a value that is slightly larger than the estimated number of options you plan to configure within the space.

In versions of ISC DHCP up to and including DHCP V3, this value was fixed at 9973.

The name of the option space can be used in option definitions. For example for DHCP V4:

option space SUNW code width 1 length width 1 hash size 3;
option SUNW.server-address code 2 = ip-address;
option SUNW.server-name code 3 = text;
option SUNW.root-path code 4 = text;

option space ISC code width 1 length width 1 hash size 3;
option ISC.sample code 1 = text;
option vendor.ISC code 2495 = encapsulate vivso-sample;
option vendor-class.ISC code 2495 = text;
option ISC.sample "configuration text here";
option vendor-class.ISC "vendor class here";

Once you have defined an option space and the format of some options, you can set up scopes that define values for those options and when to use them. For example, suppose you want to handle two different classes of clients. Using the option space definition in the previous example, you can send different option values to different clients based on the vendor-class-identifier option that the clients send, as follows:

class "vendor-classes" {
  match option vendor-class-identifier;
}

option SUNW.server-address 172.17.65.1;
option SUNW.server-name "sundhcp-server17-1";
option vivso-sample.sample “Hello world!”;

subclass "vendor-classes" "SUNW.Ultra-5_10" {
  vendor-option-space SUNW;
  option SUNW.root-path "tcpware:[sparc]";
}

subclass "vendor-classes" "SUNW.i86pc" {
  vendor-option-space SUNW;
  option SUNW.root-path "tcpware:[i86pc]";
}

Regular scoping rules apply. This lets you define values that are global in the global scope, and define values that are specific to a particular class in the local scope.

The vendor-option-space declaration indicates that in that scope the vendor-encapsulated-options option should be constructed using the values of all the options in the SUNW option space.

(DHCP V4) Note that the VIVSO option can have multiple vendor definitions all at once (even transmitted to the same client), so it is not necessary to configure it this way.

DHCP Lease Format

The DHCP server keeps a persistent database of leases it has assigned. This database is a free-form ASCII file containing a series of lease declarations. Every time a lease is acquired, renewed, or released, its new value is recorded at the end of the lease file. So, if more than one declaration appears for a given lease, the last one in the file is the current one.

In order to prevent lease the file from becoming arbitrarily large, from time to time the DHCP server creates a new dhcpd.leases file from its in-memory lease database.  Once this file has been written to disk, the old file is renamed dhcpd.leases_old, and the new file is renamed dhcpd.leases.  If the system crashes in the middle of this process, whichever dhcpd.leases file remains will contain all the lease information, so there is no need for a special crash recovery process.

Declarations

The primary declaration that is used in the dhcpd.leases file is the lease declaration.

lease ip-address { statements... }

Each lease declaration includes the client’s leased IP address. The statements within the braces define the duration of the lease and to whom it is assigned.

The following table describes the statements the DHCP server puts into a lease file.

If DHCP Failover is in use, the lease file will also contain failover-related statements. See the failover sections of this chapter for more information.

Lease Statement	Description
abandoned;	Records that the DHCP server saw the IP address in use on the network when it was thought to be free. The DHCP server detects active addresses with ping tests or "DHCP decline" messages from DHCP clients.
billing class “class-name”; (V3 only)	(V3 only) If this lease is a member of a class with “lease limit” set, this records that class.
billing subclass “class-name” subclass-data; (V3 only)	(V3 only) If this lease is a member of a subclass with “lease limit” set, this records the class and subclass.
binding state state; next binding state state; (V4 only)	(V4 only) Indicates the current lease state and what state the lease will move to when the current state expires. If Failover is not in use, the state will be either active or free.
client-hostname “hostname”;	Records the host name if the client sends one using the host-name option.
domain-name “domain-name”; (V3 only)	(V3 only) Specifies the DNS domain name sent to the client (if any).
dynamic-bootp; (V3) bootp; (V4)	Indicates the address was leased to a BOOTP client.
ends date;	Records the end time of a lease. (V4) Lease dates are specified by the DHCP server as described in the Lease Date Format section.
FQDN “fully-qualified-domain-name”; (V3 only)	(V3 only) Specifies the fully qualified domain name used by the DHCP server to perform the dynamic DNS update for the lease (if any).
hardware hardware-type mac-address;	Specifies the hardware type and the MAC address as a series of hexadecimal octets, separated by colons.
hostname “hostname”; (V3 only)	(V3 only) Records the hostname if the DHCP server looks up the hostname in DNS. This happens only if the parameter get-lease-hostnames was set.
on events { statements… }; (V4 only)	(V4 only) Records a list of statements to be executed if the given event occurs. Possible events are release and expiry. If multiple events are specified, they are separated by the vertical bar character.
option agent.circuit-id string; option agent.remote-id string; (V4 only)	(V4 only) Records the circuit ID and remote ID options sent by the relay agent, if the relay agent uses the relay agent information option.
reserved; (V4 only)	(V4 only) Indicates that the lease is reserved. See Reserved Leases section.
set variable = value; (V4 only)	(V4 only) Sets the value of a variable on the lease. For example, the vendor-class-identifier variable is used to record the client-supplied Vendor Class Identifier option. Other variables that are set are related to DDNS.
the ddns-text variable	Records the value of the client’s TXT identification record.
the ddns-fwd-name variable	Records the name the server used to update the client’s A record.
the ddns-client-fqdn variable	Records the name the client said it was using to update its own A record.
the ddns-rev-name variable	Records the name the server used to update the client’s PTR record. The name to which the PTR record points will be either ddns-fwd-name or ddns-client-fqdn.
starts date;	Records the start time of a lease. (V4) Lease dates are specified by the DHCP server as described in the Lease Date Format section.
uid client-identifier;	Records the client identifier used by the client to acquire the lease.  Clients are not required to send client identifiers, and this statement only appears if the client did in fact send one.  Client identifiers are frequently an ARP type (for example, 1 for ethernet) followed by the MAC address, just like in the hardware statement, but this is not required.  The client identifier is recorded as a colon-separated hexadecimal list or as a quoted string.  If it is recorded as a quoted string and it contains one or more non-printable characters, those characters are represented as octal escapes – a backslash character followed by three octal digits.

 

Lease Date Format (DHCP V4)

(DHCP V4 only) Lease file dates are specified in one of two ways, depending on the configuration value for the db-time-format parameter.  If it is set to default, then the date fields appear as follows:

weekday  year/month/day  hour:minute:second

The weekday is present to make it easier for a human to tell when a lease expires – it is specified as a number from zero to six, with zero being Sunday.  Weekday is ignored on input.   The year is specified with the century, so it should generally be four digits except for really long leases.   The month is specified as a number starting with 1 for January.  The day of the month is likewise specified starting with 1.  The hour is a number between 0 and 23, the minute a number between 0 and 59, and the second also a number between 0 and 59.

Default format lease times are specified in Universal Coordinated Time (UTC), not in the local time zone.

If the db-time-format parameter is configured to local, then the date fields appear as follows:

epoch  <seconds-since-epoch>; 
    # <day-name> <month-name> <day-number> <hours>:<minutes>:<seconds> <year>

The seconds-since-epoch is as according to the system's local clock (often referred to as "unix time").  The pound symbol (#) supplies a comment that describes what actual time this is according to the system's configured timezone, at the time the value was written.  It is provided only for human inspection.

If a lease will never expire, date is displayed as never instead of an actual date.

Working with DHCP Leases

The DHCP server requires that a lease database be present before it will start. Before starting the DHCP server for the first time, make sure there is a TCPWARE:DHCPD.LEASES file. If it doesn’t exist, create an empty one.

In order to prevent the lease database from growing without bound, the file is rewritten from time to time. First, a temporary lease database is created and all known leases are dumped to it. Then, the old lease database is renamed TCPWARE:DHCPD.LEASES_OLD. Finally, the newly written lease database is moved into place.

Be aware of the following situation: if the DHCP server process is killed or the system crashes after the old lease database has been renamed but before the new lease database has been moved into place, the TCPWARE:DHCPD.LEASES file disappears. The DHCP server will refuse to start. Do not create a new lease file when this happens. If you do, you will lose all your old bindings. Instead, rename TCPWARE:DHCPD.LEASES_OLD to TCPWARE:DHCPD.LEASES, restoring the old, valid lease file, and then start the DHCP server. This guarantees that a valid lease file will be restored.

Abandoned Leases

Abandoned leases are reclaimed automatically. When a client asks for a new address, and the server finds that there are no addresses available, it checks to see if there are any abandoned leases. The server allocates the oldest abandoned lease. The standard procedures for checking for lease address conflicts are still followed, so if the abandoned lease's IP address is still in use, it is re-abandoned.

If a client requests an abandoned address, the server assumes that the address was abandoned because the lease file was corrupted, and that the client is the machine that responded when the lease was pinged, causing it to be abandoned. In that case, the address is immediately assigned to the requesting client.

Static Leases

Leases that are given to clients for statically assigned IP addresses are treated differently than those for dynamically assigned IP addresses. An address is statically assigned by using a host declaration with a fixed-address statement.

Static lease information is not saved by the DHCP server. This means that they are not recorded in the lease file (DHCPD.LEASES). If your configuration uses only statically assigned IP addresses, you will not see any entries in the lease file.

This also means that NETCU SHOW DHCP[4] commands do not have any lease information to display for static assignments.

•   For SHOW DHCP/IP_ADDRESS, statically assigned IP addresses are not supported.

•   For SHOW DHCP/SUBNET and /LEASES, statically assigned IP addresses are not shown.

•   For SHOW DHCP/ALL, /HARDWARE_ADDRESS, and /CLIENT_IDENTIFIER, and in the dump file produced by /CONFIGURATION, statically assigned IP addresses are identified as a static assignment and no lease information is shown.

•   For SHOW DHCP/POOLS, statically assigned IP addresses are not included in the pool or subnet statistics.

DNS dynamic updates are supported only partially for static assignments. When the lease is granted, the appropriate A and PTR resource records are added automatically. However, since the lease information is not saved, the DHCP server does not delete the DNS entries when the lease expires or is released.

Registering Clients While the DHCP Server is Running

The DHCP server can register and unregister clients without having to restart the server. host declarations and subclass declarations can be added or removed from the running server using add and remove commands in an update file, by default TCPWARE:DHCPD.UPDATES.

The commands that can be placed into the update file are described in section Update File Statements below.

You would use host declarations if you are controlling access to IP addresses via allow/deny unknown-clients statements in your DHCPD.CONF configuration file. You would use subclass statements if you are controlling access to IP address pools using classes configured with the match statement and using pools with allow/deny members of _class_ statements.

Note!     The registration or unregistration of a client via the update file only affects the running server. The host and subclass declarations must also be added to the DHCPD.CONF configuration file.

You tell the DHCP server to execute the commands in the update file using the NETCU UPDATE DHCP or NETCU UPDATE DHCP4 command:

$ netcu update dhcp
$ netcu update dhcp4

A different file name can optionally be specified:

$ netcu update dhcp/filename=mydir:dhcpd.updates

You can verify the syntax of the update file before sending it to the DHCP server by using the NETCU SHOW DHCP/VERIFY or NETCU SHOW DHCP4/VERIFY command:

$ netcu show dhcp4/verify=(update[=filename])

If the update file name is not specified, the file TCPWARE:DHCPD.UPDATES is read. Note that the configuration file is read in before the update file. A different configuration file can be specified using the CONFIG option:

$ netcu show dhcp/verify=(config=filename,update[=filename])

You can check the DHCP server and see if a given host or subclass is known, for example to see if you need to add it, using the following netcu commands:

$ netcu show dhcp/isknown host hw-addr-or-client-id
$ netcu show dhcp4/isknown host hw-addr-or-client-id

$ netcu show dhcp/isknown subclass class-namesubclass-data
$ netcu show dhcp4/isknown subclass class-namesubclass-data

Update File Statements

This table describes the commands you can use in an update file.

Statement	Description
add host	Registers a client by adding the specified host declaration. The host declaration is in the same format as in the configuration file. This makes the specified hardware address and/or client identifier "known". add host name { [statements] } Note that static IP address assignments can be added by specifying the fixed-address statement in the host declaration.
add subclass	Registers a client by adding the specified subclass to the specified class. The class must be declared in the DHCPD.CONF configuration file. The subclass declaration is the same format as in the configuration file. This adds the specified subclass value as a member of the specified class. add subclass "class-name" subclass-data; add subclass "class-name" subclass-data { [statements] }
delete host	Un-registers a client by removing the specified host declaration. The host is specified by hardware address or client identifier. This makes the                        specified host "unknown". Note that all host declarations that match the hardware address or client identifier are deleted. delete host hw-addr-or-client-id;
delete subclass	Un-registers a client by removing the specified subclass from the specified class. This makes the specified subclass no longer a member of the class. delete subclass "class-name" subclass-data;

 

Examples:

add host fred {
  hardware ethernet 01:02:03:04:05:06;
  fixed-address 10.9.8.7;
  option routers 10.9.8.1;
}
add host wilma {
  option dhcp-client-identifier "wilma-cid";
}
delete host 01:02:03:04:05:06;
delete host "wilma-cid";

add subclass "gold" 01:01:02:03:04:05:06 {
  option host-name "fred";
}
add subclass "silver" "wilma-cid";
delete subclass "gold" 01:01:02:03:04:05:06;
delete subclass "silver" "wilma-cid";

DHCP Failover

Introduction

Since a DHCP server is responsible for the network's IP management, it can also be a potential point of network failure if it becomes unavailable. Using multiple servers with non-overlapping IP address pools is one way to provide limited fault-tolerance. For example: imagine a network with two DHCP servers. Server A has an address range of 100 IP addresses. Server B has a range of 50 different addresses. Both servers have a non-overlapping range of addresses. When a node broadcasts for an address, both servers respond, each offering an address from its own distinct range. Upon receiving both offers, the node chooses one. Typically, the response that reaches the node first is selected. In this case, Server A's. When Server B determines its offer is not needed, it returns the offered address to its own range, allowing it to be offered again.

If one of the servers is down, the other server continues to service the nodes. Now, instead of having two offers, each new node has only one offer, from the remaining server. Nodes that received their lease from the unavailable server attempt to reconnect with it. If the unavailable server does not respond in time, the nodes then attempt to get a new address from a new server. The other server can then offer an address from its own range. So, even though one server is down, the DHCP clients continue to function with the other server.

Note!     The two DHCP servers in this scenario operate without any communications or data sharing between them. Each server works as a standalone server.

Process Software takes the use of multiple servers to another level by offering DHCP Failover. DHCP Failover allows a secondary DHCP server to back up the primary DHCP server with the addition of taking into account network failure. This strategy insures that clients can reliably log into their corporate network and know they will be able to connect to corporate resources. In failover mode, the primary and the backup DHCP servers share a common IP address lease pool.

The two versions of DHCP supplied by TCPware (V3 and V4) have two different implementations of Failover. If you wish to use the failover protocol, make sure that both failover peers are running the same version of the DHCP server. The DHCP V3 and V4 implementations of Failover cannot interoperate with each other.

DHCP V3

With DHCP V3, the primary DHCP server handles all leasing and renewing of addresses during normal operations. In the event the primary DHCP server fails, the backup DHCP server automatically senses the primary server is not operating and automatically assumes complete DHCP operation. When the primary DHCP server becomes operational, it synchronizes with the backup DHCP server and resumes all the responsibilities of the primary DHCP server. All assignments performed by the backup DHCP server while acting as the primary server are transferred to the primary DHCP upon resumption of primary server responsibilities.

In the event the network fails, the secondary server believes the primary server is out of service and begins operation. The secondary server serves leases from a reserved pool shared by the failover partner servers. This reserve pool can be adjusted by the MIS system administrator.

DHCP V4

The failover protocol defines a primary server role and a secondary server role.  There are some differences in how primaries and secondaries act, but most of the differences simply have to do with providing a way for each peer to behave in the opposite way from the other.   So one server must be configured as primary, and the other must be configured as secondary, but with DHCP V4 doesn't matter much which one is which.

With DHCP V4, the primary and secondary DHCP servers both give out and renew leases during normal operations.  Each server will have about half of the available IP addresses in the pool at any given time for allocation.  If one server fails, the other server will continue to renew leases out of the pool, and will allocate new addresses out of the roughly half of available addresses that it had when communications with the other server were lost.

Configuring DHCP Failover

To configure your DHCP servers to use Failover, perform the following steps:

1   Choose one system to be the Primary and a second system to be the Secondary.

2   Determine the IP addresses of the Primary and Secondary systems. If a system has more than one IP address, choose one to use for DHCP Failover messages.

3   On the Primary system:

(V3) Create the boot file at TCPWARE:DHCPD.BOOT with the keyword "primary", the primary and secondary IP addresses, and configuration ID. The configuration ID would normally be "dhcpd".  See Boot File for DHCP V3 Failover for more information about boot files.

(V4) Add a failover peer declaration to the dhcpd.conf configuration file with the keyword “primary” and other parameters, and add failover peer references to each address pool for which you want to do Failover. See DHCP V4 Failover Configuration Statements for more information.

4   On the Secondary system:

(V3) Create the boot file at TCPWARE:DHCPD.BOOT with the keyword "secondary", the secondary and the primary IP addresses, and configuration ID. On the secondary system, the configuration ID may be "dhcpd" or may be a name that refers to the primary. Either way, the names of the configuration, lease, and state files must match this name.

(V4) Add a failover peer declaration to the dhcpd.conf configuration file with the keyword “secondary” and other parameters, and add failover peer references to each address pool for which you want to do Failover.

5   If you don't already have a configuration file, write a configuration file containing the subnets, shared networks, IP address ranges, hosts, etc, that reflect your network and the hosts you want the DHCP server to service. Include any DHCP Failover parameters as needed (see Failover Configuration File Statements).

Preferably, the configuration files on the Primary and the Secondary server systems should be the same. To help ensure that the configuration file is valid for both systems, make sure it contains a subnet statement for every subnet that either the Primary or the Secondary system has a network interface on.

(V4) Note that in DHCP V4, you can write the failover peer declaration directly in the configuration file, or you can write it in a separate file and use the include statement to include this file in the main configuration file. This latter method is preferred because it allows both the primary and secondary to use the same main configuration file, avoiding configuration mismatches.

6   Copy the configuration file to the TCPWARE directory on both the Primary and the Secondary systems.

Note!     (V3) Make sure the name of the configuration file matches the config-id parameter in the boot file for that system.

7   Make sure that both the Primary and the Secondary systems have lease files in the TCPWARE directory. If the lease file does not exist, create an empty one.

(V3) Make sure the lease file name matches config-id.

8   Run the DHCP server on both the Primary and the Secondary systems. The two servers will establish communications with each other and you're in business!

Differences between V3 and V4

The operation of the primary and secondary servers is different between V3 and V4. In the DHCP V3 implementation, the primary server gives out all of the leases during normal operation, and the secondary only gives out leases if the primary is down or unreachable. In this case, the percentage of IP addresses assigned as "backup" is kept small, usually 10-20% of the total address pool.

In contrast, in DHCP V4, during normal operations both the primary and the secondary give out leases. Ideally, they take on an equal load, and so the target percentage of "backup" leases in this case is 50%.

Important!          The DHCP V3 and V4 servers cannot be failover partners with each other. The successful operation of DHCP Failover requires the primary and secondary servers to be on the same page. The V3 and V4 implementations are too different to be able to interoperate with each other.

Another difference between the two versions is that in DHCP V3, a “boot” file is used for failover-related configuration and a “state” file is used for failover-related lease information. In DHCP V4, failover information is included in the standard configuration and lease files.

Boot File for DHCP V3 Failover

To use the DHCP V3 server with Failover, create a boot file at TCPWARE:DHCPD.BOOT. (In DHCP V4, the failover peer declaration in the configuration file is used for this purpose.)

The boot file is used to specify the following for DHCP V3 Failover operation:

•   Server's mode of operation

•   Server's own IP address

•   Partner server's IP address

•   Configuration ID

The format of the boot file is:

mode [server-IP partner-IP] "config-id";

If the boot file is not present, the V3 server operates with DHCP Failover disabled. It uses tcpware:dhcpd.conf and tcpware:dhcpd.leases for its default configuration and lease files. The V3 server does not use a state file to keep track and remember its state transitions when running in standalone mode (that is, with DHCP Failover disabled). See State File for DHCP V3 Failover for a description of state files. The following server modes are possible:

Mode	In this mode the server runs...
Primary	As the Primary server, with DHCP Failover functionality enabled. In this mode, the V3 server tries to "shadow" each of its lease transactions to its configured secondary server.
Secondary	As the Secondary or Backup server, with DHCP Failover functionality enabled. The V3 server receives lease transaction updates from its configured Primary server, and maintains an up-to-the-minute hot backup of the lease database. If the primary server crashes, or is shut down, the Secondary server takes over.
Standalone	With DHCP Failover disabled.

The IP address following the server mode is the server address, the next IP address is the secondary or backup server IP address.

The configuration ID is the file name (without the file type) of the configuration, lease, and state files. For example, if the configuration ID is ALPHA, the DHCP server looks for a configuration file named ALPHA.CONF, a lease file named ALPHA.LEASES, and a state file named ALPHA.STATE.

primary 10.23.24.11 10.23.24.25 "ALPHA";

The example boot file designates the current server as the primary with its own IP address 10.23.24.11 and the partner server's IP address 10.23.24.25. The partner server is a Secondary server.  This follows from the current server being a Primary server.

If the mode of operation is "standalone", the server's IP address and partner server's IP address are not needed. The format is as follows: 

standalone "config-id";

State File for DHCP V3 Failover

The state file is written by the DHCP V3 server when it is running with DHCP Failover enabled.  (In DHCP V4, this information is written to the lease file.)

The purpose of the state file is to save server state changes so that a server can "remember" its last state if it crashes or is re-started. Alternately, the state file can be used by the operator to force the DHCP server to start up in a desired mode (operator override). This feature allows the operator to switch the server into partner-down mode without a lengthy time-out period, or to start up in recover mode (that is, to force the DHCP server to download the entire lease database from the partner).

The V3 server appends a line to the state file every time its DHCP Failover state changes.  The last line in the file is the most current DHCP Failover state.

The state file consists of one or more lines of the following format:

server_state transaction_count; [date-time;]

server_state is one of the following:

failover-disabled	primary-comint	primary-conflict
startup	backup-comint	backup-conflict
primary-normal	primary-partnerdown	primary-recover
backup-normal	backup-partnerdown	backup-recover

 

Server-to-server messages are each assigned a monotonously increasing transaction number, which is recorded in the transaction_count field. This is an unsigned 32-bit number.

If the date-time stamp is present, the DHCP V3 server assumes that the state was recorded by the server itself. In this case, the server, upon starting up, calculates the safest state based on the recorded state and the time elapsed. If the date-time stamp is not present, the DHCP V3 server treats the entry as an operator-written override command and starts up in the specified state.

Failover Configuration File Statements

The statements listed in this section have been added to the DHCP configuration file for DHCP Failover. These are in addition to the DHCP configuration file statements listed above.

DHCP V3 Failover Configuration Statements

All the parameters for V3 Failover must be placed in the configuration file's global scope, with the exception of the backup-pool-size parameter. It may also be specified within a shared-network or subnet declaration.

Statement	Description
backup-ack-interval	The number of seconds used as the basis of the DHCP server's logarithmic back-off algorithm used for resending ACK messages to the secondary server. The default is 1 second. backup-ack-interval seconds;
backup-pool-size	This is the percentage of the IP address pool set aside for the Secondary server’s emergency use. The DHCP server will reserve no more than 50% of the available addresses. The default is 10%. backup-pool-size percent;
com-int-timeout	The number of seconds the server should wait for an expected response from its partner before switching to communication interrupted mode. The default is 600 seconds (10 minutes). com-int-timeout seconds;
failover-port	The UDP port the Primary and Secondary servers should use for DHCP V3-failover messages. The default is 647. failover-port port;
mclt	Maximum Client Lead Time: This is the length of lease in seconds to give out on a first time basis, or the client lead time for renewals. See the DHCP Failover internet draft for a more detailed explanation. The default is 3600 seconds (1 hour). mclt seconds;
safe-period-timeout	The number of seconds spent in communication interrupted state before automatic switch over to partner-down state. A value of 0 means no automatic switch over. The default is 0 seconds. safe-period-timeout seconds;
startup-delay	The number of seconds to wait during startup before the server moves from STARTUP state to the state specified in the state file. The default is 5 seconds. startup-delay seconds;

 

DHCP V4 Failover Configuration Statements

In order to configure failover in DHCP V4, you need to write a failover peer declaration that configures the failover protocol, and you need to include peer references in each pool declaration for which you want to do failover.  You do not have to do failover for all pools on a given network segment.  You must not tell one failover partner it's doing failover on a particular address pool and tell the other it is not.  You must not have any common address pools on which you are not doing failover.  A pool declaration that utilizes failover would look like this:

     pool {
          failover peer "foo";
          pool specific parameters
     };

For safety, we recommend that you either do failover or don't do failover, but don't do any mixed pools. Also, we recommend that you use the same master configuration file for both servers, and have a separate file for each failover partner that contains that partner’s peer declaration and includes the master file.  This will help you to avoid configuration mismatches.

A basic sample dhcpd.conf file for a primary server might look like this:

     failover peer "foo" {
       primary;
       address pri.example.com;
       port 519;
       peer address sec.example.com;
       peer port 520;
       max-response-delay 60;
       max-unacked-updates 10;
       mclt 3600;
       split 128;
       load balance max seconds 3;
     }

     include "tcpware:dhcpd.master";

The following table lists the statements that can appear in the failover peer declaration:

Failover Peer Statement

Description

primary or secondary	Determines whether the server is the primary server or the secondary server in the failover partnership. Only one may be specified on a given system. primary; secondary;
address	Specifies the IP address or DNS name upon which the server should listen for connections from its failover peer. Also, the value to use for the DHCP Failover Protocol server identifier. Required. address ip-address;
peer address	Specifies the IP address or DNS name to which the server should connect to reach its failover peer for failover messages. peer address ip-address;
port	Specifies the TCP port on which the server should listen for connections from its failover peer. Optional. The default is 647. port port-number;
peer port	Specifies the TCP port to which the server should connect to reach its failover peer for failover messages. Optional. The default is 647. peer port port-number;
max-response-delay	Tells the DHCP server how many seconds may pass without receiving a message from its failover peer before it assumes that connection has failed.  This number should be small enough that a transient network failure that breaks the connection will not result in the servers being out of communication for a long time, but large enough that the server isn't constantly making and breaking connections.  Required. max-response-delay seconds;
max-unacked-updates	Tells the failover peer how many BNDUPD (bind update) messages it can send before it receives a BNDACK (bind ack) from the local system.  Required. max-unacked-updates count
mclt	Defines the Maximum Client Lead Time. It is required on the primary, and optional on the secondary.  This is the length of time for which a lease may be renewed by either failover peer without contacting the other.  The longer you set this, the longer it will take for the running server to recover IP addresses after moving into partner-down state.  The shorter you set it, the more load your servers will experience when they are not communicating.  A value of 3600 seconds is reasonable. mclt seconds;
split	Specifies the split between the primary and secondary for the purposes of load balancing. Whenever a client makes a DHCP request, the DHCP server runs a hash on the client identification, resulting in a value from 0 to 255.  This is used as an index into a 256 bit field.  If the bit at that index is set, the primary is responsible.  If the bit at that index is not set, the secondary is responsible.  The split value determines how many of the leading bits are set to one.  So, in practice, higher split values will cause the primary to serve more clients than the secondary.  Lower split values, the converse is true.  Legal values are between 0 and 255, of which the most reasonable is 128 (a 50/50 split). Cannot be specified in the secondary. The primary must specify either split or hba, but not both. split index;
hba	Specifies the split between the primary and secondary as a bitmap rather than a cutoff (as split does), which theoretically allows for finer-grained control.   In practice, there is probably no need for such fine-grained control, however.  An example hba statement: hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:     00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00; This is equivalent to a split 128; statement, and identical.  The following example is also equivalent to a split of 128, but is not identical: hba aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:     aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa; They are equivalent, because half the bits are set to 0, half are set to 1 (0xa is 1010 binary) and consequently this would roughly divide the clients equally between the servers.  They are not identical, because the actual peers this would load balance to each server are different for each example. You must only have split or hba defined in the primary, never both.  For most cases, the fine-grained control that hba offers isn't necessary, and split should be used. Cannot be specified in the secondary. hba colon-separated-hex-list;
load balance max seconds	Allows you to configure a cutoff after which load balancing is disabled.  The cutoff is based on the number of seconds since the client sent its first DHCPDISCOVER or DHCPREQUEST message, and only works with clients that correctly implement the secs field.  We recommend setting this to something like 3 or 5.  The effect of this is that if one of the failover peers gets into a state where it is responding to failover messages but not responding to some client requests, the other failover peer will take over its client load automatically as the clients retry. load balance max seconds seconds;
auto-partner-down	Instructs the server to initiate a timed delay upon entering the communications-interrupted state (out of contact with the failover peer).  At the conclusion of the timer, the server will automatically enter the partner-down state. See the DHCP Failover Partner-Down State section for more information. A zero value (the default) disables the auto-partner-down feature, and any positive value indicates the time in seconds to wait before automatically entering partner- down. auto-partner-down seconds;
pool balance statements	See the DHCP V4 Pool Balancing section for information about pool balancing. max-lease-misbalance percentage; max-lease-ownership percentage; min-balance seconds; max-balance seconds;

 

DHCP V4 Pool Balancing

The DHCP V4 Server evaluates pool balance on a schedule, rather than on demand as leases are allocated (which was the old approach).

In order to understand pool balance, some elements of its operation first need to be defined.  First, there are free and backup leases.  Both of these are referred to as free-state leases.  The states free and backup are “the free states” for the purpose of this discussion.  The difference is that only the primary may allocate from free leases unless under special circumstances, and only the secondary may allocate backup leases.

When pool balance is performed, the only plausible expectation is to provide a 50/50 split of the free-state leases between the two servers.  This is because no one can predict which server will fail, regardless of the relative load placed upon the two servers, so giving each server half the leases gives both servers the same amount of failure endurance.  Therefore, there is no way to configure any different behavior, outside of some very small windows described shortly.

The first thing calculated on any pool balance run is a value referred to as lts, or "Leases To Send".  This, simply, for the primary is the difference in the count of free and backup leases, divided by two.   For the secondary, it is the difference in the backup and free leases, divided by two. The resulting value is signed:  if it is positive, the local server is expected to hand out leases to regain a 50/50 balance.  If it is negative, the remote server would need to send leases to balance the pool.  Once the lts value reaches zero, the pool is perfectly balanced (give or take one lease in the case of an odd number of total free-state leases).

The current approach is still something of a hybrid of the old approach, marked by the presence of the max-lease- misbalance parameter.  This parameter configures what used to be a 10% fixed value in earlier versions:  if lts is less than the number that are free plus the number that are backup times the max-lease-misbalance percentage, then the server will skip balancing a given pool (it won't bother moving any leases, even if some leases "should" be moved). 

The meaning of this parameter is also somewhat overloaded, however, in that it also governs the estimation of when to attempt to balance the pool (which may then also be skipped over).  The oldest leases in the free and backup states are examined.  The time they have resided in their respective queues is used as an estimate to indicate how much time it is probable it would take before the leases at the top of the list would be consumed (and thus, how long it would take to use all leases in that state). This percentage is directly multiplied by this time, and fit into the schedule if it falls within the min-balance and max-balance configured values.   The scheduled pool check time is only moved in a downwards direction, it is never increased.  Lastly, if the lts is more than double this number in the negative direction, the local server will 'panic' and transmit a Failover protocol POOLREQ (pool request) message, in the hopes that the remote system will be woken up into action.

Once the lts value exceeds the max-lease-misbalance percentage of total free-state leases as described above, leases are moved to the remote server.  This is done in two passes:

In the first pass, only leases whose most recent bound client would have been served by the remote server – according to the Load Balance Algorithm (see split and hba parameters above) – are given away to the peer.  This first pass will happily continue to give away leases, decrementing the lts value by one for each, until the lts value has reached the negative of the total number of leases multiplied by the max-lease-ownership percentage.  So it is through this value that you can permit a small misbalance of the lease pools – for the purpose of giving the peer more than a 50/50 share of leases in the hopes that their clients might someday return and be allocated by the peer (operating normally).  This process is referred to as 'MAC Address Affinity', but this is somewhat misnamed: it applies equally to DHCP Client Identifier options.  Note also that affinity is applied to leases when they enter the state free from expired or released.   In this case also, leases will not be moved from free to backup if the secondary already has more than its share.

The second pass is only entered into if the first pass fails to reduce the lts underneath the total number of free-state leases multiplied by the max-lease-ownership percentage.   In this pass, the oldest leases are given over to the peer without second thought about the Load Balance Algorithm, and this continues until the lts falls under this value.  In this way, the local server will also happily keep to itself a small percentage of the leases that would normally load balance.

 So, the max-lease-misbalance value acts as a behavioral gate.  Smaller values will cause more leases to transition states to balance the pools over time, higher values will decrease the amount of change (but may lead to pool starvation if there's a run on leases).

The max-lease-ownership value permits a small (percentage) skew in the lease balance of a percentage of the total number of free-state leases.

Finally, the min-balance and max-balance parameters make certain that a scheduled rebalance event happens within a reasonable timeframe (not to be thrown off by, for example, a 7 year old free lease).

Plausible values for the max-lease-misbalance and max-lease-ownership percentages lie between 0 and 100, inclusive, but values over 50 are indistinguishable from one another (once lts exceeds 50% of the free-state leases, one server must therefore have 100% of the leases in its respective free state).   It is recommended to select a max-lease-ownership value that is lower than the value selected for the max-lease-misbalance value.   max-lease-ownership defaults to 10, and max-lease-misbalance defaults to 15.

Plausible values for the min-balance and max-balance times (in seconds) range from 0 to (2^32)-1, but default to values 60 and 3600 respectively (to place balance events between 1 minute and 1 hour).

Failover Lease File Statements

The statements listed in this section have been added to the DHCP lease file for Failover. These are in addition to the DHCP lease file statements listed above.

DHCP V3 Failover Lease Statements

Statement	Description
acked-sec-interval seconds;	Acknowledged secondary lease interval. For information, see the DHCP Failover internet draft.
acked-sec-interval-start date;	The time when the partner was notified of the lease.
active;	This IP address has a current lease.
backup;	This IP address is reserved for use by the secondary (backup) server.
desired-interval seconds;	The length of the desired lease.
expired;	The lease for this IP address has expired.
free;	This IP address is available to be assigned.
last-partner-transaction date;	The time when the partner last updated the lease.
released;	The lease for this IP address has been released by the client or by the operator.
reset;	The DHCP server had marked this IP address as abandoned. The operator changed its status to available.
revoked;	The lease for this IP address has been revoked by the operator.
lease;	This is used in the Partner Down state to indicate that the IP address belongs to this server.
transaction-id number;	This is the transaction number that was assigned to this lease when it was queued or sent as an update to the partner server.
update-count n;	For each lease, the server which issues the lease sends an update to its partner server. This statement records the state of that update. 0      means no update is required 1      means that no update has been sent 2+    means 1 or more updates have been sent

 

DHCP V4 Failover Lease Statements

Statement	Description
tstp date;	The time the peer has been told the lease expires.
tsfp date;	The lease expiry time that the peer has acknowledged.
atsfp date;	The actual time sent from the failover partner.
cltt date;	The client’s last transaction time.
binding state state; next binding state state;	When the DHCP server is not configured to use Failover, the only possible binding states are active or free. With Failover, additional states are added, including the backup state, which indicates that the lease is available for allocation by the secondary.
failover peer state	Records the state of the primary and secondary Failover partners. failover peer “name” state {     my state state at date;     partner state state at date;     mclt seconds; }; The states of the peer named name is recorded in this declaration. Both the state of the running server (my state) and the other failover partner (partner state) are recorded. The following states are possible: unknown-state, partner-down, normal, communications-interrupted, resolution-interrupted, potential-conflict, recover, recover-done, shutdown, paused, startup. The mclt records the Maximum Client Lead Time (from the configuration file).

 

DHCP Failover Partner-Down State

It is possible during a prolonged failure to tell the remaining DHCP Failover peer that the other server is down, in which case the remaining server will (over time) reclaim all the addresses the other server had available for allocation, and begin to reuse them.  This is called putting the server into the partner-down state.

Be careful about transitioning a failover server to partner-down state.  The partner-down and communications-interrupted states are intentionally distinct because there do exist situations where a failover server can fail to communicate with its peer, but still has the ability to receive and reply to requests from DHCP clients.  Partner-down state permits the server to allocate leases from the partner's free lease pool after the mclt timer expires. This can be dangerous if the partner is in fact operating at the time (the two servers will give conflicting bindings).

It is also possible to get into this kind of dangerous situation: you put one server into the partner-down state, and then that server goes down, and the other server comes back up. The other server does not know that the first server was in the partner-down state, and may issue addresses previously issued by the other server to different clients, resulting in IP address conflicts.  Before putting a server into partner-down state, therefore, make sure that the other server will not restart automatically.

Also, the automatic partner-down feature should be used only with extreme caution. In general, it should be only be used at sites where the failover servers are directly connected to one another, such as by a dedicated hardwired link ("a heartbeat cable"). In other cases, the network manager should verify that the failover partner is really down and not coming back any time soon before putting a failover server into partner-down state manually.

When the down server comes back online, it automatically detects that it has been offline and requests a complete update from the server that was running in the partner-down state, and then both servers resume normal processing.

Transitioning to Partner-Down State

There are three ways that you can transition the DHCP server to Partner Down state:

1   The server may transition to Partner Down state automatically based on configuration settings:

·         (V3) the safe-period-timeout parameter

·         (V4) the auto-partner-down parameter of the failover peer statement

If the above parameter is specified in the configuration file, the DHCP server transitions to Partner Down state automatically after it has been in Communications Interrupted state for the specified time.

2   You can put the DHCP server into Partner Down state using the following NETCU command:

$ netcu set dhcp/partnerdown  ! V3
$ netcu set dhcp4/partnerdown ! V4

3   You can edit the DHCP server state file (V3) or lease file (V4) and specify that the server should be in partner down state.

(V3) Add a line to the end of the state file containing the Partner Down state and transaction number desired. Add either line:

•      primary-partnerdown transaction-number; (for the primary)

•      backup-partnerdown transaction-number; (for the secondary)

(V4) Edit the last failover peer state declaration in the lease file to set “my state” to partner-down, for example: (note that it is only required to set the “my state” value)

failover peer “name” state {
  my state partner-down;
  partner state state at date;
}

The next time the DHCP server is restarted, it will be in Partner Down state. You can restart the DHCP server by shutting down the server with the NETCU STOP/DHCP or NETCU STOP/DHCP4 command. NETCP automatically restarts the DHCP server.

Failover Server Restart

When a server starts that has not previously communicated with its failover peer, it must establish communications with its peer and synchronize with it before it can serve clients.  This can happen either because you have just configured your DHCP servers to perform failover for the first time, or because one of your failover servers has failed catastrophically and lost its database.

The initial recovery process is designed to ensure that when one failover peer loses its database and then resynchronizes, any leases that the failed server gave out before it failed will be honored.  When the failed server starts up, it notices that it has no saved failover state, and attempts to contact its peer.

When it has established contact, it asks the peer for a complete copy of its peer's lease database.  The peer then sends its complete database, and sends a message indicating that it is done.  The failed server then waits until mclt has passed, and once mclt has passed both servers make the transition back into normal operation.  This waiting period ensures that any leases the failed server may have given out while out of contact with its partner will have expired.

While the failed server is recovering, its partner remains in the partner-down state, which means that it is serving all clients.  The failed server provides no service at all to DHCP clients until it has made the transition into normal operation.

In the case where both servers detect that they have never before communicated with their partner, they both come up in this recovery state and follow the procedure just described.  In this case, no service will be provided to DHCP clients until mclt has expired.

Sample DHCPD.CONF File

The following is a sample DHCPD.CONF file.

#
# TCPWARE:DHCPD.CONF -- sample DHCP configuration file
#

# option definitions common to all supported networks...
option domain-name “fugue.com”;
option domain-name-servers toccato.fugue.com;
default-lease-time 43200;
option subnet-mask 255.255.255.0;
option time-offset 18000;
use-host-decl-names on;

# Shared network declaration is used to group subnets which share the same
# physical network together. The name is specified so that the shared     
# network can be referred to in log messages --
# it serves no other function.
#
# Note: You must have a subnet declaration for the subnet that the DHCP   
# server system is on even if you don’t want any address pool for the same
# subnet (or multiple subnets if the system is multi-homed).

shared-network FUGUE  {

# option definitions common to this shared network.
   option subnet-mask 255.255.255.224;
   default-lease-time 600;
   max-lease-time 7200;

# One of the two IP subnets that share this physical network
#
# Address ranges can be specified for each subnet attached to a shared    
# network. Since these subnets share the same physical network, addresses
# are pooled together, and assignments are made without regard to the     
# actual subnet. If the optional dynamic-bootp keyword is given in the    
# address range declaration, then addresses in that range can be assigned
# either with the DHCP protocol or the BOOTP protocol; otherwise, only   
# DHCP clients will have addresses allocated from the address range.
#
# Note that each IP subnet can have its own options specific to that      
# subnet. Options that are not specified in the subnet are taken from the
# shared network (if any) and then from the global option list.

subnet 204.254.239.0 netmask 255.255.255.224 {
       range 204.254.239.10 204.254.239.20;
       option broadcast-address 204.254.239.20;
       option routers prelude.fugue.com;
}

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

# Subnets can have no pooled ip addresses.
   subnet 10.10.10.0 netmask 255.255.255.0  {
   }
}

# IP subnets that are alone on their physical wire should be declared by
# themselves. The DHCP server still refers to them as shared networks in
# log messages, but this is simply an artifact of the underlying data     
# structure.
#
# Note that options can be specified in the subnet declaration that       
# supersede the global options specified earlier.

subnet 192.5.5.0 netmask 255.255.255.224 {
    range 192.5.5.26 192.5.5.30;
    option domain-name-servers bb.home.vix.com, gw.home.vix.com;
    option domain-name “vix.com”;
    option routers 192.5.5.1;
    option subnet-mask 255.255.255.224;
    option broadcast-address 192.5.5.31;
    default-lease-time 600;
    max-lease-time 7200;
}

# Hosts that 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 “toccato.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 “toccato.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”;
}

# Do not allow this one to boot
host host2
    hardware ethernet aa:cc:04:00:33:11;
    deny booting;
}

# Some other examples
host host1 {
    option dhcp-client-identifier “host1”;
    fixed-address 10.10.11.101, 10.11.22.101;
}