path: root/doc/sphinx/arm/hooks-lease-cmds.rst

.. _hooks-lease-cmds:

``lease_cmds``: Lease Commands for Easier Lease Management
==========================================================

Kea allows users to store lease information in several
backends (memfile, MySQL, and PostgreSQL), and the Lease Commands library provides an
interface that can manipulate leases in a unified, safe way.
In particular, it allows things that were previously impossible: lease
manipulation in memfile while Kea is running, sanity check changes,
lease existence checks, and removal of all leases belonging to a
specific subnet. The hook library can also catch more obscure errors, like an attempt
to add a lease with a ``subnet-id`` that does not exist in the
configuration, or configuring a lease to use an address that is outside
of the subnet to which it is supposed to belong. The library also
provides a non-programmatic way to manage user contexts associated with
leases.

The Lease Commands library is part of the open source code and is
available to every Kea user.

.. note::

   This library can only be loaded by the :iscman:`kea-dhcp4` or the
   :iscman:`kea-dhcp6` process.

There are many situations where an administrative command may be useful;
for example, during migration between servers or different vendors, when
a certain network is being retired, or when a device has been
disconnected and the system administrator knows that it will not be coming
back. The ``get`` queries may be useful for automating certain management
and monitoring tasks, and they can also act as preparatory steps for lease
updates and removals.

This library provides the following commands:

-  :isccmd:`lease4-add` - adds a new IPv4 lease.

-  :isccmd:`lease6-add` - adds a new IPv6 lease.

-  :isccmd:`lease6-bulk-apply` - creates, updates, and/or deletes multiple
   IPv6 leases in a single transaction.

-  :isccmd:`lease4-get` - checks whether an IPv4 lease with the specified
   parameters exists and returns it if it does.

-  :isccmd:`lease6-get` - checks whether an IPv6 lease with the specified
   parameters exists and returns it if it does.

-  :isccmd:`lease4-get-all` - returns all IPv4 leases or all IPv4 leases for
   the specified subnets.

-  :isccmd:`lease6-get-all` - returns all IPv6 leases or all IPv6 leases for
   the specified subnets.

-  :isccmd:`lease4-get-page` - returns a set ("page") of leases from the list
   of all IPv4 leases in the database. By iterating through the pages it
   is possible to retrieve all the leases.

-  :isccmd:`lease6-get-page` - returns a set ("page") of leases from the list
   of all IPv6 leases in the database. By iterating through the pages it
   is possible to retrieve all the leases.

-  :isccmd:`lease4-get-by-hw-address` - returns all IPv4 leases with the specified
   hardware address.

-  :isccmd:`lease4-get-by-client-id` - returns all IPv4 leases with the specified
   ``client-id``.

-  :isccmd:`lease6-get-by-duid` - returns all IPv6 leases with the specified DUID.

-  :isccmd:`lease4-get-by-hostname` - returns all IPv4 leases with the specified
   hostname.

-  :isccmd:`lease6-get-by-hostname` - returns all IPv6 leases with the specified
   hostname.

-  :isccmd:`lease4-del` - deletes an IPv4 lease with the specified parameters.

-  :isccmd:`lease6-del` - deletes an IPv6 lease with the specified parameters.

-  :isccmd:`lease4-update` - updates (replaces) an existing IPv4 lease.

-  :isccmd:`lease6-update` - updates (replaces) an existing IPv6 lease.

-  :isccmd:`lease4-wipe` - removes all leases from a specific IPv4 subnet or
   from all subnets.

-  :isccmd:`lease6-wipe` - removes all leases from a specific IPv6 subnet or
   from all subnets.

-  :isccmd:`lease4-resend-ddns` - resends a request to update DNS entries for
   an existing lease.

-  :isccmd:`lease6-resend-ddns` - resends a request to update DNS entries for
   an existing lease.

-  :isccmd:`lease4-write` - writes the IPv4 memfile lease database into a file.

-  :isccmd:`lease6-write` - writes the IPv6 memfile lease database into a file.

All commands use JSON syntax and can be issued either using the control
channel (see :ref:`ctrl-channel`) or Control Agent (see
:ref:`kea-ctrl-agent`).

