Dynamic Host Configuration Protocol (DHCP) server
|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]
All supported platforms.
|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.|
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:
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).|
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.
Leases can't be created or destroyed, but you can examine and modify their state.
Leases have the following attributes:
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:
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:
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.
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)
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.
Start dhcpd using defaults:
Start dhcpd listening on one interface:
Start dhcpd in quiet mode, servicing only en0:
dhcpd -q en0
When an error occurs, dhcpd sends a description of the error to syslogd and stderr, if dhcpd is running in the foreground.
Ted Lemon in cooperation with Vixie Enterprises.
This utility is based on copyright software of The Internet Software Consortium; for the copyright notice, see dhcpd in the appendix Third-Party Copyright Notices.
The tiny stack (npm-ttcpip.so) does not support dhcpd.
dhcp.client, /var/state/dhcp/dhcpd.leases, /etc/dhcpd.conf, dhcprelay, syslogd.