mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-28 12:37:55 +00:00
Code Issues Releases Wiki Activity

[#1235] Added V6 Leaese Query doc to the ARM

Browse Source 
modified:   arm/hooks-lease-query.rst
This commit is contained in:
Thomas Markwalder 2020-06-18 16:24:05 -04:00
parent 3aee8754b6
commit 5875af6bc8
1 changed files with 183 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

186
doc/sphinx/arm/hooks-lease-query.rst
View File

@ -4,9 +4,8 @@ lease_query: Leasequery
=======================
This library provides support for DHCPv4 Leasequery as described in
`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__. Support for DHCPv6
Lease Query (`RFC 5007 <https://tools.ietf.org/html/rfc5007>`__) will be
added in the near future.
`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__; and for DHCPv6
Lease Query (`RFC 5007 <https://tools.ietf.org/html/rfc5007>`__).
.. 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 <https://tools.ietf.org/html/rfc5007#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 <https://gitlab.isc.org/isc-projects/kea/-/issues/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 <https://tools.ietf.org/html/rfc5007#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 <https://tools.ietf.org/html/rfc5007#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 <https://tools.ietf.org/html/rfc5007#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" ]
}
}
],
: