Reference Implementations

Internet RFCs

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:

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.

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.

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.

local-state value

3.X State Interpretation

4.X State Interpretation

1

partner-down

startup

2

normal

normal

3

communications interrupted

communications interrupted

4

resolution interrupted

partner down

5

potential conflict

potential conflict

6

recover

recover

7

recover done

paused

8

shutdown

shutdown

9

paused

recover done

10

startup

resolution interrupted

11

recover wait

conflict done

254

N/A

recover wait

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.