# lease_cmds: Lease Commands

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. It provides a non programmatic way to manage user contexts associated to leases.

This library may only be loaded by `kea-dhcp4` or `kea-dhcp6` process.

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.

This library provides the following commands:

- `lease4-add` - adds new IPv4 lease;

- `lease6-add` - adds new IPv6 lease;

- `lease4-get` - checks if an IPv4 lease with the specified parameters exists and returns it if it does;

- `lease6-get` - checks if an IPv6 lease with the specified parameters exists and returns it if it does;

- `lease4-get-all` - returns all IPv4 leases or IPv4 leases for specified subnets;

- `lease6-get-all` - returns all IPv6 leases or IPv6 leases for specified subnets;

- `lease4-get-page` - returns a page of all IPv4 leases; by iterating over pages it is possible to retrieve all leases in chunks;

- `lease6-get-page` - returns a page of all IPv6 leases; by iterating over pages it is possible to retrieve all leases in chunks;

- `lease4-del` - attempts to delete an IPv4 lease with the specified parameters;

- `lease6-del` - attempts to delete an IPv6 lease with the specified parameters;

- `lease4-update` - updates an IPv4 lease;

- `lease6-update` - updates an IPv6 lease;

- `lease4-wipe` - removes all leases from a specific IPv4 subnet or all subnets;

- `lease6-wipe` - removes all leases from a specific IPv6 subnet or all subnets;

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

All commands are using JSON syntax. They can be issued either using control channel (see ) or via Control Agent (see ).

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.

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

## lease4-add, lease6-add commands

`lease4-add` and `lease6-add` 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 `lease4-add` command requires at least two parameters: an IPv4 address, and an identifier: hardware (MAC) address. A third parameter, subnet-id, was mandatory in Kea 1.4.0, but is optional beginning with Kea 1.5.0.. If not specified or 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"
        }
    }

`lease6-add` command requires four parameters: an IPv6 address, and IAID value (identity association identifier, a value sent by clients) and a DUID. The same principle for subnet-id as in lease4-add applies. If not specified or specified value is 0, Kea will try to determine the value own 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 be also 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 a prefix length. The actual prefix is set using ip-address field. Note that Kea is not able to guess subnet-id values for prefixes, so it 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 a number of 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 specified subnet-id is used.

- `expire` - 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.

- `fqdn-fwd` - 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.

- `fqdn-rev` - 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.

- `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` - hardware (MAC) address can be optionally specified for IPv6 lease. It is mandatory parameter for IPv4 lease.

- `client-id` - client identifier is an optional parameter that can be specified for IPv4 lease.

- `preferred-lft` - 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.

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

Here's an example of 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,
            "hostname": "urania.example.org",
            "user-context": { "version": 1 }
        }
    }

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:

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

Example failure:

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

### lease4-get, lease6-get commands

`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` supports: (address) or (subnet-id, identifier-type, identifier). There are two types for `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 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).

An example `lease4-get` command for getting a lease by an IPv4 address looks as follows:

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

An example of the `lease6-get` query looks as follows:

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

An example query by "hw-address" for 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 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 IPv6 lease looks as follows:

    {
        "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) are supported. 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 (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.

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

### lease4-get-all, lease6-get-all commands

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

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:

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

The `lease4-get-all` and `lease6-get-all` 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.

### lease4-get-page, lease6-get-page commands

The `lease4-get-all` and `lease6-get-all` 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 `lease4-get-page` and `lease6-get-page` implement paging mechanism for DHCPv4 and DHCPv6 servers respectively. The following command retrieves 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
        }
    }

Similaraly, 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 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.

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

In order to fetch 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 going to be:

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

because the 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 specified in the command, including the case when the `count` is equal to 0, which means that no leases were found.

### lease4-del, lease6-del commands

`leaseX-del` 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.

An example command for deleting a host reservation by address looks as follows:

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

An example IPv4 lease deletion by "hw-address" looks as follows:

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

`leaseX-del` 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.

### lease4-update, lease6-update commands

`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. All other fields may be updated. If an address needs to be changed, please use `leaseX-del` followed by `leaseX-add` commands.

Subnet-id parameter, used to be mandatory in Kea 1.4.0, but it is optional since 1.5.0. If not specified or 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 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 `leaseX-update`.

An example command updating IPv4 lease looks as follows:

    {
      "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 command updating IPv6 lease looks as follows:

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

### lease4-wipe, lease6-wipe commands

`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 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.

An example of `lease4-wipe` looks as follows:

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

An example of `lease6-wipe` looks as follows:

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

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.

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.

Note: not all backends support this command.