.. ischooklib:: libdhcp_host_cmds.so .. _hooks-host-cmds: ``libdhcp_host_cmds.so``: Host Commands ======================================= Kea can store host reservations in a database; in many larger deployments, it is useful to be able to manage that information while the server is running. The Host Commands library provides management commands for adding, querying, and deleting host reservations in a safe way without restarting the server. In particular, it validates the parameters, so an attempt to insert incorrect data - such as adding a host with a conflicting identifier in the same subnet - is rejected. Those commands are exposed via the command channel (JSON over UNIX sockets) and the Control Agent (JSON over a RESTful interface). .. note:: :ischooklib:`libdhcp_host_cmds.so` is part of the open source code and is available to every Kea user. It was previously available only to ISC customers with a paid support contract. .. note:: This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` process. Currently, the following commands are supported: - :isccmd:`reservation-add`, which adds a new host reservation. - :isccmd:`reservation-get`, which returns an existing reservation if specified criteria are matched. - :isccmd:`reservation-get-all`, which returns all reservations in a specified subnet. - :isccmd:`reservation-get-page`, a variant of :isccmd:`reservation-get-all` that returns reservations by pages, either all or in a specified subnet. - :isccmd:`reservation-get-by-address`, which returns all reservations with a specified IP address or a delegated prefix (without a prefix length), and optionally a subnet id. - :isccmd:`reservation-get-by-hostname`, which returns all reservations with a specified hostname and optionally in a subnet. - :isccmd:`reservation-get-by-id`, which returns all reservations with a specified identifier (since Kea version 1.9.0). - :isccmd:`reservation-del`, which attempts to delete a reservation matching specified criteria. - :isccmd:`reservation-update`, which updates (replaces) an existing reservation matching the given identifiers in a subnet. To use the commands that change reservation information (i.e. :isccmd:`reservation-add`, :isccmd:`reservation-del`, and :isccmd:`reservation-update`) to modify data stored in the host database, the hosts database must be specified and it must not operate in read-only mode (for details, see the ``hosts-databases`` descriptions in :ref:`hosts-databases-configuration4` and :ref:`hosts-databases-configuration6`). If the ``hosts-databases`` are not specified or are running in read-only mode, :ischooklib:`libdhcp_host_cmds.so` will load, but any attempts to use :isccmd:`reservation-add`, :isccmd:`reservation-del`, and :isccmd:`reservation-update` to modify data in that database will fail. These commands can also modify hosts from the JSON configuration independently from the hosts database. The changes provided in the JSON configuration are volatile and can be made permanent by sending the :isccmd:`config-write` command. For a description of proposed future commands, see the `Control API Requirements `__ document. All host commands use JSON syntax. They can be issued either using the control channel (see :ref:`ctrl-channel`) or via the Control Agent (see :ref:`kea-ctrl-agent`). The library can be loaded similarly to other hook libraries. It does not take any parameters, and it supports both the DHCPv4 and DHCPv6 servers. :: "Dhcp6": { "hooks-libraries": [ { "library": "/path/libdhcp_host_cmds.so" }, ... ] } The ``subnet-id`` Parameter ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before examining the individual commands, it is worth discussing the parameter ``subnet-id``. Currently, this parameter is mandatory for all of the commands supplied by this library, with the exception of :isccmd:`reservation-get-by-hostname` and :isccmd:`reservation-get-by-address`, where it is optional. ``subnet-id`` is also optional in :isccmd:`reservation-get-page`, and it is forbidden in :isccmd:`reservation-get-by-id`. Reservations can be specified globally, and are not necessarily specific to any subnet. When reservations are supplied via the configuration file, the ID of the containing subnet (or lack thereof) is implicit in the configuration structure. However, when managing reservations using host commands, it is necessary to explicitly identify the scope to which the reservation belongs. This is done via the ``subnet-id`` parameter. For global reservations, use a value of zero (0). For reservations scoped to a specific subnet, use that subnet's ID. See also the note in :ref:`command-reservation-add` about the :isccmd:`reservation-add` command for an empty (i.e. with no reserved address or prefix) reservation. On the other hand, when the ``subnet-id`` is not specified in the command parameters, it is added to each host in responses. If the ``subnet-id`` has the unused special value, this means the host entry belongs only to the other IP version (i.e. IPv6 in the DHCPv4 server or IPv4 in the DHCPv6 server) and this entry is ignored. The ``operation-target`` Parameter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Most host commands accept the ``operation-target`` parameter, which selects the host data source. The commands may process data from the server configuration (i.e., memory operation target), a database (database target), or both (all sources). The operation-target parameter is optional. By default, the commands that only read the data use all data sources (memory and database); the commands that modify the state (i.e. :isccmd:`reservation-add`, :isccmd:`reservation-del`, and :isccmd:`reservation-update`) only use the database target. The ``operation-target`` parameter accepts the following values: - ``memory`` - query or update the runtime server configuration - ``database`` - query or update host database(s) - ``all`` - query or update both runtime configuration and host database(s) - ``default`` - query or update a default host data source - it is command-specific .. isccmd:: reservation-add .. _command-reservation-add: The ``reservation-add`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-add` allows for the insertion of a new host. It takes a set of arguments that vary depending on the nature of the host reservation. Any parameters allowed in the configuration file that pertain to host reservation are permitted here. For details regarding IPv4 reservations, see :ref:`host-reservation-v4`; for IPv6 reservations, see :ref:`host-reservation-v6`. The ``subnet-id`` is mandatory. Use a value of zero (0) to add a global reservation, or the ID of the subnet to which the reservation should be added. The command can be as simple as having only the two mandatory entries: .. code-block:: json { "command": "reservation-add", "arguments": { "reservation": { "subnet-id": 1, "hw-address": "1a:1b:1c:1d:1e:1f" } } } In that case, however, it does not assign any resources to the host. An IPv4 address can be assigned as in this example: .. code-block:: json { "command": "reservation-add", "arguments": { "reservation": { "subnet-id": 1, "hw-address": "1a:1b:1c:1d:1e:1f", "ip-address": "192.0.2.202" } } } It can also take many more parameters, such as: .. code-block:: json { "command": "reservation-add", "arguments": { "reservation": { "subnet-id": 1, "client-id": "01:0a:0b:0c:0d:0e:0f", "ip-address": "192.0.2.205", "next-server": "192.0.2.1", "server-hostname": "hal9000", "boot-file-name": "/dev/null", "option-data": [ { "name": "domain-name-servers", "data": "10.1.1.202,10.1.1.203" } ], "client-classes": [ "special_snowflake", "office" ] } } } Here is an example of a complex IPv6 reservation: .. code-block:: json { "command": "reservation-add", "arguments": { "reservation": { "subnet-id": 1, "duid": "01:02:03:04:05:06:07:08:09:0A", "ip-addresses": [ "2001:db8:1:cafe::1" ], "prefixes": [ "2001:db8:2:abcd::/64" ], "hostname": "foo.example.com", "option-data": [ { "name": "vendor-opts", "data": "4491" }, { "name": "tftp-servers", "space": "vendor-4491", "data": "3000:1::234" } ] } } } The command accepts the ``operation-target`` argument. By default, it adds the reservation to the hosts database only. .. code-block:: json { "command": "reservation-add", "arguments": { "reservation": {}, "operation-target": "all" } } The command returns a status that indicates either success (result 0) or failure (result 1). A failed command always includes a text parameter that explains the cause of the failure. Here's an example of a successful addition: .. code-block:: json { "result": 0, "text": "Host added." } And here's an example of a failure: .. code-block:: json { "result": 1, "text": "Mandatory 'subnet-id' parameter missing." } As :isccmd:`reservation-add` is expected to store the host, the ``hosts-databases`` parameter must be specified in the configuration, and databases must not run in read-only mode. .. note:: Since kea version 2.7.0 an empty reservation is implicitly global, i.e. if no ``subnet-id`` entry is present and for DHCPv4 ``ip-address`` or for DHCPv6 ``ip-addresses`` and ``prefixes`` do not specify a reserved address or prefix the command is valid and adds a global (subnet-id 0) host reservation. .. isccmd:: reservation-get .. _command-reservation-get: The ``reservation-get`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-get` can be used to query the host database and retrieve existing reservations. This command supports two types of parameters: (``subnet-id``, ``address``) or (``subnet-id``, ``identifier-type``, ``identifier``). The first type of query is used when the address (either IPv4 or IPv6) is known, but the details of the reservation are not. One common use for this type of query is to find out whether a given address is reserved. The second query uses identifiers. For maximum flexibility, Kea stores the host identifying information as a pair of values: the type and the actual identifier. Currently supported identifiers are ``"hw-address"``, ``"duid"``, ``"circuit-id"``, ``"client-id"``, and ``"flex-id"``. The ``subnet-id`` is mandatory. Use a value of zero (0) to fetch a global reservation, or the ID of the subnet to which the reservation belongs. An example command for getting a host reservation by a (``subnet-id``, ``address``) pair looks as follows: :: { "command": "reservation-get", "arguments": { "subnet-id": 1, "ip-address": "192.0.2.202" } } An example query by (``subnet-id``, ``identifier-type``, ``identifier``) looks as follows: :: { "command": "reservation-get", "arguments": { "subnet-id": 4, "identifier-type": "hw-address", "identifier": "01:02:03:04:05:06" } } The command accepts the ``operation-target`` argument. By default, it gets the reservation from both the JSON configuration and the hosts database. .. code-block:: json { "command": "reservation-get", "arguments": { "subnet-id": 1, "ip-address": "192.0.2.202", "operation-target": "alternate" } } Command :isccmd:`reservation-get` typically returns the result 0 when a query was conducted properly. In particular, 0 is returned when the host was not found. If the query was successful, the host parameters are returned. An example of a query that did not find the host looks as follows: :: { "result": 0, "text": "Host not found." } Here's an example of a result returned when the host was found successfully: :: { "arguments": { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "somehost.example.org", "hw-address": "01:02:03:04:05:06", "ip-address": "192.0.2.100", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org", "subnet-id": 4 }, "result": 0, "text": "Host found." } An example result returned when the query was malformed might look like this: :: { "result": 1, "text": "No 'ip-address' provided and 'identifier-type' is either missing or not a string." } .. isccmd:: reservation-get-all .. _command-reservation-get-all: The ``reservation-get-all`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-get-all` can be used to query the host database and retrieve all reservations in a specified subnet. This command uses parameters providing the mandatory ``subnet-id``. Global host reservations can be retrieved by using a ``subnet-id`` value of zero (0). For instance, retrieving host reservations for the subnet 1: :: { "command": "reservation-get-all", "arguments": { "subnet-id": 1 } } returns some IPv4 hosts: :: { "arguments": { "hosts": [ { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "somehost.example.org", "hw-address": "01:02:03:04:05:06", "ip-address": "192.0.2.100", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org", "subnet-id": 1 }, { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "otherhost.example.org", "hw-address": "01:02:03:04:05:ff", "ip-address": "192.0.2.200", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org", "subnet-id": 1 }, ... ] }, "result": 0, "text": "72 IPv4 host(s) found." } The response returned by :isccmd:`reservation-get-all` can be very long. The DHCP server does not handle DHCP traffic while preparing a response to :isccmd:`reservation-get-all`, so if there are many reservations in a subnet, this may be disruptive; use with caution. For larger deployments, please consider using :isccmd:`reservation-get-page` instead. The command accepts the ``operation-target`` argument. By default, it gets the reservation from both the JSON configuration and the hosts database. .. code-block:: json { "command": "reservation-get-all", "arguments": { "subnet-id": 1, "operation-target": "alternate" } } For more information, see :ref:`command-reservation-get-all`. .. isccmd:: reservation-get-page .. _command-reservation-get-page: The ``reservation-get-page`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-get-page` can be used to query the host database and retrieve all reservations in a specified subnet, by pages. This command uses parameters providing the mandatory ``subnet-id``. Use a value of zero (0) to fetch global reservations. The second mandatory parameter is the page size limit. The optional ``source-index`` and ``from-host-id`` parameters, both of which default to 0, are used to chain page queries. Since Kea version 1.9.0, the ``subnet-id`` parameter is optional. The usage of the ``from`` and ``source-index`` parameters requires additional explanation. For the first call, those parameters should not be specified (or should be specified as zeros). For any follow-up calls, they should be set to the values returned in previous calls, in a next map holding ``from`` and ``source-index`` values. Subsequent calls should be issued until all reservations are returned. The end is reached once the returned list is empty, the count is 0, no next map is present, and result status 3 (empty) is returned. .. note:: The ``from`` and ``source-index`` parameters reflect the internal state of the search. There is no need to understand what they represent; it is simply a value that should be copied from one response to the next query. However, for those who are curious, the ``from`` field represents a 64-bit representation of the host identifier used by a host backend. The ``source-index`` is an internal representation of multiple host backends: 0 is used to represent hosts defined in a configuration file, and 1 represents the first database backend. In some uncommon cases there may be more than one database backend configured, so potentially there may be a 2. In any case, Kea iterates over all backends configured. For instance, retrieving host reservations for the subnet 1 and requesting the first page can be done by: :: { "command": "reservation-get-page", "arguments": { "subnet-id": 1, "limit": 10 } } Since this is the first call, ``source-index`` and ``from`` should not be specified. They are set to their zero default values. Some hosts are returned with information to get the next page: :: { "arguments": { "count": 72, "hosts": [ { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "somehost.example.org", "hw-address": "01:02:03:04:05:06", "ip-address": "192.0.2.100", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org" }, { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "otherhost.example.org", "hw-address": "01:02:03:04:05:ff", "ip-address": "192.0.2.200", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org" }, ... ], "next": { "from": 1234567, "source-index": 1 } }, "result": 0, "text": "72 IPv4 host(s) found." } Note that the ``from`` and ``source-index`` fields were specified in the response in the next map. Those two must be copied to the next command, so Kea continues from the place where the last command finished. To get the next page the following command can be sent: :: { "command": "reservation-get-page", "arguments": { "subnet-id": 1, "source-index": 1, "from": 1234567, "limit": 10 } } The response will contain a list of hosts with updated ``source-index`` and ``from`` fields. Continue calling the command until the last page is received. Its response will look like this: .. code-block:: json { "arguments": { "count": 0, "hosts": [ ] }, "result": 3, "text": "0 IPv4 host(s) found." } The command does not accept the ``operation-target`` argument. This command is more complex than :isccmd:`reservation-get-all`, but it lets users retrieve larger host reservations lists in smaller chunks. For small deployments with few reservations, it is easier to use :isccmd:`reservation-get-all`. .. isccmd:: reservation-get-by-address .. _command-reservation-get-by-address: The ``reservation-get-by-address`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-get-by-address` can be used to query the host database and retrieve all reservations for a given IP address or a delegated prefix (without a prefix length), in a specified subnet or in all subnets. This command uses parameters providing the mandatory ``ip-address`` and the optional ``subnet-id`` and ``operation-target``. For instance, retrieving host reservations for the IPv4 address "192.0.200.181" in the subnet 1: :: { "command": "reservation-get-by-address", "arguments": { "ip-address": "192.0.200.181", "subnet-id": 1 }, "service": [ "dhcp4" ] } can return two IPv4 hosts: :: { "arguments": { "hosts": [ { "boot-file-name": "", "client-classes": [], "hostname": "", "hw-address": "99:99:99:99:99:01", "ip-address": "192.0.200.181", "next-server": "0.0.0.0", "option-data": [], "server-hostname": "", "subnet-id": 1 }, { "boot-file-name": "", "circuit-id": "1234", "client-classes": [], "hostname": "", "ip-address": "192.0.200.181", "next-server": "0.0.0.0", "option-data": [], "server-hostname": "", "subnet-id": 1 } ] }, "result": 0, "text": "2 IPv4 host(s) found." } To search for all reservations in all subnets, simply skip the ``subnet-id`` parameter: :: { "command": "reservation-get-by-address", "arguments": { "ip-address": "192.0.200.181" }, "service": [ "dhcp4" ] } An example response could be: :: { "arguments": { "hosts": [ { "boot-file-name": "", "client-classes": [], "hostname": "", "hw-address": "99:99:99:99:99:01", "ip-address": "192.0.200.181", "next-server": "0.0.0.0", "option-data": [], "server-hostname": "", "subnet-id": 1 }, { "boot-file-name": "", "circuit-id": "1234", "client-classes": [], "hostname": "", "ip-address": "192.0.200.181", "next-server": "0.0.0.0", "option-data": [], "server-hostname": "", "subnet-id": 1 }, { "boot-file-name": "", "client-classes": [], "hostname": "", "hw-address": "99:99:99:99:99:02", "ip-address": "192.0.200.181", "next-server": "0.0.0.0", "option-data": [], "server-hostname": "", "subnet-id": 0 }, { "boot-file-name": "", "client-classes": [], "hostname": "", "hw-address": "99:99:99:99:99:03", "ip-address": "192.0.200.181", "next-server": "0.0.0.0", "option-data": [], "server-hostname": "", "subnet-id": 2 } ] }, "result": 0, "text": "4 IPv4 host(s) found." } When using the command for retrieving DHCP6 host reservations, one can provide either an IPv6 address or a delegated prefix as the ``ip-address`` parameter. Please notice that this command does not take prefix length as a parameter in the current implementation. Thus, searching by an IP address ``2001:db8:2:cafe::`` can return host reservations with delegated prefixes of different lengths matching this search. For example: ``2001:db8:2:cafe::/63``, ``2001:db8:2:cafe::/64``, etc. Please consider the example below: :: { "command": "reservation-get-by-address", "arguments": { "ip-address": "2001:db8:2:cafa::" }, "service": [ "dhcp6" ] } Response: :: { "arguments": { "hosts": [ { "client-classes": [], "duid": "01:02:03:04:05:06:07:88:98:fa", "hostname": "foo.example.com", "ip-addresses": [ "2001:db8:1:cafe::2" ], "option-data": [], "prefixes": [ "2001:db8:2:abcd::/64", "2001:db8:2:cafa::/63" ], "subnet-id": 8 }, { "client-classes": [], "duid": "01:02:03:04:05:06:07:88:98:fb", "hostname": "foo.example.com", "ip-addresses": [ "2001:db8:1:cafe::2" ], "option-data": [], "prefixes": [ "2001:db8:2:abcd::/64", "2001:db8:2:cafa::/64" ], "subnet-id": 8 } ] }, "result": 0, "text": "2 IPv6 host(s) found." } The command accepts the ``operation-target`` argument. By default, it gets the reservation from both the JSON configuration and the hosts database. .. code-block:: json { "command": "reservation-get-by-address", "arguments": { "ip-address": "192.0.200.181", "subnet-id": 1, "operation-target": "alternate" }, "service": [ "dhcp4" ] } .. note:: This command is useful in specific cases. By default, having more than one host reservation for the same IP address in a given subnet is not allowed, as explained in :ref:`Multiple Reservations for the Same IPv4 ` or :ref:`Multiple Reservations for the Same IPv6 `. That's why this command comes in handy when the ``ip-reservations-unique`` boolean parameter is set to ``false``. Another use case of this command is having overlapping subnets with the same IP address reservations (but with different identifiers) in different subnets. .. isccmd:: reservation-get-by-hostname .. _command-reservation-get-by-hostname: The ``reservation-get-by-hostname`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-get-by-hostname` can be used to query the host database and retrieve all reservations with a specified hostname or in a specified subnet. This command uses parameters providing the mandatory ``hostname`` and the optional ``subnet-id``. Global host reservations can be retrieved by using a ``subnet-id`` value of zero (0). Hostname matching is case-insensitive. For instance, retrieving host reservations for "foobar" in the subnet 1: :: { "command": "reservation-get-by-hostname", "arguments": { "hostname": "foobar.example.org", "subnet-id": 1 } } returns some IPv4 hosts: :: { "arguments": { "hosts": [ { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "foobar.example.org", "hw-address": "01:02:03:04:05:06", "ip-address": "192.0.2.100", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org" }, { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "foobar.example.org", "hw-address": "01:02:03:04:05:ff", "ip-address": "192.0.2.200", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org" }, ... ] }, "result": 0, "text": "5 IPv4 host(s) found." } The response returned by :isccmd:`reservation-get-by-hostname` can be long, particularly when responses are not limited to a subnet. The command accepts the ``operation-target`` argument. By default, it gets the reservation from both the JSON configuration and the hosts database. .. code-block:: json { "command": "reservation-get-by-hostname", "arguments": { "hostname": "foobar.example.org", "subnet-id": 1, "operation-target": "alternate" } } For more information, see :ref:`command-reservation-get-by-hostname`. .. note:: When using MySQL as the host backend, this command relies on the fact that the hostname column in the hosts table uses a case-insensitive collation, as explained in the :ref:`mysql-database` section of :ref:`admin`. .. isccmd:: reservation-get-by-id .. _command-reservation-get-by-id: The ``reservation-get-by-id`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-get-by-id` can be used to query the host database and retrieve all reservations with a specified identifier (``identifier-type`` and ``identifier`` parameters), independently of subnets. The syntax for parameters is the same as for :isccmd:`reservation-get`. The ``subnet-id`` parameter cannot be used, to avoid confusion. This command is available since Kea version 1.9.0. For instance, retrieving host reservations for the 01:02:03:04:05:06 MAC address: :: { "command": "reservation-get-by-id", "arguments": { "identifier-type": "hw-address", "identifier": "01:02:03:04:05:06" } } returns some IPv4 hosts: :: { "arguments": { "hosts": [ { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "foo.example.org", "hw-address": "01:02:03:04:05:06", "ip-address": "192.0.2.100", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org", "subnet-id": 123 }, { "boot-file-name": "bootfile.efi", "client-classes": [ ], "hostname": "bar.example.org", "hw-address": "01:02:03:04:05:06", "ip-address": "192.0.2.200", "next-server": "192.0.0.2", "option-data": [ ], "server-hostname": "server-hostname.example.org", "subnet-id": 345 }, ... ] }, "result": 0, "text": "5 IPv4 host(s) found." } The response returned by :isccmd:`reservation-get-by-id` can be long, particularly when responses are not limited to a subnet. The command accepts the ``operation-target`` argument. By default, it gets the reservation from both the JSON configuration and the hosts database. .. code-block:: json { "command": "reservation-get-by-id", "arguments": { "identifier-type": "hw-address", "identifier": "01:02:03:04:05:06", "operation-target": "alternate" } } For more information, see :ref:`command-reservation-get-by-id`. .. isccmd:: reservation-del .. _command-reservation-del: The ``reservation-del`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-del` can be used to delete a reservation from the host database and/or JSON configuration. This command supports two types of parameters: (``subnet-id``, ``address``) or (``subnet-id``, ``identifier-type``, ``identifier``). The first type of query is used when the address (either IPv4 or IPv6) is known, but the details of the reservation are not. One common use for this type of query is to remove a reservation (e.g. a specific address should no longer be reserved). The second query uses identifiers. For maximum flexibility, Kea stores the host identifying information as a pair of values: the type and the actual identifier. Currently supported identifiers are ``"hw-address"``, ``"duid"``, ``"circuit-id"``, ``"client-id"``, and ``"flex-id"``. The ``subnet-id`` is mandatory. Use a value of zero (0) to delete a global reservation, or the ID of the subnet from which the reservation should be deleted. An example command for deleting a host reservation by (``subnet-id``, ``address``) pair looks as follows: :: { "command": "reservation-del", "arguments": { "subnet-id": 1, "ip-address": "192.0.2.202" } } An example deletion by (``subnet-id``, ``identifier-type``, ``identifier``) looks as follows: :: { "command": "reservation-del", "arguments": { "subnet-id": 4, "identifier-type": "hw-address", "identifier": "01:02:03:04:05:06" } } Command :isccmd:`reservation-del` returns a result of 0 when the host deletion was successful, or 1 if it failed. Descriptive text is provided in the event of an error. Here are some examples of possible results: :: { "result": 1, "text": "Host not deleted (not found)." } or :: { "result": 0, "text": "Host deleted." } or :: { "result": 1, "text": "Unable to delete a host because there is no hosts-database configured." } The command accepts the ``operation-target`` argument. By default, it removes the reservation from the hosts database only. .. code-block:: json { "command": "reservation-del", "arguments": { "subnet-id": 4, "identifier-type": "hw-address", "identifier": "01:02:03:04:05:06", "operation-target": "primary" } } .. isccmd:: reservation-update .. _command-reservation-update: The ``reservation-update`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :isccmd:`reservation-update` allows for the update of an existing host. It takes the same set of arguments as :isccmd:`reservation-add`, and also requires a host identifier and a subnet ID to identify the host that is being updated. The command can be as simple as having only the two mandatory entries: .. code-block:: json { "command": "reservation-update", "arguments": { "reservation": { "subnet-id": 1, "hw-address": "1a:1b:1c:1d:1e:1f" } } } In that case, however, it does not assign any resources to the host. An IPv4 address can be assigned as in this example: .. code-block:: json { "command": "reservation-update", "arguments": { "reservation": { "subnet-id": 1, "hw-address": "1a:1b:1c:1d:1e:1f", "ip-address": "192.0.2.202" } } } It can also take many more parameters, such as: .. code-block:: json { "command": "reservation-update", "arguments": { "reservation": { "subnet-id": 1, "client-id": "01:0a:0b:0c:0d:0e:0f", "ip-address": "192.0.2.205", "next-server": "192.0.2.1", "server-hostname": "hal9000", "boot-file-name": "/dev/null", "option-data": [ { "name": "domain-name-servers", "data": "10.1.1.202,10.1.1.203" } ], "client-classes": [ "office", "special_snowflake" ] } } } Here is an example of a complex IPv6 reservation update: .. code-block:: json { "command": "reservation-update", "arguments": { "reservation": { "subnet-id": 1, "duid": "01:02:03:04:05:06:07:08:09:0A", "ip-addresses": [ "2001:db8:1:cafe::1" ], "prefixes": [ "2001:db8:2:abcd::/64" ], "hostname": "foo.example.com", "option-data": [ { "name": "vendor-opts", "data": "4491" }, { "name": "tftp-servers", "space": "vendor-4491", "data": "3000:1::234" } ] } } } The command returns a status that indicates either success (result ``0``) or failure (result ``1``), and a text parameter that confirms success or explains the cause of the failure. Here's an example of a successful update: .. code-block:: json { "result": 0, "text": "Host updated." } And here's an example of a failure: .. code-block:: json { "result": 1, "text": "Mandatory 'subnet-id' parameter missing." } The command accepts the ``operation-target`` argument. By default, it adds the reservation to the hosts database only. As :isccmd:`reservation-update` is expected to store the host, the ``hosts-databases`` parameter must be specified in the configuration, and databases must not run in read-only mode if the operation target is not the JSON configuration. As with other update and set commands, this command overwrites all the contents of the entry. If the host previously had a resource assigned to it, and the :isccmd:`reservation-update` command is missing the resource, it is deleted from the database. If an incremental update of the host is desired, this can be achieved by issuing a :isccmd:`reservation-get-by-id` to get the current state of the host, selecting the host from the response, modifying it to the required outcome, and then issuing the :isccmd:`reservation-update` command with the resulting host attached. .. _hooks-host-cmds-general-mentions: General Mentions ~~~~~~~~~~~~~~~~ .. note:: The host backends for the host cache and RADIUS hook libraries do not respond to commands that return a collection of host reservations, such as :isccmd:`reservation-get-all`. Commands returning one host entry or dedicated host cache commands should be used instead.