API Reference¶

Kea currently supports 149 commands in kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6 daemons and cb_cmds, class_cmds, high_availability, host_cache, host_cmds, lease_cmds, stat_cmds, subnet_cmds hook libraries.

Commands supported by kea-ctrl-agent daemon: build-report, config-get, config-reload, config-set, config-test, config-write, list-commands, shutdown, version-get.

Commands supported by kea-dhcp-ddns daemon: build-report, config-get, config-reload, config-set, config-test, config-write, list-commands, shutdown, version-get.

Commands supported by kea-dhcp4 daemon: build-report, cache-clear, cache-get, cache-get-by-id, cache-insert, cache-load, cache-remove, cache-size, cache-write, class-add, class-del, class-get, class-list, class-update, config-get, config-reload, config-set, config-test, config-write, dhcp-disable, dhcp-enable, ha-continue, ha-heartbeat, ha-scopes, ha-sync, lease4-add, lease4-del, lease4-get, lease4-get-all, lease4-update, lease4-wipe, leases-reclaim, libreload, list-commands, network4-add, network4-del, network4-get, network4-list, network4-subnet-add, network4-subnet-del, remote-global-parameter4-del, remote-global-parameter4-get, remote-global-parameter4-get-all, remote-global-parameter4-set, remote-network4-del, remote-network4-get, remote-network4-list, remote-network4-set, remote-option-def4-del, remote-option-def4-get, remote-option-def4-get-all, remote-option-def4-set, remote-option4-global-del, remote-option4-global-get, remote-option4-global-get-all, remote-option4-global-set, remote-option4-network-del, remote-option4-network-set, remote-option4-pool-del, remote-option4-pool-set, remote-option4-subnet-del, remote-option4-subnet-set, remote-server4-del, remote-server4-get, remote-server4-get-all, remote-server4-set, remote-subnet4-del-by-id, remote-subnet4-del-by-prefix, remote-subnet4-get-by-id, remote-subnet4-get-by-prefix, remote-subnet4-list, remote-subnet4-set, reservation-add, reservation-del, reservation-get, reservation-get-all, reservation-get-page, server-tag-get, shutdown, stat-lease4-get, statistic-get, statistic-get-all, statistic-remove, statistic-remove-all, statistic-reset, statistic-reset-all, statistic-sample-age-set, statistic-sample-age-set-all, statistic-sample-count-set, statistic-sample-count-set-all, subnet4-add, subnet4-del, subnet4-get, subnet4-list, subnet4-update, version-get.

Commands supported by kea-dhcp6 daemon: build-report, cache-clear, cache-get, cache-get-by-id, cache-insert, cache-load, cache-remove, cache-size, cache-write, class-add, class-del, class-get, class-list, class-update, config-get, config-reload, config-set, config-test, config-write, dhcp-disable, dhcp-enable, ha-continue, ha-heartbeat, ha-scopes, ha-sync, lease6-add, lease6-bulk-apply, lease6-del, lease6-get, lease6-get-all, lease6-update, lease6-wipe, leases-reclaim, libreload, list-commands, network6-add, network6-del, network6-get, network6-list, network6-subnet-add, network6-subnet-del, remote-global-parameter6-del, remote-global-parameter6-get, remote-global-parameter6-get-all, remote-global-parameter6-set, remote-network6-del, remote-network6-get, remote-network6-list, remote-network6-set, remote-option-def6-del, remote-option-def6-get, remote-option-def6-get-all, remote-option-def6-set, remote-option6-global-del, remote-option6-global-get, remote-option6-global-get-all, remote-option6-global-set, remote-option6-network-del, remote-option6-network-set, remote-option6-pd-pool-del, remote-option6-pd-pool-set, remote-option6-pool-del, remote-option6-pool-set, remote-option6-subnet-del, remote-option6-subnet-set, remote-server6-del, remote-server6-get, remote-server6-get-all, remote-server6-set, remote-subnet6-del-by-id, remote-subnet6-del-by-prefix, remote-subnet6-get-by-id, remote-subnet6-get-by-prefix, remote-subnet6-list, remote-subnet6-set, reservation-add, reservation-del, reservation-get, reservation-get-all, reservation-get-page, server-tag-get, shutdown, stat-lease6-get, statistic-get, statistic-get-all, statistic-remove, statistic-remove-all, statistic-reset, statistic-reset-all, statistic-sample-age-set, statistic-sample-age-set-all, statistic-sample-count-set, statistic-sample-count-set-all, subnet6-add, subnet6-del, subnet6-get, subnet6-list, subnet6-update, version-get.

Commands supported by class_cmds hook library: class-add, class-del, class-get, class-list, class-update.

Commands supported by high_availability hook library: ha-continue, ha-heartbeat, ha-scopes, ha-sync.

Commands supported by host_cache hook library: cache-clear, cache-get, cache-get-by-id, cache-insert, cache-load, cache-remove, cache-size, cache-write.

Commands supported by host_cmds hook library: reservation-add, reservation-del, reservation-get, reservation-get-all, reservation-get-page.

Commands supported by lease_cmds hook library: lease4-add, lease4-del, lease4-get, lease4-get-all, lease4-update, lease4-wipe, lease6-add, lease6-bulk-apply, lease6-del, lease6-get, lease6-get-all, lease6-update, lease6-wipe.

Commands supported by stat_cmds hook library: stat-lease4-get, stat-lease6-get.

Commands supported by subnet_cmds hook library: network4-add, network4-del, network4-get, network4-list, network4-subnet-add, network4-subnet-del, network6-add, network6-del, network6-get, network6-list, network6-subnet-add, network6-subnet-del, subnet4-add, subnet4-del, subnet4-get, subnet4-list, subnet4-update, subnet6-add, subnet6-del, subnet6-get, subnet6-list, subnet6-update.

build-report¶

This command returns the list of compilation options that this particular binary was built with.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (built-in)

Description and examples: see build-report command

Command syntax:

{
    "command": "build-report"
}

Response syntax:

{
    "result": 0,
    "text": <string with build details>
}

cache-clear¶

This command removes all cached host reservations.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (host_cache hook library)

Description and examples: see cache-clear command

Command syntax:

{
    "command": "cache-clear"
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

cache-get¶

This command returns the full content of the host cache.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (host_cache hook library)

Description and examples: see cache-get command

Command syntax:

{
    "command": "cache-get"
}

Response syntax:

{
    "result": 0,
    "text": "123 entries returned.",
    "arguments": <list of host reservations>
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

cache-get-by-id¶

This command returns entries matching the given identifier from the host cache.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (host_cache hook library)

Description and examples: see cache-get-by-id command

Command syntax:

{
    "command": "cache-get-by-id",
    "arguments": {
        "hw-address": "01:02:03:04:05:06"
    }
}

Response syntax:

{
    "result": 0,
    "text": "2 entries returned.",
    "arguments": <list of host reservations>
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

cache-insert¶

This command inserts a host into the cache.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (host_cache hook library)

Description and examples: see cache-insert command

Command syntax:

{
    "command": "cache-insert",
    "arguments": {
        "hw-address": "01:02:03:04:05:06",
        "subnet-id4": 4,
        "subnet-id6": 0,
        "ip-address": "192.0.2.100",
        "hostname": "somehost.example.org",
        "client-classes4": [ ],
        "client-classes6": [ ],
        "option-data4": [ ],
        "option-data6": [ ],
        "next-server": "192.0.0.2",
        "server-hostname": "server-hostname.example.org",
        "boot-file-name": "bootfile.efi",
        "host-id": 0
    }
},
{
    "command": "cache-insert",
    "arguments": {
        "hw-address": "01:02:03:04:05:06",
        "subnet-id4": 0,
        "subnet-id6": 6,
        "ip-addresses": [ "2001:db8::cafe:babe" ],
        "prefixes": [ "2001:db8:dead:beef::/64" ],
        "hostname": "",
        "client-classes4": [ ],
        "client-classes6": [ ],
        "option-data4": [ ],
        "option-data6": [ ],
        "next-server": "0.0.0.0",
        "server-hostname": "",
        "boot-file-name": "",
        "host-id": 0
    }
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

cache-load¶

This command allows the contents of a file on disk to be loaded into an in-memory cache.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (host_cache hook library)

Description and examples: see cache-load command

Command syntax:

{
    "command": "cache-load",
    "arguments": "/tmp/kea-host-cache.json"
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

cache-remove¶

This command removes entries from the host cache. It takes parameters similar to the reservation-get command.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (host_cache hook library)

Description and examples: see cache-remove command

Command syntax:

{
    "command": "cache-remove",
    "arguments": {
        "ip-address": "192.0.2.1",
        "subnet-id": 123
    }
}

Another example that removes the IPv6 host identifier by DUID and specific subnet-id is:
{
    "command": "cache-remove",
    "arguments": {
        "duid": "00:01:ab:cd:f0:a1:c2:d3:e4",
        "subnet-id": 123
    }
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

cache-size¶

This command returns the number of entries in the host cache.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (host_cache hook library)

Description and examples: see cache-size command

Command syntax:

{
    "command": "cache-size"
}

Response syntax:

{
    "result": 0,
    "text": "123 entries.",
    "arguments": { "size": 123 }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

cache-write¶

This command instructs Kea to write its host cache content to disk.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (host_cache hook library)

Description and examples: see cache-write command

Command syntax:

{
    "command": "cache-write",
    "arguments": "/path/to/the/file.json"
}

The command takes one mandatory argument that specifies the filename path of a file to be written.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

class-add¶

This command adds a new class to the existing server configuration.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.5.0 (class_cmds hook library)

Description and examples: see class-add command

Command syntax:

{
    "command": "class-add",
    "arguments": {
        "client-classes": [ {
           "name": <name of the class>,
           "test": <test expression to be evaluated on incoming packets>,
           "option-data": [ <option values here> ],
           "option-def": [ <option definitions here> ],
           "next-server": <ipv4 address>,
           "server-hostname": <string>,
           "boot-file-name": <name of the boot file>
        } ]
    }
}

The next-server, server-hostname, and boot-file-name are DHCPv4-specific. Only one client class can be added with a single command.

Response syntax:

{
    "result": 0,
    "text": "Class '<class-name>' added."
}

The command is successful (result 0), unless the class name is a duplicate or another error occurs (result 1).

class-del¶

This command removes a client class from the server configuration.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.5.0 (class_cmds hook library)

Description and examples: see class-del command

Command syntax:

{
    "command": "class-del",
    "arguments": {
        "name": <name of the class>
    }
}

Response syntax:

{
    "result": 0,
    "text": "Class '<class-name>' deleted."
}

The command returns a result of 3 (empty) if the client class does not exist. If the client class exists, the returned result is 0 if the deletion was successful; the result is 1 if the deletion is unsuccessful.

class-get¶

This command returns detailed information about an existing client class.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.5.0 (class_cmds hook library)

Description and examples: see class-get command

Command syntax:

{
    "command": "class-get",
    "arguments": {
        "name": <name of the class>
    }
}

Response syntax:

{
    "result": 0,
    "text": "Class '<class-name>' definition returned",
    "arguments": {
        "client-classes": [
            {
                "name": <name of the class>,
                "only-if-required": <only if required boolean value>,
                "test": <test expression to be evaluated on incoming packets>,
                "option-data": [ <option values here> ],
                "option-def": [ <option definitions here> ],
                "next-server": <ipv4 address>,
                "server-hostname": <string>,
                "boot-file-name": <name of the boot file>
            }
        ]
    }
}

The returned information depends on the DHCP server type, i.e. some parameters are specific to the DHCPv4 server. Also, some parameters may not be returned if they are not set for the client class. If a class with the specified name does not exist, a result of 3 (empty) is returned. If the client class is found, the result of 0 is returned. If there is an error while processing the command, the result of 1 is returned.

class-list¶

This command retrieves a list of all client classes from the server configuration.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.5.0 (class_cmds hook library)

Description and examples: see class-list command

Command syntax:

{
    "command": "class-list"
}

This command includes no arguments.

Response syntax:

{
    "result": 0,
    "text": "'<number of>' classes found",
    "arguments": {
        "client-classes": [
            {
                "name": <first class name>
            },
            {
                "name": <second class name>
            }
        ]
    }
}

The returned list of classes merely contains their names. In order to retrieve full information about one of these classes, use The class-get Command. The returned result is 3 (empty) if no classes are found. If the command is processed successfully and the list of client classes is not empty, the result of 0 is returned. If there is an error while processing the command, the result of 1 is returned.

class-update¶

This command updates an existing client class in the server configuration.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.5.0 (class_cmds hook library)

Description and examples: see class-update command

Command syntax:

{
    "command": "class-update",
    "arguments": {
        "client-classes": [ {
           "name": <name of the class>,
           "test": <test expression to be evaluated on incoming packets>,
           "option-data": [ <option values here> ],
           "option-def": [ <option definitions here> ],
           "next-server": <ipv4 address>,
           "server-hostname": <string>,
           "boot-file-name": <name of the boot file>
        } ]
    }
}

The next-server, server-hostname, and boot-file-name are DHCPv4-specific. Only one client class can be updated with a single command.

Response syntax:

{
    "result": 0,
    "text": "Class '<class-name>' updated."
}

The command returns the result of 3 (empty) if the client class does not exist. If the client class exists, the returned result is 0 if the update was successful, or 1 if the update is unsuccessful.

config-get¶

This command retrieves the current configuration used by the server. The configuration is essentially the same as the contents of the configuration file, but includes additional changes made by other commands and due to parameters’ inheritance.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (built-in)

Description and examples: see config-get command

Command syntax:

{
    "command": "config-get"
}

This command takes no parameters.

Response syntax:

{
    "result": <integer>,
    "arguments": {
        <Dhcp4, Dhcp6, or Control-agent object>: <JSON configuration here>
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

config-reload¶

This command instructs Kea to reload the configuration file that was used previously.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (built-in)

Description and examples: see config-reload command

Command syntax:

{
    "command": "config-reload"
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

config-set¶

This command instructs the server to replace its current configuration with the new configuration supplied in the command’s arguments.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (built-in)

Description and examples: see config-set command

Command syntax:

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

In the example below, ‘<server>’ is the configuration element name for a given server such as “Dhcp4” or “Dhcp6”.

Response syntax:

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

or

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

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

config-test¶

This command instructs the server to check whether the new configuration supplied in the command’s arguments can be loaded.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (built-in)

Description and examples: see config-test command

Command syntax:

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

In the example below, <server> is the configuration element name for a given server such as “Dhcp4” or “Dhcp6”.

Response syntax:

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

or

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

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

config-write¶

This command instructs the Kea server to write its current configuration to a file on disk.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (built-in)

Description and examples: see config-write command

Command syntax:

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

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

dhcp-disable¶

This command globally disables the DHCP service.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (built-in)

Description and examples: see dhcp-disable command

Command syntax:

{
    "command": "dhcp-disable",
    "arguments": {
        "max-period": 20
    }
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

dhcp-enable¶

This command globally enables the DHCP service.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (built-in)

Description and examples: see dhcp-enable command

Command syntax:

{
    "command": "dhcp-enable"
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

ha-continue¶

This command resumes the operation of a paused HA state machine.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (high_availability hook library)

Description and examples: see ha-continue command

Command syntax:

{
    "command": "ha-continue"
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

ha-heartbeat¶

This command is sent internally by a Kea partner when operating in High-Availability (HA) mode. It retrieves the server’s HA state and clock value.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (high_availability hook library)

Description and examples: see ha-heartbeat command

Command syntax:

{
    "command": "ha-heartbeat"
    }

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

The response to this command is different from the typical command response. The response includes the server state (see Server States) plus the current clock value.

ha-scopes¶

This command modifies the scope that the server is responsible for serving when operating in High Availability (HA) mode.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (high_availability hook library)

Description and examples: see ha-scopes command

Command syntax:

{
    "command": "ha-scopes",
    "service": [ <service, typically 'dhcp4' or 'dhcp6'> ],
    "arguments": {
        "scopes": [ "HA_server1", "HA_server2" ]
    }
}

In the example below, the arguments configure the server to handle traffic from both the HA_server1 and HA_server2 scopes.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

ha-sync¶

This command instructs the server running in HA mode to synchronize its local lease database with the selected peer.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.4.0 (high_availability hook library)

Description and examples: see ha-sync command

Command syntax:

{
    "command": "ha-sync",
    "service": [ <service affected: 'dhcp4' or 'dhcp6'> ],
    "arguments": {
        "server-name": <name of the partner server>,
        "max-period": <integer, in seconds>
    }
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease4-add¶

This command administratively adds a new IPv4 lease.

Supported by: kea-dhcp4

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease4-add command

Command syntax:

{
    "command": "lease4-add",
    "arguments": {
        "ip-address": "192.0.2.202",
        "hw-address": "1a:1b:1c:1d:1e:1f"
    }
}

Note that Kea 1.4 requires an additional argument, subnet-ID, which is optional as of Kea 1.5. A number of other, more-detailed, optional arguments are also supported.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease4-del¶

This command deletes a lease from the lease database.

Supported by: kea-dhcp4

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease4-del command

Command syntax:

{
    "command": "lease4-del",
    "arguments": {
        "ip-address": "192.0.2.202"
    }
}

The lease to be deleted can be specified either by IP address or by identifier-type and identifier value. The currently supported identifiers are “hw-address” and “client-id”.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease4-get¶

This command queries the lease database and retrieves existing leases.

Supported by: kea-dhcp4

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease4-get command

Command syntax:

{
    "command": "lease4-get",
    "arguments": {
        "ip-address": "192.0.2.1"
    }
}

Response syntax:

{
  "arguments": {
    "client-id": "42:42:42:42:42:42:42:42",
    "cltt": 12345678,
    "fqdn-fwd": false,
    "fqdn-rev": true,
    "hostname": "myhost.example.com.",
    "hw-address": "08:08:08:08:08:08",
    "ip-address": "192.0.2.1",
    "state": 0,
    "subnet-id": 44,
    "valid-lft": 3600
  },
  "result": 0,
  "text": "IPv4 lease found."
}

lease4-get returns a result that indicates the outcome of the operation and lease details, if found. It has one of the following values: 0 (success), 1 (error), or 2 (empty).

lease4-get-all¶

This command retrieves all IPv4 leases or all leases for the specified set of subnets.

Supported by: kea-dhcp4

Availability: 1.4.0 (lease_cmds hook library)

Description and examples: see lease4-get-all command

Command syntax:

{
    "command": "lease4-get-all",
    "arguments": "subnets"
}

The lease4-get-all command may result in very large responses.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease4-update¶

This command updates existing leases.

Supported by: kea-dhcp4

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease4-update command

Command syntax:

{
  "command": "lease4-update",
  "arguments": {
    "ip-address": "192.0.2.1",
    "hostname": "newhostname.example.org",
    "hw-address": "1a:1b:1c:1d:1e:1f",
    "subnet-id": 44,
    "force-create": true
  }
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease4-wipe¶

This command removes all leases associated with a given subnet.

Supported by: kea-dhcp4

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease4-wipe command

Command syntax:

{
    "command": "lease4-wipe",
    "arguments": {
        "subnet-id": 44
    }
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease6-add¶

This command administratively creates a new lease.

Supported by: kea-dhcp6

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease6-add command

Command syntax:

{
    "command": "lease6-add",
    "arguments": {
        "subnet-id": 66,
        "ip-address": "2001:db8::3",
        "duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
        "iaid": 1234
    }
}

lease6-add can be also used to add leases for IPv6 prefixes.

Response syntax:

{ "result": 0, "text": "Lease added." }
or
{ "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" }

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease6-bulk-apply¶

This command creates, updates, or deletes multiple IPv6 leases in a single transaction. It communicates lease changes between HA peers, but may be used in all cases where it is desirable to apply multiple lease updates in a single transaction.

Supported by: kea-dhcp6

Availability: 1.6.0 (lease_cmds hook library)

Description and examples: see lease6-bulk-apply command

Command syntax:

{
    "command": "lease6-bulk-apply",
    "arguments": {
        "deleted-leases": [
            {
                "ip-address": "2001:db8:abcd::",
                "type": "IA_PD",
                ...
            },
            {
                "ip-address": "2001:db8:abcd::234",
                "type": "IA_NA",
                ...
            }
        ],
        "leases": [
            {
                "subnet-id": 66,
                "ip-address": "2001:db8:cafe::",
                "type": "IA_PD",
                ...
            },
            {
                "subnet-id": 66,
                "ip-address": "2001:db8:abcd::333",
                "type": "IA_NA",
                ...
            }
        ]
    }
}

If any of the leases is malformed, all changes are rolled back. If the leases are well-formed but the operation fails for one or more leases, these leases are listed in the response; however, the changes are preserved for all leases for which the operation was successful. The “deleted-leases” and “leases” are optional parameters, but one of them must be specified.

Response syntax:

{
    "result": 0,
    "text": "IPv6 leases bulk apply completed.",
    "arguments": {
        "failed-deleted-leases": [
            {
                "ip-address": "2001:db8:abcd::",
                "type": "IA_PD",
                "result": <control result>,
                "error-message": <error message>
            }
        ],
        "failed-leases": [
            {
                "ip-address": "2001:db8:cafe::",
                "type": "IA_PD",
                "result": <control result>,
                "error-message": <error message>
            }
        ]
    }
}

The “failed-deleted-leases” holds the list of leases which failed to delete; this includes leases which were not found in the database. The “failed-leases” includes the list of leases which failed to create or update. For each lease for which there was an error during processing, insertion into the database, etc., the result is set to 1. For each lease which was not deleted because the server did not find it in the database, the result of 3 is returned.

lease6-del¶

This command deletes a lease from the lease database.

Supported by: kea-dhcp6

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease6-del command

Command syntax:

{
    "command": "lease6-del",
    "arguments": {
        "ip-address": "192.0.2.202"
    }
}

lease6-del returns a result that indicates the outcome of the operation. It has one of the following values: 0 (success), 1 (error), or 3 (empty).

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease6-get¶

This command queries the lease database and retrieves existing leases.

Supported by: kea-dhcp6

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease6-get command

Command syntax:

{
  "command": "lease6-get",
  "arguments": {
    "ip-address": "2001:db8:1234:ab::",
    "type": "IA_PD"
  }
}

lease6-get returns a result that indicates the outcome of the operation and lease details, if found. It has one of the following values: 0 (success), 1 (error), or 2 (empty).

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease6-get-all¶

This command retrieves all IPv6 leases or all leases for the specified set of subnets.

Supported by: kea-dhcp6

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease6-get-all command

Command syntax:

{
    "command": "lease6-get-all",
    "arguments": {
        "subnets": [ 1, 2, 3, 4 ]
    }
}

Response syntax:

{
    "arguments": {
        "leases": [
            {
                "cltt": 12345678,
                "duid": "42:42:42:42:42:42:42:42",
                "fqdn-fwd": false,
                "fqdn-rev": true,
                "hostname": "myhost.example.com.",
                "hw-address": "08:08:08:08:08:08",
                "iaid": 1,
                "ip-address": "2001:db8:2::1",
                "preferred-lft": 500,
                "state": 0,
                "subnet-id": 44,
                "type": "IA_NA",
                "valid-lft": 3600
            },
            {
                "cltt": 12345678,
                "duid": "21:21:21:21:21:21:21:21",
                "fqdn-fwd": false,
                "fqdn-rev": true,
                "hostname": "",
                "iaid": 1,
                "ip-address": "2001:db8:0:0:2::",
                "preferred-lft": 500,
                "prefix-len": 80,
                "state": 0,
                "subnet-id": 44,
                "type": "IA_PD",
                "valid-lft": 3600
            }
        ]
    },
    "result": 0,
    "text": "2 IPv6 lease(s) found."
}

The lease6-get-all command may result in very large responses.

lease6-update¶

This command updates existing leases.

Supported by: kea-dhcp6

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease6-update command

Command syntax:

{
  "command": "lease6-update",
  "arguments": {
    "ip-address": "2001:db8::1",
    "duid": "88:88:88:88:88:88:88:88",
    "iaid": 7654321,
    "hostname": "newhostname.example.org",
    "subnet-id": 66,
    "force-create": false
  }
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

lease6-wipe¶

This command removes all leases associated with a given subnet.

Supported by: kea-dhcp6

Availability: 1.3.0 (lease_cmds hook library)

Description and examples: see lease6-wipe command

Command syntax:

{
  "command": "lease6-wipe",
  "arguments": {
    "subnet-id": 66
  }
}

Note: not all backends support this command.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

leases-reclaim¶

This command instructs the server to reclaim all expired leases immediately.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see leases-reclaim command

Command syntax:

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

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

libreload¶

This command first unloads and then reloads all currently loaded hooks libraries.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (built-in)

Description and examples: see libreload command

Command syntax:

{
    "command": "libreload",
    "arguments": { }
}

The server responds with 0, indicating success, or 1, indicating a failure.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

list-commands¶

This command retrieves a list of all commands supported by the server.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see list-commands command

Command syntax:

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

The server responds with a list of all supported commands.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network4-add¶

This command adds a new shared network.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network4-add command

Command syntax:

{
    "command": "network4-add",
    "arguments": {
        "shared-networks": [ {
            "name": "floor13",
            "subnet4": [
            {
                "id": 100,
                "pools": [ { "pool": "192.0.2.2-192.0.2.99" } ],
                "subnet": "192.0.2.0/24",
                "option-data": [
                    {
                        "name": "routers",
                        "data": "192.0.2.1"
                    }
                ]
            },
            {
                "id": 101,
                "pools": [ { "pool": "192.0.3.2-192.0.3.99" } ],
                "subnet": "192.0.3.0/24",
                "option-data": [
                    {
                        "name": "routers",
                        "data": "192.0.3.1"
                    }
                ]
            } ]
        } ]
    }
}

Response syntax:

{
    "arguments": {
        "shared-networks": [ { "name": "floor13" } ]
    },
    "result": 0,
    "text": "A new IPv4 shared network 'floor13' added"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network4-del¶

This command deletes existing shared networks.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network4-del command

Command syntax:

{
    "command": "network4-del",
    "arguments": {
        "name": "floor13"
    }
}

Response syntax:

{
    "arguments": {
        "shared-networks": [
            {
                "name": "floor13"
            }
        ]
    },
    "result": 0,
    "text": "IPv4 shared network 'floor13' deleted"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network4-get¶

This command retrieves detailed information about shared networks, including subnets that are currently part of a given network.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network4-get command

Command syntax:

{
    "command": "network4-get",
    "arguments": {
        "name": "floor13"
    }
}

Response syntax:

{
    "result": 0,
    "text": "Info about IPv4 shared network 'floor13' returned",
    "arguments": {
        "shared-networks": [
        {
            "match-client-id": true,
            "name": "floor13",
            "option-data": [ ],
            "rebind-timer": 90,
            "relay": {
                "ip-address": "0.0.0.0"
            },
            "renew-timer": 60,
            "reservation-mode": "all",
            "subnet4": [
                {
                    "subnet": "192.0.2.0/24",
                    "id": 5,
                    // many other subnet-specific details here
                },
                {
                    "subnet": "192.0.3.0/31",
                    "id": 6,
                    // many other subnet-specific details here
                }
            ],
            "valid-lifetime": 120
        }
        ]
    }
}

Note that the actual response contains many additional fields that are omitted here for clarity.

network4-list¶

This command retrieves the full list of currently configured shared networks.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network4-list command

Command syntax:

{
    "command": "network4-list"
}

Response syntax:

{
    "arguments": {
        "shared-networks": [
            { "name": "floor1" },
            { "name": "office" }
        ]
    },
    "result": 0,
    "text": "2 IPv4 network(s) found"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network4-subnet-add¶

This command adds existing subnets to existing shared networks.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network4-subnet-add command

Command syntax:

{
    "command": "network4-subnet-add",
    "arguments": {
        "name": "floor13",
        "id": 5
    }
}

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network4-subnet-del¶

This command removes a subnet that is part of an existing shared network and demotes it to a plain, stand-alone subnet.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network4-subnet-del command

Command syntax:

{
    "command": "network4-subnet-del",
    "arguments": {
        "name": "floor13",
        "id": 5
    }
 }

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network6-add¶

This command adds a new shared network.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network6-add command

Command syntax:

{
    "command": "network4-add",
    "arguments": {
        "shared-networks": [ {
            "name": "floor13",
            "subnet4": [
            {
                "id": 100,
                "pools": [ { "pool": "192.0.2.2-192.0.2.99" } ],
                "subnet": "192.0.2.0/24",
                "option-data": [
                    {
                        "name": "routers",
                        "data": "192.0.2.1"
                    }
                ]
            },
            {
                "id": 101,
                "pools": [ { "pool": "192.0.3.2-192.0.3.99" } ],
                "subnet": "192.0.3.0/24",
                "option-data": [
                    {
                        "name": "routers",
                        "data": "192.0.3.1"
                    }
                ]
            } ]
        } ]
    }
}

The network6-add command uses the same syntax as network4-add for both the query and the response. However, there are some parameters that are IPv4-only (e.g. match-client-id) and some that are IPv6-only (e.g. interface-id).

Response syntax:

{
    "arguments": {
        "shared-networks": [ { "name": "floor13" } ]
    },
    "result": 0,
    "text": "A new IPv4 shared network 'floor13' added"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network6-del¶

This command deletes existing shared networks.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network6-del command

Command syntax:

{
    "command": "network4-del",
    "arguments": {
        "name": "floor13"
    }
}

The network6-del command uses exactly the same syntax as network4-del for both the query and the response.

Response syntax:

{
    "command": "network4-del",
    "arguments": {
        "name": "floor13",
        "subnets-action": "delete"
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network6-get¶

The network6-get command retrieves detailed information about shared networks, including subnets that are currently part of a given network.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network6-get command

Command syntax:

{
    "command": "network4-get",
    "arguments": {
        "name": "floor13"
    }
}

Response syntax:

{
    "result": 0,
    "text": "Info about IPv4 shared network 'floor13' returned",
    "arguments": {
        "shared-networks": [
        {
            "match-client-id": true,
            "name": "floor13",
            "option-data": [ ],
            "rebind-timer": 90,
            "relay": {
                "ip-address": "0.0.0.0"
            },
            "renew-timer": 60,
            "reservation-mode": "all",
            "subnet4": [
                {
                    "subnet": "192.0.2.0/24",
                    "id": 5,
                    // many other subnet specific details here
                },
                {
                    "subnet": "192.0.3.0/31",
                    "id": 6,
                    // many other subnet specific details here
                }
            ],
            "valid-lifetime": 120
        }
        ]
    }
}

Note that the actual response contains many additional fields that are omitted here for clarity.

network6-list¶

This command retrieves the full list of currently configured shared networks.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network6-list command

Command syntax:

{
    "command": "network4-list"
}

The network6-list command uses exactly the same syntax as network4-list for both the query and the response.

Response syntax:

{
    "arguments": {
        "shared-networks": [
            { "name": "floor1" },
            { "name": "office" }
        ]
    },
    "result": 0,
    "text": "2 IPv4 network(s) found"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network6-subnet-add¶

This command adds existing subnets to existing shared networks.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network6-subnet-add command

Command syntax:

{
    "command": "network4-subnet-add",
    "arguments": {
        "name": "floor13",
        "id": 5
    }
}

The network6-subnet-add command uses exactly the same syntax as network4-subnet-add for both the query and the response.

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

network6-subnet-del¶

This command removes a subnet that is part of an existing shared network and demotes it to a plain, stand-alone subnet.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see network6-subnet-del command

Command syntax:

{
    "command": "network4-subnet-del",
    "arguments": {
        "name": "floor13",
        "id": 5
    }
 }

The network6-subnet-del command uses exactly the same syntax as network4-subnet-del for both the query and the response.

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-global-parameter4-del¶

This command deletes a global DHCPv4 parameter from the configuration database. The server uses the value specified in the configuration file, or a default value if the parameter is not specified, after deleting the parameter from the database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-global-parameter4-del command

Command syntax:

{
    "command": "remote-global-parameter4-del",
    "arguments": {
        "parameters": [ <parameter name as string> ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command carries the list including exactly one name of the parameter to be deleted. The server-tags list is mandatory and it must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 global parameter(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-global-parameter4-get¶

This command fetches the selected global parameter for the server from the specified database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-global-parameter4-get command

Command syntax:

{
    "command": "remote-global-parameter4-get",
    "arguments": {
        "parameters": [ <parameter name as string> ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command carries a list including exactly one name of the parameter to be fetched. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed; it fetches the global parameter value shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 global parameter found.",
    "arguments": {
        "parameters": {
            <parameter name>: <parameter value>,
            "metadata": {
                "server-tags": [ <server tag> ]
            }
        },
        "count": 1
    }
}

The returned response contains a map with a global parameter name/value pair. The value may be a JSON string, integer, real, or boolean. The metadata is included and provides database-specific information associated with the returned object. If the “all” server tag is specified, the command attempts to fetch the global parameter value associated with all servers. If the explicit server tag is specified, the command fetches the value associated with the given server. If the server-specific value does not exist, the remote-global-parameter4-get command fetches the value associated with all servers.

remote-global-parameter4-get-all¶

This command fetches all global parameters for the server from the specified database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-global-parameter4-get-all command

Command syntax:

{
    "command": "remote-global-parameter4-get-all",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The special server tag “all” is allowed; it fetches the global parameters shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 global parameters found.",
    "arguments": {
        "parameters": [
            {
                <first parameter name>: <first parameter value>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            },
            {
                <second parameter name>: <second parameter value>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains a list of maps. Each map contains a global parameter name/value pair. The value may be a JSON string, integer, real, or boolean. The metadata is appended to each parameter and provides database-specific information associated with the returned objects. If the server tag “all” is included in the command, the response contains the global parameters shared among all servers. It excludes server-specific global parameters. If an explicit server tag is included in the command, the response contains all global parameters directly associated with the given server, and the global parameters associated with all servers when server-specific values are not present.

remote-global-parameter4-set¶

This command creates or updates one or more global parameters in the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-global-parameter4-set command

Command syntax:

{
    "command": "remote-global-parameter4-set",
    "arguments": {
        "parameters": {
            <first parameter name>: <first parameter value>,
            <second parameter name>: <second parameter value>
        },
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command carries multiple global parameters with their values. Care should be taken when specifying more than one parameter; in some cases, only a subset of the parameters may be successfully stored in the database and other parameters may fail to be stored. In such cases the remote-global-parameter4-get-all command may be useful to verify the contents of the database after the update. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed; it associates the specified parameters with all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 global parameter(s) successfully set.",
    "arguments": {
        "parameters": {
            <first parameter name>: <first parameter value>,
            <second parameter name>: <second parameter value>
        },
        "count": 2
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-global-parameter6-del¶

This command deletes a global DHCPv6 parameter from the configuration database. The server uses the value specified in the configuration file, or a default value if the parameter is not specified in the configuration file, after deleting the parameter from the database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-global-parameter6-del command

Command syntax:

{
    "command": "remote-global-parameter6-del",
    "arguments": {
        "parameters": [ <parameter name as string> ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command carries the list including exactly one name of the parameter to be deleted. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 global parameter(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-global-parameter6-get¶

This command fetches the selected global parameter for the server from the specified database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-global-parameter6-get command

Command syntax:

{
    "command": "remote-global-parameter6-get",
    "arguments": {
        "parameters": [ <parameter name as string> ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command carries a list including exactly one name of the parameter to be fetched. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed; it fetches the global parameter value shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 global parameter found.",
    "arguments": {
        "parameters": {
            <parameter name>: <parameter value>,
            "metadata": {
                "server-tags": [ <server tag> ]
            }
        },
        "count": 1
    }
}

The returned response contains a map with a global parameter name/value pair. The value may be a JSON string, integer, real, or boolean. The metadata is included and provides database-specific information associated with the returned object. If the “all” server tag is specified, the command attempts to fetch the global parameter value associated with all servers. If the explicit server tag is specified, the command fetches the value associated with the given server. If the server-specific value does not exist, the remote-global-parameter6-get fetches the value associated with all servers.

remote-global-parameter6-get-all¶

This command fetches all global parameters for the server from the specified database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-global-parameter6-get-all command

Command syntax:

{
    "command": "remote-global-parameter6-get-all",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The special server tag “all” is allowed; it fetches the global parameters shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 global parameters found.",
    "arguments": {
        "parameters": [
            {
                <first parameter name>: <first parameter value>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            },
            {
                <second parameter name>: <second parameter value>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains a list of maps. Each map contains a global parameter name/value pair. The value may be a JSON string, integer, real, or boolean. The metadata is appended to each parameter and provides database-specific information associated with the returned objects. If the server tag “all” is included in the command, the response contains the global parameters shared among all servers. It excludes server-specific global parameters. If an explicit server tag is included in the command, the response contains all global parameters directly associated with the given server, and the global parameters associated with all servers when server-specific values are not present.

remote-global-parameter6-set¶

This command creates or updates one or more global parameters in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-global-parameter6-set command

Command syntax:

{
    "command": "remote-global-parameter6-set",
    "arguments": {
        "parameters": {
            <first parameter name>: <first parameter value>,
            <second parameter name>: <second parameter value>
        },
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command carries multiple global parameters with their values. Care should be taken when specifying more than one parameter; in some cases, only a subset of the parameters may be successfully stored in the database and other parameters may fail to be stored. In such cases the remote-global-parameter6-get-all command may be useful to verify the contents of the database after the update. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed; it associates the specified parameters with all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 global parameter(s) successfully set.",
    "arguments": {
        "parameters": {
            <first parameter name>: <first parameter value>,
            <second parameter name>: <second parameter value>
        },
        "count": 2
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-network4-del¶

This command deletes an IPv4 shared network from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-network4-del command

Command syntax:

{
    "command": "remote-network4-del",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>
            }
        ],
        "subnets-action": <'keep' | 'delete'>,
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one name of the shared network to be deleted. The subnets-action parameter denotes whether the subnets in this shared network should be deleted. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "1 IPv4 shared network(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-network4-get¶

This command fetches the selected IPv4 shared network for the server from the specified database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-network4-get command

Command syntax:

{
    "command": "remote-network4-get",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>
            }
        ],
        "subnets-include": <'full' | 'no'>,
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one name of the shared network to be returned. The subnets-include optional parameter allows for specifying whether the subnets belonging to the shared network should also be returned. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "IPv4 shared network found.",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>,
                "metadata": {
                    "server-tags": [ <first server tag>, <second server tag>, ... ]
                },
                <the rest of the shared network information, potentially including subnets>
            }
        ],
        "count": 1
    }
}

If the subnets are returned with the shared network, they are carried in the subnet4 list within the shared network definition. The metadata is included in the returned shared network definition and provides the database-specific information associated with the returned object.

remote-network4-list¶

This command fetches a list of all IPv4 shared networks from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-network4-list command

Command syntax:

{
    "command": "remote-network4-list",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <first server tag>, <second server tag>, ... ]
    }
}

The server-tags list is required for this command, and must not be empty. It may either contain one or multiple server tags as strings, or a single null value.

Response syntax:

{
    "result": 0,
    "text": "2 IPv4 shared network(s) found.",
    "arguments": {
        "shared-networks": [
            {
                "name": <first shared network name>,
                "metadata": {
                    "server-tags": [ <first server tag>, <second server tag>, ... ]
                }
            },
            {
                "name": <second shared network name>,
                "metadata": {
                    "server-tags": [ <first server tag>, ... ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains the list of maps. Each map contains the shared network name and the metadata, which provides database-specific information associated with the shared network. The returned list does not contain full definitions of the shared networks; use remote-network4-get to fetch the full information about the selected shared networks. If the command includes explicit server tags as strings (including the special server tag “all”), the list contains all shared networks which are associated with any of the specified tags. A network is returned even if it is associated with multiple servers and only one of the specified tags matches. If the command includes the null value in the server-tags list, the response contains all shared networks which are assigned to no servers (unassigned).

remote-network4-set¶

This command creates or replaces an IPv4 shared network in the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-network4-set command

Command syntax:

{
    "command": "remote-network4-set",
    "arguments": {
        "shared-networks": [
            {
                <shared network specification excluding subnets list>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <first server tag>, <second server tag>, ... ]
    }
}

The provided list must contain exactly one shared network specification, and must not contain subnets (the “subnet4” parameter). The subnets are added to the shared network using the remote-subnet4-set command. The server-tags list is mandatory and must contain one or more server tags as strings to explicitly associate the shared network with one or more user-defined servers. It may include the special server tag “all” to associate the network with all servers.

Response syntax:

{
    "result": 0,
    "text": "IPv4 shared network successfully set."
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-network6-del¶

This command deletes an IPv6 shared network from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-network6-del command

Command syntax:

{
    "command": "remote-network6-del",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>
            }
        ],
        "subnets-action": <'keep' | 'delete'>,
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one name of the shared network to be deleted. The subnets-action parameter indicates whether the subnets in this shared network should be deleted. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "1 IPv6 shared network(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-network6-get¶

This command fetches the selected IPv6 shared network for the server from the specified database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-network6-get command

Command syntax:

{
    "command": "remote-network6-get",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>
            }
        ],
        "subnets-include": <'full' | 'no'>,
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one name of the shared network to be returned. The subnets-include optional parameter allows for specifying whether the subnets belonging to the shared network should also be returned. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "IPv6 shared network found.",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>,
                "metadata": {
                    "server-tags": [ <first server tag>, <second server tag>, ... ]
                },
                <the rest of the shared network information, potentially including subnets>
            }
        ],
        "count": 1
    }
}

If the subnets are returned with the shared network, they are carried in the subnet6 list within the shared network definition. The metadata is included in the returned shared network definition and provides the database-specific information associated with the returned object.

remote-network6-list¶

This command fetches a list of all IPv6 shared networks from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-network6-list command

Command syntax:

{
    "command": "remote-network6-list",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <first server tag>, <second server tag>, ... ]
    }
}

The server-tags list is required for this command, and must not be empty. It may either contain one or multiple server tags as strings, or a single null value.

Response syntax:

{
    "result": 0,
    "text": "2 IPv6 shared network(s) found.",
    "arguments": {
        "shared-networks": [
            {
                "name": <first shared network name>,
                "metadata": {
                    "server-tags": [ <first server tag>, <second server tag>, ... ]
                }
            },
            {
                "name": <second shared network name>,
                "metadata": {
                    "server-tags": [ <first server tag>, ... ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains the list of maps. Each map contains the shared network name and the metadata, which provides database-specific information associated with the shared network. The returned list does not contain full definitions of the shared networks; use remote-network6-get to fetch the full information about the selected shared networks. If the command includes explicit server tags as strings (including the special server tag “all”), the list contains all shared networks which are associated with any of the specified tags. A network is returned even if it is associated with multiple servers and only one of the specified tags matches. If the command includes the null value in the server-tags list, the response contains all shared networks which are assigned to no servers (unassigned).

remote-network6-set¶

This command creates or replaces an IPv6 shared network in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-network6-set command

Command syntax:

{
    "command": "remote-network6-set",
    "arguments": {
        "shared-networks": [
            {
                <shared network specification excluding subnets list>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <first server tag>, <second server tag>, ... ]
    }
}

The provided list must contain exactly one shared network specification, and must not contain subnets (the “subnet6” parameter). The subnets are added to the shared network using the remote-subnet6-set command. The server-tags list is mandatory and must contain one or more server tags as strings to explicitly associate the shared network with one or more user-defined servers. It may include the special server tag “all” to associate the network with all servers.

Response syntax:

{
    "result": 0,
    "text": "IPv6 shared network successfully set."
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option-def4-del¶

This command deletes a DHCPv4 option definition from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option-def4-del command

Command syntax:

{
    "command": "remote-option-def4-del",
    "arguments": {
        "option-defs": [ {
            "code": <option code>,
            "space": <option space>
        } ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command includes a list with exactly one option definition specification, comprising an option name and code. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv4 option definition(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option-def4-get¶

This command fetches a DHCPv4 option definition from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option-def4-get command

Command syntax:

{
    "command": "remote-option-def4-get",
    "arguments": {
        "option-defs": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The desired option definition is identified by the pair of option code/space values. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed, to fetch the option definition instance shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 option definition found.",
    "arguments": {
        "option-defs": [
            {
                <option definition>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ],
        "count": 1
    }
}

The metadata is included and provides database-specific information associated with the returned object. If the “all” server tag is specified, the command attempts to fetch the option definition associated with all servers. If the explicit server tag is specified, the command fetches the option definition associated with the given server. If the server-specific option definition does not exist, the remote-option-def4-get command fetches the option definition associated with all servers.

remote-option-def4-get-all¶

This command fetches all DHCPv4 option definitions from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option-def4-get-all command

Command syntax:

{
    "command": "remote-option-def4-get-all",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The special server tag “all” is allowed, to fetch the option definitions shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "2 DHCPv4 option definition(s) found.",
    "arguments": {
        "option-defs": [
            {
                <first option definition>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            },
            {
                <second option definition>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains a list of maps. Each map contains an option definition specification and the metadata, including database-specific information associated with the returned objects. If the server tag “all” is included in the command, the response contains the option definitions shared among all servers. It excludes server-specific option definitions. If an explicit server tag is included in the command, the response contains all option definitions directly associated with the given server, and the option definitions associated with all servers when server-specific option definitions are not present.

remote-option-def4-set¶

This command creates or replaces a DHCPv4 option definition in the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option-def4-set command

Command syntax:

{
    "command": "remote-option-def4-set",
    "arguments": {
        "option-defs": [
            {
                <option definition specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The provided list must contain exactly one option definition specification. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed; it associates the specified option definition with all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 option definition set."
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option-def6-del¶

This command deletes a DHCPv6 option definition from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option-def6-del command

Command syntax:

{
    "command": "remote-option-def6-del",
    "arguments": {
        "option-defs": [ {
            "code": <option code>,
            "space": <option space>
        } ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command includes a list with exactly one option definition specification, comprising an option name and code. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv6 option definition(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option-def6-get¶

This command fetches a DHCPv6 option definition from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option-def6-get command

Command syntax:

{
    "command": "remote-option-def6-get",
    "arguments": {
        "option-defs": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The desired option definition is identified by the pair of option code/space values. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed, to fetch the option definition instance shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 option definition found.",
    "arguments": {
        "option-defs": [
            {
                <option definition>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ],
        "count": 1
    }
}

The metadata is included and provides database-specific information associated with the returned object. If the “all” server tag is specified, the command fetches the option definition associated with all servers. If the explicit server tag is specified, the command fetches the option definition associated with the given server. If the server-specific option definition does not exist, the remote-option-def6-get command fetches the option definition associated with all servers.

remote-option-def6-get-all¶

This command fetches all DHCPv6 option definitions from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option-def6-get-all command

Command syntax:

{
    "command": "remote-option-def6-get-all",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The special server tag “all” is allowed, to fetch the option definitions shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "2 DHCPv6 option definition(s) found.",
    "arguments": {
        "option-defs": [
            {
                <first option definition>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            },
            {
                <second option definition>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains a list of maps. Each map contains an option definition specification and the metadata, including database-specific information associated with the returned objects. If the server tag “all” is included in the command, the response contains the option definitions shared among all servers. It excludes server-specific option definitions. If an explicit server tag is included in the command, the response contains all option definitions directly associated with the given server, and the option definitions associated with all servers when server-specific option definitions are not present.

remote-option-def6-set¶

This command creates or replaces a DHCPv6 option definition in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option-def6-set command

Command syntax:

{
    "command": "remote-option-def6-set",
    "arguments": {
        "option-defs": [
            {
                <option definition specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The provided list must contain exactly one option definition specification. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed; it associates the specified option definition with all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 option definition set."
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option4-global-del¶

This command deletes a DHCPv4 global option from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-global-del command

Command syntax:

{
    "command": "remote-option4-global-del",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command includes a list with exactly one option specification, comprising an option name and code. Specifying an empty list, a value of null, or multiple server tags will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv4 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option4-global-get¶

This command fetches a global DHCPv4 option for the server from the specified database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-global-get command

Command syntax:

{
    "command": "remote-option4-global-get",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The option is identified by the pair of option code/space values. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed, to fetch the global option instance shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 option is found.",
    "arguments": {
        "options": [
            {
                <option information>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ]
    }
}

The metadata is included and provides database specific information associated with the returned object. If the “all” server tag is specified, the command fetches the global option associated with all servers. If the explicit server tag is specified, the command fetches the global option associated with the given server. If the server specific option does not exist, it fetches the option associated with all servers.

remote-option4-global-get-all¶

This command fetches all DHCPv4 global options for the server from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-global-get-all command

Command syntax:

{
    "command": "remote-option4-global-get-all",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The special server tag “all” is allowed, to fetch the global options shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "2 DHCPv4 option(s) found.",
    "arguments": {
        "options": [
            {
                <first option specification>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            },
            {
                <second option specification>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains a list of maps. Each map contains a global option specification and the metadata, including database-specific information associated with the returned object. If the server tag “all” is included in the command, the response contains the global options shared among all servers. It excludes server-specific global options. If an explicit server tag is included in the command, the response contains all global options directly associated with the given server, and the options associated with all servers when server-specific options are not present.

remote-option4-global-set¶

This command creates or replaces a DHCPv4 global option in the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-global-set command

Command syntax:

{
    "command": "remote-option4-global-set",
    "arguments": {
        "options": [
            {
                <global option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The provided list must contain exactly one option specification. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed; it associates the specified option with all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 option set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option4-network-del¶

This command deletes a DHCPv4 option from a shared network from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-network-del command

Command syntax:

{
    "command": "remote-option4-network-del",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>
            }
        ],
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly one name of the shared network and exactly one option specification, comprising an option name and code. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv4 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option4-network-set¶

This command creates or replaces a DHCPv4 option in a shared network in the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-network-set command

Command syntax:

{
    "command": "remote-option4-network-set",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>
            }
        ],
        "options": [
            {
                <shared network option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

The provided lists must contain exactly one name of the shared network and one option specification. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 option successfully set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option4-pool-del¶

This command deletes a DHCPv4 option from an address pool from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-pool-del command

Command syntax:

{
    "command": "remote-option4-pool-del",
    "arguments": {
        "pools": [
            {
                "pool": <pool range or prefix>
            }
        ],
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly one address pool specification and exactly one option specification comprising an option space name and code. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv4 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option4-pool-set¶

This command creates or replaces a DHCPv4 option in an address pool in the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-pool-set command

Command syntax:

{
    "command": "remote-option4-pool-set",
    "arguments": {
        "pools": [
            {
                "pool": <pool range or prefix>
            }
        ],
        "options": [
            {
                <address pool option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly address pool specification and exactly one option specification. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 option successfully set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option4-subnet-del¶

This command deletes a DHCPv4 option from a subnet from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-subnet-del command

Command syntax:

{
    "command": "remote-option4-subnet-del",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>
            }
        ],
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly one ID of the subnet and exactly one option specification, comprising an option name and code. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv4 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option4-subnet-set¶

This command creates or replaces a DHCPv4 option in a subnet in the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option4-subnet-set command

Command syntax:

{
    "command": "remote-option4-subnet-set",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>
            }
        ],
        "options": [
            {
                <subnet option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

The provided lists must contain exactly one ID of the subnet and one option specification. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 option successfully set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-global-del¶

This command deletes a DHCPv6 global option from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-global-del command

Command syntax:

{
    "command": "remote-option6-global-del",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

This command includes a list with exactly one option specification, comprising an option name and code. Specifying an empty list, a value of null, or multiple server tags will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv6 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-global-get¶

This command fetches a global DHCPv6 option for the server from the specified database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-global-get command

Command syntax:

{
    "command": "remote-option6-global-get",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The option is identified by the pair of option code/space values. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed, to fetch the global option instance shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 option is found.",
    "arguments": {
        "options": [
            {
                <option information>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ]
    }
}

The metadata is included and provides database-specific information associated with the returned object. If the “all” server tag is specified, the command attempts to fetch the global option associated with all servers. If the explicit server tag is specified, the command will fetch the global option associated with the given server. If the server-specific option does not exist, it fetches the option associated with all servers.

remote-option6-global-get-all¶

This command fetches all DHCPv6 global options for the server from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-global-get-all command

Command syntax:

{
    "command": "remote-option6-global-get-all",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The special server tag “all” is allowed, to fetch the global options shared by all servers.

Response syntax:

{
    "result": 0,
    "text": "2 DHCPv6 option(s) found.",
    "arguments": {
        "options": [
            {
                <first option specification>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            },
            {
                <second option specification>,
                "metadata": {
                    "server-tags": [ <server tag> ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains a list of maps. Each map contains a global option specification and the metadata, including database-specific information associated with the returned object. If the server tag “all” is included in the command, the response contains the global options shared between all servers. It excludes server-specific global options. If an explicit server tag is included in the command, the response contains all global options directly associated with the given server, and the options associated with all servers when server-specific options are not present.

remote-option6-global-set¶

This command creates or replaces a DHCPv6 global option in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-global-set command

Command syntax:

{
    "command": "remote-option6-global-set",
    "arguments": {
        "options": [
            {
                <global option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <single server tag as string> ]
    }
}

The provided list must contain exactly one option specification. The server-tags list is mandatory and must contain exactly one server tag. Specifying an empty list, a value of null, or multiple server tags will result in an error. The server tag “all” is allowed; it associates the specified option with all servers.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 option set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-network-del¶

This command deletes a DHCPv6 option from a shared network from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-network-del command

Command syntax:

{
    "command": "remote-option6-network-del",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>
            }
        ],
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly one name of the shared network and exactly one option specification, comprising an option name and code. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv6 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-network-set¶

This command creates or replaces a DHCPv6 option in a shared network in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-network-set command

Command syntax:

{
    "command": "remote-option6-network-set",
    "arguments": {
        "shared-networks": [
            {
                "name": <shared network name>
            }
        ],
        "options": [
            {
                <shared network option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

The provided lists must contain exactly one name of the shared network and one option specification. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 option successfully set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-pd-pool-del¶

This command deletes a DHCPv6 option from a prefix delegation pool from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-pd-pool-del command

Command syntax:

{
    "command": "remote-option6-pd-pool-del",
    "arguments": {
        "pd-pools": [
            {
                "prefix": <pool prefix (address part)>
                "prefix-len": <pool prefix (length part)>
            }
        ],
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly one prefix delegation pool specification and exactly one option specification, comprising an option name and code. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv6 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-pd-pool-set¶

This command creates or replaces a DHCPv6 option in a prefix delegation pool in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-pd-pool-set command

Command syntax:

{
    "command": "remote-option6-pd-pool-set",
    "arguments": {
        "pd-pools": [
            {
                "prefix": <pool prefix (address part)>
                "prefix-len": <pool prefix (length part)>
            }
        ],
        "options": [
            {
                <prefix delegation pool option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly one prefix delegation pool specification and exactly one option specification. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 option successfully set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-pool-del¶

This command deletes a DHCPv6 option from an address pool from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-pool-del command

Command syntax:

{
    "command": "remote-option6-pool-del",
    "arguments": {
        "pools": [
            {
                "pool": <pool range or prefix>
            }
        ],
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly one address pool specification and exactly one option specification, comprising an option name and code. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv6 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-pool-set¶

This command creates or replaces a DHCPv6 option in an address pool in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-pool-set command

Command syntax:

{
    "command": "remote-option6-pool-set",
    "arguments": {
        "pools": [
            {
                "pool": <pool range or prefix>
            }
        ],
        "options": [
            {
                <address pool option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly address pool specification and exactly one option specification. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 option successfully set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-subnet-del¶

This command deletes a DHCPv6 option from a subnet from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-subnet-del command

Command syntax:

{
    "command": "remote-option6-subnet-del",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>
            }
        ],
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes two lists with exactly one ID of the subnet and exactly one option specification, comprising an option name and code. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv6 option(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-option6-subnet-set¶

This command creates or replaces a DHCPv6 option in a subnet in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-option6-subnet-set command

Command syntax:

{
    "command": "remote-option6-subnet-set",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>
            }
        ],
        "options": [
            {
                <subnet option specification>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

The provided lists must contain exactly one ID of the subnet and one option specification. Specifying an empty list, a value of null, or a server tag will result in an error.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 option successfully set.",
    "arguments": {
        "options": [
            {
                "code": <option code>,
                "space": <option space>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-server4-del¶

This command deletes information about a DHCPv4 server from the configuration database. Any configuration explicitly associated with the deleted server is automatically disassociated. In addition, configuration elements not shareable with other servers (e.g. global DHCP parameters) are deleted. Shareable configuration elements (e.g. subnets, shared networks) are not deleted as they may be used by other servers.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-server4-del command

Command syntax:

{
    "command": "remote-server4-del",
    "arguments": {
        "servers": [
            {
                "server-tag": <server name>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command carries the list including exactly one map with the tag of the server to be deleted.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv4 server(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-server4-get¶

This command fetches information about the DHCPv4 server, such as the server tag and description.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-server4-get command

Command syntax:

{
    "command": "remote-server4-get",
    "arguments": {
        "servers": [
            {
                "server-tag": <server tag>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command carries the list including exactly one map with the tag of the server to be fetched.

Response syntax:

{
    "result": 0,
    "text": "DHCP server 'server tag' found.",
    "arguments": {
        "servers": [
            {
                "server-tag": <server tag>,
                "description": <server description>
            }
        ],
        "count": 1
    }
}

The server tag is the unique identifier of the server, used to associate the configuration elements in the database with the particular server instance. The returned server description is specified by the user when setting the server information.

remote-server4-get-all¶

This command fetches information about all DHCPv4 servers specified by the user.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-server4-get-all command

Command syntax:

{
    "command": "remote-server4-get-all",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command contains no arguments besides the optional remote.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 servers found.",
    "arguments": {
        "servers": [
            {
                "server-tag": <first server tag>,
                "description": <first server description>
            },
            {
                "server-tag": <second server tag>,
                "description": <second server description>
            }
        ],
        "count": 2
    }
}

The returned response contain a list of maps. Each map contains a server tag uniquely identifying a server, and the user-defined description of the server. The Kea Configuration Backend uses the keyword all to associate parts of the configuration with all servers. Internally, it creates the logical server all for this purpose. However, this logical server is not returned as a result of the remote-server4-get-all command; only the user-defined servers are returned.

remote-server4-set¶

This command creates or replaces information about the DHCPv4 server in the database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-server4-set command

Command syntax:

{
    "command": "remote-server4-set",
    "arguments": {
        "servers": [
            {
                "server-tag": <server tag>,
                "description": <server description>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

The provided list must contain exactly one server specification. The server-tag must be unique across all servers within the configuration database. The description is the arbitrary text describing the server, its location within the network, etc.

Response syntax:

{
    "result": 0,
    "text": "DHCPv4 server successfully set.",
    "arguments": {
        "servers": [
            {
                "server-tag": <server tag>,
                "description": <server description>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-server6-del¶

This command deletes information about a DHCPv6 server from the configuration database. Any configuration explicitly associated with the deleted server is automatically disassociated. In addition, configuration elements not shareable with other servers (e.g. global DHCP parameters) are deleted. Shareable configuration elements (e.g. subnets, shared networks) are not deleted as they may be used by other servers.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-server6-del command

Command syntax:

{
    "command": "remote-server6-del",
    "arguments": {
        "servers": [
            {
                "server-tag": <server name>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command carries the list including exactly one map with the tag of the server to be deleted.

Response syntax:

{
    "result": 0,
    "text": "1 DHCPv6 server(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-server6-get¶

This command fetches information about the DHCPv6 server, such as the server tag and description.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-server6-get command

Command syntax:

{
    "command": "remote-server6-get",
    "arguments": {
        "servers": [
            {
                "server-tag": <server tag>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command carries the list including exactly one map with the tag of the server to be fetched.

Response syntax:

{
    "result": 0,
    "text": "DHCP server 'server tag' found.",
    "arguments": {
        "servers": [
            {
                "server-tag": <server tag>,
                "description": <server description>
            }
        ],
        "count": 1
    }
}

The server tag is the unique identifier of the server, used to associate the configuration elements in the database with the particular server instance. The returned server description is specified by the user when setting the server information.

remote-server6-get-all¶

This command fetches information about all DHCPv6 servers specified by the user.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-server6-get-all command

Command syntax:

{
    "command": "remote-server6-get-all",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command contains no arguments besides the optional remote.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 servers found.",
    "arguments": {
        "servers": [
            {
                "server-tag": <first server tag>,
                "description": <first server description>
            },
            {
                "server-tag": <second server tag>,
                "description": <second server description>
            }
        ],
        "count": 2
    }
}

The returned response contain a list of maps. Each map contains a server tag uniquely identifying a server, and the user-defined description of the server. The Kea Configuration Backend uses the keyword all to associate parts of the configuration with all servers. Internally, it creates the logical server all for this purpose. However, this logical server is not returned as a result of the remote-server6-get-all command; only the user-defined servers are returned.

remote-server6-set¶

This command creates or replaces information about the DHCPv6 server in the database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-server6-set command

Command syntax:

{
    "command": "remote-server6-set",
    "arguments": {
        "servers": [
            {
                "server-tag": <server tag>,
                "description": <server description>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

The provided list must contain exactly one server specification. The server-tag must be unique across all servers within the configuration database. The description is the arbitrary text describing the server, its location within the network, etc.

Response syntax:

{
    "result": 0,
    "text": "DHCPv6 server successfully set.",
    "arguments": {
        "servers": [
            {
                "server-tag": <server tag>,
                "description": <server description>
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-subnet4-del-by-id¶

This command deletes an IPv4 subnet by ID from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet4-del-by-id command

Command syntax:

{
    "command": "remote-subnet4-del-by-id",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one ID of the subnet to be deleted. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "1 IPv4 subnet(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-subnet4-del-by-prefix¶

This command deletes an IPv4 subnet by prefix from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet4-del-by-prefix command

Command syntax:

{
    "command": "remote-subnet4-del-by-prefix",
    "arguments": {
        "subnets": [
            {
                "subnet": <subnet prefix>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one prefix of the subnet to be deleted. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "1 IPv4 subnet(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-subnet4-get-by-id¶

This command fetches the selected IPv4 subnet by ID from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet4-get-by-id command

Command syntax:

{
    "command": "remote-subnet4-get-by-id",
    "arguments": {
        "subnets": [ {
            "id": <subnet identifier>
        } ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one ID of the subnet to be returned. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet found.",
    "arguments": {
        "subnets": [ {
            "id": <subnet identifier>,
            "subnet": <subnet prefix>,
            "shared-network-name": <shared network name> | null,
            "metadata": {
                "server-tags": [ <first server tag>, <second server tag>, ... ]
            },
            <the rest of the subnet specification here>
        } ],
        "count": 1
    }
}

If the shared network name is null, it means that the returned subnet does not belong to any shared network (a global subnet). The metadata is included in the returned subnet definition and provides database-specific information associated with the returned object.

remote-subnet4-get-by-prefix¶

This command fetches the selected IPv4 subnet by prefix from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet4-get-by-prefix command

Command syntax:

{
    "command": "remote-subnet4-get-by-prefix",
    "arguments": {
        "subnets": [ {
            "subnet": <subnet prefix>
        } ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one prefix of the subnet to be returned. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet found.",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>,
                "subnet": <subnet prefix>,
                "shared-network-name": <shared network name> | null,
                "metadata": {
                    "server-tags": [ <first server tag>, <second server tag>, ... ]
                },
                <the rest of the subnet specification here>
            }
        ],
        "count": 1
    }
}

If the shared network name is null, it means that the returned subnet does not belong to any shared network (global subnet). The metadata is included in the returned subnet definition and provides database-specific information associated with the returned object.

remote-subnet4-list¶

This command fetches a list of all IPv4 subnets from the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet4-list command

Command syntax:

{
    "command": "remote-subnet4-list",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <first server tag>, <second server tag>, ... ]
    }
}

The server-tags list is required for this command, and must not be empty. It may either contain one or multiple server tags as strings, or a single null value.

Response syntax:

{
    "result": 0,
    "text": "2 IPv4 subnets found.",
    "arguments": {
        "subnets": [
            {
                "id": <first subnet identifier>,
                "subnet": <first subnet prefix>,
                "shared-network-name": <shared network name> | null,
                "metadata": {
                    "server-tags": [ <first server tag>, <second server tag>, ... ]
                }
            },
            {
                "id": <second subnet identifier>,
                "subnet": <second subnet prefix>,
                "shared-network-name": <shared network name> | null,
                "metadata": {
                    "server-tags": [ <first server tag>, ... ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains a list of maps. Each map contains a subnet identifier, prefix, and shared network name to which the subnet belongs. If the subnet does not belong to a shared network, the name is null. The metadata includes database-specific information associated with the subnets. The returned list does not contain full subnet definitions; use remote-subnet4-get to fetch the full information about the selected subnets. If the command includes explicit server tags as strings (including the special server tag “all”), the list contains all subnets which are associated with any of the specified tags. A subnet is returned even if it is associated with multiple servers and only one of the specified tags matches. If the command includes the null value in the server-tags list, the response contains all subnets which are assigned to no servers (unassigned).

remote-subnet4-set¶

This command creates or replaces an IPv4 subnet in the configuration database.

Supported by: kea-dhcp4

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet4-set command

Command syntax:

{
    "command": "remote-subnet4-set",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>,
                "subnet": <subnet prefix>,
                "shared-network-name": <shared network name> | null,
                <the rest of the subnet specification here>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <first server tag>, <second server tag>, ... ]
    }
}

The provided list must contain exactly one subnet specification. The shared-network-name parameter is required for these commands; it associates the subnet with the shared network by its name. If the subnet must not belong to any shared network (a global subnet), the null value must be specified for the shared network name. The server-tags list is mandatory and must contain one or more server tags as strings to explicitly associate the subnet with one or more user-defined servers. The remote-subnet4-set command may include the special server tag “all” to associate the subnet with all servers.

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet successfully set.",
    "arguments": {
        "id": <subnet identifier>,
        "subnet": <subnet prefix>
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-subnet6-del-by-id¶

This command deletes an IPv6 subnet by ID from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet6-del-by-id command

Command syntax:

{
    "command": "remote-subnet6-del-by-id",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one ID of the subnet to be deleted. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "1 IPv6 subnet(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-subnet6-del-by-prefix¶

This command deletes an IPv6 subnet by prefix from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet6-del-by-prefix command

Command syntax:

{
    "command": "remote-subnet6-del-by-prefix",
    "arguments": {
        "subnets": [
            {
                "subnet": <subnet prefix>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one prefix of the subnet to be deleted. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "1 IPv6 subnet(s) deleted.",
    "arguments": {
        "count": 1
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

remote-subnet6-get-by-id¶

This command fetches the selected IPv6 subnet by ID from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet6-get-by-id command

Command syntax:

{
    "command": "remote-subnet6-get-by-id",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one ID of the subnet to be returned. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "IPv6 subnet found.",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>,
                "subnet": <subnet prefix>,
                "shared-network-name": <shared network name> | null,
                "metadata": {
                    "server-tags": [ <first server tag>, <second server tag>, ... ]
                },
                <the rest of the subnet specification here>
            }
        ],
        "count": 1
    }
}

If the shared network name is null, it means that the returned subnet does not belong to any shared network (a global subnet). The metadata is included in the returned subnet definition and provides database-specific information associated with the returned object.

remote-subnet6-get-by-prefix¶

This command fetches the selected IPv6 subnet by prefix from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet6-get-by-prefix command

Command syntax:

{
    "command": "remote-subnet6-get-by-prefix",
    "arguments": {
        "subnets": [
            {
                "subnet": <subnet prefix>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        }
    }
}

This command includes a list with exactly one prefix of the subnet to be returned. The server-tags parameter must not be specified for this command.

Response syntax:

{
    "result": 0,
    "text": "IPv6 subnet found.",
    "arguments": {
        "subnets": [ {
            "id": <subnet identifier>,
            "subnet": <subnet prefix>,
            "shared-network-name": <shared network name> | null,
            "metadata": {
                "server-tags": [ <first server tag>, <second server tag>, ... ]
            },
            <the rest of the subnet specification here>
        } ],
        "count": 1
    }
}

If the shared network name is null, it means that the returned subnet does not belong to any shared network (global subnet). The metadata is included in the returned subnet definition and provides database-specific information associated with the returned object.

remote-subnet6-list¶

This command fetches a list of all IPv6 subnets from the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet6-list command

Command syntax:

{
    "command": "remote-subnet6-list",
    "arguments": {
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <first server tag>, <second server tag>, ... ]
    }
}

The server-tags list is required for this command, and must not be empty. It may either contain one or multiple server tags as strings, or a single null value.

Response syntax:

{
    "result": 0,
    "text": "2 IPv6 subnets found.",
    "arguments": {
        "subnets": [
            {
                "id": <first subnet identifier>,
                "subnet": <first subnet prefix>,
                "shared-network-name": <shared network name> | null,
                "metadata": {
                    "server-tags": [ <first server tag>, <second server tag>, ... ]
                }
            },
            {
                "id": <second subnet identifier>,
                "subnet": <second subnet prefix>,
                "shared-network-name": <shared network name> | null,
                "metadata": {
                    "server-tags": [ <first server tag>, ... ]
                }
            }
        ],
        "count": 2
    }
}

The returned response contains a list of maps. Each map contains a subnet identifier, prefix, and shared network name to which the subnet belongs. If the subnet does not belong to a shared network, the name is null. The metadata includes database-specific information associated with the subnets. The returned list does not contain full subnet definitions; use remote-subnet6-get to fetch the full information about the selected subnets. If the command includes explicit server tags as strings (including the special server tag “all”), the list contains all subnets which are associated with any of the specified tags. A subnet is returned even if it is associated with multiple servers and only one of the specified tags matches. If the command includes the null value in the server-tags list, the response contains all subnets which are assigned to no servers (unassigned).

remote-subnet6-set¶

This command creates or replaces an IPv6 subnet in the configuration database.

Supported by: kea-dhcp6

Availability: 1.6.0 (cb_cmds hook library)

Description and examples: see remote-subnet6-set command

Command syntax:

{
    "command": "remote-subnet6-set",
    "arguments": {
        "subnets": [
            {
                "id": <subnet identifier>,
                "subnet": <subnet prefix>,
                "shared-network-name": <shared network name> | null,
                <the rest of the subnet specification here>
            }
        ],
        "remote": {
            <specification of the database to connect to>
        },
        "server-tags": [ <first server tag>, <second server tag>, ... ]
    }
}

The provided list must contain exactly one subnet specification. The shared-network-name parameter is required for these commands; it associates the subnet with the shared network by its name. If the subnet must not belong to any shared network (a global subnet), the null value must be specified for the shared network name. The server-tags list is mandatory and must contain one or more server tags as strings to explicitly associate the subnet with one or more user-defined servers. The remote-subnet6-set command may include the special server tag “all” to associate the subnet with all servers.

Response syntax:

{
    "result": 0,
    "text": "IPv6 subnet successfully set.",
    "arguments": {
        "id": <subnet identifier>,
        "subnet": <subnet prefix>
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

reservation-add¶

This command adds a new host reservation. The reservation may include IPv4 addresses, IPv6 addresses, IPv6 prefixes, various identifiers, a class the client will be assigned to, DHCPv4 and DHCPv6 options, and more.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (host_cmds hook library)

Description and examples: see reservation-add command

Command syntax:

{
    "command": "reservation-add",
    "arguments": {
        "reservation": {
            "boot-file-name": <string>,
            "comment": <string>,
            "client-id": <string>,
            "circuit-id": <string>,
            "duid": <string>,
            "flex-id": <string>,
            "ip-address": <string (IPv4 address)>,
            "ip-addresses": [ <comma-separated strings> ],
            "hw-address": <string>,
            "hostname": <string>,
            "next-server": <string (IPv4 address)>,
            "option-data-list": [ <comma-separated structures defining options> ],
            "prefixes": [ <comma-separated IPv6 prefixes> ],
            "reservation-client-classes": [ <comma-separated strings> ],
            "server-hostname": <string>,
            "subnet-id": <integer>,
            "user-context": <any valid JSON>
        }
    }
}

Note that ip-address, client-id, next-server, server-hostname, and boot-file-name are IPv4-specific. duid, ip-addresses, and prefixes are IPv6-specific.

Response syntax:

{
    "result": <integer>,
    "text": <string>
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

reservation-del¶

This command deletes an existing host reservation.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (host_cmds hook library)

Description and examples: see reservation-del command

Command syntax:

{
    "command": "reservation-del",
    "arguments": {
        "subnet-id": <integer>,
        "ip-address": <string>,
        "identifier-type": <one of 'hw-address', 'duid', 'circuit-id', 'client-id' and 'flex-id'>,
        "identifier": <string>
    }
}

The host reservation can be identified by either the (subnet-id, ip-address) pair or a triplet of (subnet-id, identifier-type, identifier).

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

reservation-get¶

This command retrieves an existing host reservation.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (host_cmds hook library)

Description and examples: see reservation-get command

Command syntax:

{
    "command": "reservation-get",
    "arguments": {
        "subnet-id": <integer>,
        "identifier-type": <one of 'hw-address', 'duid', 'circuit-id', 'client-id' and 'flex-id'>,
        "identifier": <string>
    }
}

The host reservation can be identified by either the (subnet-id, ip-address) pair or a triplet of (subnet-id, identifier-type, identifier).

Response syntax:

{
    "result": <integer>,
    "text": <string>,
    "arguments": {
        "boot-file-name": <string>,
        "comment": <string>,
        "client-id": <string>,
        "circuit-id": <string>,
        "duid": <string>,
        "flex-id": <string>,
        "ip-address": <string (IPv4 address)>,
        "ip-addresses": [ <comma-separated strings> ],
        "hw-address": <string>,
        "hostname": <string>,
        "next-server": <string (IPv4 address)>,
        "option-data-list": [ <comma-separated structures defining options> ],
        "prefixes": [ <comma-separated IPv6 prefixes> ],
        "reservation-client-classes": [ <comma-separated strings> ],
        "server-hostname": <string>,
        "subnet-id": <integer>,
        "user-context": <any valid JSON>
    }
}

The arguments object appears only if a host is found. Many fields in the arguments object appear only if a specific field is set.

reservation-get-all¶

This command retrieves all host reservations for a specified subnet.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (host_cmds hook library)

Description and examples: see reservation-get-all command

Command syntax:

{
    "command": "reservation-get-all",
    "arguments": {
        "subnet-id": <integer>
    }
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

The reservation-get-all command may result in very large responses.

reservation-get-page¶

This command retrieves host reservations for a specified subnet by page.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (host_cmds hook library)

Description and examples: see reservation-get-page command

Command syntax:

{
    "command": "reservation-get-page",
    "arguments": {
        "subnet-id": <integer>,
        "limit": <integer>,
        "source-index": <integer>,
        "from": <integer>
    }
}

The subnet-id and the page size limit are mandatory. The source-index and from host id are optional and default to 0. Values to use to load the next page are returned in responses in a next map.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

server-tag-get¶

This command returns the server tag used by the server. Server tag is essential configuration parameter in the Config Backend configuration. This parameter is configured in the local config file. This command does not take any parameters.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (built-in)

Description and examples: see server-tag-get command

Command syntax:

{
    "command": "server-tag-get"
}

Response syntax:

{
    "result": 0,
    "arguments": {
        "server-tag": "office1"
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

shutdown¶

This command instructs the server to initiate its shutdown procedure.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see shutdown command

Command syntax:

{
    "command": "shutdown"
}

The server responds with a confirmation that the shutdown procedure has been initiated.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

stat-lease4-get¶

This command fetches lease statistics for a range of known IPv4 subnets.

Supported by: kea-dhcp4

Availability: 1.4.0 (stat_cmds hook library)

Description and examples: see stat-lease4-get command

Command syntax:

{
  "command": "stat-lease4-get"
}

Response syntax:

{
    "result": 0,
    "text": "stat-lease4-get: 2 rows found",
    "arguments": {
      "result-set": {
        "columns": [ "subnet-id",
                       "total-addresses",
                       "assigned-addresses",
                       "declined-addresses" ],
        "rows": [
          [ 10, 256, 111, 0 ],
          [ 20, 4098, 2034, 4 ]
        ],
      "timestamp": "2018-05-04 15:03:37.000000"
      }
    }
  }

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

stat-lease6-get¶

This command fetches lease statistics for a range of known IPv6 subnets.

Supported by: kea-dhcp6

Availability: 1.4.0 (stat_cmds hook library)

Description and examples: see stat-lease6-get command

Command syntax:

{
  "command": "stat-lease6-get",
  "arguments": {
    "subnet-id" : 10
  }
}

Response syntax:

{
    "result": 0,
    "text": "stat-lease6-get: 2 rows found",
    "arguments": {
      "result-set": {
        "columns": [ "subnet-id", "total-nas", "assigned-nas", "declined-nas", "total-pds", "assigned-pds" ],
        "rows": [
          [ 10, 4096, 2400, 3, 0, 0],
          [ 20, 0, 0, 0, 1048, 233 ],
          [ 30, 256, 60, 0, 1048, 15 ]
        ],
      "timestamp": "2018-05-04 15:03:37.000000"
      }
    }
  }

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-get¶

This command retrieves a single statistic. It takes a single string parameter called name that specifies the statistic name.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see statistic-get command

Command syntax:

{
    "command": "statistic-get",
    "arguments": {
        "name": "pkt4-received"
    }
}

The server responds with the details of the requested statistic, with a result of 0 indicating success, and the specified statistic as the value of the “arguments” parameter.

Response syntax:

{
   "result": 0,
   "arguments": {
       "pkt4-received": [ [ "first_value", "2019-07-30 10:11:19.498739" ], [ "second_value", "2019-07-30 10:11:19.498662" ] ]
       }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-get-all¶

This command retrieves all recorded statistics.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see statistic-get-all command

Command syntax:

{
    "command": "statistic-get-all",
    "arguments": { }
}

The server responds with the details of all recorded statistics, with a result of 0 indicating that it iterated over all statistics (even when the total number of statistics is zero).

Response syntax:

{
   "result": 0,
   "arguments": {
       "declined-addresses": [ [ 0, "2019-07-30 10:04:28.386733" ] ],
       "reclaimed-declined-addresses": [ [ 0, "2019-07-30 10:04:28.386735" ] ],
       "reclaimed-leases": [ [ 0, "2019-07-30 10:04:28.386736" ] ],
       "subnet[1].assigned-addresses": [ [ 0, "2019-07-30 10:04:28.386740" ] ],
       "subnet[1].declined-addresses": [ [ 0, "2019-07-30 10:04:28.386743" ] ],
       "subnet[1].reclaimed-declined-addresses": [ [ 0, "2019-07-30 10:04:28.386745" ] ],
       "subnet[1].reclaimed-leases": [ [ 0, "2019-07-30 10:04:28.386747" ] ],
       "subnet[1].total-addresses": [ [ 200, "2019-07-30 10:04:28.386719" ] ]
       }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-remove¶

This command deletes a single statistic. It takes a single string parameter called name that specifies the statistic name.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see statistic-remove command

Command syntax:

{
    "command": "statistic-remove",
    "arguments": {
        "name": "pkt4-received"
    }
}

If the specific statistic is found and its removal is successful, the server responds with a status of 0, indicating success, and an empty parameters field. If an error is encountered (e.g. the requested statistic was not found), the server returns a status code of 1 (error) and the text field contains the error description.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-remove-all¶

This command deletes all statistics.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see statistic-remove-all command

Command syntax:

{
    "command": "statistic-remove-all",
    "arguments": { }
}

If the removal of all statistics is successful, the server responds with a status of 0, indicating success, and an empty parameters field. If an error is encountered, the server returns a status code of 1 (error) and the text field contains the error description.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-reset¶

This command sets the specified statistic to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time duration, and “” for string type. It takes a single string parameter called name that specifies the statistic name.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see statistic-reset command

Command syntax:

{
    "command": "statistic-reset",
    "arguments": {
        "name": "pkt4-received"
    }
}

If the specific statistic is found and the reset is successful, the server responds with a status of 0, indicating success, and an empty parameters field. If an error is encountered (e.g. the requested statistic was not found), the server returns a status code of 1 (error) and the text field contains the error description.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-reset-all¶

This command sets all statistics to their neutral values: 0 for integer, 0.0 for float, 0h0m0s0us for time duration, and “” for string type.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.0.0 (built-in)

Description and examples: see statistic-reset-all command

Command syntax:

{
    "command": "statistic-reset-all",
    "arguments": { }
}

If the operation is successful, the server responds with a status of 0, indicating success, and an empty parameters field. If an error is encountered, the server returns a status code of 1 (error) and the text field contains the error description.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-sample-age-set¶

This command sets a time-based limit for a single statistic. It takes two parameters: a string called name and an integer value called duration.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (built-in)

Description and examples: see statistic-sample-age-set command

Command syntax:

{
    "command": "statistic-sample-age-set",
    "arguments": {
        "name": "pkt4-received",
        "duration": 1245
    }
}

The server responds with a message about a successfully set limit for the given statistic, with a result of 0 indicating success, and an empty parameters field. If an error is encountered (e.g. the requested statistic was not found), the server returns a status code of 1 (error) and the text field contains the error description.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-sample-age-set-all¶

This command sets a time-based limit for all statistics. It takes a single integer parameter called duration.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (built-in)

Description and examples: see statistic-sample-age-set-all command

Command syntax:

{
    "command": "statistic-sample-age-set-all",
    "arguments": {
        "duration": 1245
    }
}

The server responds with a message about successfully set limits for all statistics, with a result of 0 indicating success, and an empty parameters field. If an error is encountered, the server returns a status code of 1 (error) and the text field contains the error description.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-sample-count-set¶

This command sets a size-based limit for a single statistic. It takes two parameters: a string called name and an integer value called max-samples.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (built-in)

Description and examples: see statistic-sample-count-set command

Command syntax:

{
    "command": "statistic-sample-count-set",
    "arguments": {
        "name": "pkt4-received",
        "max-samples": 100
    }
}

The server responds with a message about a successfully set limit for the given statistic, with a result of 0 indicating success, and an empty parameters field. If an error is encountered (e.g. the requested statistic was not found), the server returns a status code of 1 (error) and the text field contains the error description.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

statistic-sample-count-set-all¶

This command sets a size-based limit for all statistics. It takes a single integer parameter called max-samples.

Supported by: kea-dhcp4, kea-dhcp6

Availability: 1.6.0 (built-in)

Description and examples: see statistic-sample-count-set-all command

Command syntax:

{
    "command": "statistic-sample-count-set-all",
    "arguments": {
        "max-samples": 100
    }
}

The server responds with a message about successfully set limits for all statistics, with a result of 0 indicating success, and an empty parameters field. If an error is encountered, the server returns a status code of 1 (error) and the text field contains the error description.

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

subnet4-add¶

This command creates and adds a new subnet to the existing server configuration. This operation has no impact on other subnets.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see subnet4-add command

Command syntax:

{
    "command": "subnet4-add",
    "arguments": {
        "subnets": [ {
            "id": 123,
            "subnet": "10.20.30.0/24",
            ...
        } ]
    }
}

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet added",
    "arguments": {
        "subnets": [
            {
                "id": 123,
                "subnet": "10.20.30.0/24"
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

subnet4-del¶

This command removes a subnet from the server’s configuration. This command has no effect on other configured subnets, but removing a subnet has certain implications which the server’s administrator should be aware of.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see subnet4-del command

Command syntax:

{
    "command": "subnet4-del",
    "arguments": {
        "id": 123
    }
}

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet 192.0.2.0/24 (id 123) deleted",
    "arguments": {
        "subnets": [
            {
                "id": 123,
                "subnet": "192.0.2.0/24"
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

subnet4-get¶

This command retrieves detailed information about the specified subnet. This command usually follows subnet4-list, which discovers available subnets with their respective subnet identifiers and prefixes.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see subnet4-get command

Command syntax:

{
    "command": "subnet4-get",
    "arguments": {
        "id": 10
    }
}

Response syntax:

{
    "result": 0,
    "text": "Info about IPv4 subnet 10.0.0.0/8 (id 10) returned",
    "arguments": {
        "subnets": [
            {
                "subnet": "10.0.0.0/8",
                "id": 1,
                "option-data": [
                    ...
                ],
                ...
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

subnet4-list¶

This command lists all currently configured subnets. The subnets are returned in a brief format, i.e. a subnet identifier and subnet prefix are included for each subnet.

Supported by: kea-dhcp4

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see subnet4-list command

Command syntax:

{
    "command": "subnet4-list"
}

Response syntax:

{
    "result": 0,
    "text": "2 IPv4 subnets found",
    "arguments": {
        "subnets": [
            {
                "id": 10,
                "subnet": "10.0.0.0/8"
            },
            {
                "id": 100,
                "subnet": "192.0.2.0/24"
            }
        ]
    }
}

If no IPv4 subnets are found, an error code is returned along with the error description.

subnet4-update¶

This command updates a subnet in the existing server configuration. This operation has no impact on other subnets.

Supported by: kea-dhcp4

Availability: 1.6.0 (subnet_cmds hook library)

Description and examples: see subnet4-update command

Command syntax:

{
    "command": "subnet4-update",
    "arguments": {
        "subnets": [ {
            "id": 123,
            "subnet": "10.20.30.0/24",
            ...
        } ]
    }
}

Response syntax:

{
    "result": 0,
    "text": "IPv4 subnet updated",
    "arguments": {
        "subnets": [
            {
                "id": 123,
                "subnet": "10.20.30.0/24"
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

subnet6-add¶

This command creates and adds a new subnet to the existing server configuration. This operation has no impact on other subnets.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see subnet6-add command

Command syntax:

{
    "command": "subnet6-add",
    "arguments": {
        "subnet6": [ {
            "id": 234,
            "subnet": "2001:db8:1::/64",
            ...
        } ]
    }
}

Response syntax:

{
    "result": 0,
    "text": "IPv6 subnet added",
    "arguments": {
        "subnet6": [
            {
                "id": 234,
                "subnet": "2001:db8:1::/64"
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

subnet6-del¶

This command removes a subnet from the server’s configuration. This command has no effect on other configured subnets, but removing a subnet has certain implications which the server’s administrator should be aware of.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see subnet6-del command

Command syntax:

{
    "command": "subnet6-del",
    "arguments": {
        "id": 234
    }
}

Response syntax:

{
    "result": 0,
    "text": "IPv6 subnet 2001:db8:1::/64 (id 234) deleted",
    "subnets": [
        {
            "id": 234,
            "subnet": "2001:db8:1::/64"
        }
    ]
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

subnet6-get¶

This command retrieves detailed information about the specified subnet. This command usually follows subnet6-list, which discovers available subnets with their respective subnet identifiers and prefixes.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see subnet6-get command

Command syntax:

{
    "command": "subnet6-get",
    "arguments": {
        "id": 11
    }
}

Response syntax:

{
    "result": 0,
    "text": "Info about IPv6 subnet 2001:db8:1::/64 (id 11) returned",
    "arguments": {
        "subnets": [
            {
                "subnet": "2001:db8:1::/64",
                "id": 1,
                "option-data": [
                    ...
                ],
                ...
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

subnet6-list¶

This command lists all currently configured subnets. The subnets are returned in a brief format, i.e. a subnet identifier and subnet prefix are included for each subnet.

Supported by: kea-dhcp6

Availability: 1.3.0 (subnet_cmds hook library)

Description and examples: see subnet6-list command

Command syntax:

{
    "command": "subnet6-list"
}

Response syntax:

{
    "result": 0,
    "text": "2 IPv6 subnets found",
    "arguments": {
        "subnets": [
            {
                "id": 11,
                "subnet": "2001:db8:1::/64"
            },
            {
                "id": 233,
                "subnet": "3000::/16"
            }
        ]
    }
}

If no IPv6 subnets are found, an error code is returned along with the error description.

subnet6-update¶

This command updates a subnet in the existing server configuration. This operation has no impact on other subnets.

Supported by: kea-dhcp6

Availability: 1.6.0 (subnet_cmds hook library)

Description and examples: see subnet6-update command

Command syntax:

{
    "command": "subnet6-update",
    "arguments": {
        "subnet6": [ {
            "id": 234,
            "subnet": "2001:db8:1::/64",
            ...
        } ]
    }
}

Response syntax:

{
    "result": 0,
    "text": "IPv6 subnet updated",
    "arguments": {
        "subnet6": [
            {
                "id": 234,
                "subnet": "2001:db8:1::/64"
            }
        ]
    }
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)

version-get¶

This command returns extended information about the Kea version that is running. The returned string is the same as if Kea were run with the -V command-line option.

Supported by: kea-ctrl-agent, kea-dhcp-ddns, kea-dhcp4, kea-dhcp6

Availability: 1.2.0 (built-in)

Description and examples: see version-get command

Command syntax:

{
    "command": "version-get"
}

Response syntax:

{
    "result": <integer>,
    "text": "<string>"
}

Result is an integer representation of the status. Currently supported statuses are:

0 - success
1 - error
2 - unsupported
3 - empty (command was completed successfully, but no data was affected or returned)