The library can be loaded in the same way as other hook libraries, and
it does not take any parameters. It supports both the DHCPv4 and DHCPv6
servers.

::

   "Dhcp6": {
       "hooks-libraries": [
           {
               "library": "/path/libdhcp_lease_cmds.so"
           },
           ...
       ]
   }

.. isccmd:: lease4-add
.. _command-lease4-add:

.. isccmd:: lease6-add
.. _command-lease6-add:

The ``lease4-add``, ``lease6-add`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :isccmd:`lease4-add` and
:isccmd:`lease6-add` commands allow a new lease
to be created. Typically Kea creates a lease when it first sees a new
device; however, sometimes it may be convenient to create the lease
manually. The :isccmd:`lease4-add` command requires at least two parameters:
an IPv4 address and an identifier, i.e. hardware (MAC) address. A third
parameter, ``subnet-id``, is optional. If the ``subnet-id`` is not specified or
the specified value is 0, Kea tries to determine the value by running
a subnet-selection procedure. If specified, however, its value must
match the existing subnet. The simplest successful call might look as
follows:

::

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

The :isccmd:`lease6-add` command requires three parameters: an IPv6 address,
an IAID value (identity association identifier, a value sent by
clients), and a DUID. As with :isccmd:`lease4-add`, the ``subnet-id`` parameter is
optional. If the ``subnet-id`` is not specified or the provided value is 0,
Kea tries to determine the value by running a subnet-selection
procedure. If specified, however, its value must match the existing
subnet. For example:

::

   {
       "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
       }
   }

The :isccmd:`lease6-add` command can also be used to add leases for IPv6 prefixes.
In this case there are three additional parameters that must be specified:
``subnet-id``, ``type`` (set to "IA_PD"), and prefix length. The actual
prefix is set using the ``ip-address`` field. Note that Kea cannot guess
``subnet-id`` values for prefixes; they must be specified explicitly. For
example, to configure a lease for prefix 2001:db8:abcd::/48, the
following command can be used:

::

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

The commands can take several additional optional parameters:

-  ``valid-lft`` - specifies the lifetime of the lease, expressed in
   seconds. If not specified, the value configured in the subnet related
   to the specified ``subnet-id`` is used.

-  ``expire`` - creates a timestamp of the lease expiration time,
   expressed in UNIX format (seconds since 1 Jan 1970). If not
   specified, the default value is the current time plus the lease lifetime (the value
   of ``valid-lft``).

-  ``fqdn-fwd`` - specifies whether the lease should be marked as if a
   forward DNS update were conducted. This only affects the
   data stored in the lease database, and no DNS update will be
   performed. If configured, a DNS update to remove the A or AAAA
   records will be conducted when the lease is removed due to expiration
   or being released by a client. If not specified, the default value is
   ``false``. The hostname parameter must be specified if ``fqdn-fwd`` is set to
   ``true``.

-  ``fqdn-rev`` - specifies whether the lease should be marked as if
   reverse DNS update were conducted. This only affects the
   data stored in the lease database, and no DNS update will be
   performed.. If configured, a DNS update to remove the PTR record will
   be conducted when the lease is removed due to expiration or being
   released by a client. If not specified, the default value is ``false``.
   The hostname parameter must be specified if ``fqdn-fwd`` is set to ``true``.

-  ``hostname`` - specifies the hostname to be associated with this
   lease. Its value must be non-empty if either ``fqdn-fwd`` or ``fqdn-rev`` are
   set to ``true``. If not specified, the default value is an empty string.

-  ``hw-address`` - optionally specifies a hardware (MAC) address for an
   IPv6 lease. It is a mandatory parameter for an IPv4 lease.

-  ``client-id`` - optionally specifies a client identifier for an IPv4
   lease.

-  ``preferred-lft`` - optionally specifies a preferred lifetime for
   IPv6 leases. If not specified, the value configured for the subnet
   corresponding to the specified ``subnet-id`` is used. This parameter is
   not used when adding an IPv4 lease.

-  ``state`` - specifies the state of an added lease, which can be 0 for ``default``,
   1 for ``declined``, and 2 for the ``expired-reclaimed`` state. Any other
   value causes an error. Using 1 for a ``"IA_PD"`` lease type is
   illegal and will be rejected.

-  ``user-context`` - specifies the user context to be associated with
   this lease. It must be a JSON map.

Here is an example of a fairly complex lease addition:

::

   {
       "command": "lease6-add",
       "arguments": {
           "subnet-id": 66,
           "ip-address": "2001:db8::3",
           "duid": "01:02:03:04:05:06:07:08",
           "iaid": 1234,
           "hw-address": "1a:1b:1c:1d:1e:1f",
           "preferred-lft": 500,
           "valid-lft": 1000,
           "expire": 12345678,
           "fqdn-fwd": true,
           "fqdn-rev": true,
           "state": 0,
           "hostname": "urania.example.org",
           "user-context": { "version": 1 }
       }
   }

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 failure. For example:

::

   { "result": 0, "text": "Lease added." }

Example failure:

::

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


.. isccmd:: lease6-bulk-apply
.. _command-lease6-bulk-apply:

The lease6-bulk-apply Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :isccmd:`lease6-bulk-apply` was implemented to address
the performance penalty in High-Availability mode when a single DHCPv6
transaction resulted in multiple lease updates sent to the partner, if
multiple address and/or prefix leases were allocated. Consider the case
when a DHCPv6 client requests the assignment of two IPv6 addresses and two IPv6
prefixes: it may result in the allocation of four leases. In addition,
DHCPv6 may assign a different address than the one requested by the client during
the renew or rebind stage, and delete the leases previously used by this client.
There are six lease changes sent between the HA partners in this case.
Sending these updates as individual commands, e.g. via :isccmd:`lease6-update`,
is highly inefficient and produces unnecessary delays in communication,
both between the HA partners and in sending the response to the DHCPv6 client.

The :isccmd:`lease6-bulk-apply` command deals with this
problem by aggregating all lease changes - both deleted leases and
new or updated leases - in a single command.
The receiving server iterates over the deleted leases and deletes them
from its lease database. Next, it iterates over the new/updated leases
and adds them to the database or updates them if they already exist.

Even though High Availability is the major application for
this command, it can be freely used in all cases when it is desirable to
send multiple lease changes in a single command.

In the following example, we delete two leases and add
or update two other leases in the database:


::

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

If any of the leases are malformed, no lease changes are applied
to the lease database. If the leases are well-formed but there is a
failure to apply any of the lease changes to the database, the command
continues to be processed for other leases. All the leases for which
the command was unable to apply the changes in the database are
listed in the response. For example:

::

    {
        "result": 0,
        "text": "Bulk apply of 2 IPv6 leases completed",
        "arguments": {
            "failed-deleted-leases": [
                {
                    "ip-address": "2001:db8:abcd::",
                    "type": "IA_PD",
                    "result": 3,
                    "error-message": "no lease found"
                }
            ],
            "failed-leases": [
                {
                    "ip-address": "2001:db8:cafe::",
                    "type": "IA_PD",
                    "result": 1,
                    "error-message": "unable to communicate with the lease database"
                }
            ]
        }
    }

The response above indicates that the hook library was unable to
delete the lease for prefix "2001:db8:abcd::" and add or update the lease
for prefix "2001:db8:cafe::". However, there are two other lease changes
which have been applied as indicated by the text message. The
``result`` is the status constant that indicates the type
of the error experienced for the particular lease. The meanings of the
returned codes are the same as the results returned for the commands.
In particular, the result of 1 indicates an error while processing the
lease, e.g. a communication error with the database. The result of 3
indicates that an attempt to delete the lease was unsuccessful because
such a lease doesn't exist (an empty result).

.. isccmd:: lease4-get
.. _command-lease4-get:

.. isccmd:: lease6-get
.. _command-lease6-get:

The ``lease4-get``, ``lease6-get`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:isccmd:`lease4-get` and :isccmd:`lease6-get` can be used to query the lease database
and retrieve existing leases. There are two types of parameters the
:isccmd:`lease4-get` command supports: (``address``) or (``subnet-id``,
``identifier-type``, ``identifier``). There are also two types for
:isccmd:`lease6-get`: (``address``, ``type``) or (``subnet-id``, ``identifier-type``,
``identifier``, ``IAID``, ``type``). The first type of query is used when the
address (either IPv4 or IPv6) is known, but the details of the lease are
not; one common use case of this type of query is to find out whether a
given address is being used. The second query uses identifiers;
currently supported identifiers for leases are: ``"hw-address"`` (IPv4
only), ``"client-id"`` (IPv4 only), and ``"duid"`` (IPv6 only).

An example :isccmd:`lease4-get` command for getting a lease using an IPv4
address is:

::

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

An example of the :isccmd:`lease6-get` query is:

::

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

An example query by ``"hw-address"`` for an IPv4 lease looks as follows:

::

   {
       "command": "lease4-get",
       "arguments": {
           "identifier-type": "hw-address",
           "identifier": "08:08:08:08:08:08",
           "subnet-id": 44
       }
   }

An example query by ``"client-id"`` for an IPv4 lease looks as follows:

::

   {
       "command": "lease4-get",
       "arguments": {
           "identifier-type": "client-id",
           "identifier": "01:01:02:03:04:05:06",
           "subnet-id": 44
       }
   }

An example query by (``subnet-id``, ``identifier-type``, ``identifier``, ``iaid``, ``type``)
for an IPv6 lease is:

::

   {
       "command": "lease4-get",
       "arguments": {
           "identifier-type": "duid",
           "identifier": "08:08:08:08:08:08",
           "iaid": 1234567,
           "type": "IA_NA",
           "subnet-id": 44
       }
   }

The ``type`` is an optional parameter. Supported values are: ``IA_NA``
(non-temporary address) and ``IA_PD`` (IPv6 prefix). If not specified, ``IA_NA``
is assumed.

:isccmd:`lease4-get` and :isccmd:`lease6-get` return an indication of the result of the operation
and lease details, if found. The result has one of the following values: 0
(success), 1 (error), or 3 (empty). An empty result means that a query
has been completed properly, but the object (a lease in this case) has
not been found.
The lease parameters, if found, are returned as arguments.
``client-id`` is not returned if empty.

