Skip to content

GitLab

Commit eb57dac1 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

[5350] Documentation updated.

parent 28558468
Hide whitespace changes
Inline Side-by-side
Showing with 112 additions and 26 deletions
doc/examples/kea4/advanced.json
View file @ eb57dac1
......@@ -80,11 +80,22 @@
"match-client-id": true,
// The following list defines subnets. Each subnet consists of at
// least subnet and pool entries.
// least subnet and pool entries. One extra feature that requires some
// explanation is user-context. This is a structure that you can define
// in subnets and pools. It is parsed by Kea, but not used directly.
// It is intended to keep anything you may want to put there - comments,
// extra designations, floor or depatment names etc. This structures
// will be made available to Kea hooks.
"subnet4": [
{
"pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
"subnet": "192.0.2.0/24"
"pools": [ {
"pool": "192.0.2.1 - 192.0.2.200",
"user-context": { "info": "what a large pool" }
} ],
"subnet": "192.0.2.0/24",
"user-context": {
"comment": "Our first subnet!"
}
},
{
// This particular subnet has match-client-id value changed.
......
doc/examples/kea6/advanced.json
View file @ eb57dac1
......@@ -59,7 +59,6 @@
// This entry marks options 110, 120 and 130 as RSOO-enabled.
"relay-supplied-options": [ "110", "120", "130" ],
// This defines a control socket. If defined, Kea will open a UNIX socket
// and will listen for incoming commands. See section 15 of the Kea User's
// Guide for list of supported commands.
......@@ -79,11 +78,28 @@
"renew-timer": 1000,
"rebind-timer": 2000,
// The following list defines subnets. Each subnet consists of at
// least subnet and pool entries.
// The following list defines subnets. Each subnet consists of at
// least subnet and pool entries. Note the user-context being
// used throughout the definitions. This is something that is not
// being used by Kea, it's simply parsed and stored in appropriate
// structures. You can put anything you want in the user-context
// as long as it is a valid JSON.
"subnet6": [
{
"pools": [ { "pool": "2001:db8:1::/80" } ],
"pools": [
{
"pool": "2001:db8:1::/80",
// This is user context specified for this particular
// pool. You can use it to describe the pool in some way.
// Just keep in mind that the structure will not be used
// by Kea itself. It will be made available to hooks if
// they want to use it.
"user-context": { "department": "engineering" }
}],
// Here's the user-context for the whole subnet.
"user-context": { "comment": "Floor one, west wing" },
// This defines PD (prefix delegation) pools. In this case
// we have only one pool. That consists of /64 prefixes
......@@ -95,7 +111,13 @@
"prefix-len": 48,
"delegated-len": 64,
"excluded-prefix": "2001:db8:abcd:1234::",
"excluded-prefix-len": 62
"excluded-prefix-len": 62,
// Another user-context for this PD pool. Again, you can put anything
// you want in there as long as it's valid JSON.
"user-context": {
"purpose": "For CPE devices"
}
}
],
"subnet": "2001:db8:1::/64",
......
doc/guide/dhcp4-srv.xml
View file @ eb57dac1
......@@ -3915,7 +3915,7 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
</section>
<section>
<title>User context in IPv4 pools</title>
<title>User contexts in IPv4</title>
<para>
Kea allows loading hook libraries that sometimes could benefit from
additional parameters. If such a parameter is specific to the whole
......@@ -3923,11 +3923,23 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
However, sometimes there is a need to specify parameters that are
different for each pool.
</para>
<para>
User contexts can store arbitrary data as long as it is valid JSON
syntax. Some hook libraries may expect specific formatting, though.
Please consult specific hook library documentation for details.
</para>
<para>
User contexts can be specified on either subnet or pool level. One
other useful usage is the ability to store comments or descriptions.
</para>
<para>
Let's consider an imaginary case of devices that have color LED
lights. Depending on their location, they should glow red, blue or
green. It would be easy to write a hook library that would send
specific values as maybe vendor option. However, the server has to
specific values as maybe a vendor option. However, the server has to
have some way to specify that value for each pool. This need is
addressed by user contexts. In essence, any user data can specified
in the user context as long as it is a valid JSON map. For example,
......@@ -3939,8 +3951,22 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
"subnet4": [
{
"subnet": "192.0.2.0/24",
"pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
<userinput>"user-context": { "colour": "red" }</userinput>
"pools": [ {
"pool": "192.0.2.10 - 192.0.2.20",
// This is pool specific user context
<userinput>"user-context": { "colour": "red" }</userinput>
} ],
// This is a subnet specific user context. You can put whatever type
// of information you want as long as it is a valid JSON.
<userinput>"user-context": {
"comment": "network on the second floor",
"last-modified": "2017-09-04 13:32",
"description": "you can put here anything you like",
"phones": [ "x1234", "x2345" ],
"devices-registered": 42,
"billing": false
}</userinput>
},
...
],
......@@ -3951,11 +3977,10 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
<para>
It should be noted that Kea will not use that information, but will
simply store and make it available to hook libraries. It is up to the
hook library to extract that information and make use of it.</para>
hook library to extract that information and make use of it.
</para>
<para>
Currently only pools allow definition of user contexts, but this
concept is expected to be enhanced to other structures in the future.
For more background information, see <xref linkend="user-context"/>
For more background information, see <xref linkend="user-context"/>.
</para>
</section>
......
doc/guide/dhcp6-srv.xml
View file @ eb57dac1
......@@ -4071,7 +4071,7 @@ If not specified, the default value is:
</section>
<section>
<title>User context in IPv6 pools</title>
<title>User contexts in IPv6</title>
<para>
Kea allows loading hook libraries that sometimes could benefit from
additional parameters. If such a parameter is specific to the whole
......@@ -4079,6 +4079,18 @@ If not specified, the default value is:
However, sometimes there is a need to specify parameters that are
different for each pool.
</para>
<para>
User contexts can store arbitrary data as long as it is valid JSON
syntax. Some hook libraries may expect specific formatting, though.
Please consult specific hook library documentation for details.
</para>
<para>
User contexts can be specified on either subnet or pool level. One
other useful usage is the ability to store comments or descriptions.
</para>
<para>
Let's consider an example where certain parameters are supposed
to be delivered to clients in form of additional options,
......@@ -4093,20 +4105,31 @@ If not specified, the default value is:
parameters used by the hook library when it is loaded.
An example configuration could look as follows:
<screen>
"Dhcp4": {
"Dhcp6": {
"subnet6": [ {
"pd-pools": [
{
"prefix": "2001:db8::",
"prefix-len": 56,
"delegated-len": 64,
// This is a pool specific context.
<userinput>"user-context": {
"threshold-percent": 85,
"v4-network": "192.168.0.0/16",
"v4-overflow": "10.0.0.0/16"
}</userinput>
} ],
"subnet": "2001:db8::/32"
"subnet": "2001:db8::/32",
// This is a subnet specific context. You can put any type of
// information here as long as it is a valid JSON.
<userinput>"user-context": {
"comment": "Those v4-v6 migration technologies are tricky.",
"experimental": true,
"billing-department": 42,
"contact-points": [ "Alice", "Bob" ]
}</userinput>
} ],
...
}</screen>
......@@ -4119,10 +4142,7 @@ If not specified, the default value is:
and make use of it.
</para>
<para>
Currently only address and prefix pools allow definition of user
contexts, but this concept is expected to be enhanced to other
structures in the future. For more background information, see <xref
linkend="user-context"/>
For more background information, see <xref linkend="user-context"/>.
</para>
</section>
......
doc/guide/hooks.xml
View file @ eb57dac1
......@@ -1969,9 +1969,17 @@ If the subnet exists the response will be similar to this:
and makes it available for the hook libraries.
</para>
<para>
As of Kea 1.2, the only structures that allow user contexts are address
and prefix pools, but it is expected to extend other structures with the
user context capability.
Another use case for user contexts may be storing comments and other
information that will be retained by Kea. Regular comments are discarded
when configuration is loaded, but user contexts are retained. This is
useful if you want your comments to survive config-set, config-get
operations for example.
</para>
<para>
As of Kea 1.3, the structures that allow user contexts are pools of all
types (addresses and prefixes) and subnets. These are supported in both
DHCPv4 and DHCPv6. It is expected that other structures will be extended
in the future to provide the user context capability.
</para>
</section>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment