+++ /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