An example result returned when the host was found:

::

   {
     "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."
   }

.. note::

   The client last transaction time (``cltt`` field) is bound to the
   valid lifetime (``valid-lft``) and to the expire date (not reported
   here but stored in databases) by the equation
   :math:`cltt + valid\_lft = expire`

   at the exception of the infinite valid lifetime coded by the
   0xfffffff (4294967295) special value which makes the expire value
   to overflow on MySQL and old PostgreSQL backends where timestamps
   are 32 bit long. So in these lease databases the expire date is the
   same as the cltt i.e.
   :math:`cltt = expire` when :math:`valid\_lft = 4294967295` and the
   lease backend is MySQL or PostgreSQL.

.. isccmd:: lease4-get-all
.. _command-lease4-get-all:

.. isccmd:: lease6-get-all
.. _command-lease6-get-all:

The ``lease4-get-all``, ``lease6-get-all`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:isccmd:`lease4-get-all` and :isccmd:`lease6-get-all` are used to retrieve all IPv4
or IPv6 leases, or all leases for the specified set of subnets. All
leases are returned when there are no arguments specified with the
command, as in the following example:

::

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

If arguments are provided, it is expected that they contain the
``"subnets"`` parameter, which is a list of subnet identifiers for which
leases should be returned. For example, to retrieve all IPv6
leases belonging to the subnets with identifiers 1, 2, 3, and 4:

::

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

The returned response contains a detailed list of leases in the
following format:

::

   {
       "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."
   }

.. warning::

   The :isccmd:`lease4-get-all` and
   :isccmd:`lease6-get-all` commands may result in
   very large responses. This may have a negative impact on the DHCP
   server's responsiveness while the response is generated and
   transmitted over the control channel, as the server imposes no
   restriction on the number of leases returned as a result of this
   command.

.. isccmd:: lease4-get-page
.. _command-lease4-get-page:

.. isccmd:: lease6-get-page
.. _command-lease6-get-page:

The ``lease4-get-page``, ``lease6-get-page`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :isccmd:`lease4-get-all` and
:isccmd:`lease6-get-all` commands may result in
very large responses; generating such a response may consume CPU
bandwidth as well as memory. It may even cause the server to become
unresponsive. In the case of large lease databases it is usually better to
retrieve leases in chunks, using the paging mechanism.
:isccmd:`lease4-get-page` and :isccmd:`lease6-get-page` implement a paging mechanism
for DHCPv4 and DHCPv6 servers, respectively. The following command
retrieves the first 1024 IPv4 leases:

