From afcccdb46abee646fa7b30a9f08206e8dfdcca6c Mon Sep 17 00:00:00 2001 From: Thomas Markwalder Date: Thu, 2 Apr 2020 09:53:25 -0400 Subject: [PATCH] [#1010] Updated ARM and all-keys.json modified: doc/examples/kea4/all-keys.json doc/examples/kea6/all-keys.json doc/sphinx/arm/dhcp4-srv.rst doc/sphinx/arm/dhcp6-srv.rst --- doc/examples/kea4/all-keys.json | 12 +++++++ doc/examples/kea6/all-keys.json | 12 +++++++ doc/sphinx/arm/dhcp4-srv.rst | 44 +++++++++++++++++++++++ doc/sphinx/arm/dhcp6-srv.rst | 62 +++++++++++++++++++++++++++++++++ 4 files changed, 130 insertions(+) diff --git a/doc/examples/kea4/all-keys.json b/doc/examples/kea4/all-keys.json index 40609f125a..d7d1fd3340 100644 --- a/doc/examples/kea4/all-keys.json +++ b/doc/examples/kea4/all-keys.json @@ -511,6 +511,10 @@ // DHCP client renews the lease. "renew-timer": 30, + // Global value to store extended information (e.g. relay agent + // information) with each lease. + "store-extended-info:" true, + // Governs how the Kea DHCPv4 server should deal with the invalid // data received from the client. "sanity-checks": { @@ -609,6 +613,10 @@ // network is selected for client assignments. "require-client-classes": [ "late" ], + // Turn off storage of extended information (e.g. relay agent + // information) with each lease for this shared-network. + "store-extended-info:" false, + // Shared network level server hostname set in 'sname' field. "server-hostname": "", @@ -672,6 +680,10 @@ // in 'siaddr'. "next-server": "0.0.0.0", + // Turn on storage of extended information (e.g. relay agent + // information) with each lease for this subnet. + "store-extended-info:" true, + // Subnet level list of DHCP options. "option-data": [ { diff --git a/doc/examples/kea6/all-keys.json b/doc/examples/kea6/all-keys.json index c823b3d217..c6e3e29ac9 100644 --- a/doc/examples/kea6/all-keys.json +++ b/doc/examples/kea6/all-keys.json @@ -452,6 +452,10 @@ // DHCP client renews the lease. "renew-timer": 30, + // Global value to store extended information (e.g. relay agent + // information) with each lease. + "store-extended-info:" true, + // Governs how the Kea DHCPv6 server should deal with the invalid // data received from the client. "sanity-checks": { @@ -574,6 +578,10 @@ // network is selected for client assignments. "require-client-classes": [ "late" ], + // Turn off storage of extended information (e.g. relay agent + // information) with each lease for this shared-network. + "store-extended-info:" false, + // List of IPv6 subnets belonging to this shared network. "subnet6": [ { @@ -618,6 +626,10 @@ // which the response is sent. "interface-id": "", + // Turn on storage of extended information (e.g. relay agent + // information) with each lease for this subnet. + "store-extended-info:" true, + // Subnet level list of DHCP options. "option-data": [ { diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 6515667abc..3b946d5da8 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -3693,6 +3693,50 @@ An example configuration that sets this parameter looks as follows: ... } +.. _dhcp4-store-extended-info: + +Storing Extended Lease Information +---------------------------------- +In order to support such features as DHCP LeaseQuery +(`RFC 4388 `__) it is necessary to +store additional information with each lease. Because the amount +of information stored for each lease has ramifications in terms of +performance and system resource consumption, storing this additional +information is configurable through the "store-extended-info" parameter. +It defaults to false and may be set at the global, shared-network, and +subnet levels. + +:: + + "Dhcp4": { + "store-extended-info": true, + ... + } + +When enabled, information relevant to the DHCPREQUEST asking for the lease is +added into the lease's user-context as a map element labeled "ISC". Currently, +the map will contain a single value, the relay-agent-info option (DHCP Option 82), +when the DHCPREQUEST received contains it. Other values may be added at a +future date. Since DHCPREQUESTs sent as renewals will likely not contain this +information, the values taken from the last DHCPREQUEST that did contain it will +be retained on the lease. The lease's user-context will look something like this: + +:: + + { "ISC": { "relay-agent-info": "0x52050104AABBCCDD" } } + +.. note:: + This feature is intended to be used in conjunction with an upcoming LeaseQuery + hook library and at this time there is other use for this information within Kea. + +.. note:: + It is possible that other hook libraries are already making use of user-context. + Enabling store-extended-info should not interfere with any other user-context + content so long as it does not also use an element labled "ISC". In other + words, user-context is intended to be a flexible container serving mulitple + purposes. As long as no other purpose also writes an "ISC" element to + user-contex there should not be a conflict. + .. _host-reservation-v4: Host Reservation in DHCPv4 diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 6d716ee34f..1787b90fc1 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -3187,6 +3187,68 @@ An example configuration that sets this parameter looks as follows: ... } +.. _store-extended-info-v6: + +Storing Extended Lease Information +---------------------------------- +In order to support such features as DHCPv6 Reconfigure +(`RFC 3315 `__) and LeaseQuery +(`RFC 5007 `__) it is necessary to +store additional information with each lease. Because the amount +of information stored for each lease has ramifications in terms of +performance and system resource consumption, storing this additional +information is configurable through the "store-extended-info" parameter. +It defaults to false and may be set at the global, shared-network, and +subnet levels. + +:: + + "Dhcp6": { + "store-extended-info": true, + ... + } + +When enabled, information relevant to the DHCPv6 query (e.g. REQUEST, RENEW, +or REBIND) asking for the lease is added into the lease's user-context as a +map element labeled "ISC". Currently the information contained in the map +will be a list of relays, one for each relay message layer that encloses the +client query. Other values may be added at a future date. The lease's +user-context for a two-hop query might look something like this (shown +pretty-printed for clarity): + +:: + + { + "ISC": { + "relays": [ + { + "hop": 2, + "link": "2001:db8::1", + "peer": "2001:db8::2" + }, + { + "hop": 1, + "link": "2001:db8::3", + "options": "0x00C800080102030405060708", + "peer": "2001:db8::4" + }] + } + } + + +.. note:: + This feature is intended to be used in conjunction with an upcoming + LeaseQuery hook library and at this time there is other use for this + information within Kea. + +.. note:: + It is possible that other hook libraries are already making use of + user-context. Enabling store-extended-info should not interfere with + any other user-context content so long as it does not also use an element + labled "ISC". In other words, user-context is intended to be a flexible + container serving mulitple purposes. As long as no other purpose also + writes an "ISC" element to user-contex there should not be a conflict. + .. _host-reservation-v6: Host Reservation in DHCPv6