# 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 backends (memfile, MySQL, PostgreSQL and Cassandra), and this library provides a interface that can manipulate leases in a unified, safe way. 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 specific subnet. It can also catch more obscure errors, like an attempt to add a lease with a subnet-id that does not exist in the configuration, or configuring a lease to use an address that is outside of the subnet to which it is supposed to belong. The library also provides a non-programmatic way to manage user contexts associated with leases.

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 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 a new IPv4 lease;

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

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

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

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

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

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

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

- `lease4-del` - deletes an IPv4 lease with the specified parameters;

- `lease6-del` - deletes 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 from all subnets;

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

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

All commands use JSON syntax and can be issued either using control channel (see ) or Control Agent (see ).

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.

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

## lease4-add, lease6-add Commands

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 prefix is set using ip-address field. Note that Kea cannot guess subnet-id values for prefixes; they must be specified explicitly. For example, to configure a lease for prefix 2001:db8:abcd::/48, the following command can be used:

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

The commands can take 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 the specified subnet-id is used.

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

- `fqdn-fwd` - specifies whether the lease should be marked as if a forward DNS update were conducted. 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 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.

- `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,
            "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). A failed command always includes a text parameter that explains the cause of failure. For example:

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

Example failure:

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

### 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` command supports: (address) or (subnet-id, identifier-type, identifier). There are also 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 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 (success), 1 (error), or 2 (empty). An empty result means that a query has been completed properly, but the object (a lease in this case) has not been found. The lease parameters, if found, are returned as arguments.

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

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.

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

### 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 is where an administrator wants a specified address to no longer be used. The second form of the command uses identifiers. For maximum flexibility, this interface uses identifiers as a pair of values: type and the actual identifier. The currently supported identifiers are "hw-address" (IPv4 only), "client-id" (IPv4 only), and "duid" (IPv6 only).

An example command for deleting a lease by address is:

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

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

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

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

### lease4-update, lease6-update Commands

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

### 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 an existing subnet is being retired. Note that the leases are not properly expired: no DNS updates are carried out, no log messages are created, and hooks are not called for the leases being removed.

An example of `lease4-wipe` is:

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

An example of `lease6-wipe` is:

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

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

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

Note: not all backends support this command.