From: Thomas Markwalder Date: Wed, 9 Aug 2017 18:45:21 +0000 (-0400) Subject: [5280] Wordsmithing on doc/guide/hooks.xml X-Git-Tag: trac5124a_base~12 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=7bbf47ef728be430d58d29743a1c27ca82fe2c81;p=thirdparty%2Fkea.git [5280] Wordsmithing on doc/guide/hooks.xml --- diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml index 1fae6cf7f5..d706747d0e 100644 --- a/doc/guide/hooks.xml +++ b/doc/guide/hooks.xml @@ -1003,24 +1003,24 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows
lease_cmds: Lease Commands - This section describes a hook library that offers a number of new + 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 an unified interface that can + 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 it is supposed to belong to. + of the subnet to which it is supposed to belong. There are many use cases when an administrative command may be useful: during migration between servers (possibly even between - different vendors), when certain network is being retired, when a + 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 + 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. @@ -1034,20 +1034,20 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows lease6-add - adds new IPv6 lease; - lease4-get - checks if n IPv4 lease with - specified parameters exists and returns it if it does; + lease4-get - checks if an IPv4 lease with + the specified parameters exists and returns it if it does; - lease6-get - checks if n IPv6 lease with - 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-del - attempts to delete an IPv4 - lease with specified parameters; + lease with the specified parameters; lease6-del - attempts to delete an IPv6 - lease with specified parameters; + lease with the specified parameters; lease4-update - updates an IPv4 lease; @@ -1077,7 +1077,7 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows - The library can be loaded in similar way as other hook libraries. It + 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. @@ -1100,8 +1100,8 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows 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 indentifier: hardware - (MAC) address. A simplest successful call may looks as follows: + parameters: an IPv4 address, a subnet-id and an identifier: hardware + (MAC) address. The simplest successful call might look as follows: { "command": "lease4-add", @@ -1116,7 +1116,7 @@ An example deletion by (subnet-id, identifier-type, identifier) looks as follows lease6-add command requires four - paramaters: an IPv6 address, a subnet-id, and iaid value + paramaters: an IPv6 address, a subnet-id, and IAID value (identity association identifier, a value sent by clients) and a DUID: @@ -1142,6 +1142,7 @@ 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", @@ -1152,9 +1153,9 @@ command can be used: The commands can take a number of additional optional parameters: - valid-lft - specified a lifetime of the + valid-lft - specifies the lifetime of the lease, expressed in seconds. If not specified, the value - configured in a subnet related to specified subnet-id is + configured in the subnet related to specified subnet-id is used. @@ -1167,7 +1168,7 @@ The commands can take a number of additional optional parameters: 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, DNS + 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 specifed, the default value is false. Hostname @@ -1177,7 +1178,7 @@ The commands can take a number of additional optional parameters: 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, DNS + 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 specifed, the default value is false. Hostname parameter must be @@ -1201,13 +1202,13 @@ The commands can take a number of additional optional parameters: preferred-lft - Preferred lifetime is an optional parameter for IPv6 leases. If not specified, the value - configured for a subnet corresponding to the specified subnet-id + 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 additions: + Here's an example of more complex lease addition: { @@ -1246,7 +1247,7 @@ The commands can take a number of additional optional parameters: 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 + 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 @@ -1351,9 +1352,9 @@ An example result returned when the host was found: 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 + 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 aren't. One common use case of this type of query + 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 @@ -1386,7 +1387,7 @@ as follows: leaseX-get returns a result that - indicates a result of the operation. It has one of the + indicates a outcome of the operation. 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. @@ -1398,8 +1399,8 @@ as follows: lease4-update and lease6-update commands can be used to update existing leases. Since all lease database backends are indexed by IP - addressed, it is not possible to update an address. All other fields - could be updated. If an address is to be changes, please use + 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. @@ -1442,7 +1443,7 @@ as follows: lease4-wipe, lease6-wipe commands lease4-wipe and lease6-wipe are designed to remove all - leases associated with a given subnet. This adminitrative + 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 @@ -1467,7 +1468,7 @@ as follows: The commands return a textual description of the - number of leases returned and 0 (success) status code if any + 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 parameeters are incorrect or some other exception is