--- /dev/null
+<!--
+ - Copyright (C) 2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
+ <section xml:id="lease-cmds">
+ <title>lease_cmds: Lease Commands</title>
+ <para>
+ This section describes the hook library that offers a number of new
+ commands used to manage leases. Kea provides a way to store lease
+ information in several backends (memfile, MySQL, PostgreSQL and
+ Cassandra). This library provides a unified interface that can
+ manipulate leases in an unified, safe way. In particular, it allows
+ things previously impossible: manipulate leases in memfile while Kea
+ is running, sanity check changes, check lease existence and remove all
+ leases belonging to specific subnet. It can also catch more obscure
+ errors, like adding a lease with 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.
+
+ <note>
+ <para>This library may only be loaded by <command>kea-dhcp4</command>
+ or <command>kea-dhcp6</command> process.
+ </para>
+ </note>
+ </para>
+
+ <para>There are many use cases when an administrative command may be
+ useful: during migration between servers (possibly even between
+ different vendors), when a certain network is being retired, when a
+ device has been disconnected and the sysadmin knows for sure that it
+ will not be coming 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.</para>
+
+ <para>
+ This library provides the following commands:
+ <itemizedlist>
+ <listitem>
+ <para><command>lease4-add</command> - adds new IPv4 lease;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-add</command> - adds new IPv6 lease;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-get</command> - checks if an IPv4 lease with
+ the specified parameters exists and returns it if it does;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-get</command> - checks if an IPv6 lease with
+ the specified parameters exists and returns it if it does;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-get-all</command> - returns all IPv4 leases
+ or IPv4 leases for specified subnets;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-get-all</command> - returns all IPv6 leases
+ or IPv6 leases for specified subnets;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-get-page</command> - returns a page of all
+ IPv4 leases; by iterating over pages it is possible to retrieve
+ all leases in chunks;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-get-page</command> - returns a page of all
+ IPv6 leases; by iterating over pages it is possible to retrieve
+ all leases in chunks;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-del</command> - attempts to delete an IPv4
+ lease with the specified parameters;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-del</command> - attempts to delete an IPv6
+ lease with the specified parameters;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-update</command> - updates an IPv4 lease;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-update</command> - updates an IPv6 lease;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-wipe</command> - removes all leases from a
+ specific IPv4 subnet or all subnets;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-wipe</command> - removes all leases from a
+ specific IPv6 subnet or all subnets;</para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+
+ <para>Lease commands library is part of the open source code and is
+ available to every Kea user.</para>
+
+ <para>
+ All commands are using JSON syntax. They can be issued either using
+ control channel (see <xref linkend="ctrl-channel"/>) or via Control
+ Agent (see <xref linkend="kea-ctrl-agent"/>).
+ </para>
+
+ <para>
+ The library can be loaded in the same way as other hook libraries. It
+ does not take any parameters. It supports both DHCPv4 and DHCPv6
+ servers.
+<screen>
+"Dhcp6": { <userinput>
+ "hooks-libraries": [
+ {
+ "library": "/path/libdhcp_lease_cmds.so"
+ }
+ ...
+ ] </userinput>
+}
+</screen>
+ </para>
+
+ <section>
+ <title>lease4-add, lease6-add commands</title>
+ <para>
+ <command>lease4-add</command> and <command>lease6-add</command>
+ commands allow for the creation of a new lease. Typically Kea creates a lease
+ on its own, when it first sees a new device. However, sometimes it may
+ be convenient to create the lease administratively. The
+ <command>lease4-add</command> command requires at least three
+ parameters: an IPv4 address, a subnet-id and an identifier: hardware
+ (MAC) address. The simplest successful call might look as follows:
+<screen>
+{
+ "command": "lease4-add",
+ "arguments": {
+ "subnet-id": 44,
+ "ip-address": "192.0.2.202",
+ "hw-address": "1a:1b:1c:1d:1e:1f"
+ }
+}
+</screen>
+ </para>
+
+ <para><command>lease6-add</command> command requires four
+ parameters: an IPv6 address, a subnet-id, and IAID value
+ (identity association identifier, a value sent by clients) and
+ a DUID:
+<screen>
+{
+ "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
+ }
+}</screen>
+
+<command>lease6-add</command> can be also used to add leases for IPv6
+prefixes. In this case there are two parameters that must be
+specified: type (set to value of "IA_PD") and a prefix
+length. The actual prefix is set using ip-address field. For example,
+to configure a lease for prefix 2001:db8:abcd::/48, the following
+command can be used:
+
+<screen>
+{
+ "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
+ }
+}</screen>
+
+The commands can take a number of additional optional parameters:
+ <itemizedlist>
+ <listitem>
+ <para><command>valid-lft</command> - specifies the lifetime of the
+ lease, expressed in seconds. If not specified, the value
+ configured in the subnet related to specified subnet-id is
+ used.</para>
+ </listitem>
+ <listitem>
+ <para><command>expire</command> - timestamp of the lease
+ expiration time, expressed in unix format (seconds since 1 Jan
+ 1970). If not specified, the default value is now + valid
+ lifetime.</para>
+ </listitem>
+ <listitem>
+ <para><command>fqdn-fwd</command> - specifies whether the lease
+ should be marked as if forward DNS update was conducted. Note this
+ only affects the lease parameter and the actual DNS update will
+ not be conducted at the lease insertion time. 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. Hostname
+ parameter must be specified in fqdn-fwd is set to true.</para>
+ </listitem>
+ <listitem>
+ <para><command>fqdn-rev</command> - specifies whether the lease
+ should be marked as if reverse DNS update was conducted. Note this
+ only affects the lease parameter and the actual DNS update will
+ not be conducted at the lease insertion time. 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. Hostname parameter must be
+ specified in fqdn-fwd is set to true.</para>
+ </listitem>
+ <listitem>
+ <para><command>hostname</command> - 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.</para>
+ </listitem>
+ <listitem>
+ <para><command>hw-address</command> - hardware (MAC) address can
+ be optionally specified for IPv6 lease. It is mandatory parameter
+ for IPv4 lease.</para>
+ </listitem>
+ <listitem>
+ <para><command>client-id</command> - client identifier is an
+ optional parameter that can be specified for IPv4 lease.</para>
+ </listitem>
+ <listitem>
+ <para><command>preferred-lft</command> - Preferred lifetime is an
+ optional parameter 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 in IPv4.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Here's an example of more complex lease addition:
+
+<screen>
+{
+ "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,
+ "hostname": "urania.example.org"
+ }
+}
+</screen>
+ </para>
+
+ <para>
+ The command returns a status that indicates either a success (result
+ 0) or a failure (result 1). Failed command always includes text
+ parameter that explains the cause of failure. Example results:
+ <screen>{ "result": 0, "text": "Lease added." }</screen> Example failure:
+ <screen>{ "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" }</screen>
+ </para>
+
+
+ <section>
+ <title>lease4-get, lease6-get commands</title>
+ <para><command>lease4-get</command> or <command>lease6-get</command>
+ can be used to query the lease database and retrieve existing
+ leases. There are two types of parameters the
+ <command>lease4-get</command> supports: (address) or (subnet-id,
+ identifier-type, identifier). There are two types for
+ <command>lease6-get</command>: (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 aren't. One common use case of this type of query is to
+ find out whether a given address is being used or not. The second
+ query uses identifiers. Currently supported identifiers for leases are:
+ "hw-address" (IPv4 only), "client-id" (IPv4 only) and "duid" (IPv6 only).
+ </para>
+
+ <para>
+ An example <command>lease4-get</command> command for getting a lease
+ by an IPv4 address looks as follows:
+<screen>
+{
+ "command": "lease4-get",
+ "arguments": {
+ "ip-address": "192.0.2.1"
+ }
+}
+</screen>
+ </para>
+
+ <para>An example of the <command>lease6-get</command> query
+ looks as follows:
+<screen>
+{
+ "command": "lease6-get",
+ "arguments": {
+ "ip-address": "2001:db8:1234:ab::",
+ "type": "IA_PD"
+ }
+}</screen>
+ </para>
+
+ <para>An example query by "hw-address" for IPv4 lease looks
+ as follows:
+<screen>
+{
+ "command": "lease4-get",
+ "arguments": {
+ "identifier-type": "hw-address",
+ "identifier": "08:08:08:08:08:08",
+ "subnet-id": 44
+ }
+}</screen>
+
+ </para>
+
+ <para>An example query by "client-id" for IPv4 lease looks
+ as follows:
+<screen>
+{
+ "command": "lease4-get",
+ "arguments": {
+ "identifier-type": "client-id",
+ "identifier": "01:01:02:03:04:05:06",
+ "subnet-id": 44
+ }
+}</screen>
+
+ </para>
+
+ <para>An example query by (subnet-id, identifier-type,
+ identifier, iaid, type) for IPv6 lease looks as follows:
+<screen>
+{
+ "command": "lease4-get",
+ "arguments": {
+ "identifier-type": "duid",
+ "identifier": "08:08:08:08:08:08",
+ "iaid": 1234567,
+ "type": "IA_NA",
+ "subnet-id": 44
+ }
+}</screen>
+The type is an optional parameter. Supported values are: IA_NA
+(non-temporary address) and IA_PD (IPv6 prefix) are supported.
+If not specified, IA_NA is assumed.
+ </para>
+
+ <para><command>leaseX-get</command> returns a result that indicates a
+ result of the operation and lease details, if found. It has one of the
+ following values: 0 (success), 1 (error) or 2 (empty). The 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.
+ </para>
+
+ <para>
+An example result returned when the host was found:
+<screen>{
+ "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."
+}</screen>
+</para>
+
+ </section>
+
+ <section>
+ <title>lease4-get-all, lease6-get-all commands</title>
+ <para><command>lease4-get-all</command> and
+ <command>lease6-get-all</command> 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:
+<screen>
+{
+ "command": "lease4-get-all"
+}
+</screen>
+ </para>
+
+ <para>If the arguments are provided, it is expected that they contain
+ "subnets" parameter, being 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:
+<screen>
+{
+ "command": "lease6-get-all",
+ "arguments": {
+ "subnets": [ 1, 2, 3, 4 ]
+ }
+}
+</screen>
+ </para>
+
+ <para>
+ The returned response contains a detailed list of leases in the
+ following format:
+<screen>{
+ "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."
+}</screen>
+ </para>
+
+ <warning>
+ <para>The <command>lease4-get-all</command> and
+ <command>lease6-get-all</command> commands may result in very
+ large responses. This may have negative impact on the DHCP server
+ 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.
+ </para>
+ </warning>
+
+ </section>
+
+ <section>
+ <title>lease4-get-page, lease6-get-page commands</title>
+ <para>The <command>lease4-get-all</command> and
+ <command>lease6-get-all</command> commands may result in very
+ large responses. Generating such a response may consume CPU bandwith
+ 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 paging mechanism. The
+ <command>lease4-get-page</command> and <command>lease6-get-page</command>
+ implement paging mechanism for DHCPv4 and DHCPv6 servers respectively.
+ The following command retrieves first 1024 IPv4 leases:
+<screen>
+{
+ "command": "lease4-get-page",
+ "arguments": {
+ "from": "start",
+ "count": 1024
+ }
+}
+</screen>
+ </para>
+
+ <para>The keyword <command>start</command> denotes that the first page
+ of leases should be retrieved. Alternatively, an IPv4 zero address
+ can be specified to retrieve the first page:
+<screen>
+{
+ "command": "lease4-get-page",
+ "arguments": {
+ "from": "0.0.0.0",
+ "count": 1024
+ }
+}
+</screen>
+ </para>
+
+ <para>Similaraly, the IPv6 zero address can be specified in the
+ <command>lease6-get-page</command> command:
+<screen>
+{
+ "command": "lease6-get-page",
+ "arguments": {
+ "from": "::",
+ "count": 6
+ }
+}
+</screen>
+ </para>
+
+ <para>The response has the following structure:
+<screen>
+{
+ "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,
+ "total-count": 5000
+ },
+ "result": 0,
+ "text": "6 IPv6 lease(s) found."
+}
+</screen>
+
+ </para>
+
+ <para>Note that the leases' details were excluded from the response above
+ for brevity.</para>
+
+ <para>Generally, the returned list isn't 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 case of
+ highly distributed databases, such as Cassandra, ordering may be inefficient
+ or even impossible.</para>
+
+ <para>The <command>count</command> parameter contains a number of returned
+ leases on the page. The <command>total-count</command> parameter contains
+ the total number of leases in the database. The client can use this value
+ to estimate progress in fetching leases from the database and output
+ progress percentage in the log file. For example: a server participating
+ in High Availability configuration needs to fetch all leases from the
+ partner server. If the number of leases is high, this may take considerable
+ amount of time during which both servers do not respond to the DHCP queries.
+ In such cases it may be useful for the administrator to know how the
+ database synchronization is progressing.
+ </para>
+
+ <para>In order to fetch next page the client must use the last address
+ of the current page as an input to the next
+ <command>lease4-get-page</command> or <command>lease6-get-page</command>
+ command call. In this example it is going to be:
+<screen>
+{
+ "command": "lease6-get-page",
+ "arguments": {
+ "from": "2001:db8:2::7",
+ "count": 6
+ }
+}
+</screen>
+ because the 2001:db8:2::7 is the last address on the current page.
+ </para>
+
+ <para>The client may assume that it has reached the last page when the
+ <command>count</command> value is lower than specified in the command,
+ including the case when the <command>count</command> is equal to 0,
+ which means that no leases were found.
+ </para>
+
+ </section>
+
+ <section>
+ <title>lease4-del, lease6-del commands</title>
+ <para><command>leaseX-del</command> can be used to delete a lease from
+ the lease database. There are two types of parameters this command
+ supports, similar to 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 of this type of query
+ is to remove a lease (e.g. you want a specific address to no longer be
+ used, no matter who may use it). The second query uses
+ identifiers. For maximum flexibility, this interface uses identifiers
+ as a pair of values: type and the actual identifier. Currently
+ supported identifiers are "hw-address" (IPv4 only), "client-id"
+ (IPv4 only) and "duid" (IPv6 only), but additional types may be added
+ in the future. </para>
+
+ <para>
+ An example command for deleting a host reservation by address looks
+ as follows:
+<screen>
+{
+ "command": "lease4-del",
+ "arguments": {
+ "ip-address": "192.0.2.202"
+ }
+}</screen>
+
+An example IPv4 lease deletion by "hw-address" looks as follows:
+
+<screen>{
+ "command": "lease4-del",
+ "arguments": {
+ "identifier": "08:08:08:08:08:08",
+ "identifier-type": "hw-address",
+ "subnet-id": 44
+ }
+}</screen>
+ </para>
+
+ <para><command>leaseX-del</command> returns a result that
+ indicates a 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.
+ </para>
+ </section>
+
+ <section>
+ <title>lease4-update, lease6-update commands</title>
+ <para><command>lease4-update</command> and
+ <command>lease6-update</command> 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. All other fields
+ may be updated. If an address needs to be changed, please use
+ <command>leaseX-del</command> followed by
+ <command>leaseX-add</command> commands.</para>
+
+ <para>The optional boolean parameter "force-create" specifies
+ if the lease should be created if it doesn't exist in the database.
+ It defaults to false, which indicates that the lease is not created
+ if it doesn't exist. In such 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 doesn't exist, the new lease is
+ created as a result of receiving the <command>leaseX-update</command>.
+ </para>
+
+ <para>
+ An example command updating IPv4 lease looks as follows:
+<screen>{
+ "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
+ }
+}</screen>
+ </para>
+
+ <para>
+ An example command updating IPv6 lease looks as follows:
+<screen>{
+ "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
+ }
+}</screen>
+ </para>
+ </section>
+
+ <section>
+ <title>lease4-wipe, lease6-wipe commands</title>
+ <para><command>lease4-wipe</command> and
+ <command>lease6-wipe</command> are designed to remove all
+ leases associated with a given subnet. This administrative
+ task is expected to be used when existing subnet is being
+ retired. Note that the leases are not properly expired,
+ there are no DNS updates conducted, no log messages and
+ hooks are not called for leases being removed.</para>
+
+ <para>An example of <command>lease4-wipe</command> looks as follows:
+<screen>{
+ "command": "lease4-wipe",
+ "arguments": {
+ "subnet-id": 44
+ }
+}</screen>
+ </para>
+
+ <para>An example of <command>lease6-wipe</command> looks as follows:
+<screen>{
+ "command": "lease6-wipe",
+ "arguments": {
+ "subnet-id": 66
+ }
+}</screen>
+ </para>
+
+ <para>The commands return a textual description of the
+ number of leases removed and 0 (success) status code if any
+ leases were removed and 2 (empty) if there were no
+ leases. Status code 1 (error) may be returned in case the
+ parameters are incorrect or some other exception is
+ encountered.</para>
+
+ <para>The subnet-id 0 has 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.</para>
+
+ <para>Note: not all backends support this command.</para>
+ </section>
+ </section>
+ </section>
<!-- === lease_cmds ================================================== -->
<!-- ================================================================= -->
- <section xml:id="lease-cmds">
- <title>lease_cmds: Lease Commands</title>
- <para>
- This section describes the hook library that offers a number of new
- commands used to manage leases. Kea provides a way to store lease
- information in several backends (memfile, MySQL, PostgreSQL and
- Cassandra). This library provides a unified interface that can
- manipulate leases in an unified, safe way. In particular, it allows
- things previously impossible: manipulate leases in memfile while Kea
- is running, sanity check changes, check lease existence and remove all
- leases belonging to specific subnet. It can also catch more obscure
- errors, like adding a lease with 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.
-
- <note>
- <para>This library may only be loaded by <command>kea-dhcp4</command>
- or <command>kea-dhcp6</command> process.
- </para>
- </note>
- </para>
-
- <para>There are many use cases when an administrative command may be
- useful: during migration between servers (possibly even between
- different vendors), when a certain network is being retired, when a
- device has been disconnected and the sysadmin knows for sure that it
- will not be coming 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.</para>
-
- <para>
- This library provides the following commands:
- <itemizedlist>
- <listitem>
- <para><command>lease4-add</command> - adds new IPv4 lease;</para>
- </listitem>
- <listitem>
- <para><command>lease6-add</command> - adds new IPv6 lease;</para>
- </listitem>
- <listitem>
- <para><command>lease4-get</command> - checks if an IPv4 lease with
- the specified parameters exists and returns it if it does;</para>
- </listitem>
- <listitem>
- <para><command>lease6-get</command> - checks if an IPv6 lease with
- the specified parameters exists and returns it if it does;</para>
- </listitem>
- <listitem>
- <para><command>lease4-get-all</command> - returns all IPv4 leases
- or IPv4 leases for specified subnets;</para>
- </listitem>
- <listitem>
- <para><command>lease6-get-all</command> - returns all IPv6 leases
- or IPv6 leases for specified subnets;</para>
- </listitem>
- <listitem>
- <para><command>lease4-del</command> - attempts to delete an IPv4
- lease with the specified parameters;</para>
- </listitem>
- <listitem>
- <para><command>lease6-del</command> - attempts to delete an IPv6
- lease with the specified parameters;</para>
- </listitem>
- <listitem>
- <para><command>lease4-update</command> - updates an IPv4 lease;</para>
- </listitem>
- <listitem>
- <para><command>lease6-update</command> - updates an IPv6 lease;</para>
- </listitem>
- <listitem>
- <para><command>lease4-wipe</command> - removes all leases from a
- specific IPv4 subnet or all subnets;</para>
- </listitem>
- <listitem>
- <para><command>lease6-wipe</command> - removes all leases from a
- specific IPv6 subnet or all subnets;</para>
- </listitem>
- </itemizedlist>
-
- </para>
-
- <para>Lease commands library is part of the open source code and is
- available to every Kea user.</para>
-
- <para>
- All commands are using JSON syntax. They can be issued either using
- control channel (see <xref linkend="ctrl-channel"/>) or via Control
- Agent (see <xref linkend="kea-ctrl-agent"/>).
- </para>
-
- <para>
- The library can be loaded in the same way as other hook libraries. It
- does not take any parameters. It supports both DHCPv4 and DHCPv6
- servers.
-<screen>
-"Dhcp6": { <userinput>
- "hooks-libraries": [
- {
- "library": "/path/libdhcp_lease_cmds.so"
- }
- ...
- ] </userinput>
-}
-</screen>
- </para>
-
- <section>
- <title>lease4-add, lease6-add commands</title>
- <para>
- <command>lease4-add</command> and <command>lease6-add</command>
- commands allow for the creation of a new lease. Typically Kea creates a lease
- on its own, when it first sees a new device. However, sometimes it may
- be convenient to create the lease administratively. The
- <command>lease4-add</command> command requires at least three
- parameters: an IPv4 address, a subnet-id and an identifier: hardware
- (MAC) address. The simplest successful call might look as follows:
-<screen>
-{
- "command": "lease4-add",
- "arguments": {
- "subnet-id": 44,
- "ip-address": "192.0.2.202",
- "hw-address": "1a:1b:1c:1d:1e:1f"
- }
-}
-</screen>
- </para>
-
- <para><command>lease6-add</command> command requires four
- parameters: an IPv6 address, a subnet-id, and IAID value
- (identity association identifier, a value sent by clients) and
- a DUID:
-<screen>
-{
- "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
- }
-}</screen>
-
-<command>lease6-add</command> can be also used to add leases for IPv6
-prefixes. In this case there are two parameters that must be
-specified: type (set to value of "IA_PD") and a prefix
-length. The actual prefix is set using ip-address field. For example,
-to configure a lease for prefix 2001:db8:abcd::/48, the following
-command can be used:
-
-<screen>
-{
- "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
- }
-}</screen>
-
-The commands can take a number of additional optional parameters:
- <itemizedlist>
- <listitem>
- <para><command>valid-lft</command> - specifies the lifetime of the
- lease, expressed in seconds. If not specified, the value
- configured in the subnet related to specified subnet-id is
- used.</para>
- </listitem>
- <listitem>
- <para><command>expire</command> - timestamp of the lease
- expiration time, expressed in unix format (seconds since 1 Jan
- 1970). If not specified, the default value is now + valid
- lifetime.</para>
- </listitem>
- <listitem>
- <para><command>fqdn-fwd</command> - specifies whether the lease
- should be marked as if forward DNS update was conducted. Note this
- only affects the lease parameter and the actual DNS update will
- not be conducted at the lease insertion time. 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. Hostname
- parameter must be specified in fqdn-fwd is set to true.</para>
- </listitem>
- <listitem>
- <para><command>fqdn-rev</command> - specifies whether the lease
- should be marked as if reverse DNS update was conducted. Note this
- only affects the lease parameter and the actual DNS update will
- not be conducted at the lease insertion time. 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. Hostname parameter must be
- specified in fqdn-fwd is set to true.</para>
- </listitem>
- <listitem>
- <para><command>hostname</command> - 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.</para>
- </listitem>
- <listitem>
- <para><command>hw-address</command> - hardware (MAC) address can
- be optionally specified for IPv6 lease. It is mandatory parameter
- for IPv4 lease.</para>
- </listitem>
- <listitem>
- <para><command>client-id</command> - client identifier is an
- optional parameter that can be specified for IPv4 lease.</para>
- </listitem>
- <listitem>
- <para><command>preferred-lft</command> - Preferred lifetime is an
- optional parameter 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 in IPv4.</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>Here's an example of more complex lease addition:
-
-<screen>
-{
- "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,
- "hostname": "urania.example.org"
- }
-}
-</screen>
- </para>
-
- <para>
- The command returns a status that indicates either a success (result
- 0) or a failure (result 1). Failed command always includes text
- parameter that explains the cause of failure. Example results:
- <screen>{ "result": 0, "text": "Lease added." }</screen> Example failure:
- <screen>{ "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" }</screen>
- </para>
-
-
- <section>
- <title>lease4-get, lease6-get commands</title>
- <para><command>lease4-get</command> or <command>lease6-get</command>
- can be used to query the lease database and retrieve existing
- leases. There are two types of parameters the
- <command>lease4-get</command> supports: (address) or (subnet-id,
- identifier-type, identifier). There are two types for
- <command>lease6-get</command>: (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 aren't. One common use case of this type of query is to
- find out whether a given address is being used or not. The second
- query uses identifiers. Currently supported identifiers for leases are:
- "hw-address" (IPv4 only), "client-id" (IPv4 only) and "duid" (IPv6 only).
- </para>
-
- <para>
- An example <command>lease4-get</command> command for getting a lease
- by an IPv4 address looks as follows:
-<screen>
-{
- "command": "lease4-get",
- "arguments": {
- "ip-address": "192.0.2.1"
- }
-}
-</screen>
- </para>
-
- <para>An example of the <command>lease6-get</command> query
- looks as follows:
-<screen>
-{
- "command": "lease6-get",
- "arguments": {
- "ip-address": "2001:db8:1234:ab::",
- "type": "IA_PD"
- }
-}</screen>
- </para>
-
- <para>An example query by "hw-address" for IPv4 lease looks
- as follows:
-<screen>
-{
- "command": "lease4-get",
- "arguments": {
- "identifier-type": "hw-address",
- "identifier": "08:08:08:08:08:08",
- "subnet-id": 44
- }
-}</screen>
-
- </para>
-
- <para>An example query by "client-id" for IPv4 lease looks
- as follows:
-<screen>
-{
- "command": "lease4-get",
- "arguments": {
- "identifier-type": "client-id",
- "identifier": "01:01:02:03:04:05:06",
- "subnet-id": 44
- }
-}</screen>
-
- </para>
-
- <para>An example query by (subnet-id, identifier-type,
- identifier, iaid, type) for IPv6 lease looks as follows:
-<screen>
-{
- "command": "lease4-get",
- "arguments": {
- "identifier-type": "duid",
- "identifier": "08:08:08:08:08:08",
- "iaid": 1234567,
- "type": "IA_NA",
- "subnet-id": 44
- }
-}</screen>
-The type is an optional parameter. Supported values are: IA_NA
-(non-temporary address) and IA_PD (IPv6 prefix) are supported.
-If not specified, IA_NA is assumed.
- </para>
-
- <para><command>leaseX-get</command> returns a result that indicates a
- result of the operation and lease details, if found. It has one of the
- following values: 0 (success), 1 (error) or 2 (empty). The 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.
- </para>
-
- <para>
-An example result returned when the host was found:
-<screen>{
- "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."
-}</screen>
-</para>
-
- </section>
-
- <section>
- <title>lease4-get-all, lease6-get-all commands</title>
- <para><command>lease4-get-all</command> and
- <command>lease6-get-all</command> 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:
-<screen>
-{
- "command": "lease4-get-all"
-}
-</screen>
- </para>
-
- <para>If the arguments are provided, it is expected that they contain
- "subnets" parameter, being 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:
-<screen>
-{
- "command": "lease6-get-all",
- "arguments": {
- "subnets": [ 1, 2, 3, 4 ]
- }
-}
-</screen>
- </para>
-
- <para>
- The returned response contains a detailed list of leases in the
- following format:
-<screen>{
- "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."
-}</screen>
- </para>
-
- <warning>
- <para>The <command>lease4-get</command> and
- <command>lease6-get</command> commands may result in very
- large responses. This may have negative impact on the DHCP server
- 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.
- </para>
- </warning>
-
- </section>
-
- <section>
- <title>lease4-del, lease6-del commands</title>
- <para><command>leaseX-del</command> can be used to delete a lease from
- the lease database. There are two types of parameters this command
- supports, similar to 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 of this type of query
- is to remove a lease (e.g. you want a specific address to no longer be
- used, no matter who may use it). The second query uses
- identifiers. For maximum flexibility, this interface uses identifiers
- as a pair of values: type and the actual identifier. Currently
- supported identifiers are "hw-address" (IPv4 only), "client-id"
- (IPv4 only) and "duid" (IPv6 only), but additional types may be added
- in the future. </para>
-
- <para>
- An example command for deleting a host reservation by address looks
- as follows:
-<screen>
-{
- "command": "lease4-del",
- "arguments": {
- "ip-address": "192.0.2.202"
- }
-}</screen>
-
-An example IPv4 lease deletion by "hw-address" looks as follows:
-
-<screen>{
- "command": "lease4-del",
- "arguments": {
- "identifier": "08:08:08:08:08:08",
- "identifier-type": "hw-address",
- "subnet-id": 44
- }
-}</screen>
- </para>
-
- <para><command>leaseX-del</command> returns a result that
- indicates a 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.
- </para>
- </section>
-
- <section>
- <title>lease4-update, lease6-update commands</title>
- <para><command>lease4-update</command> and
- <command>lease6-update</command> 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. All other fields
- may be updated. If an address needs to be changed, please use
- <command>leaseX-del</command> followed by
- <command>leaseX-add</command> commands.</para>
-
- <para>The optional boolean parameter "force-create" specifies
- if the lease should be created if it doesn't exist in the database.
- It defaults to false, which indicates that the lease is not created
- if it doesn't exist. In such 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 doesn't exist, the new lease is
- created as a result of receiving the <command>leaseX-update</command>.
- </para>
-
- <para>
- An example command updating IPv4 lease looks as follows:
-<screen>{
- "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
- }
-}</screen>
- </para>
-
- <para>
- An example command updating IPv6 lease looks as follows:
-<screen>{
- "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
- }
-}</screen>
- </para>
- </section>
-
- <section>
- <title>lease4-wipe, lease6-wipe commands</title>
- <para><command>lease4-wipe</command> and
- <command>lease6-wipe</command> are designed to remove all
- leases associated with a given subnet. This administrative
- task is expected to be used when existing subnet is being
- retired. Note that the leases are not properly expired,
- there are no DNS updates conducted, no log messages and
- hooks are not called for leases being removed.</para>
-
- <para>An example of <command>lease4-wipe</command> looks as follows:
-<screen>{
- "command": "lease4-wipe",
- "arguments": {
- "subnet-id": 44
- }
-}</screen>
- </para>
-
- <para>An example of <command>lease6-wipe</command> looks as follows:
-<screen>{
- "command": "lease6-wipe",
- "arguments": {
- "subnet-id": 66
- }
-}</screen>
- </para>
-
- <para>The commands return a textual description of the
- number of leases removed and 0 (success) status code if any
- leases were removed and 2 (empty) if there were no
- leases. Status code 1 (error) may be returned in case the
- parameters are incorrect or some other exception is
- encountered.</para>
-
- <para>The subnet-id 0 has 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.</para>
-
- <para>Note: not all backends support this command.</para>
- </section>
- </section>
- </section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks-lease-cmds.xml"/>
<section xml:id="subnet-cmds">
<title>subnet_cmds: Subnet Commands</title>
projects / thirdparty / kea.git / commitdiff
