.. _api: API Reference ============= Kea currently supports 166 commands in :ref:`kea-ctrl-agent `, :ref:`kea-dhcp-ddns `, :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` daemons and :ref:`cb_cmds `, :ref:`class_cmds `, :ref:`high_availability `, :ref:`host_cache `, :ref:`host_cmds `, :ref:`lease_cmds `, :ref:`stat_cmds `, :ref:`subnet_cmds ` hook libraries. .. _commands-kea-ctrl-agent: Commands supported by `kea-ctrl-agent` daemon: :ref:`build-report `, :ref:`config-get `, :ref:`config-reload `, :ref:`config-set `, :ref:`config-test `, :ref:`config-write `, :ref:`list-commands `, :ref:`shutdown `, :ref:`status-get `, :ref:`version-get `. .. _commands-kea-dhcp-ddns: Commands supported by `kea-dhcp-ddns` daemon: :ref:`build-report `, :ref:`config-get `, :ref:`config-reload `, :ref:`config-set `, :ref:`config-test `, :ref:`config-write `, :ref:`list-commands `, :ref:`shutdown `, :ref:`status-get `, :ref:`version-get `. .. _commands-kea-dhcp4: Commands supported by `kea-dhcp4` daemon: :ref:`build-report `, :ref:`cache-clear `, :ref:`cache-flush `, :ref:`cache-get `, :ref:`cache-get-by-id `, :ref:`cache-insert `, :ref:`cache-load `, :ref:`cache-remove `, :ref:`cache-size `, :ref:`cache-write `, :ref:`class-add `, :ref:`class-del `, :ref:`class-get `, :ref:`class-list `, :ref:`class-update `, :ref:`config-backend-pull `, :ref:`config-get `, :ref:`config-reload `, :ref:`config-set `, :ref:`config-test `, :ref:`config-write `, :ref:`dhcp-disable `, :ref:`dhcp-enable `, :ref:`ha-continue `, :ref:`ha-heartbeat `, :ref:`ha-maintenance-cancel `, :ref:`ha-maintenance-notify `, :ref:`ha-maintenance-start `, :ref:`ha-scopes `, :ref:`ha-sync `, :ref:`lease4-add `, :ref:`lease4-del `, :ref:`lease4-get `, :ref:`lease4-get-all `, :ref:`lease4-get-by-client-id `, :ref:`lease4-get-by-hostname `, :ref:`lease4-get-by-hw-address `, :ref:`lease4-get-page `, :ref:`lease4-resend-ddns `, :ref:`lease4-update `, :ref:`lease4-wipe `, :ref:`leases-reclaim `, :ref:`libreload `, :ref:`list-commands `, :ref:`network4-add `, :ref:`network4-del `, :ref:`network4-get `, :ref:`network4-list `, :ref:`network4-subnet-add `, :ref:`network4-subnet-del `, :ref:`remote-global-parameter4-del `, :ref:`remote-global-parameter4-get `, :ref:`remote-global-parameter4-get-all `, :ref:`remote-global-parameter4-set `, :ref:`remote-network4-del `, :ref:`remote-network4-get `, :ref:`remote-network4-list `, :ref:`remote-network4-set `, :ref:`remote-option-def4-del `, :ref:`remote-option-def4-get `, :ref:`remote-option-def4-get-all `, :ref:`remote-option-def4-set `, :ref:`remote-option4-global-del `, :ref:`remote-option4-global-get `, :ref:`remote-option4-global-get-all `, :ref:`remote-option4-global-set `, :ref:`remote-option4-network-del `, :ref:`remote-option4-network-set `, :ref:`remote-option4-pool-del `, :ref:`remote-option4-pool-set `, :ref:`remote-option4-subnet-del `, :ref:`remote-option4-subnet-set `, :ref:`remote-server4-del `, :ref:`remote-server4-get `, :ref:`remote-server4-get-all `, :ref:`remote-server4-set `, :ref:`remote-subnet4-del-by-id `, :ref:`remote-subnet4-del-by-prefix `, :ref:`remote-subnet4-get-by-id `, :ref:`remote-subnet4-get-by-prefix `, :ref:`remote-subnet4-list `, :ref:`remote-subnet4-set `, :ref:`reservation-add `, :ref:`reservation-del `, :ref:`reservation-get `, :ref:`reservation-get-all `, :ref:`reservation-get-by-hostname `, :ref:`reservation-get-by-id `, :ref:`reservation-get-page `, :ref:`server-tag-get `, :ref:`shutdown `, :ref:`stat-lease4-get `, :ref:`statistic-get `, :ref:`statistic-get-all `, :ref:`statistic-remove `, :ref:`statistic-remove-all `, :ref:`statistic-reset `, :ref:`statistic-reset-all `, :ref:`statistic-sample-age-set `, :ref:`statistic-sample-age-set-all `, :ref:`statistic-sample-count-set `, :ref:`statistic-sample-count-set-all `, :ref:`status-get `, :ref:`subnet4-add `, :ref:`subnet4-del `, :ref:`subnet4-get `, :ref:`subnet4-list `, :ref:`subnet4-update `, :ref:`version-get `. .. _commands-kea-dhcp6: Commands supported by `kea-dhcp6` daemon: :ref:`build-report `, :ref:`cache-clear `, :ref:`cache-flush `, :ref:`cache-get `, :ref:`cache-get-by-id `, :ref:`cache-insert `, :ref:`cache-load `, :ref:`cache-remove `, :ref:`cache-size `, :ref:`cache-write `, :ref:`class-add `, :ref:`class-del `, :ref:`class-get `, :ref:`class-list `, :ref:`class-update `, :ref:`config-backend-pull `, :ref:`config-get `, :ref:`config-reload `, :ref:`config-set `, :ref:`config-test `, :ref:`config-write `, :ref:`dhcp-disable `, :ref:`dhcp-enable `, :ref:`ha-continue `, :ref:`ha-heartbeat `, :ref:`ha-maintenance-cancel `, :ref:`ha-maintenance-notify `, :ref:`ha-maintenance-start `, :ref:`ha-scopes `, :ref:`ha-sync `, :ref:`lease6-add `, :ref:`lease6-bulk-apply `, :ref:`lease6-del `, :ref:`lease6-get `, :ref:`lease6-get-all `, :ref:`lease6-get-by-duid `, :ref:`lease6-get-by-hostname `, :ref:`lease6-get-page `, :ref:`lease6-resend-ddns `, :ref:`lease6-update `, :ref:`lease6-wipe `, :ref:`leases-reclaim `, :ref:`libreload `, :ref:`list-commands `, :ref:`network6-add `, :ref:`network6-del `, :ref:`network6-get `, :ref:`network6-list `, :ref:`network6-subnet-add `, :ref:`network6-subnet-del `, :ref:`remote-global-parameter6-del `, :ref:`remote-global-parameter6-get `, :ref:`remote-global-parameter6-get-all `, :ref:`remote-global-parameter6-set `, :ref:`remote-network6-del `, :ref:`remote-network6-get `, :ref:`remote-network6-list `, :ref:`remote-network6-set `, :ref:`remote-option-def6-del `, :ref:`remote-option-def6-get `, :ref:`remote-option-def6-get-all `, :ref:`remote-option-def6-set `, :ref:`remote-option6-global-del `, :ref:`remote-option6-global-get `, :ref:`remote-option6-global-get-all `, :ref:`remote-option6-global-set `, :ref:`remote-option6-network-del `, :ref:`remote-option6-network-set `, :ref:`remote-option6-pd-pool-del `, :ref:`remote-option6-pd-pool-set `, :ref:`remote-option6-pool-del `, :ref:`remote-option6-pool-set `, :ref:`remote-option6-subnet-del `, :ref:`remote-option6-subnet-set `, :ref:`remote-server6-del `, :ref:`remote-server6-get `, :ref:`remote-server6-get-all `, :ref:`remote-server6-set `, :ref:`remote-subnet6-del-by-id `, :ref:`remote-subnet6-del-by-prefix `, :ref:`remote-subnet6-get-by-id `, :ref:`remote-subnet6-get-by-prefix `, :ref:`remote-subnet6-list `, :ref:`remote-subnet6-set `, :ref:`reservation-add `, :ref:`reservation-del `, :ref:`reservation-get `, :ref:`reservation-get-all `, :ref:`reservation-get-by-hostname `, :ref:`reservation-get-by-id `, :ref:`reservation-get-page `, :ref:`server-tag-get `, :ref:`shutdown `, :ref:`stat-lease6-get `, :ref:`statistic-get `, :ref:`statistic-get-all `, :ref:`statistic-remove `, :ref:`statistic-remove-all `, :ref:`statistic-reset `, :ref:`statistic-reset-all `, :ref:`statistic-sample-age-set `, :ref:`statistic-sample-age-set-all `, :ref:`statistic-sample-count-set `, :ref:`statistic-sample-count-set-all `, :ref:`status-get `, :ref:`subnet6-add `, :ref:`subnet6-del `, :ref:`subnet6-get `, :ref:`subnet6-list `, :ref:`subnet6-update `, :ref:`version-get `. .. _commands-cb_cmds: Commands supported by `cb_cmds` hook library: :ref:`remote-global-parameter4-del `, :ref:`remote-global-parameter4-get `, :ref:`remote-global-parameter4-get-all `, :ref:`remote-global-parameter4-set `, :ref:`remote-global-parameter6-del `, :ref:`remote-global-parameter6-get `, :ref:`remote-global-parameter6-get-all `, :ref:`remote-global-parameter6-set `, :ref:`remote-network4-del `, :ref:`remote-network4-get `, :ref:`remote-network4-list `, :ref:`remote-network4-set `, :ref:`remote-network6-del `, :ref:`remote-network6-get `, :ref:`remote-network6-list `, :ref:`remote-network6-set `, :ref:`remote-option-def4-del `, :ref:`remote-option-def4-get `, :ref:`remote-option-def4-get-all `, :ref:`remote-option-def4-set `, :ref:`remote-option-def6-del `, :ref:`remote-option-def6-get `, :ref:`remote-option-def6-get-all `, :ref:`remote-option-def6-set `, :ref:`remote-option4-global-del `, :ref:`remote-option4-global-get `, :ref:`remote-option4-global-get-all `, :ref:`remote-option4-global-set `, :ref:`remote-option4-network-del `, :ref:`remote-option4-network-set `, :ref:`remote-option4-pool-del `, :ref:`remote-option4-pool-set `, :ref:`remote-option4-subnet-del `, :ref:`remote-option4-subnet-set `, :ref:`remote-option6-global-del `, :ref:`remote-option6-global-get `, :ref:`remote-option6-global-get-all `, :ref:`remote-option6-global-set `, :ref:`remote-option6-network-del `, :ref:`remote-option6-network-set `, :ref:`remote-option6-pd-pool-del `, :ref:`remote-option6-pd-pool-set `, :ref:`remote-option6-pool-del `, :ref:`remote-option6-pool-set `, :ref:`remote-option6-subnet-del `, :ref:`remote-option6-subnet-set `, :ref:`remote-server4-del `, :ref:`remote-server4-get `, :ref:`remote-server4-get-all `, :ref:`remote-server4-set `, :ref:`remote-server6-del `, :ref:`remote-server6-get `, :ref:`remote-server6-get-all `, :ref:`remote-server6-set `, :ref:`remote-subnet4-del-by-id `, :ref:`remote-subnet4-del-by-prefix `, :ref:`remote-subnet4-get-by-id `, :ref:`remote-subnet4-get-by-prefix `, :ref:`remote-subnet4-list `, :ref:`remote-subnet4-set `, :ref:`remote-subnet6-del-by-id `, :ref:`remote-subnet6-del-by-prefix `, :ref:`remote-subnet6-get-by-id `, :ref:`remote-subnet6-get-by-prefix `, :ref:`remote-subnet6-list `, :ref:`remote-subnet6-set `. .. _commands-class_cmds: Commands supported by `class_cmds` hook library: :ref:`class-add `, :ref:`class-del `, :ref:`class-get `, :ref:`class-list `, :ref:`class-update `. .. _commands-high_availability: Commands supported by `high_availability` hook library: :ref:`ha-continue `, :ref:`ha-heartbeat `, :ref:`ha-maintenance-cancel `, :ref:`ha-maintenance-notify `, :ref:`ha-maintenance-start `, :ref:`ha-scopes `, :ref:`ha-sync `. .. _commands-host_cache: Commands supported by `host_cache` hook library: :ref:`cache-clear `, :ref:`cache-flush `, :ref:`cache-get `, :ref:`cache-get-by-id `, :ref:`cache-insert `, :ref:`cache-load `, :ref:`cache-remove `, :ref:`cache-size `, :ref:`cache-write `. .. _commands-host_cmds: Commands supported by `host_cmds` hook library: :ref:`reservation-add `, :ref:`reservation-del `, :ref:`reservation-get `, :ref:`reservation-get-all `, :ref:`reservation-get-by-hostname `, :ref:`reservation-get-by-id `, :ref:`reservation-get-page `. .. _commands-lease_cmds: Commands supported by `lease_cmds` hook library: :ref:`lease4-add `, :ref:`lease4-del `, :ref:`lease4-get `, :ref:`lease4-get-all `, :ref:`lease4-get-by-client-id `, :ref:`lease4-get-by-hostname `, :ref:`lease4-get-by-hw-address `, :ref:`lease4-get-page `, :ref:`lease4-resend-ddns `, :ref:`lease4-update `, :ref:`lease4-wipe `, :ref:`lease6-add `, :ref:`lease6-bulk-apply `, :ref:`lease6-del `, :ref:`lease6-get `, :ref:`lease6-get-all `, :ref:`lease6-get-by-duid `, :ref:`lease6-get-by-hostname `, :ref:`lease6-get-page `, :ref:`lease6-resend-ddns `, :ref:`lease6-update `, :ref:`lease6-wipe `. .. _commands-stat_cmds: Commands supported by `stat_cmds` hook library: :ref:`stat-lease4-get `, :ref:`stat-lease6-get `. .. _commands-subnet_cmds: Commands supported by `subnet_cmds` hook library: :ref:`network4-add `, :ref:`network4-del `, :ref:`network4-get `, :ref:`network4-list `, :ref:`network4-subnet-add `, :ref:`network4-subnet-del `, :ref:`network6-add `, :ref:`network6-del `, :ref:`network6-get `, :ref:`network6-list `, :ref:`network6-subnet-add `, :ref:`network6-subnet-del `, :ref:`subnet4-add `, :ref:`subnet4-del `, :ref:`subnet4-get `, :ref:`subnet4-list `, :ref:`subnet4-update `, :ref:`subnet6-add `, :ref:`subnet6-del `, :ref:`subnet6-get `, :ref:`subnet6-list `, :ref:`subnet6-update `. .. _ref-build-report: build-report ------------ This command returns the list of compilation options that this particular binary was built with. Supported by: :ref:`kea-ctrl-agent `, :ref:`kea-dhcp-ddns `, :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.2.0 (built-in) Access: read *(parameter ignored in this Kea version)* Description and examples: see :ref:`build-report command ` Command syntax: :: { "command": "build-report" } Response syntax: :: { "result": 0, "text": } .. _ref-cache-clear: cache-clear ----------- This command removes all cached host reservations. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.4.0 (:ref:`host_cache ` hook library) Access: write *(parameter ignored in this Kea version)* Description and examples: see :ref:`cache-clear command ` Command syntax: :: { "command": "cache-clear" } Response syntax: :: { "result": , "text": "" } 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) .. _ref-cache-flush: cache-flush ----------- This command removes up to the given number or all cached host reservations. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.4.0 (:ref:`host_cache ` hook library) Access: write *(parameter ignored in this Kea version)* Description and examples: see :ref:`cache-flush command ` Command syntax: :: { "command": "cache-flush", "arguments": 5 } Response syntax: :: { "result": , "text": "" } 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) .. _ref-cache-get: cache-get --------- This command returns the full content of the host cache. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.4.0 (:ref:`host_cache ` hook library) Access: read *(parameter ignored in this Kea version)* Description and examples: see :ref:`cache-get command ` Command syntax: :: { "command": "cache-get" } Response syntax: :: { "result": 0, "text": "123 entries returned.", "arguments": } 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) .. _ref-cache-get-by-id: cache-get-by-id --------------- This command returns entries matching the given identifier from the host cache. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.6.0 (:ref:`host_cache ` hook library) Access: read *(parameter ignored in this Kea version)* Description and examples: see :ref:`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": } 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) .. _ref-cache-insert: cache-insert ------------ This command inserts a host into the cache. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.4.0 (:ref:`host_cache ` hook library) Access: write *(parameter ignored in this Kea version)* Description and examples: see :ref:`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": , "text": "" } 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) .. _ref-cache-load: cache-load ---------- This command allows the contents of a file on disk to be loaded into an in-memory cache. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.4.0 (:ref:`host_cache ` hook library) Access: write *(parameter ignored in this Kea version)* Description and examples: see :ref:`cache-load command ` Command syntax: :: { "command": "cache-load", "arguments": "/tmp/kea-host-cache.json" } Response syntax: :: { "result": , "text": "" } 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) .. _ref-cache-remove: cache-remove ------------ This command removes entries from the host cache. It takes parameters similar to the ``reservation-get`` command. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.4.0 (:ref:`host_cache ` hook library) Access: write *(parameter ignored in this Kea version)* Description and examples: see :ref:`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": , "text": "" } 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) .. _ref-cache-size: cache-size ---------- This command returns the number of entries in the host cache. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.6.0 (:ref:`host_cache ` hook library) Access: read *(parameter ignored in this Kea version)* Description and examples: see :ref:`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) .. _ref-cache-write: cache-write ----------- This command instructs Kea to write its host cache content to disk. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.4.0 (:ref:`host_cache ` hook library) Access: write *(parameter ignored in this Kea version)* Description and examples: see :ref:`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": , "text": "" } 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) .. _ref-class-add: class-add --------- This command adds a new class to the existing server configuration. Supported by: :ref:`kea-dhcp4 `, :ref:`kea-dhcp6 ` Availability: 1.5.0 (:ref:`class_cmds ` hook library) Access: write *(parameter ignored in this Kea version)* Description and examples: see :ref:`class-add command ` Command syntax: :: { "command": "class-add", "arguments": { "client-classes": [ { "name": , "test": , "option-data": [