`dhcpd`

Dynamic Host Configuration Protocol (DHCP) server

Syntax:

You must be root to run this utility.

dhcpd [-p port] [-q] [-t] [-T] [-tf trace-output-file] 
      [-d] [-f] [-cf config-file] [-lf lease-file] 
      [-pf pid-file] [-a ARP-module-path] 
      [-play traceplayback-file] 
      [interface [... interface]

Options:

-a path

The path for the io-net ARP-module. This option is used only if more than one path is available. The default is /dev/io-net/ip_en.

-cf file

Alternative configuration file (e.g. for testing). We recommend the default, /etc/dhcpd.conf, for normal use.

-d

Debug option. Do not move to the background and log to stderr. The default logs errors to syslogd.

-f

Run dhcpd as a foreground process rather than allowing it to run as a daemon in the background (the default). This is useful when running dhcpd under a debugger.

-lf file

Alternative lease file (e.g. for testing). We recommend the default, /var/state/dhcp/dhcpd.leases, for normal production use.

-p port

The UDP port for receiving datagrams. The default is port 67 or as specified in /etc/services. The port used for transmitting is the one with the next highest number (e.g. if dhcpd receives on port 67, it transmits on port 68). If you use alternate port numbers, you must configure any relay agents or clients you're using to use the same alternate port numbers.

-pf file

An alternative file to store the PID of dhcpd. The default is /var/run/dhcpd.pid.

-q

Quiet mode. Use when you want to avoid printing the entire copyright message on startup (e.g. when starting dhcpd from a script).

-t

Test only the syntax of the /etc/dhcpd.conf file and exit.

-T

Test only the syntax of the lease database and exit.

-tf trace-output-file

Log entire startup state and transactions performed (only for debugging purposes).

-play traceplayback-file

Play back a trace-output file to reproduce behavior recorded using the -tf option (only for debugging purposes).

If the dhcpd doesn't work properly, you should use -tf to provide a trace-output file for technical support. It can be used in combination with the -play option to reproduce. When specifying -play option, use -lf for an alternate lease file. This won't change the current lease database.

interface

Specify the interface(s) that dhcpd will service. By default, dhcpd listens for DHCP packets on all interfaces capable of handling broadcast messages.

Description:

The dhcpd utility normally runs as a daemon in the background. It responds to requests for IP addresses and network information from clients on a TCP/IP network. The utility uses Dynamic Host Configuration Protocol (DHCP) or, with some restrictions, the Internet Bootstrap Protocol (BOOTP).

In order to support multiple interfaces, you should use npm-tcpip.so with reuseport_unicast option.

IP addresses are obtained from a list kept in /etc/dhcpd.conf, the DHCP configuration file. Editing this file enables a network administrator to assign static configuration to known hosts and dynamic configuration to unknown hosts added to the network. For more information on the contents of this file, see /etc/dhcpd.conf.

On startup, dhcpd reads the /etc/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, dhcpd allocates an address from this list.

When dhcpd assigns an IP address to a client, it stores the details (e.g. expiry time) in the /var/state/dhcp/dhcpd.leases file. Before you start DHCP for the first time, you must create this file:

# touch /var/state/dhcp/dhcpd.leases

For more information on the makeup of the leases file, see /var/state/dhcp/dhcpd.leases.

Under DHCP, after the lease has expired, dhcpd reclaims the IP address by adding it to the /etc/dhcpd.conf list.

BOOTP, however, does not allow for an associated lease expiry time, so you may have to reclaim expired BOOTP IP address leases yourself. The DHCP configuration file provides two parameter statements that may help you get around this problem:

dynamic-bootp-lease-cutoff date;
dynamic-bootp-lease-length length;

For more information, see the Parameter statements section in /etc/dhcpd.conf.

If you do change anything in /etc/dhcpd.conf, remember to restart dhcpd (the /var/run/dhcpd.pid file contains the PID of dhcpd).

OMAPI

The DHCP server lets you modify some of its configuration while it's running. Without stopping the server, you can modify database files, and then restart it. This capability is currently provided using OMAPI -- an API for manipulating remote objects. OMAPI clients connect to the server using TCP/IP, authenticate, and can then examine the server's current status and make changes to it.

Rather than implement the underlying OMAPI protocol directly, your programs should use the dhcpctl() API or OMAPI (API) itself. The dhcpctl() is a wrapper that handles some of the housekeeping chores that OMAPI doesn't do automatically.

OMAPI exports objects, which can then be examined and modified. The DHCP server exports the following objects: lease, host, failover-state, and group. Each object has a number of methods: lookup, create, and destroy. In addition, it's possible to look at attributes that are stored on objects, and in some cases to modify those attributes.

Lease object

Leases can't be created or destroyed, but you can examine and modify their state.

Leases have the following attributes:

state integer lookup, examine

1: free
2: active
3: expired
4: released
5: abandoned
6: reset
7: backup
8: reserved
9: bootp

ip-address data lookup, examine

IP address of the lease.

dhcp-client-identifier data lookup, examine, update

Client identifier that the client used when it acquired the lease. Not all clients send client identifiers, so this may be empty.

client-hostname data examine, update

Value the client sent in the host-name option.

host handle examine

Host declaration associated with this lease, if any acquired its lease.

hardware-type integer examine, update

Type of network interface that the client reported when it acquired its lease.

ends time examine

Time when the lease's current state ends, as understood by the client.

tstp time examine

Time when the lease's current state ends, as understood by the server.

tsfp time examine

time when the lease's current state ends, as understood by the failover peer (if there is no failover peer, this value is undefined).

cltt time examine

Time of the last transaction with the client on this lease.

Host object

Hosts can be created, destroyed, looked up, examined, and modified. If a host declaration is created or deleted using OMAPI, that information is recorded in the dhcpd.leases file. You can delete host declarations that are declared in the dhcpd.conf file.

Hosts have the following attributes:

name data lookup, examine, modify: the name of the host declaration. This name must be unique among all host declarations.
group handle examine, modify: the named group associated with the host declaration, if there is one.
hardware-address data lookup, examine, modify: the link-layer address that'll be used to match the client, if any. Valid only if hardware-type is also present.
hardware-type integer lookup, examine, modify: the type of the network interface that will be used to match the client,if any. Only valid if hardware-address is also present.
dhcp-client-identifier data lookup, examine, modify: the dhcp-client-identifier option that will be used to match the client, if any.
ip-address data examine, modify: fixed IP address which is reserved for a DHCP client that matches this host declaration.

Named groups can be created, destroyed, looked up, examined and modified. If a group declaration is created or deleted using OMAPI, that information will be recorded in the dhcpd.leases file. You can delete group declarations that are declared in the dhcpd.conf file.

Named groups currently can be associated only with hosts -- this lets you attach set of statements efficiently to more than one host declaration.

Groups have the following attributes:

name data: Name of the group. All groups that are created using OMAPI must have names; the names must be unique among all groups.
statements data: List of statements in the format of the dhcpd.conf file that will be executed whenever a message from a client whose host declaration references this group is processed.

Control object

The control object allows you to shut the server down. If the server is doing failover with another peer, it'll make a clean transition into the shutdown state and notify its peer, so that the peer can go into partner down, and then record the "recover" state in the lease file so that when the server is restarted, it'll automatically resynchronize with its peer.

On shutdown, the server will also attempt to cleanly shut down all OMAPI connections. If these connections don't go down cleanly after five seconds, they are shut down preemptively. It can take as much as 25 seconds from the beginning of the shutdown process to the time that the server actually exits.

To shut the server down, open its control object and set the state attribute to 2.

Failover-state object

The failover-state object tracks the state of the failover protocol as it's being managed for a given failover peer. The failover object has the following attributes (please also see the description for the dhcpd.conf file)

name data examine

Indicates the name of the failover peer relationship, as described in the server's dhcpd.conf file.

partner-address data examine

Indicates the failover partner's IP address.

local-address data examine

Indicates the IP address that's being used by the DHCP server for the failover peer.

mclt integer examine

Indicates the maximum client lead time in this failover relationship.

load-balance-max-secs integer examine

Indicates the maximum value for the seconds field in a client request before load balancing is bypassed.

load-balance-hba data examine

Indicates the load balancing hash bucket array for this failover relationship.

local-state integer examine, modify

Indicates the present state of the DHCP server in this failover relationship. Possible values for state are:

1: partner down
2: normal
3: communications interrupted
4: resolution interrupted
5: potential conflict
6: recover
7: recover done
8: shutdown
9: paused
10: startup
11: recover wait

In general it's not a good idea to make changes to this state. However, in the case that the failover partner is known to be down, it can be useful to set the DHCP server's failover state to partner down. At this point the DHCP server will take over service of the failover partner's leases as soon as possible, and will give out normal leases, not leases that are restricted by MCLT. If you do put the DHCP server into the partner-down state when the other DHCP server is not in that state, but isn't reachable, IP address assignment conflicts are possible, even likely. Once a server has been put into partner-down mode, its failover partner must not be brought back online until communication is possible between the two servers.

partner-state integer examine

Indicates the present state of the failover partner.

local-stos integer examine

Indicates the time at which the DHCP server entered its present state in this failover relationship.

partner-stos integer examine

Indicates the time at which the failover partner entered its present state.

skew integer examine

Indicates the skew between the failover partner's clock and this DHCP server's clock.

max-response-delay integer examine

Indicates the time in seconds after which, if no message is received from the failover partner, the partner is assumed to be out of communication.

cur-unacked-updates integer examine

Indicates the number of update messages that have been received from the failover partner but not yet processed.

Examples:

Start dhcpd using defaults:

dhcpd

Start dhcpd listening on one interface:

dhcpd en0

Start dhcpd in quiet mode, servicing only en0:

dhcpd -q en0

Files:

/etc/dhcpd.conf: Default configuration file.
/var/state/dhcp/dhcpd.leases: Contains information about leases.
/var/run/dhcpd.pid: Contain the PID number of the currently running dhcpd.
/var/lib/dhcp/dhcpd.leases~: Backup of dhcpd.leases file.

`dhcpd`

Syntax:

Runs on:

Options:

Description:

OMAPI

Lease object

Host object

Control object

Failover-state object

Examples:

Files:

Errors:

Author:

License:

Caveats:

See also: