From: Marcin Siodelski Date: Wed, 27 Jun 2018 11:59:08 +0000 (+0200) Subject: [5651] Described lease4-get-page and lease6-get-page cmds. X-Git-Tag: trac5694_base~5^2~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=76b6d3befea853c05ab2e11785df8efc76e2a92a;p=thirdparty%2Fkea.git [5651] Described lease4-get-page and lease6-get-page cmds. --- diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index 1cb54cc6fc..4fdd7c0ca6 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -7,9 +7,9 @@ dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging.xml -DOCBOOK += ddns.xml hooks.xml hooks-ha.xml hooks-host-cache.xml hooks-radius.xml -DOCBOOK += hooks-stat-cmds.xml libdhcp.xml lfc.xml stats.xml ctrl-channel.xml -DOCBOOK += faq.xml classify.xml shell.xml agent.xml +DOCBOOK += ddns.xml hooks.xml hooks-ha.xml hooks-host-cache.xml hooks-lease-cmds.xml +DOCBOOK += hooks-radius.xml hooks-stat-cmds.xml libdhcp.xml lfc.xml stats.xml +DOCBOOK += ctrl-channel.xml faq.xml classify.xml shell.xml agent.xml EXTRA_DIST = $(DOCBOOK) diff --git a/doc/guide/hooks-lease-cmds.xml b/doc/guide/hooks-lease-cmds.xml new file mode 100644 index 0000000000..e72d6e6750 --- /dev/null +++ b/doc/guide/hooks-lease-cmds.xml @@ -0,0 +1,746 @@ + + +
+ 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. + + + 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 three + parameters: an IPv4 address, a subnet-id and an identifier: hardware + (MAC) address. The simplest successful call might look as follows: + +{ + "command": "lease4-add", + "arguments": { + "subnet-id": 44, + "ip-address": "192.0.2.202", + "hw-address": "1a:1b:1c:1d:1e:1f" + } +} + + + + lease6-add command requires four + parameters: an IPv6 address, a subnet-id, and IAID value + (identity association identifier, a value sent by clients) and + a DUID: + +{ + "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 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: + + +{ + "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. + + + + + 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" + } +} + + + + + 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", + "count": 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", + "count": 1024 + } +} + + + + Similaraly, the IPv6 zero address can be specified in the + lease6-get-page command: + +{ + "command": "lease6-get-page", + "arguments": { + "from": "::", + "count": 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, + "total-count": 5000 + }, + "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. The total-count 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. + + + 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. + + 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. +
+
+
diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index dd2177d253..dfe8244738 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -1657,599 +1657,7 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows -
- 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. - - - 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-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 three - parameters: an IPv4 address, a subnet-id and an identifier: hardware - (MAC) address. The simplest successful call might look as follows: - -{ - "command": "lease4-add", - "arguments": { - "subnet-id": 44, - "ip-address": "192.0.2.202", - "hw-address": "1a:1b:1c:1d:1e:1f" - } -} - - - - lease6-add command requires four - parameters: an IPv6 address, a subnet-id, and IAID value - (identity association identifier, a value sent by clients) and - a DUID: - -{ - "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 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: - - -{ - "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. - - - - - 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" - } -} - - - - - 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 and - lease6-get 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-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. - - 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. -
-
-
+
subnet_cmds: Subnet Commands