diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/sphinx/arm/hooks-lease-cmds.rst | 1073 |
1 files changed, 1073 insertions, 0 deletions
diff --git a/doc/sphinx/arm/hooks-lease-cmds.rst b/doc/sphinx/arm/hooks-lease-cmds.rst new file mode 100644 index 0000000..61ee755 --- /dev/null +++ b/doc/sphinx/arm/hooks-lease-cmds.rst @@ -0,0 +1,1073 @@ +.. ischooklib:: libdhcp_lease_cmds.so +.. _hooks-lease-cmds: + +``libdhcp_lease_cmds.so``: 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. + +.. note:: + + :ischooklib:`libdhcp_lease_cmds.so` 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:`lease4-get` and :isccmd:`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:`lease4-update` / :isccmd:`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:`lease4-update` / :isccmd:`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:`lease4-update` / :isccmd:`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. |