::

   {
       "command": "lease4-get-page",
       "arguments": {
           "from": "start",
           "limit": 1024
       }
   }

The keyword ``start`` denotes that the first page of leases should be
retrieved. Alternatively, an IPv4 zero address can be specified to
retrieve the first page:

::

   {
       "command": "lease4-get-page",
       "arguments": {
           "from": "0.0.0.0",
           "limit": 1024
       }
   }

Similarly, the IPv6 zero address can be specified in the
:isccmd:`lease6-get-page` command:

::

   {
       "command": "lease6-get-page",
       "arguments": {
           "from": "::",
           "limit": 6
       }
   }

The response has the following structure:

::

   {
       "arguments": {
           "leases": [
               {
                   "ip-address": "2001:db8:2::1",
                   ...
               },
               {
                   "ip-address": "2001:db8:2::9",
                   ...
               },
               {
                   "ip-address": "2001:db8:3::1",
                   ...
               },
               {
                   "ip-address": "2001:db8:5::3",
                   ...
               },
               {
                   "ip-address": "2001:db8:4::1",
                   ...
               },
               {
                   "ip-address": "2001:db8:2::7",
                   ...
               },
               ...
           ],
           "count": 6
       },
       "result": 0,
       "text": "6 IPv6 lease(s) found."
   }

Note that the leases' details were excluded from the response above for
brevity.

Generally, the returned list is not sorted in any particular order. Some
lease database backends may sort leases in ascending order of addresses,
but the controlling client must not rely on this behavior.

The ``count`` parameter contains the number of returned leases on the
page.

To fetch the next page, the client must use the last address of the
current page as an input to the next :isccmd:`lease4-get-page` or
:isccmd:`lease6-get-page` command call. In this example it is:

::

   {
       "command": "lease6-get-page",
       "arguments": {
           "from": "2001:db8:2::7",
           "count": 6
       }
   }

because 2001:db8:2::7 is the last address on the current page.

The client may assume that it has reached the last page when the
``count`` value is lower than that specified in the command; this
includes the case when the ``count`` is equal to 0, meaning that no
leases were found.

.. isccmd:: lease4-get-by-hw-address
.. _command-lease4-get-by-hw-address:

.. isccmd:: lease4-get-by-client-id
.. _command-lease4-get-by-client-id:

.. isccmd:: lease6-get-by-duid
.. _command-lease6-get-by-duid:

.. isccmd:: lease4-get-by-hostname
.. _command-lease4-get-by-hostname:

.. isccmd:: lease6-get-by-hostname
.. _command-lease6-get-by-hostname:

