2019-06-06 18:25:46 +02:00
|
|
|
.. _lease-cmds:
|
|
|
|
|
|
|
|
lease_cmds: Lease Commands
|
|
|
|
==========================
|
|
|
|
|
|
|
|
This section describes the hook library with commands used to manage
|
|
|
|
leases. Kea provides a way to store lease information in several
|
2019-06-26 16:03:19 -04:00
|
|
|
backends (memfile, MySQL, PostgreSQL, and Cassandra), and this library
|
|
|
|
provides an interface that can manipulate leases in a unified, safe way.
|
2019-06-06 18:25:46 +02:00
|
|
|
In particular, it allows things previously impossible: lease
|
|
|
|
manipulation in memfile while Kea is running, sanity check changes,
|
|
|
|
lease existence checks, and removal of all leases belonging to a
|
2019-06-26 16:03:19 -04:00
|
|
|
specific subnet. The hook library can also catch more obscure errors, like an attempt
|
2019-06-06 18:25:46 +02:00
|
|
|
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.
|
|
|
|
|
2019-07-01 14:20:05 -04:00
|
|
|
.. note::
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
This library may only be loaded by the ``kea-dhcp4`` or the
|
|
|
|
``kea-dhcp6`` process.
|
|
|
|
|
|
|
|
There are many use cases 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
|
2019-06-26 16:03:19 -04:00
|
|
|
disconnected and the system administrator knows that it will not be coming
|
2019-06-06 18:25:46 +02:00
|
|
|
back. The "get" queries may be useful for automating certain management
|
|
|
|
and monitoring tasks. They can also act as preparatory steps for lease
|
|
|
|
updates and removals.
|
|
|
|
|
|
|
|
This library provides the following commands:
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
- ``lease4-add`` - adds a new IPv4 lease.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
- ``lease6-add`` - adds a new IPv6 lease.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-18 13:34:01 +02:00
|
|
|
- ``lease6-bulk-apply`` - creates, updates and/or deletes multiple
|
|
|
|
IPv6 leases in a single transaction.
|
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
- ``lease4-get`` - checks whether an IPv4 lease with the specified
|
2019-06-26 16:03:19 -04:00
|
|
|
parameters exists and returns it if it does.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``lease6-get`` - checks whether an IPv6 lease with the specified
|
2019-06-26 16:03:19 -04:00
|
|
|
parameters exists and returns it if it does.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``lease4-get-all`` - returns all IPv4 leases or all IPv4 leases for
|
2019-06-26 16:03:19 -04:00
|
|
|
the specified subnets.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``lease6-get-all`` - returns all IPv6 leases or all IPv6 leases for
|
2019-06-26 16:03:19 -04:00
|
|
|
the specified subnets.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``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
|
2019-06-26 16:03:19 -04:00
|
|
|
is possible to retrieve all the leases.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``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
|
2019-06-26 16:03:19 -04:00
|
|
|
is possible to retrieve all the leases.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-10-16 23:10:01 +02:00
|
|
|
- ``lease4-get-by-hw-address`` - return all IPv4 leases with the specified
|
|
|
|
hardware address.
|
|
|
|
|
|
|
|
- ``lease4-get-by-client-id`` - return all IPv4 leases with the specified
|
|
|
|
client id.
|
|
|
|
|
2019-10-25 15:54:34 +02:00
|
|
|
- ``lease6-get-by-duid`` - returns all IPv6 leases with the specified DUID.
|
2019-10-16 23:10:01 +02:00
|
|
|
|
|
|
|
- ``lease4-get-by-hostname`` - return all IPv4 leases with the specified
|
|
|
|
hostname.
|
|
|
|
|
|
|
|
- ``lease6-get-by-hostname`` - return all IPv6 leases with the specified
|
|
|
|
hostname.
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
- ``lease4-del`` - deletes an IPv4 lease with the specified parameters.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
- ``lease6-del`` - deletes an IPv6 lease with the specified parameters.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
- ``lease4-update`` - updates an IPv4 lease.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
- ``lease6-update`` - updates an IPv6 lease.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``lease4-wipe`` - removes all leases from a specific IPv4 subnet or
|
2019-06-26 16:03:19 -04:00
|
|
|
from all subnets.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``lease6-wipe`` - removes all leases from a specific IPv6 subnet or
|
2019-06-26 16:03:19 -04:00
|
|
|
from all subnets.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-03-18 11:05:02 -04:00
|
|
|
- ``lease4-resend-ddns`` - resend a request to update DNS entries for
|
2020-03-18 15:05:11 -04:00
|
|
|
an existing lease.
|
2020-03-18 10:19:49 -04:00
|
|
|
|
2020-03-18 11:05:02 -04:00
|
|
|
- ``lease6-resend-ddns`` - resend a request to update DNS entries for
|
2020-03-18 15:05:11 -04:00
|
|
|
an existing lease.
|
2020-03-18 10:19:49 -04:00
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
The lease commands library is part of the open source code and is
|
|
|
|
available to every Kea user.
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
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`).
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
The library can be loaded in the same way as other hook libraries, and
|
|
|
|
it does not take any parameters. It supports both DHCPv4 and DHCPv6
|
|
|
|
servers.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
"Dhcp6": {
|
2019-06-06 18:25:46 +02:00
|
|
|
"hooks-libraries": [
|
|
|
|
{
|
|
|
|
"library": "/path/libdhcp_lease_cmds.so"
|
|
|
|
}
|
|
|
|
...
|
2019-06-26 16:03:19 -04:00
|
|
|
]
|
2019-06-06 18:25:46 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
.. _command-lease4-add:
|
|
|
|
|
2019-07-18 14:37:52 +02:00
|
|
|
.. _command-lease6-add:
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The lease4-add, lease6-add Commands
|
2019-08-16 19:58:41 +02:00
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
The ``lease4-add`` and ``lease6-add`` commands allow for the creation of
|
|
|
|
a new lease. Typically Kea creates a lease when it first sees a new
|
|
|
|
device; however, sometimes it may be convenient to create the lease
|
|
|
|
manually. The ``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 will try 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 ``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 lease4-add, the subnet-id parameter is
|
|
|
|
optional. If the subnet-id is not specified or the provided value is 0,
|
|
|
|
Kea will try 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
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
``lease6-add`` 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 value of "IA_PD"), and prefix length. The actual
|
2019-06-26 16:03:19 -04:00
|
|
|
prefix is set using the ip-address field. Note that Kea cannot guess
|
2019-06-06 18:25:46 +02:00
|
|
|
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
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The commands can take several additional optional parameters:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``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,
|
2019-06-26 16:03:19 -04:00
|
|
|
expressed in UNIX format (seconds since 1 Jan 1970). If not
|
2019-06-06 18:25:46 +02:00
|
|
|
specified, the default value is now + the lease lifetime (the value
|
|
|
|
of valid-lft).
|
|
|
|
|
|
|
|
- ``fqdn-fwd`` - specifies whether the lease should be marked as if a
|
2019-06-26 16:03:19 -04:00
|
|
|
forward DNS update were conducted. Note this only affects the
|
2019-06-06 18:25:46 +02:00
|
|
|
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. Note this only affects the 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 fwdn-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.
|
|
|
|
|
2020-01-24 15:23:05 +01:00
|
|
|
- ``state`` - specify the state of added lease, can be 0 for ``default``,
|
2020-01-24 14:46:49 +01:00
|
|
|
1 for ``declined`` and 2 for ``expired-reclaimed`` state. Any other
|
2020-07-29 21:15:45 +03:00
|
|
|
value will cause error. Note that using 1 for a "IA_PD" lease type is
|
|
|
|
illegal and will be rejected.
|
2020-01-24 14:46:49 +01:00
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
- ``user-context`` - specifies the user context to be associated with
|
|
|
|
this lease. It must be a JSON map.
|
|
|
|
|
|
|
|
Here is an example of a more 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,
|
2020-01-24 14:46:49 +01:00
|
|
|
"state": 0,
|
2019-06-06 18:25:46 +02:00
|
|
|
"hostname": "urania.example.org",
|
|
|
|
"user-context": { "version": 1 }
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The command returns a status that indicates either success (result 0)
|
|
|
|
or failure (result 1). A failed command always includes a text
|
2019-06-06 18:25:46 +02:00
|
|
|
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)" }
|
|
|
|
|
2019-07-18 13:34:01 +02:00
|
|
|
|
|
|
|
.. _command-lease6-bulk-apply:
|
|
|
|
|
|
|
|
The lease6-bulk-apply Command
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
The ``lease6-bulk-apply`` was implemented to address
|
|
|
|
the performance penalty in the High Availability 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. That may result in allocation of 4 leases. In addition, the
|
|
|
|
DHCPv6 may assign different address than requested by the client during
|
|
|
|
the renew or rebind and delete the leases previously used by this client.
|
|
|
|
The are 6 of lease changes sent between the HA partners is in this case.
|
|
|
|
Sending these updates in individual commands, e.g. ``lease6-update``
|
|
|
|
is highly inefficient and produces unnecessary delays in communication
|
|
|
|
between the HA partners and in sending the response to the DHCPv6 client.
|
|
|
|
|
|
|
|
The ``lease6-bulk-apply`` command deals with this
|
|
|
|
problem by aggregating all lease changes in a single command. Both
|
|
|
|
deleted leases and new/updated leases are conveyed 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 the High Avialability is the major application for
|
|
|
|
this command, it can be freely used in all cases when it is desired to
|
|
|
|
send multiple lease changes in a single command.
|
|
|
|
|
|
|
|
In the following example, we ask to delete two leases and to 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 is malformed, no leases 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
|
|
|
|
will continue to be processed for other leases. All the leases for which
|
|
|
|
the command was unable to apply the changes in the database will be
|
|
|
|
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::",
|
2019-07-18 14:07:25 +02:00
|
|
|
"type": "IA_PD",
|
|
|
|
"result": 3,
|
|
|
|
"error-message": "no lease found"
|
2019-07-18 13:34:01 +02:00
|
|
|
}
|
|
|
|
],
|
|
|
|
"failed-leases": [
|
|
|
|
{
|
|
|
|
"ip-address": "2001:db8:cafe::",
|
|
|
|
"type": "IA_PD",
|
2019-07-18 14:07:25 +02:00
|
|
|
"result": 1,
|
|
|
|
"error-message": "unable to communicate with the lease database"
|
2019-07-18 13:34:01 +02:00
|
|
|
}
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
The response above indicates that the hooks 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
|
2019-07-18 14:07:25 +02:00
|
|
|
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 meaning 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 lease doesn't exist (empty result).
|
2019-07-18 13:34:01 +02:00
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
.. _command-lease4-get:
|
|
|
|
|
2019-07-18 14:37:52 +02:00
|
|
|
.. _command-lease6-get:
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The lease4-get, lease6-get Commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
``lease4-get`` or ``lease6-get`` can be used to query the lease database
|
|
|
|
and retrieve existing leases. There are two types of parameters the
|
|
|
|
``lease4-get`` command supports: (address) or (subnet-id,
|
|
|
|
identifier-type, identifier). There are also two types for
|
2019-06-26 16:03:19 -04:00
|
|
|
``lease6-get``: (address, type) or (subnet-id, identifier-type,
|
2019-06-06 18:25:46 +02:00
|
|
|
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 ``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 ``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.
|
|
|
|
|
|
|
|
``leaseX-get`` returns a result that indicates a result of the operation
|
|
|
|
and lease details, if found. It has one of the following values: 0
|
2020-08-17 13:15:48 -04:00
|
|
|
(success), 1 (error), or 3 (empty). An empty result means that a query
|
2019-06-06 18:25:46 +02:00
|
|
|
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.
|
|
|
|
|
|
|
|
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."
|
|
|
|
}
|
|
|
|
|
|
|
|
.. _command-lease4-get-all:
|
|
|
|
|
2019-07-18 14:37:52 +02:00
|
|
|
.. _command-lease6-get-all:
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The lease4-get-all, lease6-get-all Commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
``lease4-get-all`` and ``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"
|
|
|
|
}
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
If arguments are provided, it is expected that they contain the
|
2019-06-06 18:25:46 +02:00
|
|
|
"subnets" parameter, which is a list of subnet identifiers for which the
|
|
|
|
leases should be returned. For example, in order 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."
|
|
|
|
}
|
|
|
|
|
|
|
|
..
|
|
|
|
|
2019-07-01 14:20:05 -04:00
|
|
|
.. warning::
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
The ``lease4-get-all`` and ``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.
|
|
|
|
|
2020-03-30 18:50:37 +02:00
|
|
|
.. _command-lease4-get-page:
|
|
|
|
|
|
|
|
.. _command-lease6-get-page:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The lease4-get-page, lease6-get-page Commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
The ``lease4-get-all`` and ``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 case of large lease databases it is usually better to
|
|
|
|
retrieve leases in chunks, using the paging mechanism.
|
|
|
|
``lease4-get-page`` and ``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
|
|
|
|
``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. In cases of
|
|
|
|
highly distributed databases, such as Cassandra, ordering may be
|
|
|
|
inefficient or even impossible.
|
|
|
|
|
|
|
|
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 ``lease4-get-page`` or
|
|
|
|
``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.
|
|
|
|
|
2019-10-16 23:10:01 +02:00
|
|
|
.. _command-lease4-get-by-hw-address:
|
|
|
|
|
|
|
|
.. _command-lease4-get-by-client-id:
|
|
|
|
|
|
|
|
.. _command-lease6-get-by-duid:
|
|
|
|
|
|
|
|
.. _command-lease4-get-by-hostname:
|
|
|
|
|
|
|
|
.. _command-lease6-get-by-hostname:
|
|
|
|
|
2020-07-21 08:47:08 -04:00
|
|
|
The lease4-get-by-\*, lease6-get-by-\* Commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-10-16 23:10:01 +02:00
|
|
|
|
|
|
|
``leaseX-get-by-Y`` can be used to query the lease database and
|
|
|
|
retrieve all existing leases with a specified hardware address (IPv4
|
|
|
|
only), client id IPv4 only), duid (IPv6 only) identifiers or hostname.
|
|
|
|
|
|
|
|
An example ``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 ``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 than ``leaseX-get-all``. This list can be
|
|
|
|
empty and usually is never large.
|
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
.. _command-lease4-del:
|
|
|
|
|
2019-07-18 14:37:52 +02:00
|
|
|
.. _command-lease6-del:
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The lease4-del, lease6-del Commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
``leaseX-del`` can be used to delete a lease from the lease database.
|
2019-06-26 16:03:19 -04:00
|
|
|
There are two types of parameters this command supports, similar to the
|
2019-06-06 18:25:46 +02:00
|
|
|
leaseX-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
|
2019-06-26 16:03:19 -04:00
|
|
|
a pair of values: the type and the actual identifier. The currently
|
2019-06-06 18:25:46 +02:00
|
|
|
supported identifiers are "hw-address" (IPv4 only), "client-id" (IPv4
|
|
|
|
only), and "duid" (IPv6 only).
|
|
|
|
|
2020-07-17 11:56:15 -04:00
|
|
|
An example command for deleting a lease by address is
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
{
|
|
|
|
"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
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-07-17 11:56:15 -04:00
|
|
|
|
2020-07-21 08:47:08 -04:00
|
|
|
As of Kea 1.7.10, a new parameter, ``update-ddns``, is supported (IPv4 and IPv6).
|
2020-07-21 13:10:11 +02:00
|
|
|
When true it instructs the server to queue a request to kea-dhcp-ddns to
|
2020-07-21 13:01:07 +02:00
|
|
|
remove DNS entries after the lease is successfully deleted if:
|
2020-07-17 11:56:15 -04:00
|
|
|
|
2020-07-21 13:10:11 +02:00
|
|
|
- DDNS updating is enabled. (i.e. "dhcp-ddns":{ "enable-updates": true })
|
2020-07-17 11:56:15 -04:00
|
|
|
- The lease's hostname is not be empty.
|
|
|
|
- At least one of the lease's DNS direction flags (fdqn_fwd or fdqn_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
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
``leaseX-del`` returns 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.
|
|
|
|
|
|
|
|
.. _command-lease4-update:
|
|
|
|
|
2019-07-18 14:37:52 +02:00
|
|
|
.. _command-lease6-update:
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The lease4-update, lease6-update Commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
The ``lease4-update`` and ``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
|
|
|
|
``leaseX-del`` followed by ``leaseX-add``.
|
|
|
|
|
|
|
|
The subnet-id parameter is optional. If not specified, or if the
|
|
|
|
specified value is 0, Kea will try 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
|
2019-06-26 16:03:19 -04:00
|
|
|
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
|
2019-06-06 18:25:46 +02:00
|
|
|
exist. In such a case, an error is returned as a result of 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 ``leaseX-update``.
|
|
|
|
|
|
|
|
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
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
.. _command-lease4-wipe:
|
|
|
|
|
2019-07-18 14:37:52 +02:00
|
|
|
.. _command-lease6-wipe:
|
|
|
|
|
2019-06-26 16:03:19 -04:00
|
|
|
The lease4-wipe, lease6-wipe Commands
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
``lease4-wipe`` and ``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. Note that the leases
|
2019-06-26 16:03:19 -04:00
|
|
|
are not properly expired; no DNS updates are carried out, no log
|
2019-06-06 18:25:46 +02:00
|
|
|
messages are created, and hooks are not called for the leases being
|
|
|
|
removed.
|
|
|
|
|
|
|
|
An example of ``lease4-wipe`` is:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
{
|
|
|
|
"command": "lease4-wipe",
|
|
|
|
"arguments": {
|
|
|
|
"subnet-id": 44
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
An example of ``lease6-wipe`` is:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
{
|
|
|
|
"command": "lease6-wipe",
|
|
|
|
"arguments": {
|
|
|
|
"subnet-id": 66
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-03-18 11:05:02 -04:00
|
|
|
The commands return a text description of the number of leases removed,
|
2020-08-17 13:15:48 -04:00
|
|
|
plus the status code 0 (success) if any leases were removed or 3 (empty)
|
2020-03-18 11:05:02 -04:00
|
|
|
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: not all backends support this command.
|
|
|
|
|
2020-03-18 10:19:49 -04:00
|
|
|
.. _command-lease4-resend-ddns:
|
|
|
|
|
|
|
|
.. _command-lease6-resend-ddns:
|
|
|
|
|
|
|
|
The lease4-resend-ddns, lease6-resend-ddns Commands
|
2020-03-18 11:05:02 -04:00
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2020-03-18 10:19:49 -04:00
|
|
|
|
|
|
|
``lease4-resend-ddns`` or ``lease6-resend-ddns`` can be used to generate
|
|
|
|
a request to kea-dhcp-ddns to update the DNS entries for an existing
|
|
|
|
lease. The desired lease is selected by a single parameter, "ip-address".
|
|
|
|
In order for an update request to be generated, DDNS updating must be enabled
|
2020-03-18 15:05:11 -04:00
|
|
|
and DNS entries must have already been made (or attempted) for the lease.
|
2020-03-18 11:05:02 -04:00
|
|
|
In other words all of the following must be true:
|
2020-03-18 10:19:49 -04:00
|
|
|
|
|
|
|
- DDNS updating must be enabled. (i.e. "dhcp-ddns":{ "enable-updates": true"})
|
2020-03-18 15:05:11 -04:00
|
|
|
- The lease's hostname must not be empty.
|
2020-03-18 11:05:02 -04:00
|
|
|
- At least one of the lease's DNS direction flags (fdqn_fwd or fdqn_rev) must be true.
|
2020-03-18 10:19:49 -04:00
|
|
|
|
|
|
|
An example ``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 ``lease6-resend-ddns`` query is:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
{
|
|
|
|
"command": "lease6-resend-ddns",
|
|
|
|
"arguments": {
|
2020-03-18 11:05:02 -04:00
|
|
|
"ip-address": "2001:db8:1::1"
|
2020-03-18 10:19:49 -04:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
``leaseX-resend-ddns`` returns a result that indicates a result of the operation.
|
2020-08-17 13:15:48 -04:00
|
|
|
It has one of the following values: 0 (success), 1 (error), or 3 (empty). An empty
|
2020-03-18 10:19:49 -04:00
|
|
|
result means that a query has been completed properly, but the object (a lease in
|
|
|
|
this case) has not been found.
|
|
|
|
|
2020-03-18 11:05:02 -04:00
|
|
|
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 kea-dhcp-ddns.
|
2020-03-18 10:19:49 -04:00
|
|
|
|
|
|
|
An example result returned when the lease was found:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
{
|
|
|
|
"result": 0,
|
|
|
|
"text": "NCR generated for: 2001:db8:1::1, hostname: example.com."
|
|
|
|
}
|
|
|
|
|