ISC DHCP API Interface

The ISC DHCP server provides an application programming interface (API) to query and manipulate lease data while the server is running. The Object Management API (OMAPI) enables remote access via a TCP/IP connection. The OMAPI functions exposed by the ISC DHCP server utilize a thin wrapper over OMAPI called dhcpctl, which provides access to objects that correspond to actual DHCP server objects, including lease, host, group, control and failover-state objects as described below. OMAPI enables gets and sets of attribute values of server objects such as leases and updates them on the server. However, OMAPI does not provide a comprehensive interface to the DHCP server for configuration and lease status collection and thus is not the only interface needed to centrally manage the ISC DHCP server. Instead editing of the DHCP configuration file on the server (or editing and copying or transferring the file to the server) then restarting the DHCP daemon provide the only current method of creating and managing the server configuration. To manage lease states and address capacity, periodic collection of the server lease file is necessary; the server does not report lease assignments upon occurrence.

Lease Object

The lease object corresponding to a lease can neither be created nor deleted using the API, but it can be fetched and modified. The following attributes are currently exposed for lease objects. For each attribute, the ability to use the attribute to lookup this lease (lookup key), read, and/or modify via OMAPI is denoted in parentheses following the attribute name.

• state (lookup key, read-only) - the lease state in encoded as an integer of the following possible values:
  • 1 = free
  • 2 = active
  • 3 = expired
  • 4 = released
  • 5 = abandoned
  • 6 = reset
  • 7 = backup
  • 8 = reserved
  • 9 = bootp
• ip-address (lookup key, read-only) - IP address of the lease
• dhcp-client-identifier (lookup key, read, update) - the client identifier for the lease
• client-hostname (read, update) - the client hostname associated with this lease
• host (read-only) - the host declaration name associated with this lease from the configuration file if any
• hardware-address (read, update) - the hardware address associated with this lease object
• hardware-type (read, update) - the hardware type associated with the lease (ethernet, token-ring or fddi)
• ends (read-only) - the time when this lease's current state ends according to the client
• tstp (read-only) - the time when this lease's current state ends according to the server
• tsfp (read-only) - the time when this lease's current state ends according to the failover server if configured; if in the partner-down state, this attribute may be adjusted by the server for expired, released or reset leases.
• atsfp (read-only) - the actual tsfp value send from the failover peer if configured
• cltt (read-only) - the time of the last transaction with the client on this lease

Host Object

Like lease objects, host objects can be fetched and updated using the API; but unlike lease objects, host objects may also be created and deleted. The following are attributes of the host object

• name (lookup key, read, modify) - the host declaration name
• group (read, modify) - group to which this host is associated, if any
• hardware-address (lookup key, read, modify) - the hardware address of the host
• hardware-type (read, modify) - the hardware type of the host (ethernet, token-ring, or fddi)
• dhcp-client-identifier (lookup key, read, modify) - the client identifier of the host if defined
• ip-address (read, modify) - the IP address if defined with a fixed-address parameter for the host
• statements (modify) - a list of declaration and/or parameter statements in configuration file format which are to be executed when a message from this host is being processed
• known (read, modify) - indicates if the client associated with this host declaration is to be treated as known.

Group Object

The group object corresponds to the group declaration in the configuration file. Group objects may be created, fetched, modified and deleted. The following attributes may be processed for group objects.

• name (lookup key, modify) - the name of the group declaration
• statements (modify) - a list of declaration and/or parameter statements in configuration file format which are to be executed when a message from a host within this group is being processed

Failover-State Object

The failover-state object enables retrieval of failover attributes for the server. It also enables modification of the failover state of the server.

• name (lookup key, read) - the name assigned in the failover peer statement in the configuration file.
• partner-address (read) - the failover partner's IP address (corresponds to the peer-address statement)
• local-address (read) - the IP address of this server as used for failover communications (corresponds to the address statement)
• partner-port (read) - the TCP port number used by the failover partner for failover communications as configured in the peer port parameter.
• local-port (read) - the TCP port used by this server to listen for failover communications
• max-outstanding-updates (read) - the maximum number of outstanding or unacknowledged packets as configured via the max-unacked-updates parameter.
• mclt (read) - the maximum client lead time value
• load-balance-max-secs (read) - the value of the corresponding parameter within this failover declaration
• load-balance-hba (read) - the hash bucket array (hba) algorithm was used prior to the simpler split directive, hence the terminology; this attribute indicates the split value
• local-state (read, modify) - indicates the current state of this server with respect to failover. Interpretation of the value of this attribute have changed from ISC dhcpd 3.x to 4.x per the table below.

• partner-state (read) - indicates the current state of the failover peer as encoded for local-state
• local-stos (read) - the time when this server entered its current local-state
• partner-stos (read) - the time when the failover peer entered its current partner-state.
• hierarchy (read) - indicates if this server is the primary (value = 0) or secondary (1) per the corresponding statement within this failover declaration
• last-packet-sent (read) - the time when the most recent failover packet was sent from this server to its failover peer
• last-timestamp-received (read) - the timestamp from the last message received by this server from its failover peer
• skew (read) - indicates the skew between this server's clock and its failover peer's
• max-response-delay (read) - the number of seconds the server shall wait before it concludes the failover peer is down
• cur-unacked-updates (read) - provides the current number of update messages that have been sent for which no acknowledgment has been received

Control Object

The control object enables graceful shutdown of the DHCP server by setting the control object state attribute to 2. The server will close all OMAPI connections and notify its failover peer if one exists.