The ``lease4-get-by-*``, ``lease6-get-by-*`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``lease4-get-by-*`` and ``lease6-get-by-*`` can be used to query the lease database and
retrieve all existing leases matching a given feature (denoted by the ``*``). These
can include a specified hardware address (IPv4
only), ``client-id`` IPv4 only), ``duid`` (IPv6 only) identifiers, or hostname.

An example :isccmd:`lease4-get-by-hw-address` command for getting IPv4 leases
with a given hardware address is:

::

    {
        "command": "lease4-get-by-hw-address",
        "arguments": {
            "hw-address": "08:08:08:08:08:08"
        }
    }

An example of the :isccmd:`lease6-get-by-hostname` is:

::

    {
        "command": "lease6-get-by-hostname",
        "arguments": {
            "hostname": "myhost.example.org"
        }
    }

The ``by`` key is the only parameter. The returned response contains a detailed
list of leases in the same format as :isccmd:`lease4-get-all` or :isccmd:`lease6-get-all`. This list can be
empty and is usually not large.

.. isccmd:: lease4-del
.. _command-lease4-del:

.. isccmd:: lease6-del
.. _command-lease6-del:

The ``lease4-del``, ``lease6-del`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:isccmd:`lease4-del` and :isccmd:`lease6-del` can be used to delete a lease from the lease database.
There are two types of parameters these commands support, similar to the
:isccmd::isccmd:`lease4-get` and `lease6-get` commands: (``address``) for both v4 and v6, (``subnet-id``,
``identifier-type``, ``identifier``) for v4, and (``subnet-id``, ``identifier-type``,
``identifier``, ``type``, ``IAID``) for v6. The first type of query is used when the
address (either IPv4 or IPv6) is known, but the details of the lease are
not. One common use case is where an administrator wants a specified
address to no longer be used. The second form of the command uses
identifiers. For maximum flexibility, this interface uses identifiers as
a pair of values: the type and the actual identifier. The currently
supported identifiers are ``"hw-address"`` (IPv4 only), ``"client-id"`` (IPv4
only), and ``"duid"`` (IPv6 only).

An example command for deleting a lease by address is:

::

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

An example IPv4 lease deletion by ``"hw-address"`` is:

::

   {
     "command": "lease4-del",
     "arguments": {
       "identifier": "08:08:08:08:08:08",
       "identifier-type": "hw-address",
       "subnet-id": 44
     }
   }


Another parameter called ``update-ddns``, when ``true``, instructs the server to
queue a request to :iscman:`kea-dhcp-ddns` to remove DNS entries after the lease is
successfully deleted if:

- DDNS updating is enabled (i.e. ``"dhcp-ddns":{ "enable-updates": true }``).
- The lease's hostname is not empty.
- At least one of the lease's DNS direction flags (``fqdn_fwd`` or ``fqdn_rev``) is true.

This parameter defaults to ``false``. An example of its use is shown below:

::

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


Commands :isccmd:`lease4-del` and :isccmd:`lease6-del` return a result that indicates the outcome
of the operation. It has one of the following values: 0 (success), 1 (error),
or 3 (empty). The empty result means that a query has been completed properly,
but the object (a lease, in this case) has not been found.

.. isccmd:: lease4-update
.. _command-lease4-update:

.. isccmd:: lease6-update
.. _command-lease6-update:

The ``lease4-update``, ``lease6-update`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :isccmd:`lease4-update` and
:isccmd:`lease6-update` commands can be used to
update existing leases. Since all lease database backends are indexed by
IP addresses, it is not possible to update an address, but all other
fields may be altered. If an address needs to be changed, please use
:isccmd:`lease4-del` / :isccmd:`lease6-del` followed by :isccmd:`lease4-add` / :isccmd:`lease6-add`.

The ``subnet-id`` parameter is optional. If not specified, or if the
specified value is 0, Kea tries to determine its value by running a
subnet-selection procedure. If specified, however, its value must match
the existing subnet.

The optional boolean parameter ``"force-create"`` specifies whether the
lease should be created if it does not exist in the database. It defaults
to ``false``, which indicates that the lease is not created if it does not
exist. In such a case, an error is returned when trying to
update a non-existing lease. If the ``"force-create"`` parameter is set to
``true`` and the updated lease does not exist, the new lease is created as a
result of receiving the :isccmd::isccmd:`lease4-update`/`lease6-update` command.

An example of a command to update an IPv4 lease is:

::

   {
     "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
     }
   }

An example of a command to update an IPv6 lease is:

::

   {
     "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
     }
   }

As with other update commands, this command overwrites all the contents of the
entry. If the lease previously had a resource assigned to it, and the
:isccmd::isccmd:`lease4-update`/`lease6-update` command is missing the resource, it is
deleted from the lease database. If an incremental update of the lease is
desired, then this can be achieved by doing a :isccmd:`lease4-get` / :isccmd:`lease6-get`
command to get the current state of the lease, picking the lease out of the
response, modifying it to the required outcome, and then issuing the
:isccmd::isccmd:`lease4-update`/`lease6-update` command with the resulting lease attached.

.. isccmd:: lease4-wipe
.. _command-lease4-wipe:

.. isccmd:: lease6-wipe
.. _command-lease6-wipe:

The ``lease4-wipe``, ``lease6-wipe`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:isccmd:`lease4-wipe` and :isccmd:`lease6-wipe` are designed to remove all leases
associated with a given subnet. This administrative task is expected to
be used when an existing subnet is being retired. The leases
are not properly expired; no DNS updates are carried out, no log
messages are created, and hooks are not called for the leases being
removed.

