Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
ISC Open Source Projects
Kea
Commits
eb57dac1
Commit
eb57dac1
authored
Sep 04, 2017
by
Tomek Mrugalski
🛰
Browse files
[5350] Documentation updated.
parent
28558468
Changes
5
Hide whitespace changes
Inline
Side-by-side
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 context
s
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 context
s
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>
"Dhcp
4
": {
"Dhcp
6
": {
"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>
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment