mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-29 13:07:50 +00:00
[#1235] Added V6 Leaese Query doc to the ARM
modified: arm/hooks-lease-query.rst
This commit is contained in:
Thomas Markwalder
parent
3aee8754b6
commit
5875af6bc8
@ -4,9 +4,8 @@ lease_query: Leasequery
|
|||||||
=======================
|
=======================
|
||||||
|
|
||||||
This library provides support for DHCPv4 Leasequery as described in
|
This library provides support for DHCPv4 Leasequery as described in
|
||||||
`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__. Support for DHCPv6
|
`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__; and for DHCPv6
|
||||||
Lease Query (`RFC 5007 <https://tools.ietf.org/html/rfc5007>`__) will be
|
Lease Query (`RFC 5007 <https://tools.ietf.org/html/rfc5007>`__).
|
||||||
added in the near future.
|
|
||||||
|
|
||||||
.. note::
|
.. 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" ]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
:
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user