--- /dev/null
+.. _api:
+
+*************
+API Reference
+*************
+
+Kea currently supports 121 commands: ``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`` , ``lease6-add`` , ``lease6-del`` ,
+``lease6-get`` , ``lease6-get-all`` , ``lease6-update`` ,
+``lease6-wipe`` , ``leases-reclaim`` , ``libreload`` , ``list-commands``
+, ``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`` ,
+``remote-global-parameter4-del`` , ``remote-global-parameter4-get`` ,
+``remote-global-parameter4-get-all`` , ``remote-global-parameter4-set``
+, ``remote-global-parameter6-del`` , ``remote-global-parameter6-get`` ,
+``remote-global-parameter6-get-all`` , ``remote-global-parameter6-set``
+, ``remote-network4-del`` , ``remote-network4-get`` ,
+``remote-network4-list`` , ``remote-network4-set`` ,
+``remote-network6-del`` , ``remote-network6-get`` ,
+``remote-network6-list`` , ``remote-network6-set`` ,
+``remote-option-def4-del`` , ``remote-option-def4-get`` ,
+``remote-option-def4-get-all`` , ``remote-option-def4-set`` ,
+``remote-option-def6-del`` , ``remote-option-def6-get`` ,
+``remote-option-def6-get-all`` , ``remote-option-def6-set`` ,
+``remote-option4-global-del`` , ``remote-option4-global-get`` ,
+``remote-option4-global-get-all`` , ``remote-option4-global-set`` ,
+``remote-option6-global-del`` , ``remote-option6-global-get`` ,
+``remote-option6-global-get-all`` , ``remote-option6-global-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`` ,
+``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`` , ``shutdown`` , ``stat-lease4-get`` ,
+``stat-lease6-get`` , ``statistic-get`` , ``statistic-get-all`` ,
+``statistic-remove`` , ``statistic-remove-all`` , ``statistic-reset`` ,
+``statistic-reset-all`` , ``subnet4-add`` , ``subnet4-del`` ,
+``subnet4-get`` , ``subnet4-list`` , ``subnet4-update`` ,
+``subnet6-add`` , ``subnet6-del`` , ``subnet6-get`` , ``subnet6-list`` ,
+``subnet6-update`` , ``version-get`` .
+
+Commands supported by the kea-ctrl-agent daemon: ``build-report`` ,
+``config-get`` , ``config-reload`` , ``config-set`` , ``config-test`` ,
+``config-write`` , ``list-commands`` , ``shutdown`` , ``version-get`` .
+
+Commands supported by the kea-dhcp-ddns daemon: ``build-report`` ,
+``config-get`` , ``config-reload`` , ``config-set`` , ``config-test`` ,
+``config-write`` , ``list-commands`` , ``shutdown`` , ``version-get`` .
+
+Commands supported by the 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-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``
+, ``shutdown`` , ``stat-lease4-get`` , ``statistic-get`` ,
+``statistic-get-all`` , ``statistic-remove`` , ``statistic-remove-all``
+, ``statistic-reset`` , ``statistic-reset-all`` , ``subnet4-add`` ,
+``subnet4-del`` , ``subnet4-get`` , ``subnet4-list`` ,
+``subnet4-update`` , ``version-get`` .
+
+Commands supported by the 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-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-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``
+, ``shutdown`` , ``stat-lease6-get`` , ``statistic-get`` ,
+``statistic-get-all`` , ``statistic-remove`` , ``statistic-remove-all``
+, ``statistic-reset`` , ``statistic-reset-all`` , ``subnet6-add`` ,
+``subnet6-del`` , ``subnet6-get`` , ``subnet6-list`` ,
+``subnet6-update`` , ``version-get`` .
+
+.. _commands-cb_cmds-lib:
+
+Commands supported by the Configuration Backend Commands (cb_cmds) hooks library:
+``remote-global-parameter4-del`` , ``remote-global-parameter4-get`` ,
+``remote-global-parameter4-get-all`` , ``remote-global-parameter4-set``
+, ``remote-global-parameter6-del`` , ``remote-global-parameter6-get`` ,
+``remote-global-parameter6-get-all`` , ``remote-global-parameter6-set``
+, ``remote-network4-del`` , ``remote-network4-get`` ,
+``remote-network4-list`` , ``remote-network4-set`` ,
+``remote-network6-del`` , ``remote-network6-get`` ,
+``remote-network6-list`` , ``remote-network6-set`` ,
+``remote-option-def4-del`` , ``remote-option-def4-get`` ,
+``remote-option-def4-get-all`` , ``remote-option-def4-set`` ,
+``remote-option-def6-del`` , ``remote-option-def6-get`` ,
+``remote-option-def6-get-all`` , ``remote-option-def6-set`` ,
+``remote-option4-global-del`` , ``remote-option4-global-get`` ,
+``remote-option4-global-get-all`` , ``remote-option4-global-set`` ,
+``remote-option6-global-del`` , ``remote-option6-global-get`` ,
+``remote-option6-global-get-all`` , ``remote-option6-global-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`` ,
+``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`` .
+
+.. _commands-class_cmds-lib:
+
+Commands supported by the Class Commands (class_cmds) hooks library: ``class-add`` ,
+``class-del`` , ``class-get`` , ``class-list`` , ``class-update`` .
+
+.. _commands-high_availability-lib:
+
+Commands supported by the High Availability (high_availability) hooks library: ``ha-continue`` ,
+``ha-heartbeat`` , ``ha-scopes`` , ``ha-sync`` .
+
+.. _commands-host_cache-lib:
+
+Commands supported by the Host Cache (host_cache) hooks library: ``cache-clear`` ,
+``cache-get`` , ``cache-get-by-id`` , ``cache-insert`` , ``cache-load``
+, ``cache-remove`` , ``cache-size`` , ``cache-write`` .
+
+.. _commands-host_cmds-lib:
+
+Commands supported by the Host Commands (host_cmds) hooks library: ``reservation-add`` ,
+``reservation-del`` , ``reservation-get`` , ``reservation-get-all`` ,
+``reservation-get-page`` .
+
+.. _commands-lease_cmds-lib:
+
+Commands supported by the Lease Commands (lease_cmds) hooks library: ``lease4-add`` ,
+``lease4-del`` , ``lease4-get`` , ``lease4-get-all`` , ``lease4-update``
+, ``lease4-wipe`` , ``lease6-add`` , ``lease6-del`` , ``lease6-get`` ,
+``lease6-get-all`` , ``lease6-update`` , ``lease6-wipe`` .
+
+.. _commands-stat_cmds-lib:
+
+Commands supported by the Supplemental Statistics Commands (stat_cmds) hooks library: ``stat-lease4-get`` ,
+``stat-lease6-get`` .
+
+.. _commands-subnet_cmds-lib:
+
+Commands supported by the Subnet Commands (subnet_cmds) hooks 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`` .
+
+.. _reference-build-report:
+
+build-report reference
+======================
+
+``build-report`` - returns a list of compilation options that this
+particular binary was built with.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.2.0 (built-in)
+
+Description and examples: see :ref:`command-build-report`
+
+Command syntax:
+
+::
+
+ {
+ "command": "build-report"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": <string with build details>
+ }
+
+.. _reference-cache-clear:
+
+cache-clear reference
+=====================
+
+``cache-clear`` - removes all cached host reservations.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
+
+Description and examples: see :ref:`command-cache-clear`
+
+Command syntax:
+
+::
+
+ {
+ "command": "cache-clear"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-cache-get:
+
+cache-get reference
+===================
+
+``cache-get`` - returns full content of the host cache.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
+
+Description and examples: see :ref:`command-cache-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "cache-get"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": 0
+ "text": "123 entries returned."
+ "arguments": <list of host reservations>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-cache-get-by-id:
+
+cache-get-by-id reference
+=========================
+
+``cache-get-by-id`` - returns entries matching the given identifier from
+the host cache.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
+
+Description and examples: see :ref:`command-cache-get-by-id`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-cache-insert:
+
+cache-insert reference
+======================
+
+``cache-insert`` - manually inserts a host into the cache.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
+
+Description and examples: see :ref:`command-cache-insert`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-cache-load:
+
+cache-load reference
+====================
+
+``cache-load`` - 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 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
+
+Description and examples: see :ref:`command-cache-load`
+
+Command syntax:
+
+::
+
+ {
+ "command": "cache-load",
+ "arguments": "/tmp/kea-host-cache.json"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-cache-remove:
+
+cache-remove reference
+======================
+
+``cache-remove`` - works similarly to the reservation-get command.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
+
+Description and examples: see :ref:`command-cache-remove`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-cache-size:
+
+cache-size reference
+====================
+
+``cache-size`` - returns the number of entries in the host cache.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
+
+Description and examples: see :ref:`command-cache-size`
+
+Command syntax:
+
+::
+
+ {
+ "command": "cache-size"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": 0
+ "text": "123 entries."
+ "arguments": { "size": 123 }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-cache-write:
+
+cache-write reference
+=====================
+
+``cache-write`` - instructs Kea to write its host cache content to disk.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (:ref:`The Host Cache hooks library<commands-host_cache-lib>`)
+
+Description and examples: see :ref:`command-cache-write`
+
+Command syntax:
+
+::
+
+ {
+ "command": "cache-write",
+ "arguments": "/path/to/the/file.json"
+ }
+
+The command takes one mandatory argument that specifies a filename path
+of a file to be written.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-class-add:
+
+class-add reference
+===================
+
+``class-add`` - creates and adds a new class to
+the existing server configuration.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
+
+Description and examples: see :ref:`command-class-add`
+
+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 defintions 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`` commands 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 will be successful (result 0), unless the class name is a
+duplicate or another error occurs (result 1).
+
+.. _reference-class-del:
+
+class-del reference
+===================
+
+``class-del`` - removes a client class from the server configuration.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
+
+Description and examples: see :ref:`command-class-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "class-del",
+ "arguments": {
+ "name": <name of the class>
+ }
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "Class '<class-name>' deleted."
+ }
+
+The command will return 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 and the result is 1 if the deletion is
+unsuccessful.
+
+.. _reference-class-get:
+
+class-get reference
+===================
+
+``class-get`` - returns detailed information about an existing client class.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
+
+Description and examples: see :ref:`command-class-get`
+
+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 defintions 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 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.
+
+.. _reference-class-list:
+
+class-list reference
+====================
+
+``class-list`` - retrieves a list of all client
+classes from the server configuration.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
+
+Description and examples: see :ref:`command-class-list`
+
+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. To
+retrieve full information about one of these classes, use
+:ref:`command-class-get`. 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.
+
+.. _reference-class-update:
+
+class-update reference
+======================
+
+``class-update`` - updates an existing client
+class in the server configuration.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.5.0 (:ref:`The Class Commands hooks library<commands-class_cmds-lib>`)
+
+Description and examples: see :ref:`command-class-update`
+
+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 defintions 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`` commands 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 will return 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 and 1 if the update is unsuccessful.
+
+.. _reference-config-get:
+
+config-get reference
+====================
+
+``config-get`` - retrieves the current configuration used by the server.
+The configuration is roughly equal to the configuration file, but
+includes additional changes made by other commands and due to parameters
+inheritance.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.2.0 (built-in)
+
+Description and examples: see :ref:`command-config-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "config-get"
+ }
+
+This command takes no parameters.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "arguments": {
+ <JSON configuration here, starting with Dhcp4, Dhcp6, or Control-agent object>
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-config-reload:
+
+config-reload reference
+=======================
+
+``config-reload`` - instructs Kea to load
+again the configuration file that was used previously.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.2.0 (built-in)
+
+Description and examples: see :ref:`command-config-reload`
+
+Command syntax:
+
+::
+
+ {
+ "command": "config-reload"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-config-set:
+
+config-set reference
+====================
+
+``config-set`` - instructs the server to replace
+its current configuration with the new configuration supplied in the
+command's arguments.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.2.0 (built-in)
+
+Description and examples: see :ref:`command-config-set`
+
+Command syntax:
+
+::
+
+ {
+ "command": "config-set",
+ "arguments": {
+ "<server>": {
+ }
+ }
+ }
+
+where <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)" }
+
+The 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 were
+ affected or returned)
+
+.. _reference-config-test:
+
+config-test reference
+=====================
+
+``config-test`` - instructs the server to check
+whether the new configuration supplied in the command's arguments can be
+loaded.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.2.0 (built-in)
+
+Description and examples: see :ref:`command-config-test`
+
+Command syntax:
+
+::
+
+ {
+ "command": "config-test",
+ "arguments": {
+ "<server>": {
+ }
+ }
+ }
+
+where <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)" }
+
+The 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 were
+ affected or returned)
+
+.. _reference-config-write:
+
+config-write reference
+======================
+
+``config-write`` - instructs the Kea server to
+write its current configuration to a file on disk.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.2.0 (built-in)
+
+Description and examples: see :ref:`command-config-write`
+
+Command syntax:
+
+::
+
+ {
+ "command": "config-write",
+ "arguments": {
+ "filename": "config-modified-2017-03-15.json"
+ }
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-dhcp-disable:
+
+dhcp-disable reference
+======================
+
+``dhcp-disable`` - globally disables the DHCP service.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (built-in)
+
+Description and examples: see :ref:`command-dhcp-disable`
+
+Command syntax:
+
+::
+
+ {
+ "command": "dhcp-disable",
+ "arguments": {
+ "max-period": 20
+ }
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-dhcp-enable:
+
+dhcp-enable reference
+=====================
+
+``dhcp-enable`` - globally enables the DHCP service.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (built-in)
+
+Description and examples: see :ref:`command-dhcp-enable`
+
+Command syntax:
+
+::
+
+ {
+ "command": "dhcp-enable"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-ha-continue:
+
+ha-continue reference
+=====================
+
+``ha-continue`` - resumes the operation of the
+paused HA state machine.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (:ref:`The High Availability hooks library<commands-high_availability-lib>`)
+
+Description and examples: see :ref:`command-ha-continue`
+
+Command syntax:
+
+::
+
+ {
+ "command": "ha-continue"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-ha-heartbeat:
+
+ha-heartbeat reference
+======================
+
+``ha-heartbeat`` - is sent internally by a Kea partner when
+operating in High Availability (HA) mode; it retrieves the server HA
+state and clock value.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.4.0 (:ref:`The High Availability hooks library<commands-high_availability-lib>`)
+
+Description and examples: see :ref:`ha-server-states`
+
+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 will include the server state (see
+:ref:`ha-server-states` plus the current clock value.
+
+.. _reference-ha-scopes:
+
+ha-scopes reference
+===================
+
+``ha-scopes`` - 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 (:ref:`The High Availability hooks library<commands-high_availability-lib>`)
+
+Description and examples: see :ref:`command-ha-scopes`
+
+Command syntax:
+
+::
+
+ {
+ "command": "ha-scopes",
+ "service": [ <service, typically "dhcp4" or "dhcp6"> ],
+ "arguments": {
+ "scopes": [ "HA_server1", "HA_server2" ]
+ }
+
+In the example given, the arguments configure the server to handle
+traffic from both HA_server1 and HA_server2 scopes.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-ha-sync:
+
+ha-sync reference
+=================
+
+``ha-sync`` - 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 (:ref:`The High Availability hooks library<commands-high_availability-lib>`)
+
+Description and examples: see :ref:`command-ha-sync`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease4-add:
+
+lease4-add reference
+====================
+
+``lease4-add`` - adds a new IPv4 lease administratively.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-add`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease4-del:
+
+lease4-del reference
+====================
+
+``lease4-del`` - deletes a lease from the lease database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "lease4-del",
+ "arguments": {
+ "ip-address": "192.0.2.202"
+ }
+ }
+
+Specify the lease to be deleted either by IP address, or by
+identifier-type and identifier value. Currently supported identifiers
+are "hw-address" and "client-id".
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease4-get:
+
+lease4-get reference
+====================
+
+``lease4-get`` - queries the lease database and retrieves existing leases.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-get`
+
+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 a result of the operation and
+lease details, if found. It has one of the following values: 0
+(success), 1 (error), or 2 (empty).
+
+.. _reference-lease4-get-all:
+
+lease4-get-all reference
+========================
+
+``lease4-get-all`` - retrieves all IPv4 leases
+or all leases for the specified set of subnets.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.4.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-get-all`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease4-update:
+
+lease4-update reference
+=======================
+
+``lease4-update`` - updates existing leases.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-update`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease4-wipe:
+
+lease4-wipe reference
+=====================
+
+``lease4-wipe`` - removes all leases associated with a given subnet.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-wipe`
+
+Command syntax:
+
+::
+
+ {
+ "command": "lease4-wipe",
+ "arguments": {
+ "subnet-id": 44
+ }
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease6-add:
+
+lease6-add reference
+====================
+
+``lease6-add`` - creates a new lease administratively.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-add`
+
+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." }
+ { "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease6-del:
+
+lease6-del reference
+====================
+
+``lease6-del`` - deletes a lease from the lease database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "lease6-del",
+ "arguments": {
+ "ip-address": "192.0.2.202"
+ }
+ }
+
+``lease6-del`` returns a result that indicates a outcome of the operation.
+It has one of the following values: 0 (success), 1 (error), or 3 (empty).
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease6-get:
+
+lease6-get reference
+====================
+
+``lease6-get`` - queries the lease database and retrieves existing leases.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "lease6-get",
+ "arguments": {
+ "ip-address": "2001:db8:1234:ab::",
+ "type": "IA_PD"
+ }
+ }
+
+``lease6-get`` returns a result that indicates a result 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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease6-get-all:
+
+lease6-get-all reference
+========================
+
+``lease6-get-all`` - retrieves all IPv6 leases
+or all leases for the specified set of subnets.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-get-all`
+
+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.
+
+.. _reference-lease6-update:
+
+lease6-update reference
+=======================
+
+``lease6-update`` - updates existing leases.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-update`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-lease6-wipe:
+
+lease6-wipe reference
+=====================
+
+``lease6-wipe`` - removes all leases associated with a given subnet.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Lease Commands hooks library<commands-lease_cmds-lib>`)
+
+Description and examples: see :ref:`command-lease4-wipe`
+
+Command syntax:
+
+::
+
+ {
+ "command": "lease6-wipe",
+ "arguments": {
+ "subnet-id": 66
+ }
+ }
+
+Note: not all backends support this command.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-leases-reclaim:
+
+leases-reclaim reference
+========================
+
+``leases-reclaim`` - 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 :ref:`command-leases-reclaim`
+
+Command syntax:
+
+::
+
+ {
+ "command": "leases-reclaim",
+ "arguments": {
+ "remove": true
+ }
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-libreload:
+
+libreload reference
+===================
+
+``libreload`` - unloads and then loads all currently loaded hook libraries.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.2.0 (built-in)
+
+Description and examples: see :ref:`command-libreload`
+
+Command syntax:
+
+::
+
+ {
+ "command": "libreload",
+ "arguments": { }
+ }
+
+The server will respond with a result of 0 indicating success, or 1
+indicating a failure.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-list-commands:
+
+list-commands reference
+=======================
+
+``list-commands`` - retrieves a list of all commands supported by the server.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.0.0 (built-in)
+
+Description and examples: see :ref:`command-list-commands`
+
+Command syntax:
+
+::
+
+ {
+ "command": "list-commands",
+ "arguments": { }
+ }
+
+The server will respond with a list of all supported commands.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network4-add:
+
+network4-add reference
+======================
+
+``network4-add`` - adds a new shared network.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-add`
+
+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"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network4-del:
+
+network4-del reference
+======================
+
+``network4-del`` - deletes existing shared networks.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "network4-del",
+ "arguments": {
+ "name": "floor13"
+ }
+ }
+
+Response syntax:
+
+::
+
+ {
+ "arguments": {
+ "shared-networks": [
+ {
+ "name": "floor13"
+ }
+ ]
+ },
+ "result": 0,
+ "text": "IPv4 shared network 'floor13' deleted"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network4-get:
+
+network4-get reference
+======================
+
+``network4-get`` - retrieves detailed
+information about shared networks, including subnets currently being
+part of a given network.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-get`
+
+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
+ },
+ {
+ "id": 6,
+ "subnet": "192.0.3.0/31",
+ // many other subnet specific details here
+ }
+ ],
+ "valid-lifetime": 120
+ }
+ ]
+ }
+ }
+
+Note that the actual response contains many additional fields that are
+omitted here for clarity.
+
+.. _reference-network4-list:
+
+network4-list reference
+=======================
+
+``network4-list`` - retrieves the full list of currently configured shared networks.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-list`
+
+Command syntax:
+
+::
+
+ {
+ "command": "network4-list"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "arguments": {
+ "shared-networks": [
+ { "name": "floor1" },
+ { "name": "office" }
+ ]
+ },
+ "result": 0,
+ "text": "2 IPv4 network(s) found"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network4-subnet-add:
+
+network4-subnet-add reference
+=============================
+
+``network4-subnet-add`` - adds existing subnets to existing shared networks.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-subnet-add`
+
+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'"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network4-subnet-del:
+
+network4-subnet-del reference
+=============================
+
+``network4-subnet-del`` - 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 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-subnet-del`
+
+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'"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network6-add:
+
+network6-add reference
+======================
+
+``network6-add`` - adds a new shared network.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-add`
+
+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 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"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network6-del:
+
+network6-del reference
+======================
+
+``network6-del`` - deletes existing shared networks.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "network4-del",
+ "arguments": {
+ "name": "floor13"
+ }
+ }
+
+The ``network6-del`` command uses exactly the same syntax as ``network4-del``
+for both the command and the response.
+
+Response syntax:
+
+::
+
+ {
+ "command": "network4-del",
+ "arguments": {
+ "name": "floor13",
+ "subnets-action": "delete"
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network6-get:
+
+network6-get reference
+======================
+
+``network6-get`` - retrieves detailed
+information about shared networks, including subnets that are currently
+part of a given network.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-get`
+
+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
+ },
+ {
+ "id": 6,
+ "subnet": "192.0.3.0/31",
+ // many other subnet specific details here
+ }
+ ],
+ "valid-lifetime": 120
+ }
+ ]
+ }
+ }
+
+Note that the actual response contains many additional fields that are
+omitted here for clarity.
+
+.. _reference-network6-list:
+
+network6-list reference
+=======================
+
+``network6-list`` - retrieves the full list of currently configured shared networks.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-list`
+
+Command syntax:
+
+::
+
+ {
+ "command": "network4-list"
+ }
+
+The ``network6-list`` command follows 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"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network6-subnet-add:
+
+network6-subnet-add reference
+=============================
+
+``network6-subnet-add`` - adds existing subnets to existing shared networks.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-subnet-add`
+
+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 command and the response.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor1'"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-network6-subnet-del:
+
+network6-subnet-del reference
+=============================
+
+``network6-subnet-del`` - 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 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-network4-subnet-del`
+
+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 command and the response.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-global-parameter4-del:
+
+remote-global-parameter4-del reference
+======================================
+
+``remote-global-parameter4-del`` - deletes a
+global DHCPv4 parameter from the configuration database. The server will
+use 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-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-global-parameter4-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-global-parameter4-del",
+ "arguments": {
+ "parameters": [ <parameter name> ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command carries the list including exactly one name of the
+parameter to be deleted.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv4 global parameter(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-global-parameter4-get:
+
+remote-global-parameter4-get reference
+======================================
+
+``remote-global-parameter4-get`` - fetches the
+selected global parameter for the server from the specified database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-global-parameter4-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-global-parameter4-get"
+ "arguments": {
+ "parameters": [ <parameter name> ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command carries a list including exactly one name of the parameter
+to be fetched.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv4 global parameter found.",
+ "arguments": {
+ "parameters": {
+ <parameter name>: <parameter value>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-global-parameter4-get-all:
+
+remote-global-parameter4-get-all reference
+==========================================
+
+``remote-global-parameter4-get-all`` - fetches all
+global parameters for the server from the specified database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-global-parameter4-get-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-global-parameter4-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 global parameters found.",
+ "arguments": {
+ "parameters": [
+ {
+ <first parameter name>: <first parameter value>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ },
+ {
+ <second parameter name>: <second parameter value>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-global-parameter4-set:
+
+remote-global-parameter4-set reference
+======================================
+
+``remote-global-parameter4-set`` - creates or
+updates one or more global parameters in the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-global-parameter4-set`
+
+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>
+ }
+ }
+ }
+
+This command carries multiple global parameters with their values. Care
+should be taken when specifying more than one parameter, because 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.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv4 global parameter(s) successfully set."
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-global-parameter6-del:
+
+remote-global-parameter6-del reference
+======================================
+
+``remote-global-parameter6-del`` - deletes a
+global DHCPv6 parameter from the configuration database. The server will
+use 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 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-global-parameter4-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-global-parameter6-del",
+ "arguments": {
+ "parameters": [ <parameter name> ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command carries the list including exactly one name of the
+parameter to be deleted.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv6 global parameter(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-global-parameter6-get:
+
+remote-global-parameter6-get reference
+======================================
+
+``remote-global-parameter6-get`` - fetches the
+selected global parameter for the server from the specified database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-global-parameter4-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-global-parameter6-get"
+ "arguments": {
+ "parameters": [ <parameter name> ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command carries a list including exactly one name of the parameter
+to be fetched.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv6 global parameter found.",
+ "arguments": {
+ "parameters": {
+ <parameter name>: <parameter value>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-global-parameter6-get-all:
+
+remote-global-parameter6-get-all reference
+==========================================
+
+``remote-global-parameter6-get-all`` - fetches all
+global parameters for the server from the specified database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-global-parameter4-get-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-global-parameter6-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 global parameters found.",
+ "arguments": {
+ "parameters": [
+ {
+ <first parameter name>: <first parameter value>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ },
+ {
+ <second parameter name>: <second parameter value>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-global-parameter6-set:
+
+remote-global-parameter6-set reference
+======================================
+
+``remote-global-parameter6-set`` - creates or
+updates one or more global DHCP parameters in the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-global-parameter4-set`
+
+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>
+ }
+ }
+ }
+
+This command carries multiple global parameters with their values. Care
+should be taken when specifying more than one parameter, because 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.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv6 global parameter(s) successfully set."
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-network4-del:
+
+remote-network4-del reference
+=============================
+
+``remote-network4-del`` - deletes an IPv4 shared
+network from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-network4-del`
+
+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`` command denotes whether the subnets in
+this shared network should be deleted or not.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 IPv4 shared network(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-network4-get:
+
+remote-network4-get reference
+=============================
+
+``remote-network4-get`` - fetches the selected IPv4
+shared network for the server from the specified database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-network4-get`
+
+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
+specifies whether the subnets belonging to the shared network should
+also be returned.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "IPv4 shared network found.",
+ "arguments": {
+ "shared-networks": [
+ {
+ "name": <shared network name>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-network4-list:
+
+remote-network4-list reference
+==============================
+
+``remote-network4-list`` - fetches a list of all
+IPv4 shared networks from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-network4-list`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-network4-list"
+ "arguments": {
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command contains no arguments besides the optional ``remote``.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "2 IPv4 shared network(s) found.",
+ "arguments": {
+ "shared-networks": [
+ {
+ "name": <first shared network name>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ },
+ {
+ "name": <second shared network name>,
+ "metadata": {
+ "server-tag": <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 complete information about the selected
+shared networks.
+
+.. _reference-remote-network4-set:
+
+remote-network4-set reference
+=============================
+
+``remote-network4-set`` - creates or replaces an
+IPv4 shared network in the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-network4-set`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-network4-set",
+ "arguments": {
+ "shared-networks": [
+ {
+ <shared network specification excluding subnets list>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+The provided list must contain exactly one shared network specification.
+It must not contain subnets ("subnet4" parameter); the subnets are added
+to the shared network using the ``remote-subnet4-set`` command.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "IPv4 shared network successfully set."
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-network6-del:
+
+remote-network6-del reference
+=============================
+
+``remote-network6-del`` - deletes an IPv6 shared
+network from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-network4-del`
+
+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`` command denotes whether the subnets in
+this shared network should be deleted or not.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 IPv6 shared network(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-network6-get:
+
+remote-network6-get reference
+=============================
+
+``remote-network6-get`` - fetches the selected IPv6
+shared network for the server from the specified database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-network4-get`
+
+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
+specifies whether the subnets belonging to the shared network should
+also be returned.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "IPv6 shared network found.",
+ "arguments": {
+ "shared-networks": [
+ {
+ "name": <shared network name>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-network6-list:
+
+remote-network6-list reference
+==============================
+
+``remote-network6-list`` - fetches a list of all
+IPv6 shared networks from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-network4-list`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-network6-list"
+ "arguments": {
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command contains no arguments besides the optional ``remote``.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "2 IPv6 shared network(s) found.",
+ "arguments": {
+ "shared-networks": [
+ {
+ "name": <first shared network name>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ },
+ {
+ "name": <second shared network name>,
+ "metadata": {
+ "server-tag": <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 complete information about the selected
+shared networks.
+
+.. _reference-remote-network6-set:
+
+remote-network6-set reference
+=============================
+
+``remote-network6-set`` - creates or replaces an
+IPv6 shared network in the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-network4-set`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-network6-set",
+ "arguments": {
+ "shared-networks": [
+ {
+ <shared network specification excluding subnets list>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+The provided list must contain exactly one shared network specification.
+It must not contain subnets ("subnet6" parameter); the subnets are added
+to the shared network using the ``remote-subnet6-set`` command.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "IPv6 shared network successfully set."
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-option-def4-del:
+
+remote-option-def4-del reference
+================================
+
+``remote-option-def4-del`` - deletes a DHCPv4
+option definition from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option-def4-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option-def4-del",
+ "arguments": {
+ "option-defs": [ {
+ "code": <option code>,
+ "space": <option space
+ } ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command includes a list with exactly one option definition
+specification comprising an option name and code.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 DHCPv4 option definition(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-option-def4-get:
+
+remote-option-def4-get reference
+================================
+
+``remote-option-def4-get`` - fetches a DHCPv4
+option definition from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option-def4-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option-def4-get",
+ "arguments": {
+ "option-defs": [
+ {
+ "code": <option code>,
+ "space": <option space>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+The desired option definition is identified by the pair of option
+code/space values.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv4 option definition found.",
+ "arguments": {
+ "option-defs": [
+ {
+ <option definition>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ }
+ ],
+ "count": 1
+ }
+ }
+
+The metadata is included and provides database-specific information
+associated with the returned object.
+
+.. _reference-remote-option-def4-get-all:
+
+remote-option-def4-get-all reference
+====================================
+
+``remote-option-def4-get-all`` - fetches all
+DHCPv4 option definitions from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option-def4-get-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option-def4-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": "2 DHCPv4 option definition(s) found.",
+ "arguments": {
+ "option-defs": [
+ {
+ <first option definition>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ },
+ {
+ <second option definition>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-option-def4-set:
+
+remote-option-def4-set reference
+================================
+
+``remote-option-def4-set`` - creates or replaces a
+DHCPv4 option definition in the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option-def4-set`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option-def4-set",
+ "arguments": {
+ "option-defs": [
+ {
+ <option definition specification>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+The provided list must contain exactly one option definition
+specification.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv4 option definition set."
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-option-def6-del:
+
+remote-option-def6-del reference
+================================
+
+``remote-option-def6-del`` - deletes a DHCPv6
+option definition from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option-def4-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option-def6-del",
+ "arguments": {
+ "option-defs": [
+ {
+ "code": <option code>,
+ "space": <option space>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command includes a list with exactly one option definition
+specification comprising an option name and code.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 DHCPv6 option definition(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-option-def6-get:
+
+remote-option-def6-get reference
+================================
+
+``remote-option-def6-get`` - fetches a DHCPv6
+option definition from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option-def4-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option-def6-get",
+ "arguments": {
+ "option-defs": [
+ {
+ "code": <option code>,
+ "space": <option space>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+The desired option definition is identified by the pair of the option
+code/space values.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv6 option definition found.",
+ "arguments": {
+ "option-defs": [
+ {
+ <option definition>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ }
+ ],
+ "count": 1
+ }
+ }
+
+The metadata is included and provides database-specific information
+associated with the returned object.
+
+.. _reference-remote-option-def6-get-all:
+
+remote-option-def6-get-all reference
+====================================
+
+``remote-option-def6-get-all`` - fetches all
+DHCPv6 option definitions from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option-def4-get-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option-def6-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": "2 DHCPv6 option definition(s) found.",
+ "arguments": {
+ "option-defs": [
+ {
+ <first option definition>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ },
+ {
+ <second option definition>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-option-def6-set:
+
+remote-option-def6-set reference
+================================
+
+``remote-option-def6-set`` - creates or replaces a
+DHCPv6 option definition in the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option-def4-set`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option-def6-set",
+ "arguments": {
+ "option-defs": [
+ {
+ <option definition specification>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+The provided list must contain exactly one option definition
+specification.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv6 option definition set."
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-option4-global-del:
+
+remote-option4-global-del reference
+===================================
+
+``remote-option4-global-del`` - deletes a DHCPv4
+global option from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option4-global-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option4-global-del",
+ "arguments": {
+ "options": [
+ {
+ "code": <option code>
+ "space": <option space>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command includes a list with exactly one option specification
+comprising an option name and code.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 DHCPv4 option(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-option4-global-get:
+
+remote-option4-global-get reference
+===================================
+
+``remote-option4-global-get`` - fetches a global
+DHCPv4 option for the server from the specified database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option4-global-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option4-global-get",
+ "arguments": {
+ "options": [
+ {
+ "code": <option code>,
+ "space": <option space>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+
+The option is identified by the pair of option code/space values.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv4 option in found.",
+ "arguments": {
+ "options": [
+ {
+ <option information>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ }
+ ]
+ }
+ }
+
+The metadata is included and provides database-specific information
+associated with the returned object.
+
+.. _reference-remote-option4-global-get-all:
+
+remote-option4-global-get-all reference
+=======================================
+
+``remote-option4-global-get-all`` - fetches all
+DHCPv4 global options for the server from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option4-global-get-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option4-global-get-all",
+ "arguments": {
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command takes no arguments besides the optional ``remote`` map.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "2 DHCPv4 option(s) found.",
+ "arguments": {
+ "options": [
+ {
+ <first option specification>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ },
+ {
+ <second option specification>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-option4-global-set:
+
+remote-option4-global-set reference
+===================================
+
+``remote-option4-global-set`` - creates or
+replaces a DHCPv4 global option in the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option4-global-set`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option4-global-set",
+ "arguments": {
+ "options": [
+ {
+ <global option specification>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+The provided list must contain exactly one option specification.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv4 option set.",
+ "arguments": {
+ "options": [
+ {
+ "code": <option code>,
+ "space": <option space>
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-option6-global-del:
+
+remote-option6-global-del reference
+===================================
+
+``remote-option6-global-del`` - deletes a DHCPv6
+global option from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option4-global-del`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option6-global-del",
+ "arguments": {
+ "options": [
+ {
+ "code": <option code>
+ "space": <option space>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command includes a list with exactly one option specification
+comprising an option name and code.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 DHCPv6 option(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-option6-global-get:
+
+remote-option6-global-get reference
+===================================
+
+``remote-option6-global-get`` - deletes a DHCPv6
+global option from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option4-global-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option6-global-get",
+ "arguments": {
+ "options": [
+ {
+ "code": <option code>,
+ "space": <option space>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+
+The option is identified by the pair of option code/space values.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv6 option found.",
+ "arguments": {
+ "options": [
+ {
+ <option information>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ }
+ ]
+ }
+ }
+
+The metadata is included and provides database-specific information
+associated with the returned object.
+
+.. _reference-remote-option6-global-get-all:
+
+remote-option6-global-get-all reference
+=======================================
+
+``remote-option6-global-get-all`` - fetches all
+DHCPv6 global options for the server from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option4-global-get-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option6-global-get-all",
+ "arguments": {
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command takes no arguments besides the optional ``remote`` map.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "2 DHCPv6 option(s) found.",
+ "arguments": {
+ "options": [
+ {
+ <first option specification>,
+ "metadata": {
+ "server-tag": <server tag>
+ }
+ },
+ {
+ <second option specification>,
+ "metadata": {
+ "server-tag": <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.
+
+.. _reference-remote-option6-global-set:
+
+remote-option6-global-set reference
+===================================
+
+``remote-option6-global-set`` - creates or
+replaces a DHCPv6 global option in the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-option4-global-set`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-option6-global-set",
+ "arguments": {
+ "options": [
+ {
+ <global option specification>
+ }
+ ],
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+The provided list must contain exactly one option specification.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "DHCPv6 option set.",
+ "arguments": {
+ "options": [
+ {
+ "code": <option code>,
+ "space": <option space>
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-subnet4-del-by-id:
+
+remote-subnet4-del-by-id reference
+==================================
+
+``remote-subnet4-del-by-id`` - deletes an IPv4
+subnet by ID from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-del-by-id`
+
+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.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 IPv4 subnet(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-subnet4-del-by-prefix:
+
+remote-subnet4-del-by-prefix reference
+======================================
+
+``remote-subnet4-del-by-prefix`` - deletes an
+IPv4 subnet by prefix from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-del-by-prefix`
+
+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.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 IPv4 subnet(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-subnet4-get-by-id:
+
+remote-subnet4-get-by-id reference
+==================================
+
+``remote-subnet4-get-by-id`` - fetches a selected
+IPv4 subnet by ID for the server from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-get-by-id`
+
+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.
+
+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-tag": <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.
+
+.. _reference-remote-subnet4-get-by-prefix:
+
+remote-subnet4-get-by-prefix reference
+======================================
+
+``remote-subnet4-get-by-prefix`` - fetches a
+selected IPv4 subnet by prefix from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-get-by-prefix`
+
+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.
+
+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-tag": <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.
+
+.. _reference-remote-subnet4-list:
+
+remote-subnet4-list reference
+=============================
+
+``remote-subnet4-list`` - fetches a list of all
+IPv4 subnets from the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-list`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-subnet4-list"
+ "arguments": {
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command includes no arguments besides the optional ``remote`` map.
+
+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-tag": <server tag>
+ }
+ },
+ {
+ "id": <second subnet identifier>,
+ "subnet": <second subnet prefix>,
+ "shared-network-name": <shared network name> | null,
+ "metadata": {
+ "server-tag": <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 complete information
+about the selected subnets.
+
+.. _reference-remote-subnet4-set:
+
+remote-subnet4-set reference
+============================
+
+``remote-subnet4-set`` - creates or replaces an
+IPv4 subnet in the configuration database.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-set`
+
+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>
+ }
+ }
+ }
+
+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 (global subnet), the ``null``
+value must be specified for the shared network name.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "IPv4 subnet successfully set.",
+ "arguments": {
+ "id": <subnet identifier>,
+ "subnet": <subnet prefix>
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-subnet6-del-by-id:
+
+remote-subnet6-del-by-id reference
+==================================
+
+``remote-subnet6-del-by-id`` - deletes an IPv6
+subnet by ID from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-del-by-id`
+
+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.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 IPv6 subnet(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-subnet6-del-by-prefix:
+
+remote-subnet6-del-by-prefix reference
+======================================
+
+``remote-subnet6-del-by-prefix`` - deletes an
+IPv6 subnet by prefix from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-del-by-prefix`
+
+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.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "1 IPv6 subnet(s) deleted.",
+ "arguments": {
+ "count": 1
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-remote-subnet6-get-by-id:
+
+remote-subnet6-get-by-id reference
+==================================
+
+``remote-subnet6-get-by-id`` - fetches a selected
+IPv6 subnet by ID for the server from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-get-by-id`
+
+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.
+
+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-tag": <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.
+
+.. _reference-remote-subnet6-get-by-prefix:
+
+remote-subnet6-get-by-prefix reference
+======================================
+
+``remote-subnet6-get-by-prefix`` - fetches a
+selected IPv6 subnet by prefix from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-get-by-prefix`
+
+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.
+
+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-tag": <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.
+
+.. _reference-remote-subnet6-list:
+
+remote-subnet6-list reference
+=============================
+
+``remote-subnet6-list`` - fetches a list of all
+IPv6 subnets from the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-list`
+
+Command syntax:
+
+::
+
+ {
+ "command": "remote-subnet6-list"
+ "arguments": {
+ "remote": {
+ <specification of the database to connect to>
+ }
+ }
+ }
+
+This command includes no arguments besides the optional ``remote`` map.
+
+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-tag": <server tag>
+ }
+ },
+ {
+ "id": <second subnet identifier>,
+ "subnet": <second subnet prefix>,
+ "shared-network-name": <shared network name> | null,
+ "metadata": {
+ "server-tag": <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 complete information
+about the selected subnets.
+
+.. _reference-remote-subnet6-set:
+
+remote-subnet6-set reference
+============================
+
+``remote-subnet6-set`` - creates or replaces an
+IPv4 subnet in the configuration database.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Configuration Backend Commands hooks library<commands-cb_cmds-lib>`)
+
+Description and examples: see :ref:`command-remote-subnet4-set`
+
+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>
+ }
+ }
+ }
+
+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 (global subnet), the ``null``
+value must be specified for the shared network name.
+
+Response syntax:
+
+::
+
+ {
+ "result": 0,
+ "text": "IPv6 subnet successfully set.",
+ "arguments": {
+ "id": <subnet identifier>,
+ "subnet": <subnet prefix>
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-reservation-add:
+
+reservation-add reference
+=========================
+
+``reservation-add`` - adds a new host reservation. The reservation may
+include an IPv4 address, 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 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
+
+Description and examples: see :ref:`command-reservation-add`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-reservation-del:
+
+reservation-del reference
+=========================
+
+``reservation-del`` - deletes an existing host reservation.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.2.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
+
+Description and examples: see :ref:`command-reservation-del`
+
+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>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-reservation-get:
+
+reservation-get reference
+=========================
+
+``reservation-get`` - attempts to retrieve an existing host reservation.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.2.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
+
+Description and examples: see :ref:`command-reservation-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "reservation-get",
+ "arguments": {
+ "subnet-id": <integer>,
+ "identifier-type": <string with one value out of: hw-address|duid|circuit-id|client-id|flex-id>,
+ "identifier": <string>;
+ }
+ }
+
+The host reservation can be identified by either a (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.
+
+.. _reference-reservation-get-all:
+
+reservation-get-all reference
+=============================
+
+``reservation-get-all`` - retrieves all host reservations for a specified
+subnet.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
+
+Description and examples: see :ref:`command-reservation-get-all`
+
+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.
+
+.. _reference-reservation-get-page:
+
+reservation-get-page reference
+==============================
+
+``reservation-get-page`` - retrieves host reservations for a specified
+subnet by page.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Host Commands hooks library<commands-host_cmds-lib>`)
+
+Description and examples: see :ref:`command-reservation-get-page`
+
+Command syntax:
+
+::
+
+ {
+ "command": "reservation-get-page",
+ "arguments": {
+ "subnet-id": <integer>,
+ "limit": <integer>,
+ "source-index": <integer>,
+ "from": <integer>
+ }
+ }
+
+The "subnet-id" and the "limit" arguments are mandatory. The "limit"
+specifies the maximum number of host reservations to be returned, and
+the "source-index" and "from" arguments should be set to 0 when retrieving
+the first page of host reservations (if they are not specified, they will
+default to 0). To fetch subsequent pages of host reservations, the returned
+values of "source-index" and "from" must be copied from the previous response.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-shutdown:
+
+shutdown reference
+==================
+
+``shutdown`` - instructs the server to initiate its
+shutdown procedure.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.0.0 (built-in)
+
+Description and examples: see :ref:`command-shutdown`
+
+Command syntax:
+
+::
+
+ {
+ "command": "shutdown"
+ }
+
+The server will respond with a confirmation that the shutdown procedure
+has been initiated.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-stat-lease4-get:
+
+stat-lease4-get reference
+=========================
+
+``stat-lease4-get`` - fetches lease
+statistics for a range of known IPv4 subnets.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.4.0 (:ref:`The Supplemental Statistics Commands hooks library<commands-stat_cmds-lib>`)
+
+Description and examples: see :ref:`command-stat-lease4-get`
+
+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"
+ }
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-stat-lease6-get:
+
+stat-lease6-get reference
+=========================
+
+``stat-lease6-get`` - fetches lease
+statistics for a range of known IPv6 subnets.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.4.0 (:ref:`The Supplemental Statistics Commands hooks library<commands-stat_cmds-lib>`)
+
+Description and examples: see :ref:`command-stat-lease4-get`
+
+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"
+ }
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-statistic-get:
+
+statistic-get reference
+=======================
+
+``statistic-get`` - 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 :ref:`command-statistic-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "statistic-get",
+ "arguments": {
+ "name": "pkt4-received"
+ }
+ }
+
+The server will respond with details of the requested statistic, with a
+result set to 0 indicating success and the specified statistic as the
+value of the "arguments" parameter.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-statistic-get-all:
+
+statistic-get-all reference
+===========================
+
+``statistic-get-all`` - retrieves all statistics recorded.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.0.0 (built-in)
+
+Description and examples: see :ref:`command-statistic-get-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "statistic-get-all",
+ "arguments": { }
+ }
+
+The server will respond with 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": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-statistic-remove:
+
+statistic-remove reference
+==========================
+
+``statistic-remove`` - attempts to delete 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 :ref:`command-statistic-remove`
+
+Command syntax:
+
+::
+
+ {
+ "command": "statistic-remove",
+ "arguments": {
+ "name": "pkt4-received"
+ }
+ }
+
+If the specific statistic is found and its removal was successful, the
+server will respond 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 will return a status code of 1 (error) and
+the text field will contain the error description.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-statistic-remove-all:
+
+statistic-remove-all reference
+==============================
+
+``statistic-remove-all`` - attempts to
+delete all statistics.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``
+
+Availability: 1.0.0 (built-in)
+
+Description and examples: see :ref:`command-statistic-remove-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "statistic-remove-all",
+ "arguments": { }
+ }
+
+If the removal of all statistics was successful, the server will respond
+with a status of 0, indicating success, and an empty parameters field. If
+an error is encountered, the server will return a status code of 1
+(error) and the text field will contain the error description.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-statistic-reset:
+
+statistic-reset reference
+=========================
+
+``statistic-reset`` - 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 :ref:`command-statistic-reset`
+
+Command syntax:
+
+::
+
+ {
+ "command": "statistic-reset",
+ "arguments": {
+ "name": "pkt4-received"
+ }
+ }
+
+If the specific statistic is found and the reset was successful, the server
+will respond 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 will return a status code of 1 (error) and
+the text field will contain the error description.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-statistic-reset-all:
+
+statistic-reset-all reference
+=============================
+
+``statistic-reset-all`` - 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 :ref:`command-statistic-reset-all`
+
+Command syntax:
+
+::
+
+ {
+ "command": "statistic-reset-all",
+ "arguments": { }
+ }
+
+If the operation is successful, the server will respond with a status of
+0, indicating success, and an empty parameters field. If an error is
+encountered, the server will return a status code of 1 (error) and the
+text field will contain the error description.
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-subnet4-add:
+
+subnet4-add reference
+=====================
+
+``subnet4-add`` - creates and adds a new subnet to
+the existing server configuration.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet4-add`
+
+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"
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-subnet4-del:
+
+subnet4-del reference
+=====================
+
+``subnet4-del`` - removes a subnet from the
+server's configuration. This command has no effect on other configured
+subnets, but administrators should exercise caution when
+using this command as removing a subnet may have unintended consequences.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet4-del`
+
+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"
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-subnet4-get:
+
+subnet4-get reference
+=====================
+
+``subnet4-get`` - retrieves detailed information
+about the specified subnet. This command usually follows the
+``subnet4-list`` command, which is used to discover available subnets with their
+respective subnet identifiers and prefixes.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet4-get`
+
+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": [
+ ....
+ ]
+ ...
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-subnet4-list:
+
+subnet4-list reference
+======================
+
+``subnet4-list`` - lists all currently configured
+subnets. The subnets are returned in a brief form, i.e. a subnet
+identifier and subnet prefix are included for each subnet.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet4-list`
+
+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.
+
+.. _reference-subnet4-update:
+
+subnet4-update reference
+========================
+
+``subnet4-update`` - updates a subnet in the
+existing server configuration.
+
+Supported by: ``kea-dhcp4``
+
+Availability: 1.6.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet4-update`
+
+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"
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-subnet6-add:
+
+subnet6-add reference
+=====================
+
+``subnet6-add`` - 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 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet6-add`
+
+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"
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-subnet6-del:
+
+subnet6-del reference
+=====================
+
+``subnet6-del`` - removes a subnet from the
+server's configuration. This command has no effect on other configured
+subnets, but administrators should exercise caution when
+using this command as removing a subnet may have unintended consequences.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet6-del`
+
+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"
+ }
+ ]
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-subnet6-get:
+
+subnet6-get reference
+=====================
+
+``subnet6-get`` - retrieves detailed information
+about the specified subnet. This command usually follows the
+``subnet6-list`` command, which is used to discover available subnets with their
+respective subnet identifiers and prefixes.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet6-get`
+
+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": [
+ ...
+ ]
+ ....
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-subnet6-list:
+
+subnet6-list reference
+======================
+
+``subnet6-list`` - lists all currently configured
+subnets. The subnets are returned in a brief form, i.e. a subnet
+identifier and subnet prefix are included for each subnet.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.3.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet6-list`
+
+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.
+
+.. _reference-subnet6-update:
+
+subnet6-update reference
+========================
+
+``subnet6-update`` - updates a subnet in the
+existing server configuration. This operation has no impact on other
+subnets.
+
+Supported by: ``kea-dhcp6``
+
+Availability: 1.6.0 (:ref:`The Subnet Commands hooks library<commands-subnet_cmds-lib>`)
+
+Description and examples: see :ref:`command-subnet6-update`
+
+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"
+ }
+ ]
+ }
+ }
+
+The 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 were
+ affected or returned)
+
+.. _reference-version-get:
+
+version-get reference
+=====================
+
+``version-get`` - returns extended information
+about the Kea version in operation. The returned string is the same as if Kea were
+run with the -V command-line option.
+
+Supported by: ``kea-dhcp4``, ``kea-dhcp6``, ``kea-dhcp-ddns``,
+``kea-ctrl-agent``
+
+Availability: 1.2.0 (built-in)
+
+Description and examples: see :ref:`command-version-get`
+
+Command syntax:
+
+::
+
+ {
+ "command": "version-get"
+ }
+
+Response syntax:
+
+::
+
+ {
+ "result": <integer>,
+ "text": <string>
+ }
+
+The 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 were
+ affected or returned)
--- /dev/null
+.. _logging:
+
+*******
+Logging
+*******
+
+Logging Configuration
+=====================
+
+During its operation Kea may produce many messages. They differ in
+severity (some are more important than others) and source (different
+components, like hooks, produce different messages). It is useful to
+understand which log messages are critical and which are not, and to
+configure logging appropriately. For example, debug-level messages
+can be safely ignored in a typical deployment. They are, however, very
+useful when debugging a problem.
+
+The logging system in Kea is configured through the loggers entry in the
+server section of your configuration file. In previous Kea releases this
+entry was in an independent Logging section; this is still supported for
+backward compatibility.
+
+Loggers
+-------
+
+Within Kea, a message is logged through an entity called a "logger."
+Different components log messages through different loggers, and each
+logger can be configured independently of the others. Some components,
+in particular the DHCP server processes, may use multiple loggers to log
+messages pertaining to different logical functions of the component. For
+example, the DHCPv4 server uses one logger for messages about packet
+reception and transmission, another logger for messages related to lease
+allocation, and so on. Some of the libraries used by the Kea server,
+such as libdhcpsrv, use their own loggers.
+
+Users implementing hooks libraries (code attached to the server at
+runtime) are responsible for creating the loggers used by those
+libraries. Such loggers should have unique names, different from the
+logger names used by Kea. In this way the messages produced by the hooks
+library can be distinguished from messages issued by the core Kea code.
+Unique names also allow the loggers to be configured independently of
+loggers used by Kea. Whenever it makes sense, a hooks library can use
+multiple loggers to log messages pertaining to different logical parts
+of the library.
+
+In the server section of a configuration file the
+configuration for zero or more loggers (including loggers used by the
+proprietary hooks libraries) can be specified. If there are no loggers specified, the
+code will use default values; these cause Kea to log messages of INFO
+severity or greater to standard output. There is a small time window
+after Kea has been started but before it has read its configuration;
+logging in this short period can be controlled using environment
+variables. For details, see :ref:`logging-during-startup`.
+
+The three main elements of a logger configuration are: ``name`` (the
+component that is generating the messages), ``severity`` (what to log),
+and ``output_commands`` (where to log). There is also a ``debuglevel``
+element, which is only relevant if debug-level logging has been
+selected.
+
+The name (string) Logger
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each logger in the system has a name: that of the component binary file
+using it to log messages. For instance, to configure logging
+for the DHCPv4 server, add an entry for a logger named “kea-dhcp4”.
+This configuration will then be used by the loggers in the DHCPv4
+server and all the libraries used by it, unless a library defines its
+own logger and there is a specific logger configuration that applies to
+that logger.
+
+When tracking down an issue with the server's operation, use of DEBUG
+logging is required to obtain the verbose output needed for problem
+diagnosis. However, the high verbosity is likely to overwhelm the
+logging system in cases where the server is processing high-volume
+traffic. To mitigate this problem, Kea can use multiple loggers, for
+different functional parts of the server, that can each be configured
+independently. If the user is reasonably confident that a problem
+originates in a specific function of the server, or that the problem is
+related to a specific type of operation, they may enable high verbosity
+only for the relevant logger, thereby limiting the debug messages to the
+required minimum.
+
+The loggers are associated with a particular library or binary of Kea.
+However, each library or binary may (and usually does) include multiple
+loggers. For example, the DHCPv4 server binary contains separate loggers
+for packet parsing, dropped packets, callouts, etc.
+
+The loggers form a hierarchy. For each program in Kea, there is a "root"
+logger, named after the program (e.g. the root logger for kea-dhcp, the
+DHCPv4 server) is named kea-dhcp4. All other loggers are children of
+this logger and are named accordingly, e.g. the allocation engine in the
+DHCPv4 server logs messages using a logger called
+kea-dhcp4.alloc-engine.
+
+This relationship is important, as each child logger derives its default
+configuration from its parent root logger. In the typical case, the root
+logger configuration is the only logging configuration specified in the
+configuration file and so applies to all loggers. If an entry is made
+for a given logger, any attributes specified override those of the root
+logger, whereas any not specified are inherited from it.
+
+To illustrate this, suppose we are using the DHCPv4 server with the
+root logger “kea-dhcp4” logging at the INFO level. In order to enable
+DEBUG verbosity for DHCPv4 packet drops, we must create a configuration
+entry for the logger called “kea-dhcp4.bad-packets” and specify severity
+DEBUG for this logger. All other configuration parameters may be omitted
+for this logger if the logger should use the default values specified in
+the root logger's configuration.
+
+If there are multiple logger specifications in the configuration that
+might match a particular logger, the specification with the more
+specific logger name takes precedence. For example, if there are entries
+for both “kea-dhcp4” and “kea-dhcp4.dhcpsrv”, the main DHCPv4 server
+program — and all libraries it uses other than the dhcpsrv library
+(libdhcpsrv) — will log messages according to the configuration in the
+first entry (“kea-dhcp4”). Messages generated by the dhcpsrv library
+will be logged according to the configuration set by the second entry.
+
+Currently defined loggers are defined in the following table. The
+"Software Package" column of this table specifies whether the particular
+loggers belong to the core Kea code (open source Kea binaries and
+libraries), or hooks libraries (open source or premium).
+
+.. table:: List of Loggers Supported by Kea Servers and Hooks Libraries Shipped With Kea and Premium Packages
+
+ +----------------------------------+------------------------+--------------------------------+
+ | Logger Name | Software Package | Description |
+ +==================================+========================+================================+
+ | ``kea-ctrl-agent`` | core | The root logger for |
+ | | | the Control Agent |
+ | | | exposing the RESTful |
+ | | | control API. All |
+ | | | components used by |
+ | | | the Control Agent |
+ | | | inherit the settings |
+ | | | from this logger. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-ctrl-agent.http`` | core | A logger which |
+ | | | outputs log messages |
+ | | | related to receiving, |
+ | | | parsing, and sending |
+ | | | HTTP messages. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4`` | core | The root logger for |
+ | | | the DHCPv4 server. |
+ | | | All components used |
+ | | | by the DHCPv4 server |
+ | | | inherit the settings |
+ | | | from this logger. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp6`` | core | The root logger for |
+ | | | the DHCPv6 server. |
+ | | | All components used |
+ | | | by the DHCPv6 server |
+ | | | inherit the settings |
+ | | | from this logger. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.alloc-engine``, | core | Used by the lease |
+ | ``kea-dhcp6.alloc-engine`` | | allocation engine, |
+ | | | which is responsible |
+ | | | for managing leases |
+ | | | in the lease |
+ | | | database, i.e. |
+ | | | creating, modifying, |
+ | | | and removing DHCP |
+ | | | leases as a result of |
+ | | | processing messages |
+ | | | from clients. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.bad-packets``, | core | Used by the DHCP |
+ | ``kea-dhcp6.bad-packets`` | | servers for logging |
+ | | | inbound client |
+ | | | packets that were |
+ | | | dropped or to which |
+ | | | the server responded |
+ | | | with a DHCPNAK. It |
+ | | | allows administrators |
+ | | | to configure a |
+ | | | separate log output |
+ | | | that contains only |
+ | | | packet drop and |
+ | | | reject entries. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.callouts``, | core | Used to log messages |
+ | ``kea-dhcp6.callouts`` | | pertaining to the |
+ | | | callouts registration |
+ | | | and execution for the |
+ | | | particular hook |
+ | | | point. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.commands``, | core | Used to log messages |
+ | ``kea-dhcp6.commands`` | | relating to the |
+ | | | handling of commands |
+ | | | received by the DHCP |
+ | | | server over the |
+ | | | command channel. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.database``, | core | Used to log messages |
+ | ``kea-dhcp6.database`` | | relating to general |
+ | | | operations on the |
+ | | | relational databases |
+ | | | and Cassandra. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.ddns``, | core | Used by the DHCP |
+ | ``kea-dhcp6.ddns`` | | server to log |
+ | | | messages related to |
+ | | | Client FQDN and |
+ | | | Hostname option |
+ | | | processing. It also |
+ | | | includes log messages |
+ | | | related to the |
+ | | | relevant DNS updates. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.dhcp4`` | core | Used by the DHCPv4 |
+ | | | server daemon to log |
+ | | | basic operations. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.dhcpsrv``, | core | The base loggers for |
+ | ``kea-dhcp6.dhcpsrv`` | | the libkea-dhcpsrv |
+ | | | library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.eval``, | core | Used to log messages |
+ | ``kea-dhcp6.eval`` | | relating to the |
+ | | | client classification |
+ | | | expression evaluation |
+ | | | code. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.host-cache-hooks``, | libdhcp_host_cache | This logger is used |
+ | ``kea-dhcp6.host-cache-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the Host |
+ | | | Cache hooks library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.flex-id-hooks``, | libdhcp_flex_id | This logger is used |
+ | ``kea-dhcp6.flex-id-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Flexible Identifiers |
+ | | | hooks library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.ha-hooks``, | libdhcp_ha hook | This logger is used |
+ | ``kea-dhcp6.ha-hooks`` | library | to log messages |
+ | | | related to the |
+ | | | operation of the High |
+ | | | Availability hooks |
+ | | | library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.hooks``, | core | Used to log messages |
+ | ``kea-dhcp6.hooks`` | | related to the |
+ | | | management of hooks |
+ | | | libraries, e.g. |
+ | | | registration and |
+ | | | deregistration of the |
+ | | | libraries, and to the |
+ | | | initialization of the |
+ | | | callouts execution |
+ | | | for various hook |
+ | | | points within the |
+ | | | DHCP server. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.host-cmds-hooks``, | libdhcp_host_cmds | This logger is used |
+ | ``kea-dhcp6.host-cmds-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the Host |
+ | | | Commands hooks |
+ | | | library. In general, |
+ | | | these will pertain to |
+ | | | the loading and |
+ | | | unloading of the |
+ | | | library and the |
+ | | | execution of commands |
+ | | | by the library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.hosts``, | core | Used within the |
+ | ``kea-dhcp6.hosts`` | | libdhcpsrv, it logs |
+ | | | messages related to |
+ | | | the management of |
+ | | | DHCP host |
+ | | | reservations, i.e. |
+ | | | retrieving |
+ | | | reservations and |
+ | | | adding new |
+ | | | reservations. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.lease-cmds-hooks``, | libdhcp_lease_cmds | This logger is used |
+ | ``kea-dhcp6.lease-cmds-hooks`` | hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Lease Commands hooks |
+ | | | library. In general, |
+ | | | these will pertain to |
+ | | | the loading and |
+ | | | unloading of the |
+ | | | library and the |
+ | | | execution of commands |
+ | | | by the library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.leases``, | core | Used by the DHCP |
+ | ``kea-dhcp6.leases`` | | server to log |
+ | | | messages related to |
+ | | | lease allocation. The |
+ | | | messages include |
+ | | | detailed information |
+ | | | about the allocated |
+ | | | or offered leases, |
+ | | | errors during the |
+ | | | lease allocation, |
+ | | | etc. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.legal-log-hooks``, | libdhcp_legal_log | This logger is used |
+ | ``kea-dhcp6.legal-log-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Forensic Logging |
+ | | | hooks library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.options``, | core | Used by the DHCP |
+ | ``kea-dhcp4.options`` | | server to log |
+ | | | messages related to |
+ | | | the processing of |
+ | | | options in the DHCP |
+ | | | messages, i.e. |
+ | | | parsing options, |
+ | | | encoding options into |
+ | | | on-wire format, and |
+ | | | packet classification |
+ | | | using options |
+ | | | contained in the |
+ | | | received packets. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.packets``, | core | This logger is mostly |
+ | ``kea-dhcp6.packets`` | | used to log messages |
+ | | | related to |
+ | | | transmission of the |
+ | | | DHCP packets, i.e. |
+ | | | packet reception and |
+ | | | the sending of a |
+ | | | response. Such |
+ | | | messages include |
+ | | | information about the |
+ | | | source and |
+ | | | destination IP |
+ | | | addresses and |
+ | | | interfaces used to |
+ | | | transmit packets. The |
+ | | | logger is also used |
+ | | | to log messages |
+ | | | related to subnet |
+ | | | selection, as this |
+ | | | selection is usually |
+ | | | based on the IP |
+ | | | addresses, relay |
+ | | | addresses, and/or |
+ | | | interface names, |
+ | | | which can be |
+ | | | retrieved from the |
+ | | | received packet even |
+ | | | before the DHCP |
+ | | | message carried in |
+ | | | the packet is parsed. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.radius-hooks``, | libdhcp_radius | This logger is used |
+ | ``kea-dhcp6.radius-hooks`` | premium hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | RADIUS hooks library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.stat-cmds-hooks``, | libdhcp_stat_cmds | This logger is used |
+ | ``kea-dhcp6.stat-cmds-hooks`` | hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Statistics Commands |
+ | | | hooks library. In |
+ | | | general, these will |
+ | | | pertain to loading |
+ | | | and unloading the |
+ | | | library and the |
+ | | | execution of commands |
+ | | | by the library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.subnet-cmds-hooks``, | libdhcp_subnet_cmds | This logger is used |
+ | ``kea-dhcp6.subnet-cmds-hooks`` | hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | Subnet Commands hooks |
+ | | | library. In general, |
+ | | | these will pertain to |
+ | | | loading and unloading |
+ | | | the library and the |
+ | | | execution of commands |
+ | | | by the library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp4.mysql-cb-hooks``, | libdhcp_mysql_cb_hooks | This logger is used |
+ | ``kea-dhcp6.mysql-cb-hooks`` | hook library | to log messages |
+ | | | related to the |
+ | | | operation of the |
+ | | | MySQL Configuration |
+ | | | Backend hooks |
+ | | | library. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp-ddns`` | core | The root logger for |
+ | | | the kea-dhcp-ddns |
+ | | | daemon. All |
+ | | | components used by |
+ | | | this daemon inherit |
+ | | | the settings from |
+ | | | this logger unless |
+ | | | there are |
+ | | | configurations for |
+ | | | more specialized |
+ | | | loggers. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp-ddns.dctl`` | core | The logger used by |
+ | | | the kea-dhcp-ddns |
+ | | | daemon for logging |
+ | | | basic information |
+ | | | about the process, |
+ | | | received signals, and |
+ | | | triggered |
+ | | | reconfigurations. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp-ddns.dhcpddns`` | core | The logger used by |
+ | | | the kea-dhcp-ddns |
+ | | | daemon for logging |
+ | | | events related to |
+ | | | DDNS operations. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp-ddns.dhcp-to-d2`` | core | Used by the |
+ | | | kea-dhcp-ddns daemon |
+ | | | for logging |
+ | | | information about |
+ | | | events dealing with |
+ | | | receiving messages |
+ | | | from the DHCP servers |
+ | | | and adding them to |
+ | | | the queue for |
+ | | | processing. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-dhcp-ddns.d2-to-dns`` | core | Used by the |
+ | | | kea-dhcp-ddns daemon |
+ | | | for logging |
+ | | | information about |
+ | | | events dealing with |
+ | | | sending and receiving |
+ | | | messages to and from |
+ | | | the DNS servers. |
+ +----------------------------------+------------------------+--------------------------------+
+ | ``kea-netconf`` | core | The root logger for |
+ | | | the NETCONF agent. |
+ | | | All components used |
+ | | | by NETCONF inherit |
+ | | | the settings from |
+ | | | this logger if there |
+ | | | is no specialized |
+ | | | logger provided. |
+ +----------------------------------+------------------------+--------------------------------+
+
+Note that user-defined hook libraries should not use any of the loggers
+mentioned above, but should instead define new loggers with names that
+correspond to the libraries using them. Suppose that a user created
+a library called “libdhcp-packet-capture” to dump packets received and
+transmitted by the server to a file. An appropriate name for the
+logger could be ``kea-dhcp4.packet-capture-hooks``. (Note that the hook
+library implementer only specifies the second part of this name, i.e.
+“packet-capture”. The first part is a root-logger name and is prepended
+by the Kea logging system.) It is also important to note that since this
+new logger is a child of a root logger, it inherits the configuration
+from the root logger, something that can be overridden by an entry in
+the configuration file.
+
+The easiest way to find a logger name is to configure all logging to go
+to a single destination and look there for specific logger names. See
+:ref:`logging-message-format` for details.
+
+The severity (string) Logger
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This specifies the category of messages logged. Each message is logged
+with an associated severity, which may be one of the following (in
+descending order of severity):
+
+- FATAL - associated with messages generated by a condition that is so
+ serious that the server cannot continue executing.
+
+- ERROR - associated with messages generated by an error condition. The
+ server will continue executing, but the results may not be as
+ expected.
+
+- WARN - indicates an out-of-the-ordinary condition. However, the
+ server will continue executing normally.
+
+- INFO - an informational message marking some event.
+
+- DEBUG - messages produced for debugging purposes.
+
+When the severity of a logger is set to one of these values, it will
+only log messages of that severity and above (e.g. setting the logging
+severity to INFO will log INFO, WARN, ERROR, and FATAL messages). The
+severity may also be set to NONE, in which case all messages from that
+logger are inhibited.
+
+.. note::
+
+ The ``keactrl`` tool, described in :ref:`keactrl`, can be configured
+ to start the servers in verbose mode. If this is the case, the
+ settings of the logging severity in the configuration file will have
+ no effect; the servers will use a logging severity of DEBUG
+ regardless of the logging settings specified in the configuration
+ file. To control severity via the configuration file,
+ please make sure that the ``kea_verbose`` value is set to "no" within
+ the ``keactrl`` configuration.
+
+The debuglevel (integer) Logger
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a logger's severity is set to DEBUG, this value specifies what
+level of debug messages should be printed. It ranges from 0 (least
+verbose) to 99 (most verbose). If severity for the logger is not DEBUG,
+this value is ignored.
+
+The output_options (list) Logger
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each logger can have zero or more ``output_options``. These specify
+where log messages are sent and are explained in detail below.
+
+The output (string) Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This value determines the type of output. There are several special
+values allowed here: ``stdout`` (messages are printed on standard
+output), ``stderr`` (messages are printed on stderr), ``syslog``
+(messages are logged to syslog using the default name), ``syslog:name``
+(messages are logged to syslog using a specified name). Any other value is
+interpreted as a filename to which messages should be written.
+
+The flush (true of false) Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Flush buffers after each log message. Doing this will reduce performance
+but will ensure that if the program terminates abnormally, all messages
+up to the point of termination are output. The default is "true".
+
+The maxsize (integer) Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This option is only relevant when the destination is a file; this is the maximum size
+in bytes that a log file may reach. When the maximum size is reached,
+the file is renamed and a new file opened. For example, a ".1" is
+appended to the name; if a ".1" file exists, it is renamed ".2", etc.
+This is referred to as rotation.
+
+The default value is 10240000 (10MB). The smallest value that can be
+specified without disabling rotation is 204800. Any value less than
+this, including 0, disables rotation.
+
+.. note::
+
+ Due to a limitation of the underlying logging library (log4cplus),
+ rolling over the log files (from ".1" to ".2", etc) may show odd
+ results; there can be multiple small files at the timing of rollover.
+ This can happen when multiple processes try to roll over the
+ files simultaneously. Version 1.1.0 of log4cplus solved this problem,
+ so if this version or later of log4cplus is used to build Kea, the
+ issue should not occur. Even for older versions, it is normally
+ expected to happen rarely unless the log messages are produced very
+ frequently by multiple different processes.
+
+The maxver (integer) Option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This option is only relevant when the destination is a file and rotation is enabled
+(i.e. maxsize is large enough). This is the maximum number of rotated
+versions that will be kept. Once that number of files has been reached,
+the oldest file, "log-name.maxver", will be discarded each time the log
+rotates. In other words, at most there will be the active log file plus
+maxver rotated files. The minimum and default value is 1.
+
+Example Logger Configurations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this example we want to set the server logging to write to the
+console using standard output.
+
+::
+
+ "Server": {
+ "loggers": [
+ {
+ "name": "kea-dhcp4",
+ "output_options": [
+ {
+ "output": "stdout"
+ }
+ ],
+ "severity": "WARN"
+ }
+ ]
+ }
+
+In this second example, we want to store debug log messages in a file
+that is at most 2MB and keep up to eight copies of old logfiles. Once the
+logfile grows to 2MB, it will be renamed and a new file will be created.
+
+::
+
+ "Server": {
+ "loggers": [
+ {
+ "name": "kea-dhcp6",
+ "output_options": [
+ {
+ "output": "/var/log/kea-debug.log",
+ "maxver": 8,
+ "maxsize": 204800,
+ "flush": true
+ }
+ ],
+ "severity": "DEBUG",
+ "debuglevel": 99
+ }
+ ]
+ }
+
+.. _logging-message-format:
+
+Logging Message Format
+----------------------
+
+Each message written to the configured logging destinations comprises a
+number of components that identify the origin of the message and, if the
+message indicates a problem, information about the problem that may be
+useful in fixing it.
+
+Consider the message below logged to a file:
+
+::
+
+ 2014-04-11 12:58:01.005 INFO [kea-dhcp4.dhcpsrv/27456]
+ DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4
+
+Note: the layout of messages written to the system logging file (syslog)
+may be slightly different. This message has been split across two lines
+here for display reasons; in the logging file, it will appear on one
+line.
+
+The log message comprises a number of components:
+
+2014-04-11 12:58:01.005
+ The date and time at which the message was generated.
+
+INFO
+ The severity of the message.
+
+[kea-dhcp4.dhcpsrv/27456]
+ The source of the message. This includes two elements: the Kea
+ process generating the message (in this case, ``kea-dhcp4``) and the
+ component within the program from which the message originated
+ (``dhcpsrv``, which is the name of the common library used by DHCP
+ server implementations). The number after the slash is a process ID
+ (PID).
+
+DHCPSRV_MEMFILE_DB
+ The message identification. Every message in Kea has a unique
+ identification, which can be used as an index to the `Kea Messages
+ Manual <https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html>`__,
+ where more information can be obtained.
+
+opening memory file lease database: type=memfile universe=4
+ A brief description. Within this text, information relating to the
+ condition that caused the message to be logged will be included. In
+ this example, the information is logged that the in-memory lease
+ database backend will be used to store DHCP leases.
+
+.. _logging-during-startup:
+
+Logging During Kea Startup
+--------------------------
+
+The logging configuration is specified in the configuration file.
+However, when Kea starts, the configuration file is not read until partway into the
+initialization process. Prior to that, the logging settings are set to
+default values, although it is possible to modify some aspects of the
+settings by means of environment variables. Note that in the absence of
+any logging configuration in the configuration file, the settings of the
+(possibly modified) default configuration will persist while the program
+is running.
+
+The following environment variables can be used to control the behavior
+of logging during startup:
+
+KEA_LOCKFILE_DIR
+ Specifies a directory where the logging system should create its lock
+ file. If not specified, it is prefix/var/run/kea, where "prefix"
+ defaults to /usr/local. This variable must not end with a slash.
+ There is one special value: "none", which instructs Kea not to create
+ a lock file at all. This may cause issues if several processes log to
+ the same file.
+
+KEA_LOGGER_DESTINATION
+ Specifies logging output. There are several special values:
+
+ stdout
+ Log to standard output.
+
+ stderr
+ Log to standard error.
+
+ syslog[:fac]
+ Log via syslog. The optional fac (which is separated from the word
+ "syslog" by a colon) specifies the facility to be used for the log
+ messages. Unless specified, messages will be logged using the
+ facility "local0".
+
+ Any other value is treated as a name of the output file. If not
+ specified otherwise, Kea will log to standard output.
--- /dev/null
+.. _netconf:
+
+********************
+YANG/NETCONF Support
+********************
+
+.. _netconf-overview:
+
+Overview
+========
+
+Kea 1.5.0 introduced optional support for a YANG/NETCONF interface with
+the new ``kea-netconf`` NETCONF agent.
+
+This bare-bones documentation is a work in progress. Its current purpose
+is to let engineers joining the project or perhaps advanced early
+adopters to get up to speed quickly.
+
+.. _netconf-install:
+
+Installing NETCONF
+==================
+
+Note that to get its NETCONF capabilities, Kea uses Sysrepo, which has
+many dependencies. Unfortunately, some of them are not available as
+packages and need to be compiled manually.
+
+Please note that building libyang requires a minimum gcc version of at
+least 4.9, so on some environments - like CentOS 7.5 - the system
+compiler cannot be used.
+
+The following sections provide installation instructions for Ubuntu
+18.04 and CentOS 7.5. Due to a more modern compiler and many available
+packages, the installation procedure is much simpler on Ubuntu.
+
+.. _netconf-ubuntu-install:
+
+Installing NETCONF on Ubuntu 18.04
+----------------------------------
+
+For detailed installation instructions, see the `Ubuntu installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/ubuntu-installation-notes>`__.
+
+.. _netconf-centos-install:
+
+Installing NETCONF on CentOS 7.5
+--------------------------------
+
+For detailed installation instructions, see the `CentOS installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/centos-installation-notes>`__.
+
+CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some Sysrepo
+dependencies require at least version 4.9, which unfortunately means
+that a new compiler has to be installed. Also, many of the Sysrepo
+dependencies are not avalable in CentOS as packages, so for the time
+being they must be installed from sources.
+
+Quick Sysrepo Overview
+======================
+
+This section offers a rather brief overview of a subset of available
+functions in Sysrepo. For more complete information, see the `Sysrepo
+homepage <https://www.sysrepo.org>`__.
+
+In YANG, configurations and state data are described in the YANG syntax
+in module files named: ``"module-name"``\ ``[@"revision"]``.yang
+
+The revision part is optional and has YYYY-MM-DD format. An alternate
+XML syntax YIN is defined but less user-friendly. Top-level modules are
+named in Kea models (a short version of schema models).
+
+To list the currently installed YANG modules:
+
+.. code-block:: console
+
+ $ sysrepoctl -l
+
+After installation the result should be similar to this:
+
+::
+
+ Sysrepo schema directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/yang/
+ Sysrepo data directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/data/
+ (Do not alter contents of these directories manually)
+
+ Module Name | Revision | Conformance | Data Owner | Permissions | Submodules | Enabled Features
+ ---------------------------------------------------------------------------------------------------------------------------
+ ietf-netconf-notifications | 2012-02-06 | Installed | root:root | 666 | |
+ ietf-netconf | 2011-06-01 | Imported | | | |
+ ietf-netconf-acm | 2012-02-22 | Imported | | | |
+ nc-notifications | 2008-07-14 | Installed | root:root | 666 | |
+ notifications | 2008-07-14 | Installed | root:root | 666 | |
+ turing-machine | 2013-12-27 | Installed | root:root | 666 | |
+ iana-if-type | 2014-05-08 | Installed | | | |
+ ietf-interfaces | 2014-05-08 | Installed | root:root | 666 | |
+ ietf-ip | 2014-06-16 | Installed | | | |
+
+There are two major modules that Kea is able to support:
+kea-dhcp4-server and kea-dhcp6-server. Note that while there is an
+active effort in the DHC working group at IETF to develop a DHCPv6 YANG
+model, a similar initiative in the past for DHCPv4 failed. Therefore,
+Kea uses its own dedicated models for DHCPv4 and DHCPv6 but partially
+supports the IETF model for DHCPv6. Those three models have extra
+modules as dependencies. The dependency modules are also provided in
+``src/share/yang/modules`` in sources and in ``share/kea/yang/modules``
+after installation.
+
+To install modules from sources, do the following:
+
+.. code-block:: console
+
+ $ cd src/share/yang/modules
+ $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang
+ $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp4-server*.yang
+ $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp6-server*.yang
+ ...
+
+Note that the first -s parameter specifies the location of the YANG
+schema repository; it can be verified with sysrepoctl -l. This is a
+parameter that is configured during Sysrepo compilation and is detected
+by the Kea configuration under the SYSREPO_REPO name.
+
+The installation should look similar to the following:
+
+.. code-block:: console
+
+ $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang
+ Installing a new module from file 'ietf-dhcpv6-server@2018-11-20.yang'...
+ Installing the YANG file to '/home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ietf-dhcpv6-server@2018-07-14.yang'...
+ Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-dhcpv6-options'...
+ Installing the YANG file to '/home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ietf-dhcpv6-options@2018-07-14.yang'...
+ Resolving dependency: 'ietf-dhcpv6-options' imports 'ietf-dhcpv6-types'...
+ Installing the YANG file to '/home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ietf-dhcpv6-types@2018-07-14.yang'...
+ Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-dhcpv6-types'...
+ Installing the YANG file to '/home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ietf-dhcpv6-types@2018-07-14.yang'...
+ Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-interfaces'...
+ Schema of the module ietf-interfaces is already installed, skipping...
+ Installing data files for module 'ietf-dhcpv6-server'...
+ Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-dhcpv6-options'...
+ Skipping installation of data files for module 'ietf-dhcpv6-options'...
+ Resolving dependency: 'ietf-dhcpv6-options' imports 'ietf-dhcpv6-types'...
+ Skipping installation of data files for module 'ietf-dhcpv6-types'...
+ Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-dhcpv6-types'...
+ Skipping installation of data files for module 'ietf-dhcpv6-types'...
+ Resolving dependency: 'ietf-dhcpv6-server' imports 'ietf-interfaces'...
+ Installing data files for module 'ietf-interfaces'...
+ Notifying sysrepo about the change...
+ Install operation completed successfully.
+
+It is possible to confirm whether the models are imported correctly by using
+sysrepoctl -l:
+
+.. code-block:: console
+
+ $ sysrepoctl -l
+ Sysrepo schema directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/yang/
+ Sysrepo data directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/data/
+ (Do not alter contents of these directories manually)
+
+ Module Name | Revision | Conformance | Data Owner | Permissions | Submodules | Enabled Features
+ ---------------------------------------------------------------------------------------------------------------------------
+ ietf-netconf-notifications | 2012-02-06 | Installed | root:root | 666 | |
+ ietf-netconf | 2011-06-01 | Imported | | | |
+ ietf-netconf-acm | 2012-02-22 | Imported | | | |
+ nc-notifications | 2008-07-14 | Installed | root:root | 666 | |
+ notifications | 2008-07-14 | Installed | root:root | 666 | |
+ turing-machine | 2013-12-27 | Installed | root:root | 666 | |
+ iana-if-type | 2014-05-08 | Installed | | | |
+ ietf-interfaces | 2014-05-08 | Installed | root:root | 666 | |
+ ietf-ip | 2014-06-16 | Installed | | | |
+ kea-dhcp4-server | 2018-11-20 | Installed | root:root | 666 | |
+ kea-dhcp6-server | 2018-11-20 | Installed | root:root | 666 | |
+ ietf-dhcpv6-server | 2018-09-04 | Installed | root:root | 666 | |
+ ietf-dhcpv6-options | 2018-09-04 | Imported | | | |
+ ietf-dhcpv6-types | 2018-01-30 | Imported | | | |
+
+To install a new revision of a module it must first be uninstalled, e.g.
+by:
+
+.. code-block:: console
+
+ sudo sysrepoctl -u -m kea-dhcp4-server
+
+If the module is used (i.e. imported) by other modules, it can be
+uninstalled only after those modules have finished using it.
+Installation and uninstallation must be done in dependency order and
+reverse-dependency order accordingly.
+
+.. _netconf-models:
+
+Supported YANG Models
+=====================
+
+The only currently supported models are ``kea-dhcp4-server`` and
+``kea-dhcp6-server``. There is partial support for
+``ietf-dhcpv6-server``, but the primary focus of testing has been on Kea DHCP
+servers. Several other models (``kea-dhcp-ddns`` and ``kea-ctrl-agent``)
+are currently not supported.
+
+.. _using-netconf:
+
+Using the NETCONF Agent
+=======================
+
+The NETCONF agent follows this algorithm:
+
+- For each managed server, get the initial configuration from the
+ server through the control socket.
+
+- Open a connection with the Sysrepo environment and establish two
+ sessions with the startup and running datastores.
+
+- Check that used (not essential) and required (essential) modules are
+ installed in the Sysrepo repository at the right revision. If an
+ essential module - that is, a module where the configuration schema for a
+ managed server is defined - is not installed, raise a fatal error.
+
+- For each managed server, get the YANG configuration from the startup
+ datastore, translate it to JSON, and load it onto the server being
+ configured.
+
+- For each managed server, subscribe a module change callback using its
+ model name.
+
+- When a running configuration is changed, try to validate or load the
+ updated configuration via the callback to the managed server.
+
+.. _netconf-configuration:
+
+Configuration
+=============
+
+The behavior described in :ref:`using-netconf`
+is controlled by a few configuration flags, which can be set in the
+global scope or in a specific managed-server scope. In the second case,
+the value defined in the managed-server scope takes precedence. These
+flags are:
+
+- ``boot-update`` - controls the initial configuration phase; when
+ true (the default), the initial configuration retrieved from the
+ classic Kea server JSON configuration file is loaded first, and then
+ the startup YANG model is loaded. This setting lets administrators
+ define a control socket in the local JSON file and then download the
+ configuration from YANG. When set to false, this phase is skipped.
+
+- ``subscribe-changes`` - controls the module change
+ subscription; when true (the default), a module change callback is
+ subscribed, but when false the phase is skipped and running
+ configuration updates are disabled. When set to true, the running
+ datastore is used to subscribe for changes.
+
+- ``validate-changes`` - controls how Kea monitors changes in
+ the Sysrepo configuration. Sysrepo offers two stages where Kea can
+ interact: validation and application. At the validation (or
+ SR_EV_VERIFY event, in the Sysrepo naming convention) stage, Kea
+ retrieves the newly committed configuration and verifies it. If the
+ configuration is incorrect for any reason, the Kea servers reject it
+ and the error is propagated back to the Sysrepo, which then returns
+ an error. This step only takes place if validate-changes is set to
+ true. In the application (or SR_EV_APPLY event in the Sysrepo naming
+ convention) stage, the actual configuration is applied. At this stage
+ Kea can receive the configuration, but it is too late to signal back
+ any errors as the configuration has already been committed.
+
+The idea behind the initial configuration phase is to boot Kea servers
+with a minimal configuration which includes only a control socket,
+making them manageable. For instance, for the DHCPv4 server:
+
+::
+
+ {
+ "Dhcp4": {
+ "control-socket": {
+ "socket-type": "unix",
+ "socket-name": "/tmp/kea4-sock"
+ }
+ }
+ }
+
+Note the alternative to boot with full configurations does not allow
+easy tracking of changes or synchronization between the JSON and YANG
+configuration sources; therefore, that setup is not really compatible
+with the YANG/NETCONF configuration management paradigm, where
+everything should be performed in YANG.
+
+With module change subscriptions enabled, the kea-netconf daemon will
+monitor any configuration changes as they appear in the Sysrepo. Such
+changes can be done using the ``sysrepocfg`` tool or remotely using any
+NETCONF client. For details, please see the Sysrepo documentation or
+:ref:`operation-example`.
+Those tools can be used to modify YANG configurations in the running
+datastore. Note that committed configurations are only updated in the
+running datastore; to keep them between server reboots they must be
+copied to the startup datastore.
+
+When module changes are tracked (using ``subscribe-changes`` set to
+true) and the running configuration has changed (e.g. using
+``sysrepocfg`` or any NETCONF client), the callback validates the
+modified configuration (if ``validate-changes`` was not set to false)
+and runs a second time to apply the new configuration. If the validation
+fails, the callback is still called again but with an ABORT (vs. APPLY)
+event with rollback changes.
+
+The returned code of the callback on an APPLY event is ignored, as it is
+too late to refuse a bad configuration.
+
+There are four ways in which a modified YANG configuration could
+possibly be incorrect:
+
+1. It can be non-compliant with the schema, e.g. an unknown entry, missing a
+ mandatory entry, a value with a bad type, or not matching a constraint.
+
+2. It can fail to be translated from YANG to JSON, e.g. an invalid user
+ context.
+
+3. It can fail Kea server sanity checks, e.g. an out-of-subnet-pool range
+ or an unsupported database type.
+
+4. The syntax may be correct and pass server sanity checks but the
+ configuration fails to run, e.g. the configuration specifies database
+ credentials but the database refuses the connection.
+
+The first case is handled by Sysrepo. The second and third cases are
+handled by kea-netconf in the validation phase (if not disabled by
+setting ``validate-changes`` to true). The last case causes the
+application phase to fail without a sensible report to Sysrepo.
+
+The managed Kea servers or agents are described in the
+``managed-servers`` section. Each sub-section begins by the service
+name: ``dhcp4``, ``dhcp6``, ``d2`` (the DHCP-DDNS server does not
+support the control channel feature yet), and ``ca`` (the control
+agent).
+
+Each managed server entry contains optionally:
+
+- ``boot-update``, ``subscribe-changes``, and ``validate-changes`` -
+ control flags.
+
+- ``model`` - specifies the YANG model / module name. For each service,
+ the default is the corresponding Kea YANG model, e.g. for ``"dhcp4"``
+ it is ``"kea-dhcp4-server"``.
+
+- ``control-socket`` - specifies the control socket for managing the
+ service configuration.
+
+A control socket is specified by:
+
+- ``socket-type`` - the socket type is either ``stdout``, ``unix``, or ``http``.
+ ``stdout`` is the default;
+ it is not really a socket, but it allows ``kea-netconf`` to run in
+ debugging mode where everything is printed on stdout, and it can also be
+ used to redirect commands easily. ``unix`` is the standard direct
+ server control channel, which uses UNIX sockets, and ``http`` uses
+ a control agent, which accepts HTTP connections.
+
+- ``socket-name`` - the local socket name for the ``unix`` socket type
+ (default empty string).
+
+- ``socket-url`` - the HTTP URL for the ``http`` socket type (default
+ ``http://127.0.0.1:8000/``).
+
+User contexts can store arbitrary data as long as they are in valid JSON
+syntax and their top-level element is a map (i.e. the data must be
+enclosed in curly brackets). They are accepted at the NETCONF entry,
+i.e. below the top-level, managed-service entry, and control-socket
+entry scopes.
+
+Hooks libraries can be loaded by the NETCONF agent just as with other
+servers or agents; however, currently no hook points are defined. The
+``hooks-libraries`` list contains the list of hooks libraries that
+should be loaded by kea-netconf, along with their configuration
+information specified with ``parameters``.
+
+Please consult :ref:`logging` for details on how to configure
+logging. The NETCONF agent's root logger's name is ``kea-netconf``, as
+given in the example above.
+
+.. _netconf-example:
+
+A kea-netconf Configuration Example
+===================================
+
+The following example demonstrates the basic NETCONF configuration. More
+examples are available in the ``doc/examples/netconf`` directory in the
+Kea sources.
+
+::
+
+ # This is a simple example of a configuration for the NETCONF agent.
+ # This server provides a YANG interface for all Kea servers and the agent.
+ {
+ "Netconf":
+ {
+ # Control flags can be defined in the global scope or
+ # in a managed server scope. Precedences are:
+ # - use the default value (true)
+ # - use the global value
+ # - use the local value.
+ # So this overwrites the default value:
+ "boot-update": false,
+
+ # This map specifies how each server is managed. For each server there
+ # is a name of the YANG model to be used and the control channel.
+ //
+ # Currently three control channel types are supported:
+ # "stdout" which outputs the configuration on the standard output,
+ # "unix" which uses the local control channel supported by the
+ # "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
+ # and "http" which uses the Control Agent "ca" to manage itself or
+ # to forward commands to "dhcp4" or "dhcp6".
+ "managed-servers":
+ {
+ # This is how kea-netconf can communicate with the DHCPv4 server.
+ "dhcp4":
+ {
+ "comment": "DHCP4 server",
+ "model": "kea-dhcp4-server",
+ "control-socket":
+ {
+ "socket-type": "unix",
+ "socket-name": "/tmp/kea4-ctrl-socket"
+ }
+ },
+
+ # DHCPv6 parameters.
+ "dhcp6":
+ {
+ "model": "kea-dhcp6-server",
+ "control-socket":
+ {
+ "socket-type": "unix",
+ "socket-name": "/tmp/kea6-ctrl-socket"
+ }
+ },
+
+ # Currently the DHCP-DDNS (nicknamed D2) server does not support
+ # a command channel.
+ "d2":
+ {
+ "model": "kea-dhcp-ddns",
+ "control-socket":
+ {
+ "socket-type": "stdout",
+ "user-context": { "in-use": false }
+ }
+ },
+
+ # Of course the Control Agent (CA) supports HTTP.
+ "ca":
+ {
+ "model": "kea-ctrl-agent",
+ "control-socket":
+ {
+ "socket-type": "http",
+ "socket-url": "http://127.0.0.1:8000/"
+ }
+ }
+ },
+
+ # kea-netconf is able to load hooks libraries that augment its operation.
+ # Currently there are no hook points defined in kea-netconf
+ # processing.
+ "hooks-libraries": [
+ # The hooks libraries list may contain more than one library.
+ {
+ # The only necessary parameter is the library filename.
+ "library": "/opt/local/netconf-commands.so",
+
+ # Some libraries may support parameters. Make sure you
+ # type this section carefully, as kea-netconf does not
+ # validate it (because the format is library-specific).
+ "parameters": {
+ "param1": "foo"
+ }
+ }
+ ],
+
+ # Similar to other Kea components, NETCONF also uses logging.
+ "loggers": [
+ {
+ "name": "kea-netconf",
+ "output_options": [
+ {
+ "output": "/var/log/kea-netconf.log",
+ # Several additional parameters are possible in
+ # addition to the typical output.
+ # Flush determines whether logger flushes output
+ # to a file.
+ # Maxsize determines maximum filesize before
+ # the file is being rotated.
+ # Maxver specifies the maximum number of
+ # rotated files being kept.
+ "flush": true,
+ "maxsize": 204800,
+ "maxver": 4
+ }
+ ],
+ "severity": "INFO",
+ "debuglevel": 0
+ }
+ ]
+ }
+ }
+
+.. _netconf-start-stop:
+
+Starting and Stopping the NETCONF Agent
+=======================================
+
+kea-netconf accepts the following command-line switches:
+
+- ``-c file`` - specifies the configuration file.
+
+- ``-d`` - specifies whether the agent logging should be switched to
+ debug/verbose mode. In verbose mode, the logging severity and
+ debuglevel specified in the configuration file are ignored and
+ "debug" severity and the maximum debuglevel (99) are assumed. The
+ flag is convenient for temporarily switching the server into maximum
+ verbosity, e.g. when debugging.
+
+- ``-t file`` - specifies the configuration file to be tested.
+ Kea-netconf attempts to load it and conducts sanity checks; note that
+ certain checks are possible only while running the actual server. The
+ actual status is reported with exit code (0 = configuration looks ok,
+ 1 = error encountered). Kea will print out log messages to standard
+ output and error to standard error when testing configuration.
+
+- ``-v`` - displays the version of kea-netconf and exits.
+
+- ``-V`` - displays the extended version information for kea-netconf
+ and exits. The listing includes the versions of the libraries
+ dynamically linked to Kea.
+
+- ``-W`` - displays the Kea configuration report and exits. The report
+ is a copy of the ``config.report`` file produced by ``./configure``;
+ it is embedded in the executable binary.
+
+.. _operation-example:
+
+A Step-by-Step NETCONF Agent Operation Example
+==============================================
+
+.. note::
+
+ Copies of example configurations presented within this section can be
+ found in the Kea source code, under
+ ``doc/examples/netconf/kea-dhcp6-operations``.
+
+.. _operation-example-setup:
+
+Setup of NETCONF Agent Operation Example
+----------------------------------------
+
+The test box has an Ethernet interface named eth1. On some systems it is
+possible to rename interfaces, for instance on a Linux with an ens38
+interface:
+
+.. code-block:: console
+
+ # ip link set down dev ens38
+ # ip link set name eth1 dev ens38
+ # ip link set up dev eth1
+
+The interface must have an address in the test prefix:
+
+.. code-block:: console
+
+ # ip -6 addr add 2001:db8::1/64 dev eth1
+
+The Kea DHCPv6 server must be launched with the configuration specifying
+a control socket used to receive control commands. The ``kea-netconf``
+process uses this socket to communicate with the DHCPv6 server, i.e. it
+pushes translated configurations to that server using control commands.
+The following is the example control socket specification for the Kea
+DHCPv6 server:
+
+::
+
+ {
+ "Dhcp6": {
+ "control-socket": {
+ "socket-type": "unix",
+ "socket-name": "/tmp/kea6-sock"
+ }
+ }
+ }
+
+In order to launch the Kea DHCPv6 server using the configuration
+contained within the ``boot.json`` file, run:
+
+.. code-block:: console
+
+ # kea-dhcp6 -d -c boot.json
+
+The current configuration of the server can be fetched via control
+socket by running:
+
+.. code-block:: console
+
+ # echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof'
+
+The following is the example ``netconf.json`` configuration for
+``kea-netconf``, to manage the Kea DHCPv6 server:
+
+::
+
+ {
+ "Netconf":
+ {
+ "managed-servers":
+ {
+ "dhcp6":
+ {
+ "control-socket":
+ {
+ "socket-type": "unix",
+ "socket-name": "/tmp/kea6-sock"
+ }
+ }
+ },
+
+ "loggers":
+ [
+ {
+ "name": "kea-netconf",
+ "output_options":
+ [
+ {
+ "output": "stderr"
+ }
+ ],
+ "severity": "DEBUG",
+ "debuglevel": 99
+ }
+ ]
+ }
+ }
+
+Note that in production there should not be a need to log at the DEBUG level.
+
+The Kea NETCONF agent is launched by:
+
+.. code-block:: console
+
+ # kea-netconf -d -c netconf.json
+
+Now that both ``kea-netconf`` and ``kea-dhcp6`` are running, it is
+possible to populate updates to the configuration to the DHCPv6 server.
+The following is the configuration extracted from ``startup.xml``:
+
+.. code-block:: xml
+
+ <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
+ <subnet6>
+ <id>1</id>
+ <pool>
+ <start-address>2001:db8::1:0</start-address>
+ <end-address>2001:db8::1:ffff</end-address>
+ <prefix>2001:db8::1:0/112</prefix>
+ </pool>
+ <subnet>2001:db8::/64</subnet>
+ </subnet6>
+ <interfaces-config>
+ <interfaces>eth1</interfaces>
+ </interfaces-config>
+ <control-socket>
+ <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-type>unix</socket-type>
+ </control-socket>
+ </config>
+
+To populate this new configuration:
+
+.. code-block:: console
+
+ # sysrepocfg -d startup -f xml -i startup.xml kea-dhcp6-server
+
+``kea-netconf`` pushes the configuration found in the Sysrepo startup
+datastore to all Kea servers during its initialization phase, after it
+subscribes to module changes in the Sysrepo running datastore. This
+action copies the configuration from the startup datastore to the
+running datastore and enables the running datastore, making it
+available.
+
+Changes to the running datastore are applied after validation to the Kea
+servers. Note that they are not by default copied back to the startup
+datastore, i.e. changes are not permanent.
+
+.. _operation-example-errors:
+
+Error Handling in NETCONF Operation Example
+-------------------------------------------
+
+There are four classes of issues with the configurations applied via
+NETCONF:
+
+1. The configuration does not comply with the YANG schema.
+
+2. The configuration cannot be translated from YANG to the Kea JSON.
+
+3. The configuration is rejected by the Kea server.
+
+4. The configuration was validated by the Kea server but cannot be
+ applied.
+
+In the first case, consider the following ``BAD-schema.xml``
+configuration file:
+
+.. code-block:: xml
+
+ <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
+ <subnet4>
+ <id>1</id>
+ <pool>
+ <start-address>2001:db8::1:0</start-address>
+ <end-address>2001:db8::1:ffff</end-address>
+ <prefix>2001:db8::1:0/112</prefix>
+ </pool>
+ <subnet>2001:db8::/64</subnet>
+ </subnet6>
+ <interfaces-config>
+ <interfaces>eth1</interfaces>
+ </interfaces-config>
+ <control-socket>
+ <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-type>unix</socket-type>
+ </control-socket>
+ </config>
+
+It is directly rejected by ``sysrepocfg``:
+
+.. code-block:: console
+
+ # sysrepocfg -d running -f xml -i BAD-schema.xml kea-dhcp6-server
+
+In the second case, the configuration is rejected by ``kea-netconf``.
+For example, consider this ``BAD-translator.xml`` file:
+
+.. code-block:: xml
+
+ <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
+ <subnet6>
+ <id>1</id>
+ <pool>
+ <start-address>2001:db8::1:0</start-address>
+ <end-address>2001:db8::1:ffff</end-address>
+ <prefix>2001:db8::1:0/112</prefix>
+ </pool>
+ <subnet>2001:db8::/64</subnet>
+ </subnet6>
+ <interfaces-config>
+ <interfaces>eth1</interfaces>
+ </interfaces-config>
+ <control-socket>
+ <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-type>unix</socket-type>
+ </control-socket>
+ <user-context>bad</user-context>
+ </config>
+
+In the third case, the configuration is presented to the Kea DHCPv6
+server and fails to validate as in this ``BAD-config.xml`` file:
+
+.. code-block:: xml
+
+ <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
+ <subnet6>
+ <id>1</id>
+ <pool>
+ <start-address>2001:db8:1::0</start-address>
+ <end-address>2001:db8:1::ffff</end-address>
+ <prefix>2001:db8:1::0/112</prefix>
+ </pool>
+ <subnet>2001:db8::/64</subnet>
+ </subnet6>
+ <interfaces-config>
+ <interfaces>eth1</interfaces>
+ </interfaces-config>
+ <control-socket>
+ <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-type>unix</socket-type>
+ </control-socket>
+ </config>
+
+In the last case, the misconfiguration is detected too late and the
+change must be reverted in Sysrepo, e.g. using the startup datastore as
+a backup. For this reason, please use the ``sysrepocfg`` ``--permanent``
+/ ``-p`` option (or any similar feature of NETCONF clients) with care.
+
+.. _operation-example-2pools:
+
+NETCONF Operation Example with Two Pools
+----------------------------------------
+
+This example adds a second pool to the initial (i.e. startup)
+configuration in the ``twopools.xml`` file:
+
+.. code-block:: xml
+
+ <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
+ <subnet6>
+ <id>1</id>
+ <pool>
+ <start-address>2001:db8::1:0</start-address>
+ <end-address>2001:db8::1:ffff</end-address>
+ <prefix>2001:db8::1:0/112</prefix>
+ </pool>
+ <pool>
+ <start-address>2001:db8::2:0</start-address>
+ <end-address>2001:db8::2:ffff</end-address>
+ <prefix>2001:db8::2:0/112</prefix>
+ </pool>
+ <subnet>2001:db8::/64</subnet>
+ </subnet6>
+ <interfaces-config>
+ <interfaces>eth1</interfaces>
+ </interfaces-config>
+ <control-socket>
+ <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-type>unix</socket-type>
+ </control-socket>
+ </config>
+
+This configuration is installed by:
+
+.. code-block:: console
+
+ # sysrepocfg -d running -f xml -i twopools.xml kea-dhcp6-server
+
+.. _operation-example-2subnets:
+
+NETCONF Operation Example with Two Subnets
+------------------------------------------
+
+This example specifies two subnets in the ``twosubnets.xml`` file:
+
+.. code-block:: xml
+
+ <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
+ <subnet6>
+ <id>1</id>
+ <pool>
+ <start-address>2001:db8:1::</start-address>
+ <end-address>2001:db8:1::ffff</end-address>
+ <prefix>2001:db8:1::/112</prefix>
+ </pool>
+ <subnet>2001:db8:1::/64</subnet>
+ </subnet6>
+ <subnet6>
+ <id>2</id>
+ <pool>
+ <start-address>2001:db8:2::</start-address>
+ <end-address>2001:db8:2::ffff</end-address>
+ <prefix>2001:db8:2::/112</prefix>
+ </pool>
+ <subnet>2001:db8:2::/64</subnet>
+ </subnet6>
+ <interfaces-config>
+ <interfaces>eth1</interfaces>
+ </interfaces-config>
+ <control-socket>
+ <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-type>unix</socket-type>
+ </control-socket>
+ </config>
+
+This configuration is installed by:
+
+.. code-block:: console
+
+ # sysrepocfg -d running -f xml -i twosubnets.xml kea-dhcp6-server
+
+.. _operation-example-logging:
+
+NETCONF Operation Example with Logging
+--------------------------------------
+
+This example adds a logger entry to the initial (i.e. startup)
+configuration in the ``logging.xml`` file:
+
+.. code-block:: xml
+
+ <config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp6-server">
+ <interfaces-config>
+ <interfaces>eth1</interfaces>
+ </interfaces-config>
+ <subnet6>
+ <id>1</id>
+ <pool>
+ <start-address>2001:db8::1:0</start-address>
+ <end-address>2001:db8::1:ffff</end-address>
+ <prefix>2001:db8::1:0/112</prefix>
+ </pool>
+ <subnet>2001:db8::/64</subnet>
+ </subnet6>
+ <control-socket>
+ <socket-name>/tmp/kea6-sock</socket-name>
+ <socket-type>unix</socket-type>
+ </control-socket>
+ <logger>
+ <name>kea-dhcp6</name>
+ <output-option>
+ <output>stderr</output>
+ </output-option>
+ <debuglevel>99</debuglevel>
+ <severity>DEBUG</severity>
+ </logger>
+ </config>
+
+The corresponding Kea configuration in JSON is:
+
+::
+
+ {
+ "Dhcp6": {
+ "control-socket": {
+ "socket-name": "/tmp/kea6-sock",
+ "socket-type": "unix"
+ },
+ "interfaces-config": {
+ "interfaces": [ "eth1" ]
+ },
+ "subnet6": [
+ {
+ "id": 1,
+ "pools": [
+ {
+ "pool": "2001:db8::1:0/112"
+ }
+ ],
+ "subnet": "2001:db8::/64"
+ }
+ ],
+ "loggers": [
+ {
+ "name": "kea-dhcp6",
+ "output_options": [
+ {
+ "output": "stderr"
+ }
+ ],
+ "severity": "DEBUG",
+ "debuglevel": 99
+ }
+ ]
+ }
+ }
+
+Finally, any of the previous examples can be replayed using
+``sysrepocfg`` in edit mode as follows:
+
+.. code-block:: console
+
+ # sysrepocfg -d running -f xml -e vi kea-dhcp6-server
+
+or, of course, using a NETCONF client like ``netopeer2-cli`` from the
+`Netopeer2 <https://github.com/CESNET/Netopeer2>`__ NETCONF Toolset.
projects / thirdparty / kea.git / commitdiff
