18. Management API

A classic approach to daemon configuration assumes that the server's configuration is stored in configuration files and, when the configuration is changed, the daemon is restarted. This approach has the significant disadvantage of introducing periods of downtime when client traffic is not handled. Another risk is that if the new configuration is invalid for any reason, the server may refuse to start, which will further extend the downtime period until the issue is resolved.

To avoid such problems, the DHCPv4, DHCPv6, and D2 servers in Kea include support for a mechanism that allows online reconfiguration without requiring server shutdown. Both servers can be instructed to open control sockets, which is a communications channel. The server is able to receive commands on that channel, act on them, and report back status.

The DHCPv4, DHCPv6, and D2 servers receive commands over the UNIX domain sockets. For details on how to configure these sockets, see UNIX Control Socket, UNIX Control Socket and UNIX Control Socket. While it is possible to control the servers directly using UNIX domain sockets, that requires that the controlling client be running on the same machine as the server. SSH is usually used to connect remotely to the controlled machine.

Network administrators usually prefer using some form of a RESTful API to control the servers, rather than using UNIX domain sockets directly. Kea version 3 extends servers by HTTP/HTTPS sockets. For details on how to configure these sockets, see HTTP/HTTPS Control Socket, HTTP/HTTPS Control Socket and HTTP/HTTPS Control Socket.

Control connections over both HTTP and UNIX domain sockets are guarded with timeouts. The timeout value is set to 10 seconds and is not configurable.

This API can be used by external tools to manage and monitor Kea operation. An example of such a monitoring tool is ISC's Stork. For details, see Monitoring Kea With Stork.

18.1. Data Syntax

Communication over the control channel is conducted using JSON structures. If configured, Kea opens a socket and listens for incoming connections. A process connecting to this socket is expected to send JSON commands structured as follows:

{
    "command": "foo",
    "arguments": {
        "param1": "value1",
        "param2": "value2",
        ...
    }
}

The same command sent over the RESTful interface to the server has the following structure:

POST / HTTP/1.1\r\n
Content-Type: application/json\r\n
Content-Length: 147\r\n\r\n
{
    "command": "foo",
    "arguments": {
        "param1": "value1",
        "param2": "value2",
        ...
    }
}

The command parameter contains the name of the command to execute and it is mandatory. The arguments map contains the parameters required to carry out the given command. The exact content and format of the map are command-specific.

The server processing the incoming command sends a response of the form:

{
    "result": 0, // 0|1|2|3|4
    "text": "textual description",
    "arguments": {
        "argument1": "value1",
        "argument2": "value2",
        ...
    }
}

The result value is a status code indicating a result of the command. The following general status codes are currently supported:

0 - the command has been processed successfully.
1 - a general error or failure has occurred during the command processing.
2 - the specified command is unsupported by the server receiving it.
3 - the requested operation has been completed but the requested resource was not found. This status code is returned when a command returns no resources or affects no resources.
4 - the well-formed command has been processed but the requested changes could not be applied, because they were in conflict with the server state or its notion of the configuration.
5 - the command processed has failed and the configuration has been partially altered. The rollback mechanism was not able to restore the previous configuration.

For example, a well-formed command that requests a subnet that exists in a server's configuration returns the result 0. If the server encounters an error condition, it returns 1. If the command asks for an IPv6 subnet, but was sent to a DHCPv4 server, it returns 2. If the query asks for a subnet with subnet-id that has matches, the result is 3. If the command attempts to update a lease but the specified subnet-id does not match the identifier in the server's configuration, the result is 4.

Hook libraries can sometimes return additional status codes specific to their use cases.

The text field typically appears when the result is non-zero and contains a description of the error encountered, but it often also appears for successful outcomes. The exact text is command-specific, but in general uses plain English to describe the outcome of the command. The arguments map contains additional data values returned by the server which are specific to the command issued. The map may be present, but that depends on the specific command.

Note

Since Kea 1.9.7, it is possible to put comments in commands as in the configuration file. For instance:

{
    "command": "foo",
    # command arguments are here.
    "arguments": {
        "param1": "value1",
        ...
        /*
        "param2": "value2",
        ...
        */
    }
}

