`dhcpd`

Dynamic Host Configuration Protocol (DHCP) server

You must be root to run this utility.

Syntax:

dhcpd [options...] &

Options:

-a: Apply the assigned IP address as an alias instead of overwriting the current configuration.
-b: Request the DHCP server to broadcast its response packets to the client where appropriate. The default is off.
-D ident: Specify the client identifier. The default identifier is the MAC address.
-d: Debug option. Do not move to the background and log to stderr. The default logs errors to syslogd.
-h hostname: The host name of the client. The default is supplied by server if available.
-I num: The number of times to poll waiting for the interface to become available. Polls every 2 seconds (default 5).
-i interface: The name of the interface to configure. The default is the first interface found.
-m: Write resolv.conf data as in-memory configuration strings (Neutrino only; the default is off.)
-n: Don't apply DHCP-supplied nameservers.
-P port: Specify the server port. The default is the dhcp port or port 67.
-p port: Specify the client port. The default is the dhcpc port or port 68.
-r: Add .node_number to the resolv.conf file name. Off by default.
-s host: Specify the preferred server; accept packets only from this server.
-T sec: Specify in seconds the time to wait for the client to complete (server ACK) its negotiation with the server. This is applied every time the client returns to the initialize (DISCOVER) state. The dhcp.client terminates on timeout with exit status 3.
-t num: Attempt to reach the server num times before giving up and terminating. Each attempt lasts 1 minute. The default is to attempt forever.
-u: Don't move to the background until the interface is configured.

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 io-pkt* with the 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 to use to match the client, if any.
ip-address data examine, modify: The fixed IP address that's 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 isn't a good idea to change 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 -i 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:

Contributing author:

License:

See also: