diff --git a/doc/sphinx/arm/hooks-lease-query.rst b/doc/sphinx/arm/hooks-lease-query.rst index 6b8bdcf58e..4c692d43a0 100644 --- a/doc/sphinx/arm/hooks-lease-query.rst +++ b/doc/sphinx/arm/hooks-lease-query.rst @@ -4,9 +4,8 @@ lease_query: Leasequery ======================= This library provides support for DHCPv4 Leasequery as described in -`RFC 4388 `__. Support for DHCPv6 -Lease Query (`RFC 5007 `__) will be -added in the near future. +`RFC 4388 `__; and for DHCPv6 +Lease Query (`RFC 5007 `__). .. note:: @@ -141,3 +140,184 @@ addresses: } ], : + +.. _lease-query-dhcpv6: + +DHCPv6 Leasequery +~~~~~~~~~~~~~~~~~ + +DHCPv6 simple Leasequery provides a requester the ability to query for +active lease information for either a single IP address or a single client +DUID. The query type and parameters are conveyed in an ``lq-query`` option (44) +attached to a DHCPV6_LEASEQUERY message. Briefly, + +- query-type + + This is either ``query-by-address`` (1) or ``query-by-clientid`` (2) + +- link-address + + Global link address, when not empty, instructs the query to be + limited to leases within that "link". Kea uses this value to + select only leases that belong to subnets whose prefix matches + this value. Note that active leases for prefix delegations for + a matched subnet will be included in the query reply, even if the + delegated prefix itself falls outside the subnet prefix. + +- query-options + + A single ``iaaddr`` option (12) must be supplied when querying by address. + When querying by client ID, a single ``clientid`` option (1) must be + supplied. RFC 5007 also calls for an optional, ``oro`` option (6), to + request specific options be returned for matched leases. This is + not currently implemented. + +.. note:: + + `RFC 5007, Section 3.3 `__ + states that querying by IP address should return either a leases (e.g. + binding) for the address itself or a lese for a delegated prefix that + contains the address. The latter is not currently implemented. Leases for + delegated prefixes may only be returned when querying by client ID. See + `gitlab issue #1275 `__ + +DHCPV6_LEASEQUERY queries will only be honored if the source address of +the query matches an entry in a list of known IP addresses which are +permitted to query. This list of valid requester addresses is specified +as part of the Leasequery hook library’s configuration (See the section +on configuration below). Queries received from unknown requesters will be +logged and dropped. + +In response to a valid query, the server will carry out the requisite +activities and return a DHCPV6_LEASEQUERY_REPLY. All replies will contain +at least a ``status-code`` option (13) that indicates the outcome of the query +as detailed in the following table: + +.. tabularcolumns:: |p{0.5\linewidth}|p{0.3\linewidth}|p{0.1\linewidth}|p{0.3\linewidth}| + +.. table:: DHCPV6_LEASEQUERY_REPLY Status Option Values per Query Outcome + :class: longtable + :widths: 50 30 10 30 + + +--------------------------------------+-------------------------+--------+------------------------------+ + | | Status | Status | Status | + | Query Outcome | Label | Code | Text | + +======================================+=========================+========+==============================+ + | Invalid query type field | STATUS_UnknownQueryType | 7 | "unknown query-type" | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by IP address that does not | STATUS_Malformed | 10 | "missing D6O_IAADDR" | + | contain an address option | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by IP address for an address | STATUS_NotConfigured | 9 | "address not in a configured | + | that does fall within any configured | | | pool" | + | pools | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by IP address which found only | STATUS_Success | 0 | "inactive lease exists" | + | an inactive lease (e.g. expired, | | | | + | declined, reclaimed-expired) | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by IP address that found no | STATUS_Success | 0 | "no active lease" | + | leases (active or otherwise) | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by IP address that found an | STATUS_Success | 0 | "active lease found" | + | active lease for the address | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by Client ID that does not | STATUS_Malformed | 10 | "missing D6O_CLIENTID" | + | contain a client ID option | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by Client ID with a link | STATUS_NotConfigured | 9 | "not a configured link" | + | address that does not match any | | | | + | configured subnets | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by client id which found no | STATUS_Success | 0 | "no active leases" | + | matching leases | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + | Query by client id which found one | STATUS_Success | 0 | "active lease(s) found" | + | or more active leases | | | | + +--------------------------------------+-------------------------+--------+------------------------------+ + +For those scenarios where the query was either invalid or no matching, active +leases were found the DHCPV6_LEASEQUERY_REPLY will only contain the status-code +option (12) per the above table. + +When a query finds active leases in more than one subnet and query's link-address +is empty, then in addition to the status-code, the DHCPV6_LEASEQUERY_REPLY will +contain an ``lq-client-link`` option (48). The lq-client-link will contain a list of +IPv6 addresses, one for each subnet in which a lease was found (see +`RFC 5007, Section 4.1.2.5 `__) +If, however, the query's link-address is not empty, the list of queries will be +pruned to contain only leases that belong to that subnet. + +When the query results in one or more active leases which all belong to a single +subnet, in addition to the status-code, the DHCPV6_LEASEQUERY_REPLY will contain a +client-data option (45) (see +`RFC 5007, Section 4.1.2.2 `__) +The client-data option will encapsulate the following options: + +.. tabularcolumns:: |p{0.2\linewidth}|p{0.1\linewidth}|p{0.7\linewidth}| + +.. table:: OPTION_CLIENT_DATA returned when active lease(s) are found + :class: longtable + :widths: 30 10 70 + + +------------------------------+-------+-----------------------------------------------+ + | Option | Code | Content | + +==============================+=======+===============================================+ + | clientid | 1 | copied from the lease (if one) | + +------------------------------+-------+-----------------------------------------------+ + | clt-time | 46 | amount of time that has elapsed since the | + | | | lease's client-last-transaction-time (CLTT) | + | | | This value will also be used by the server to | + | | | adjust life time and timer values. | + +------------------------------+-------+-----------------------------------------------+ + | iaaddr | 5 | One option per matched address, fields in | + | | | each option: | + | | | - lease address | + | | | - valid life time reduced by CLTT | + | | | - preferred life time reduced by CLTT | + +------------------------------+-------+-----------------------------------------------+ + | iaprefix | 5 | One option per matched prefix, fields in | + | | | each option: | + | | | - prefix | + | | | - prefix length | + | | | - valid life time reduced by CLTT | + | | | - preferred life time reduced by CLTT | + +------------------------------+-------+-----------------------------------------------+ + +If the lease with the most recent CLTT value (Client Last +Transmission Time) has relay information in it's user-context (see +:ref:`store-extended-info-v6`), then an OPTION_LQ_RELAY_DATA option will be +added to the reply (see +`RFC 5007, Section 4.1.2.4 `__) + +The relay information on the lease is a list with an entry for each +relay layer the client packet (e.g. DHCPV6_REQUEST) traversed, with the +first entry in list being the outermost layer (closest to the server). The +``peer-address`` field of the lq-rely-option is set to the peer address of this +relay. The list of relays is then used to construct a DHCPV6_RELAY_FORW message +equivalent to that which contained the client packet, minus the client packet. +This message is stored in the ``DHCP-relay-message`` field of the lq-relay-data option. + +.. _lease-query-dhcpv6-config: + +DHCPv6 Leasequery Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configuring the Leasequery hook library for use is straight forward. It currently +supports a single parameter, ``requesters``, which is a list of IP addresses from +which DHCPV6_LEASEQUERY packets will be accepted. In other words, it is a list of +known requesters. The following shows an example configuration with two requester +addresses: + +:: + + : + "hooks-libraries": [ + { + "library": "lib/kea/hooks/libdhcp_lease_query.so", + "parameters": { + "requesters": [ "2001:db8:1::1", "2001:db8:2::1" ] + } + } + ], + :