Note

Since Kea 2.7.5 it is possible to specify extra HTTP headers which are added to HTTP responses. Each header is specified by its name and value with optionally a user context. For instance:

{
    "http-headers": [
        {
            "name": "Strict-Transport-Security",
            "value": "max-age=31536000"
        }
     ],
 ...
 }

adds a HSTS header declaring that HTTPS (vs HTTP) must be used for one year.

18.2. HTTP Command Response Format

For backward compatibility with the obsolete (removed) Control Agent responses received by HTTP are always wrapped in an array (JSON list) of one element.

For example, the response for a command sent would be structured as follows:

[
    {
        "result": 0, // 0|1|2|3|4
        "text": "textual description",
        "arguments": {
            "argument1": "value1",
            "argument2": "value2",
            ...
        }
    }
]

An exception to this are authentication or authorization errors which cause server to reject the command entirely. The response to such an error is formatted as a single entry (JSON map) as follows:

{
    "result": 403,
    "text": "Forbidden"
}

These types of errors are possible on systems configured for either basic authentication or agents that load libdhcp_rbac.so.

18.3. Using the Control Channel

The easiest way to start interacting with the control API is to use common UNIX/Linux tools such as socat and curl.

In order to control the given Kea service via a UNIX domain socket, use socat in interactive mode as follows:

$ socat UNIX:/path/to/the/kea/socket -

or in batch mode, include the "ignoreeof" option as shown below to ensure socat waits long enough for the server to respond:

$ echo "{ some command...}" | socat UNIX:/path/to/the/kea/socket -,ignoreeof

where /path/to/the/kea/socket is the path specified in the Dhcp4/control-socket/socket-name parameter in the Kea configuration file. Text passed to socat is sent to Kea and the responses received from Kea are printed to standard output. This approach communicates with the specific server directly.

It is also easy to open a UNIX socket programmatically. An example of a simple client written in C is available in the Kea Developer's Guide, in the Control Channel Overview chapter, in the Using Control Channel section.

To use Kea's RESTful API with curl, use the following:

$ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get" }' http://kea.example.org:8000/

This assumes that the server is running on host kea.example.org and is running the RESTful service on port 8000.

18.4. Commands Supported by Both the DHCPv4 and DHCPv6 Servers

18.4.1. The `build-report` Command

The build-report command returns on the control channel what the command line -W argument displays, i.e. the embedded content of the config.report file. This command does not take any parameters.

{
    "command": "build-report"
}

18.4.2. The `config-get` Command

The config-get command retrieves the current configuration used by the server. This command does not take any parameters. The configuration returned is roughly equal to the configuration that was loaded using the -c command-line option during server start-up, or was later set using the config-set command. However, there may be certain differences, as comments are not retained. If the original configuration used file inclusion, the returned configuration includes all parameters from all included files. In Kea 2.4.0 and later, the successful response also contains a SHA-256 digest that can be used to easily determine whether a configuration has changed.

Warning

The returned configuration is not redacted, i.e. it contains database passwords in plain text, if those were specified in the original configuration. Care should be taken not to expose the command channel to unprivileged users.

An example command invocation looks like this:

{
    "command": "config-get"
}

18.4.3. The `config-hash-get` Command

The config-hash-get command retrieves the SHA-256 hash of the current configuration used by the server. This command does not take any parameters. The returned hash can be used to detect configuration changes.

An example command invocation looks like this:

{
    "command": "config-hash-get"
}

And the server's response:

{
    "result": 0,
    "arguments": {
        "hash": "5C3C90EF7035249E2FF74D003C19F34EE0B83A3D329E741B52B2EF95A2C9CC5C"
     }
 }

In Kea 2.4.0 and later, config-set and config-get also return the SHA-256 hash of the new or current configuration. This may be used to determine whether a configuration has changed.

18.4.4. The `config-reload` Command

The config-reload command instructs Kea to load again the configuration file that was used previously. This operation is useful if the configuration file has been changed by some external source; for example, a system administrator can tweak the configuration file and use this command to force Kea to pick up the changes.