An example of :isccmd:`lease4-wipe` is:

::

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

An example of :isccmd:`lease6-wipe` is:

::

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

The commands return a text description of the number of leases removed,
plus the status code 0 (success) if any leases were removed or 3 (empty)
if there were no leases. Status code 1 (error) may be returned if the
parameters are incorrect or some other exception is encountered.

``subnet-id`` 0 has a special meaning; it tells Kea to delete leases from
all configured subnets. Also, the ``subnet-id`` parameter may be omitted. If
not specified, leases from all subnets are wiped.

Note: currently only memfile lease storage supports this command.

.. isccmd:: lease4-resend-ddns
.. _command-lease4-resend-ddns:

.. isccmd:: lease6-resend-ddns
.. _command-lease6-resend-ddns:

The ``lease4-resend-ddns``, ``lease6-resend-ddns`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:isccmd:`lease4-resend-ddns` and :isccmd:`lease6-resend-ddns` can be used to generate
a request to :iscman:`kea-dhcp-ddns` to update the DNS entries for an existing
lease.  The desired lease is selected by a single parameter, ``"ip-address"``.
For an update request to be generated, DDNS updating must be enabled
and DNS entries must have already been made (or attempted) for the lease.
In other words, all of the following must be true:

- DDNS updating must be enabled (i.e. ``"dhcp-ddns":{ "enable-updates": true"}``).
- The lease's hostname must not be empty.
- At least one of the lease's DNS direction flags (``fqdn_fwd`` or ``fqdn_rev``) must be true.

An example :isccmd:`lease4-resend-ddns` command for getting a lease using an IPv4
address is:

::

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

An example of the :isccmd:`lease6-resend-ddns` query is:

::

   {
     "command": "lease6-resend-ddns",
     "arguments": {
       "ip-address": "2001:db8:1::1"
     }
   }

Commands :isccmd:`lease4-resend-ddns` and :isccmd:`lease6-resend-ddns` return an indication of the
result of the operation. It has one of the following values: 0 (success), 1 (error),
or 3 (empty). An empty result means that a query has been completed properly, but the
object (a lease in this case) has not been found.

A successful result does not mean that DNS has been successfully updated; it
indicates that a request to update DNS has been successfully created and
queued for transmission to :iscman:`kea-dhcp-ddns`.

Here's an example of a result returned when the lease was found:

::

   {
     "result": 0,
     "text": "NCR generated for: 2001:db8:1::1, hostname: example.com."
   }

.. isccmd:: lease4-write
.. _command-lease4-write:

.. isccmd:: lease6-write
.. _command-lease6-write:

The ``lease4-write``, ``lease6-write`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:isccmd:`lease4-write` and :isccmd:`lease6-write` can be used for recovery in emergency
situations where the memfile lease file is damaged, e.g. removed by
accident or truncated by a full file system, but the in-memory database
is still valid. These commands are supported only by the memfile database
backend and write the lease database into a CSV file. They take the path
of the file as the ``filename`` argument. If the specified output file
is the same as the configured memfile one, the backend closes and reopens
the file in an attempt to synchronize both the files and the in-memory images
of the lease database. The extension ``.bak`` with server PID number is added
to the previous filename. For example ``.bak14326``.

.. note::

   These commands do not replace the LFC mechanism; they should be used
   only in exceptional circumstances, such as when recovering after
   running out of disk space.