Care should be taken when using this in conjunction with the config-set command. Kea remembers the location of the configuration file it was started with, and this configuration can be significantly changed using the config-set command. When config-reload is issued after config-set, Kea attempts to reload its original configuration from the file, possibly losing all changes introduced using config-set or other commands.

The config-reload command does not take any parameters. An example command invocation looks like this:

{
    "command": "config-reload"
}

If the configuration file is incorrect, reloading it can raise an error which leaves the server in an unusable state. See The config-set Command to learn how to recover from a non-working server.

18.4.5. The `config-test` Command

The config-test command instructs the server to check whether the new configuration supplied in the command's arguments can be loaded. The supplied configuration is expected to be the full configuration for the target server, along with an optional logger configuration. The configuration is sanity-checked to the extent possible without the server actually attempting to load it; it is possible for a configuration which successfully passes this command to still fail in the config-set command or at launch time. The structure of the command is as follows:

{
    "command": "config-test",
    "arguments":  {
        "<server>": {
        }
    }
}

where <server> is the configuration element name for a given server, such as "Dhcp4" or "Dhcp6". For example:

{
    "command": "config-test",
    "arguments":  {
        "Dhcp6": {
            ...
        }
    }
}

The server's response contains a numeric code, result (0 for success, non-zero on failure), and a string, text, describing the outcome:

{"result": 0, "text": "Configuration seems sane..." }

or

{"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }

18.4.6. The `config-write` Command

The config-write command instructs the Kea server to write its current configuration to a file on disk. It takes one optional argument, called "filename", that specifies the name of the file to write the configuration to. If not specified, the name used when starting Kea (passed as a -c argument) is used. If a relative path is specified, Kea writes its files only in the directory where it is running.

An example command invocation looks like this:

{
    "command": "config-write",
    "arguments": {
        "filename": "config-modified-2017-03-15.json"
    }
}

Note

As of Kea 2.7.9, the config file file may only be written to the same directory as the config file used when starting Kea (passed as a -c argument).

18.4.7. The `leases-reclaim` Command

The leases-reclaim command instructs the server to reclaim all expired leases immediately. The command has the following JSON syntax:

{
    "command": "leases-reclaim",
    "arguments": {
        "remove": true
    }
}

The remove boolean parameter is mandatory and indicates whether the reclaimed leases should be removed from the lease database (if true), or left in the expired-reclaimed state (if false). The latter facilitates lease affinity, i.e. the ability to re-assign an expired lease to a returning client that previously used that lease. See Configuring Lease Affinity for details. Also, see Lease Reclamation for general information about the processing of expired leases (lease reclamation).

18.4.8. The `list-commands` Command

The list-commands command retrieves a list of all commands supported by the server. It does not take any arguments. An example command may look like this:

{
    "command": "list-commands",
    "arguments": { }
}

The server responds with a list of all supported commands. The arguments element is a list of strings, each of which conveys one supported command.

18.4.9. The `config-set` Command

The config-set command instructs the server to replace its current configuration with the new configuration supplied in the command's arguments. The supplied configuration is expected to be the full configuration for the target server, along with an optional logger configuration. While optional, the logger configuration is highly recommended, as without it the server reverts to its default logging configuration. The structure of the command is as follows:

{
    "command": "config-set",
    "arguments":  {
        "<server>": {
        }
    }
}

where <server> is the configuration element name for a given server, such as "Dhcp4" or "Dhcp6". For example:

{
    "command": "config-set",
    "arguments":  {
        "Dhcp6": {
            ...
        }
    }
}

If the new configuration proves to be invalid, the server retains its current configuration; however, in some cases a fatal error message is logged indicating that the server is no longer providing any service: a working configuration must be loaded as soon as possible. If the control channel is dead, the configuration file can still be reloaded using the SIGHUP signal. If that is unsuccessful, restart the server.

Please note that the new configuration is retained in memory only; if the server is restarted or a configuration reload is triggered via a signal, the server uses the configuration stored in its configuration file. The server's response contains a numeric code, result (0 for success, non-zero on failure), and a string, text, describing the outcome:

{"result": 0, "text": "Configuration successful." }

or

{"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }

In Kea 2.4.0 and later, the successful response from a DHCPv4, DHCPv6, or DHCP-DDNS daemon also contains a SHA-256 digest of the newly set configuration. The digest can be used to easily determine whether a configuration has changed.

18.4.10. The `shutdown` Command

The shutdown command instructs the server to initiate its shutdown procedure; it is the equivalent of sending a SIGTERM signal to the process. This command does not take any arguments. An example command may look like this:

{
    "command": "shutdown",
    "arguments": {
        "exit-value": 3
    }
}

The server responds with a confirmation that the shutdown procedure has been initiated. The optional parameter, exit-value, specifies the numeric value with which the server process exits to the system. The default value is zero.

The DDNS daemon supports an extra parameter, type, which controls the way the process cleans up on exit. The supported shutdown types are:

"normal" - stops the queue manager and finishes all current transactions before exiting. This is the default.

"drain_first" - stops the queue manager but continues processing requests from the queue until it is empty.

"now" - exits immediately.

An example command may look like this:

{
    "command": "shutdown",
    "arguments": {
        "exit-value": 3,
        "type": "drain_first"
    }
}

18.4.11. The `dhcp-disable` Command

The dhcp-disable command globally disables the DHCP service. The server continues to operate, but it drops all received DHCP messages. This command is useful when the server's maintenance requires that the server temporarily stop allocating new leases and renew existing leases. It is also useful in failover-like configurations during a synchronization of the lease databases at startup, or recovery after a failure. The optional parameter max-period specifies the time in seconds after which the DHCP service should be automatically re-enabled, if the dhcp-enable command is not sent before this time elapses.

Since Kea 1.9.4, there is an additional origin parameter that specifies the command source. A server administrator should typically omit this parameter because the default value "user" indicates that the administrator sent the command. In Kea 2.5.5 through 2.5.7, this parameter was also used in communication between the HA partners to specify the identifier of an HA service sending the command in a numeric format. However, due to compatibility issues with older Kea versions that did not properly parse numeric values, it was necessary to introduce the new parameter, origin-id, in Kea 2.5.8.

It holds a numeric value representing the origin of the command. The same value can still be passed using the origin parameter, but it can cause the aforementioned compatibility issues between HA partners running different Kea versions; if both are used, origin-id takes precedence. New Kea versions favor using origin-id in communication between the HA partners, but overall, it is recommended that both parameters be omitted and the default value used.

The following codes represent the supported origins in numeric format:

1 - a user command; the same as specifying "origin": "user".

2000, 2001, 2002, etc. - origins specified by HA partners where the increments above 2000 are distinct HA service identifiers used when the partners have many relationships.

In the following example:

{
    "command": "dhcp-disable",
    "arguments": {
        "max-period": 20,
        "origin-id": 2002,
        "origin": "user"
    }
}

the effective origin is 2002, which indicates it is an HA partner sending the command for the service with ID of 2. The origin parameter will be ignored in this case.

18.4.12. The `dhcp-enable` Command

The dhcp-enable command globally enables the DHCP service.

Since Kea 1.9.4, there is an additional origin parameter that specifies the command source. A server administrator should typically omit this parameter because the default value "user" indicates that the administrator sent the command. In Kea 2.5.5 through 2.5.7, this parameter was also used in communication between the HA partners to specify the identifier of an HA service sending the command in a numeric format. However, due to compatibility issues with older Kea versions that did not properly parse numeric values, it was necessary to introduce the new parameter, origin-id, in Kea 2.5.8.

It holds a numeric value representing the origin of the command. The same value can still be passed using the origin parameter, but it can cause the aforementioned compatibility issues between HA partners running different Kea versions.; if both are used, origin-id takes precedence. New Kea versions favor using origin-id in communication between the HA partners, but overall, it is recommended that both

The following codes represent the supported origins in numeric format:

1 - a user command; the same as specifying "origin": "user".

2000, 2001, 2002, etc. - origins specified by HA partners where the increments above 2000 are distinct HA service identifiers used when the partners have many relationships.

In the following example:

{
    "command": "dhcp-enable",
    "arguments": {
        "origin-id": 2002,
        "origin": "user"
    }
}

the effective origin is 2002, which indicates it is an HA partner sending the command for the service with ID of 2. The origin parameter will be ignored in this case.

18.4.13. The `status-get` Command

The status-get command returns the server's runtime information:

pid: the process ID.

uptime: the number of seconds since the start of the server.

reload: the number of seconds since the last configuration (re)load.

high-availability: HA-specific status information about the DHCP servers configured to use the HA hook library:

local: the state, the role (primary, secondary, ...), and the scopes (i.e. what the server is actually processing) of the local server.

remote: the remote server's last known state, its served HA scopes, and the role of the remote server in the HA relationship.

multi-threading-enabled: a flag indicating whether multi-threading is enabled.

thread-pool-size: the number of DHCP service threads.

packet-queue-size: the maximum size of the packet queue. There is one queue, regardless of the number of running threads.

packet-queue-statistics: the average queue size for the last 10, 100, and 1000 packets, using an approach similar to the UNIX top command. The average queue size for the last 10 packets can be considered an instantaneous value, while the average for the last 1000 packets shows a longer-term trend.

The high-availability information is returned only when the command is sent to the DHCP servers in an HA setup. This parameter is never returned when the status-get command is sent to the DDNS daemon.

The thread-pool-size, packet-queue-size and packet-queue-statistics parameters are returned only when the command is sent to DHCP servers with multi-threading enabled. These three parameters and multi-threading-enabled are never returned when the status-get command is sent to the DDNS daemon.

To learn more about the HA status information returned by the status-get command, please refer to the The status-get Command section.

18.4.14. The `server-tag-get` Command:

The server-tag-get command returns the configured server tag of the DHCPv4 or DHCPv6 server (Configuration Sharing and Server Tags explains the server tag concept).

18.4.15. The `config-backend-pull` Command:

The config-backend-pull command triggers the polling of configuration backends (which must be configured for this command to have an effect), explained in Enabling the Configuration Backend.

18.4.16. The `version-get` Command

The version-get command returns extended information about the Kea version; it is the same information available via the -V command-line argument. This command does not take any parameters.

{
    "command": "version-get"
}

18.4.17. The `kea-lfc-start` Command

The kea-lfc-start command starts the kea-lfc process which cleans up the lease file (see The LFC Process). It takes no arguments and does not returns success when the lease backend is not the memfile, when the persist parameter of the lease-database was configured to false (but not when lfc-interval is 0), when it detected a LFC process is currently running or an error prevented a new LFC process to be started.

18.5. Commands Supported by the DHCPv4 Server

18.5.1. The `subnet4-select-test` Command

The subnet4-select-test provides a way to test DHCPv4 subnet selection based on a set of input parameters typically supplied in a client packet. Recognized parameters take strings and are:

interface - the incoming interface name

address - the client address

relay - the relay/gateway address

local - the local/destination address

remote - the remote/source address

link - the RAI link-selection address

subnet - the subnet-selection address

classes - (list of strings) client classes (allowing to select a guarded subnet)

The RAI link-selection is ignored when the ignore-rai-link-selection compatibility flag is true. When it is not ignored it has precedence over the subnet-selection.

Outside of errors possible results are:

(empty) "no selected subnet"

"selected shared network '<name>' starting with subnet '<subnet>' id <id>"

"selected subnet '<subnet>' id <id>"

18.5.2. The `subnet4o6-select-test` Command

The subnet4o6-select-test provides a way to test DHCPv4-over-DHCPv6 subnet selection based on a set of input parameters typically supplied in a client packet. Recognized parameters take strings and are:

interface - the incoming interface name of the DHCPv6 server

interface-id - the binary content of the interface-id relay option

address - the client address

relay - the relay/gateway address

local - the local/destination address

remote - the remote/source IPv6 address of the DHCPv6 server

link - the first relay link IPv6 address

subnet - the subnet-selection address

classes - (list of strings) client classes (allowing to select a guarded subnet)

According to the code only remote, interface-id and interface selectors are used. In DHCPv4-over-DHCPv6 implementation interface and remote values are transmitted from the DHCPv6 server, interface-id and link are carried in the relay info part of the DHCPv6 packet so are the same as for the DHCPv6 server.

Outside of errors possible results are:

(empty) "no selected subnet"

"selected shared network '<name>' starting with subnet '<subnet>' id <id>"

"selected subnet '<subnet>' id <id>"

18.6. Commands Supported by the DHCPv6 Server

18.6.1. The `subnet6-select-test` Command

The subnet6-select-test provides a way to test DHCPv6 subnet selection based on a set of input parameters typically supplied in a client packet. Recognized parameters take strings and are:

interface - the incoming interface name

interface-id - the binary content of the interface-id relay option

remote - the remote/source address

link - the first relay link address

classes - (list of strings) client classes (allowing to select a guarded subnet)

Outside of errors possible results are:

(empty) "no selected subnet"

"selected shared network '<name>' starting with subnet '<subnet>' id <id>"

"selected subnet '<subnet>' id <id>"

18.7. Commands Supported by the D2 Server

The D2 server supports only a subset of the DHCPv4/DHCPv6 server commands:

build-report
config-get
config-hash-get
config-reload
config-set
config-test
config-write
list-commands
shutdown
status-get
version-get

18.8. Migration from the obsolete (removed) Control Agent

Since Kea version 2.7.2 DHCP servers support HTTP/HTTPS control channels so the Control Agent (CA) is no longer needed, and since Kea version 3.1.8, the CA has been removed.

The DHCPv4, DHCPv6, and D2 servers extend the control-socket entry to control-sockets list. To migrate a CA configuration add an element to this list with:

socket-type set to http or https
socket-address with the content of CA http-host
socket-port with the content of CA http-port
trust-anchor (unchanged)
cert-file (unchanged)
key-file (unchanged)
cert-required (unchanged)
authentication (unchanged)

User context is supported too. Please look at respective HTTP control socket sections for defaults and other details: DHCP4 HTTP/HTTPS Control Socket, DHCP6 HTTP/HTTPS Control Socket and DHCP-DDNS HTTP/HTTPS Control Socket.

Beware that two servers must use different address / port pairs. This applies the HA listeners too.

For compatibility the JSON result of these HTTP/HTTPS control sockets is still encapsulated into a list.

18. Management API

18.1. Data Syntax

18.2. HTTP Command Response Format

18.3. Using the Control Channel

18.4. Commands Supported by Both the DHCPv4 and DHCPv6 Servers

18.4.1. The build-report Command

18.4.2. The config-get Command

18.4.3. The config-hash-get Command

18.4.4. The config-reload Command

18.4.5. The config-test Command

18.4.6. The config-write Command

18.4.7. The leases-reclaim Command

18.4.8. The list-commands Command

18.4.9. The config-set Command

18.4.10. The shutdown Command

18.4.11. The dhcp-disable Command

18.4.12. The dhcp-enable Command

18.4.13. The status-get Command

18.4.14. The server-tag-get Command:

18.4.15. The config-backend-pull Command:

18.4.16. The version-get Command

18.4.17. The kea-lfc-start Command

18.5. Commands Supported by the DHCPv4 Server

18.5.1. The subnet4-select-test Command

18.5.2. The subnet4o6-select-test Command

18.6. Commands Supported by the DHCPv6 Server

18.6.1. The subnet6-select-test Command

18.7. Commands Supported by the D2 Server

18.8. Migration from the obsolete (removed) Control Agent

18.4.1. The `build-report` Command

18.4.2. The `config-get` Command

18.4.3. The `config-hash-get` Command

18.4.4. The `config-reload` Command

18.4.5. The `config-test` Command

18.4.6. The `config-write` Command

18.4.7. The `leases-reclaim` Command

18.4.8. The `list-commands` Command

18.4.9. The `config-set` Command

18.4.10. The `shutdown` Command

18.4.11. The `dhcp-disable` Command

18.4.12. The `dhcp-enable` Command

18.4.13. The `status-get` Command

18.4.14. The `server-tag-get` Command:

18.4.15. The `config-backend-pull` Command:

18.4.16. The `version-get` Command

18.4.17. The `kea-lfc-start` Command

18.5.1. The `subnet4-select-test` Command

18.5.2. The `subnet4o6-select-test` Command

18.6.1. The `subnet6-select-test` Command