mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 18:08:16 +00:00
Code Issues Releases Wiki Activity
kea/doc/guide/hooks.rst

2552 lines
86 KiB
ReStructuredText
Raw Blame History

.. _hooks-libraries:
***************
Hooks Libraries
***************
.. _hooks-libraries-introduction:
Introduction
============
Kea is both flexible and customizable, via the use of "hooks." This feature
lets Kea load one or more
dynamically linked libraries (known as "hooks libraries") and, at
various points in its processing ("hook points"), call functions in
them. Those functions perform whatever custom processing is required.
The hooks concept allows the core Kea code to remain reasonably small
by moving features to external libraries that some, but not all, users
find useful. Those with no need for specific functions can simply choose not
to load the libraries.
Hooks libraries are loaded by individual Kea processes, not by Kea as a
whole. This means, among other things, that it is possible to associate one set
of libraries with the DHCP4 server and a different set with the DHCP6
server.
Another point to note is that it is possible for a process to load
multiple libraries. When processing reaches a hook point, Kea calls the
hooks library functions attached to it. If multiple libraries have
attached a function to a given hook point, Kea calls all of them, in the
order in which the libraries are specified in the configuration file.
The order may be important; consult the documentation of the libraries
for specifics.
The next section describes how to configure hooks libraries. Users who are
interested in writing their own hooks library can find information
in the `Hooks Developer's Guide section of the Kea Developer's
Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/df/d46/hooksdgDevelopersGuide.html>`__.
Note that some libraries are available under different licenses.
Please also note that some libraries may require additional dependencies and/or
compilation switches to be enabled, e.g. the RADIUS library introduced in
Kea 1.4 requires the FreeRadius-client library to be present. If
--with-free-radius option is not specified, the RADIUS library will not
be built.
Installing Hook Packages
========================
.. note::
For more details about installing the Kea Premium Hooks package, please read
`this Knowledgebase article <https://kb.isc.org/docs/aa-01587>`__.
Some hook packages are included in the base Kea sources. There is no
need to do anything special to compile or install them, as they are covered
by the usual building and installation procedures. Please
refer to :ref:`installation` for a general overview of the installation process.
ISC provides several additional premium hooks in the form of packages, which
follow a similar installation procedure but with several additional steps.
For our users' convenience, the premium hooks installation procedure is described in this section.
1. Download the package; detailed instructions are provided separately on how
to get it. The package will be a file with a name similar to
kea-premium-KEAVERSION.tar.gz. (The name may vary depending on the package
purchased.)
2. Administrators who still have the sources for the corresponding version of the
open-source Kea package still on their system from the initial Kea installation
should skip this step. Otherwise, extract the Kea source from the original
tarball that was downloaded. For example, with a download of Kea KEAVERSION.,
there should be a tarball called kea-KEAVERSION.tar.gz on the system.
Unpack this tarball:
::
$ tar zxvf kea-KEAVERSION.tar.gz
This will unpack the tarball into the kea-KEAVERSION subdirectory of
the current working directory.
3. Unpack the Kea premium tarball into the directory into which Kea was
unpacked. Once Kea KEAVERSION has been unpacked into a kea-KEAVERSION
subdirectory and the Kea premium tarball is in the current directory, the following
steps will unpack the premium tarball into the correct location:
::
$ cd kea-KEAVERSION
$ tar xvf ../kea-premium-KEAVERSION.tar.gz
Note that unpacking the Kea premium package will put the files into a
directory named "premium". Regardless of the name of the package, the
directory will always be called "premium", although its contents will vary
depending on the premium package.
4. Run ``autoreconf`` tools. This step is necessary to update Kea's build
script to include the additional directory. If this tool is not already
available on the system, install the ``automake`` and ``autoconf``
tools. To generate the configure script, please use:
::
$ autoreconf -i
5. Rerun configure, using the same configure options that were used when
originally building Kea. It is possible to verify that configure has detected the
premium package by inspecting the summary printed when it exits. The
first section of the output should look something like this:
::
Package:
Name: kea
Version: KEAVERSION
Extended version:KEAVERSION (tarball)
OS Family: Linux
Using GNU sed: yes
Premium package: yes
Included Hooks: forensic_log flex_id host_cmds
The last line indicates which specific hooks were detected. Note that
some hooks may require their own dedicated switches, e.g. the RADIUS hook
requires extra switches for FreeRADIUS. Please consult later sections of
this chapter for details.
6. Rebuild Kea
::
$ make
If the machine has multiple CPU cores, an interesting option to consider
here is using the argument -j X, where X is the number of available cores.
7. Install Kea sources along with the hooks:
::
$ sudo make install
Note that as part of the installation procedure, the install script will
eventually venture into the premium/ directory and will install additional
hook libraries and associated files.
The installation location of the hooks libraries depends on whether the
--prefix parameter was specified in the configure script. If not,
the default location will be /usr/local/lib/kea/hooks. The proper installation
of the libraries can be verified with this command:
::
$ ls -l /usr/local/lib/kea/hooks/*.so
/usr/local/lib/kea/hooks/libdhcp_class_cmds.so
/usr/local/lib/kea/hooks/libdhcp_flex_id.so
/usr/local/lib/kea/hooks/libdhcp_host_cmds.so
/usr/local/lib/kea/hooks/libdhcp_lease_cmds.so
/usr/local/lib/kea/hooks/libdhcp_legal_log.so
/usr/local/lib/kea/hooks/libdhcp_subnet_cmds.so
The exact list returned will depend on the packages installed. If the
directory was specified via --prefix, the hooks libraries will be located in
{prefix directory}/lib/kea/hooks.
Configuring Hooks Libraries
===========================
The hooks libraries for a given process are configured using the
``hooks-libraries`` keyword in the configuration for that process. (Note
that the word "hooks" is plural.) The value of the keyword is an array
of map structures, with each structure corresponding to a hooks library. For
example, to set up two hooks libraries for the DHCPv4 server, the
configuration would be:
::
"Dhcp4": {
:
"hooks-libraries": [
{
"library": "/opt/charging.so"
},
{
"library": "/opt/local/notification.so",
"parameters": {
"mail": "spam@example.com",
"floor": 13,
"debug": false,
"users": [ "alice", "bob", "charlie" ],
"languages": {
"french": "bonjour",
"klingon": "yl'el"
}
}
}
]
:
}
..
.. note::
This syntax is effective as of Kea 1.1.0, to facilitate the
specification of library-specific parameters. Libraries should allow a
parameter entry for comments, as is the case with many configuration
scopes.
.. note:
In all versions of Kea since 1.1.0, libraries
are reloaded even if their lists have not changed,
because the parameters specified for the library (or the files those
parameters point to) may have changed.
Libraries may have additional parameters that are not mandatory, in the
sense that there may be libraries that do not require them. However, for a
specific library there is often a specific requirement to specify a certain
set of parameters. Please consult the documentation for each individual library for
details. In the example above, the first library has no parameters. The
second library has five parameters: specifying mail (string parameter),
floor (integer parameter), debug (boolean parameter), lists
(list of strings), and maps (containing strings). Nested parameters can
be used if the library supports it. This topic is explained in detail in
the `Hooks Developer's Guide section of the Kea Developer's Guide
<https://jenkins.isc.org/job/Kea_doc/doxygen/df/d46/hooksdgDevelopersGuide.html>`__.
Notes:
- The full path to each library should be given.
- As noted above, the order in which the hooks are called may be important;
consult the documentation for each library for specifics.
- An empty list has the same effect as omitting the ``hooks-libraries``
configuration element altogether.
.. note::
There is one case where this is not true: if Kea is running with a
configuration that contains a ``hooks-libraries`` item, and that
item is removed and the configuration reloaded, the removal will
be ignored and the libraries remain loaded. As a workaround,
instead of removing the ``hooks-libraries`` item, change it to an
empty list. This will be fixed in a future version of Kea.
At the present time, only the kea-dhcp4 and kea-dhcp6 processes support
hooks libraries.
Available Hooks Libraries
=========================
As described above, the hooks functionality provides a way to customize
a Kea server without modifying the core code. ISC has chosen to take
advantage of this feature to provide functions that may only be useful
to a subset of Kea users. To this end, ISC has created some hooks
libraries, discussed in the following sections.
.. note::
Some of these libraries are available with the base code, while
others will be shared with organizations supporting development of
Kea. Users who would like to get access to those premium
libraries should consider purchasing a support contract from ISC. This
includes professional support, advance security notifications, input
into ISC's roadmap planning, and many other benefits, while helping
make Kea sustainable in the long term.
The following table provides a list of libraries currently available
from ISC. It is important to pay attention to which libraries may be
loaded by which Kea processes. It is a common mistake to configure the
``kea-ctrl-agent`` process to load libraries that should, in fact, be
loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` processes. If a library
from ISC does not work as expected, please make sure that it has been
loaded by the correct process per the table below.
.. warning::
While the Kea Control Agent includes the "hooks" functionality, (i.e.
hooks libraries can be loaded by this process), none of ISC's current
hooks libraries should be loaded by the Control Agent.
.. table:: List of Available Hooks Libraries
+-----------------+-----------------+-----------------+-----------------+
| Name | Availability | Since | Load by process |
+=================+=================+=================+=================+
| user_chk | Kea sources | Kea 0.8 | kea-dhcp4, |
| | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Forensic | Support | Kea 1.1.0 | kea-dhcp4, |
| Logging | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Flexible | Support | Kea 1.2.0 | kea-dhcp4, |
| Identifier | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Host Commands | Support | Kea 1.2.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Subnet Commands | Support | Kea 1.3.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Lease Commands | Kea sources | Kea 1.3.0 | kea-dhcp4, |
| | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| High | Kea sources | Kea 1.4.0 | kea-dhcp4, |
| Availability | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Statistics | Kea sources | Kea 1.4.0 | kea-dhcp4, |
| Commands | | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| RADIUS | Support | Kea 1.4.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Host Cache | Support | Kea 1.4.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| Class Commands | Support | Kea 1.5.0 | kea-dhcp4, |
| | customers | | kea-dhcp6 |
+-----------------+-----------------+-----------------+-----------------+
| MySQL | Kea sources | Kea 1.6.0 | kea-dhcp4, |
| Configuration | | | kea-dhcp6 |
| Backend | | | |
+-----------------+-----------------+-----------------+-----------------+
| Configuration | Support | Kea 1.6.0 | kea-dhcp4, |
| Backend | customers | | kea-dhcp6 |
| Commands | | | |
+-----------------+-----------------+-----------------+-----------------+
ISC hopes to see more hooks libraries become available as time
progresses, developed both internally and externally. Since this list
may evolve dynamically, it is maintained on a wiki page, available
at this link:
https://gitlab.isc.org/isc-projects/kea/wikis/Hooks-available.
Developers or others who are aware of any hooks libraries not listed there
are asked to please send a note to the kea-users or kea-dev mailing lists for
updating.
The libraries developed by ISC are described in detail in the following
sections.
user_chk: Checking User Access
------------------------------
The user_chk library is the first hooks library published by ISC. It
serves several purposes:
- To assign "new" or "unregistered" users to a restricted subnet, while
"known" or "registered" users are assigned to unrestricted subnets.
- To allow DHCP response options or vendor option values to be
customized based on user identity.
- To provide a real-time record of user registration activity, which
can be sampled by an external consumer.
- To serve as a demonstration of various capabilities possible using
the hooks interface.
Once loaded, the library allows the separation of incoming requests into known
and unknown clients. For known clients, packets are processed
as usual, although it is possible to override the sending of certain options
on a per-host basis. Clients that are not on the known
hosts list will be treated as unknown and will be assigned to the last
subnet defined in the configuration file.
As an example of a use case, this behavior may be implemented to put unknown users
into a separate subnet that leads to a "walled garden," where they can
only access a registration portal. Once they fill in necessary data,
their details are added to the known clients file and they get a proper
address after their device is restarted.
.. note::
This library was developed several years before the host reservation
mechanism became available. Host reservation is much
more powerful and flexible, but the user_chk capability
to consult an external source of information about clients and alter
Kea's behavior remains useful and of educational value.
The library reads the /tmp/user_chk_registry.txt file while being loaded
and each time an incoming packet is processed. Each line of the file is expected to
contain a self-contained JSON snippet which must have the
following two entries:
- ``type`` - whose value is "HW_ADDR" for IPv4 users or "DUID" for IPv6
users.
- ``id`` - whose value is either the hardware address or the DUID from
the request formatted as a string of hex digits, with or without ":"
delimiters.
and may have zero or more of the following entries:
- ``bootfile`` - whose value is the pathname of the desired file.
- ``tftp_server`` - whose value is the hostname or IP address of the
desired server.
A sample user registry file is shown below:
::
{ "type" : "HW_ADDR", "id" : "0c:0e:0a:01:ff:04", "bootfile" : "/tmp/v4bootfile" }
{ "type" : "HW_ADDR", "id" : "0c:0e:0a:01:ff:06", "tftp_server" : "tftp.v4.example.com" }
{ "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:04", "bootfile" : "/tmp/v6bootfile" }
{ "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:06", "tftp_server" : "tftp.v6.example.com" }
As with any other hooks libraries provided by ISC, internals of the
user_chk code are well-documented. Users may refer to the `user_chk
library section of the Kea Developer's Guide
<https://jenkins.isc.org/job/Kea_doc/doxygen/d8/db2/libdhcp_user_chk.html>`__
for information on how the code works internally. That, together with the
`Hooks Framework section of the Kea Developer's Guide
<https://jenkins.isc.org/job/Kea_doc/doxygen/index.html#hooksFramework>`__ should give users
some pointers on how to extend this library and perhaps even write one
from scratch.
legal_log: Forensic Logging Hooks
---------------------------------
This section describes the forensic log hooks library. This library
provides hooks that record a detailed log of lease assignments and
renewals into a set of log files.
Currently this library is only
available to ISC customers with a paid support contract.
.. note::
This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
In many legal jurisdictions, companies, especially ISPs, must record
information about the addresses they have leased to DHCP clients. This
library is designed to help with that requirement. If the information
that it records is sufficient, it may be used directly. If a
jurisdiction requires that a different set of information be saved, users
may use this library as a template or example to create their own custom logging
hooks.
This logging is done as a set of hooks to allow it to be customized to
any particular need. Modifying a hooks library is easier and safer than
updating the core code. In addition by using the hooks features, those
users who do not need to log this information can leave it out and avoid
any performance penalties.
Log File Naming
~~~~~~~~~~~~~~~
The names for the log files have the following form:
::
path/base-name.CCYYMMDD.txt
The "path" and "base-name" are supplied in the configuration as
described below; see :ref:`forensic-log-configuration`. The next part of the name is the
date the log file was started, with four digits for year, two digits for
month, and two digits for day. The file is rotated on a daily basis.
.. note::
When running Kea servers for both DHCPv4 and DHCPv6, the log names
must be distinct. See the examples in :ref:`forensic-log-configuration`.
DHCPv4 Log Entries
~~~~~~~~~~~~~~~~~~
For DHCPv4, the library creates entries based on DHCPREQUEST messages and
corresponding DHCPv4 leases intercepted by the lease4_select (for new
leases) and the lease4_renew (for renewed leases) hooks.
An entry is a single string with no embedded end-of-line markers and a
prepended timestamp, and has the following sections:
::
timestamp address duration device-id {client-info} {relay-info} {user-context}
Where:
- timestamp - the current date and time the log entry was written in
"%Y-%m-%d %H:%M:%S %Z" strftime format ("%Z" is the time zone name).
- address - the leased IPv4 address given out and whether it was
assigned or renewed.
- duration - the lease lifetime expressed in days (if present), hours,
minutes, and seconds. A lease lifetime of 0xFFFFFFFF will be denoted
with the text "infinite duration".
- device-id - the client's hardware address shown as numerical type and
hex digit string.
- client-info - the DHCP client id option (61) if present, shown as a
hex string.
- relay-info - for relayed packets the giaddr and the RAI circuit-id,
remote-id, and subscriber-id options (option 82 sub options: 1, 2 and
6) if present. The circuit id and remote id are presented as hex
strings.
- user-context - the optional user context associated with the lease.
For instance (line breaks added for readability; they will not be
present in the log file):
::
2018-01-06 01:02:03 CET Address: 192.2.1.100 has been renewed for 1 hrs 52 min 15 secs to a device with hardware address:
hwtype=1 08:00:2b:02:3f:4e, client-id: 17:34:e2:ff:09:92:54 connected via relay at address: 192.2.16.33,
identified by circuit-id: 68:6f:77:64:79 and remote-id: 87:f6:79:77:ef
In addition to logging lease activity driven by DHCPv4 client traffic,
the hooks library also logs entries for the following lease management control channel
commands: lease4-add, lease4-update, and lease4-del. Each entry is a
single string with no embedded end-of-line markers, and it will
typically have the following form:
``lease4-add:``
::
*timestamp* Administrator added a lease of address: *address* to a device with hardware address: *device-id*
Depending on the arguments of the add command, it may also include the
client-id and duration.
Example:
::
2018-01-06 01:02:03 CET Administrator added a lease of address: 192.0.2.202 to a device with hardware address:
1a:1b:1c:1d:1e:1f for 1 days 0 hrs 0 mins 0 secs
``lease4-update:``
::
*timestamp* Administrator updated information on the lease of address: *address* to a device with hardware address: *device-id*
Depending on the arguments of the update command, it may also include
the client-id and lease duration.
Example:
::
2018-01-06 01:02:03 CET Administrator updated information on the lease of address: 192.0.2.202 to a device
with hardware address: 1a:1b:1c:1d:1e:1f, client-id: 1234567890
``lease4-del:`` deletes have two forms, one by address and one by
identifier and identifier type:
::
*timestamp* Administrator deleted the lease for address: *address*
or
::
*timestamp* Administrator deleted a lease for a device identified by: *identifier-type* of *identifier*
Currently only a type of @b hw-address (hardware address) is supported.
Examples:
::
2018-01-06 01:02:03 CET Administrator deleted the lease for address: 192.0.2.202
2018-01-06 01:02:12 CET Administrator deleted a lease for a device identified by: hw-address of 1a:1b:1c:1d:1e:1f
DHCPv6 Log Entries
~~~~~~~~~~~~~~~~~~
For DHCPv6 the library creates entries based on lease management actions
intercepted by lease6_select (for new leases), lease6_renew (for
renewed leases), and lease6_rebind (for rebound leases).
An entry is a single string with no embedded end-of-line markers and a
prepended timestamp, and has the following sections:
::
timestamp address duration device-id {relay-info}* {user-context}
Where:
- timestamp - the current date and time the log entry was written in
"%Y-%m-%d %H:%M:%S %Z" strftime format ("%Z" is the time zone name).
- address - the leased IPv6 address or prefix given out and whether it
was assigned or renewed.
- duration - the lease lifetime expressed in days (if present), hours,
minutes, and seconds. A lease lifetime of 0xFFFFFFFF will be denoted
with the text "infinite duration".
- device-id - the client's DUID and hardware address (if present).
- relay-info - for relayed packets the content of relay agent messages,
remote-id (code 37), subscriber-id (code 38), and interface-id (code
18) options, if present. Note that interface-id option, if present,
identifies the whole interface the relay agent received the message
on. This typically translates to a single link in the network, but
it depends on the specific network topology. Nevertheless, this is
useful information to better scope down the location of the device,
so it is recorded, if present.
- user-context - the optional user context associated with the lease.
For instance (line breaks added for readability; they will not be
present in the log file):
::
2018-01-06 01:02:03 PST Address:2001:db8:1:: has been assigned for 0 hrs 11 mins 53 secs
to a device with DUID: 17:34:e2:ff:09:92:54 and hardware address: hwtype=1 08:00:2b:02:3f:4e
(from Raw Socket) connected via relay at address: fe80::abcd for client on link address: 3001::1,
hop count: 1, identified by remote-id: 01:02:03:04:0a:0b:0c:0d:0e:0f and subscriber-id: 1a:2b:3c:4d:5e:6f
In addition to logging lease activity driven by DHCPv6 client traffic,
the hooks library also logs entries for the following lease management control channel
commands: lease6-add, lease6-update, and lease6-del. Each entry is a
single string with no embedded end-of-line markers, and it will
typically have the following form:
``lease6-add:``
::
*timestamp* Administrator added a lease of address: *address* to a device with DUID: *DUID*
Depending on the arguments of the add command, it may also include the
hardware address and duration.
Example:
::
2018-01-06 01:02:03 PST Administrator added a lease of address: 2001:db8::3 to a device with DUID:
1a:1b:1c:1d:1e:1f:20:21:22:23:24 for 1 days 0 hrs 0 mins 0 secs
``lease6-update:``
::
*timestamp* Administrator updated information on the lease of address: *address* to a device with DUID: *DUID*
Depending on the arguments of the update command, it may also include
the hardware address and lease duration.
Example:
::
2018-01-06 01:02:03 PST Administrator updated information on the lease of address: 2001:db8::3 to a device with
DUID: 1a:1b:1c:1d:1e:1f:20:21:22:23:24, hardware address: 1a:1b:1c:1d:1e:1f
``lease6-del:`` deletes have two forms, one by address and one by
identifier and identifier type:
::
*timestamp* Administrator deleted the lease for address: *address*
or
::
*timestamp* Administrator deleted a lease for a device identified by: *identifier-type* of *identifier*
Currently only a type of DUID is supported.
Examples:
::
2018-01-06 01:02:03 PST Administrator deleted the lease for address: 2001:db8::3
2018-01-06 01:02:11 PST Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e:1f:20:21:22:23:24
.. _forensic-log-configuration:
Configuring the Forensic Log Hooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use this functionality, the hook library must be included in the
configuration of the desired DHCP server modules. The legal_log library
is installed alongside the Kea libraries in ``[kea-install-dir]/lib``
where ``kea-install-dir`` is determined by the "--prefix" option of the
configure script. It defaults to ``/usr/local``. Assuming the default
value, configuring kea-dhcp4 to load the legal_log library could be
done with the following Kea4 configuration:
::
"Dhcp4": {
"hooks-libraries": [
{
"library": "/usr/local/lib/libdhcp_legal_log.so",
"parameters": {
"path": "/var/kea/var",
"base-name": "kea-forensic4"
}
},
...
]
}
To configure it for kea-dhcp6, the commands are:
::
"Dhcp6": {
"hooks-libraries": [
{
"library": "/usr/local/lib/libdhcp_legal_log.so",
"parameters": {
"path": "/var/kea/var",
"base-name": "kea-forensic6"
}
},
...
]
}
Two hooks library parameters are supported:
- path - the directory in which the forensic file(s) will be written.
The default value is ``[prefix]/kea/var``. The directory must exist.
- base-name - an arbitrary value which is used in conjunction with the
current system date to form the current forensic file name. It
defaults to ``kea-legal``.
If it is desired to restrict forensic logging to certain subnets, the
"legal-logging" boolean parameter can be specified within a user context
of these subnets. For example:
::
"Dhcpv4" {
"subnet4": [
{
"subnet": "192.0.2.0/24",
"pools": [
{
"pool": "192.0.2.1 - 192.0.2.200"
}
],
"user-context": {
"legal-logging": false
}
}
]
}
This configuration disables legal logging for the subnet "192.0.2.0/24". If the
"legal-logging" parameter is not specified, it defaults to 'true', which
enables legal logging for the subnet.
The following example demonstrates how to selectively disable legal
logging for an IPv6 subnet:
::
"Dhcpv6": {
"subnet6": [
{
"subnet": "2001:db8:1::/64",
"pools": [
{
"pool": "2001:db8:1::1-2001:db8:1::ffff"
}
],
"user-context": {
"legal-logging": false
}
}
]
}
See :ref:`dhcp4-user-contexts` and :ref:`dhcp6-user-contexts` to
learn more about user contexts in Kea configuration.
.. _forensic-log-database:
Database Backend
~~~~~~~~~~~~~~~~
Log entries can be inserted into a database when Kea is configured with
database backend support. A table named "logs" is used that includes a timestamp
(timeuuid for Cassandra) generated by the database software, and a
text log with the same format as files without the timestamp.
Please refer to :ref:`mysql-database` for information on using a MySQL database; to
:ref:`pgsql-database` for PostgreSQL database information; or to :ref:`cql-database`
for information on using a Cassandra (CQL) database. The logs table is part of the Kea database schemas.
Configuration parameters are extended by standard lease database
parameters as defined in :ref:`database-configuration4`. The "type"
parameter should be "mysql", "postgresql", "cql", or "logfile". When
it is absent or set to "logfile", files are used.
This database feature is experimental and will be likely improved, for
instance to add an address/prefix index (currently the only index is
the timestamp). No specific tools are provided to operate the database,
but standard tools may be used, for example, to dump the logs table
from a CQL database:
::
$ echo 'SELECT dateOf(timeuuid), log FROM logs;' | cqlsh -k database-name
system.dateof(timeuuid) | log
---------------------------------+---------------------------------------
2018-01-06 01:02:03.227000+0000 | Address: 192.2.1.100 has been renewed ...
...
(12 rows)
$
.. _flex-id:
flex_id: Flexible Identifiers for Host Reservations
---------------------------------------------------
This section describes a hook application dedicated to generate flexible
identifiers for host reservations. The Kea software provides a way to handle
host reservations that include addresses, prefixes, options, client
classes, and other features. The reservation can be based on hardware
address, DUID, circuit-id, or client-id in DHCPv4 and on hardware
address or DUID in DHCPv6. However, there are sometimes scenarios where
the reservation is more complex; it may use options other than those mentioned
above, use parts of specific options, or perhaps even use a combination of
several options and fields to uniquely identify a client. Those
scenarios are addressed by the Flexible Identifiers hook application.
Currently this library is only available to ISC customers with a paid support
contract.
.. note::
This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
The library allows the definition of an expression, using notation initially
used only for client classification. (See
:ref:`classification-using-expressions` for a detailed description of
the syntax available.) One notable difference is that for client
classification, the expression currently has to evaluate to either true
or false, while the flexible identifier expression is expected to
evaluate to a string that will be used as an identifier. It is a valid case
for the expression to evaluate to an empty string (e.g. in cases where a
client does not send specific options). This expression is then
evaluated for each incoming packet, and this evaluation generates an
identifier that is used to identify the client. In particular, there may
be host reservations that are tied to specific values of the flexible
identifier.
The library can be loaded in a similar way as other hook libraries. It
takes a mandatory parameter ``identifier-expression`` and optional boolean
parameter ``replace-client-id``:
::
"Dhcp6": {
"hooks-libraries": [
{
"library": "/path/libdhcp_flex_id.so",
"parameters": {
"identifier-expression": "expression",
"replace-client-id": false
}
},
...
]
}
The flexible identifier library supports both DHCPv4 and DHCPv6.
Let's consider a case of an IPv6 network that has an
independent interface for each of its connected customers. Customers are
able to plug in whatever device they want, so any type of identifier
(e.g. a client-id) is unreliable. Therefore, the operator may decide to
use an option inserted by a relay agent to differentiate between
clients. In this particular deployment, the operator has verified that the
interface-id is unique for each customer-facing interface, so it
is suitable for usage as a reservation. However, only the first six bytes of
the interface-id are interesting, because remaining bytes are either
randomly changed or not unique between devices. Therefore, the customer
decided to use the first six bytes of the interface-id option inserted by the
relay agent. After adding ``flex-id``, the ``host-reservation-identifiers`` goal
can be achieved by using the following configuration:
::
"Dhcp6": {
"subnet6": [{ ..., // subnet definition starts here
"reservations": [
"flex-id": "'port1234'", // value of the first 8 bytes of the interface-id
"ip-addresses": [ "2001:db8::1" ]
],
}], // end of subnet definitions
"host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
"hooks-libraries": [
{
"library": "/path/libdhcp_flex_id.so",
"parameters": {
"identifier-expression": "substring(relay6[0].option[18].hex,0,8)"
}
},
...
]
}
.. note::
Care should be taken when adjusting the expression. If the expression
changes, then all the ``flex-id`` values may change, possibly rendering
all reservations based on ``flex-id`` unusable until they are manually updated.
It is strongly recommended that administrators start with the expression and a
handful of reservations, and then adjust the expression as needed. Once
the expression is confirmed to do what is desired of it, host reservations
can be deployed on a broader scale.
``flex-id`` values in host reservations can be specified in two ways. First,
they can be expressed as a hex string, e.g. bar string can be represented
as 626174. Alternatively, it can be expressed as a quoted value (using
double and single quotes), e.g. "'bar'". The former is more convenient
for printable characters, while hex string values are more convenient
for non-printable characters and do not require the use of the
``hexstring`` operator.
::
"Dhcp6": {
"subnet6": [{ ..., // subnet definition starts here
"reservations": [
"flex-id": "01:02:03:04:05:06", // value of the first 8 bytes of the interface-id
"ip-addresses": [ "2001:db8::1" ]
],
}], // end of subnet definitions
"host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
"hooks-libraries": [
{
"library": "/path/libdhcp_flex_id.so",
"parameters": {
"identifier-expression": "vendor[4491].option[1026].hex"
}
},
...
]
}
When ``replace-client-id`` is set to "false" (which is the default setting),
the flex-id hook library uses the evaluated flexible identifier solely for
identifying host reservations, i.e. searching for reservations within a
database. This is the functional equivalent of other identifiers, similar
to hardware address or circuit-id. However, this mode of operation
implies that if a client device is replaced, it may cause a
conflict between an existing lease (allocated to the old device) and the
new lease being allocated to the new device. The conflict arises
because the same flexible identifier is computed for the replaced device,
so the server will try to allocate the same lease. The mismatch between
client identifiers sent by the new device and the old device causes the server
to refuse this new allocation until the old lease expires. A
manifestation of this problem is dependent on the specific expression used
as the flexible identifier and is likely to appear if only options
and other parameters are used that identify where the device is connected
(e.g. circuit-id), rather than the device identification itself (e.g.
MAC address).
The flex-id library offers a way to overcome the problem with lease
conflicts by dynamically replacing the client identifier (or DUID in DHCPv6)
with a value derived from the flexible identifier. The server
processes the client's query as if the flexible identifier were sent in the
client identifier (or DUID) option. This guarantees that a returning
client (for which the same flexible identifier is evaluated) will be
assigned the same lease despite the client identifier and/or MAC address
change.
The following is a stub configuration that enables this behavior:
::
"Dhcp4": {
"hooks-libraries": [
{
"library": "/path/libdhcp_flex_id.so",
"parameters": {
"identifier-expression": "expression",
"replace-client-id": true
}
},
...
]
}
In the DHCPv4 case, the value derived from the flexible identifier is
formed by prepending one byte with a value of zero to the flexible identifier.
In the DHCPv6 case, it is formed by prepending two zero bytes before the
flexible identifier.
Note that for this mechanism to take effect, the DHCPv4 server must be
configured to respect the client identifier option value during lease
allocation, i.e. ``match-client-id`` must be set to "true". See
:ref:`dhcp4-match-client-id` for details. No additional settings are
required for DHCPv6.
If the ``replace-client-id`` option is set to "true", the value of the
``echo-client-id`` parameter (which governs whether to send back a
client-id option) is ignored.
The :ref:`lease-cmds` section describes commands used to retrieve,
update, and delete leases using various identifiers, such as "hw-address" and
"client-id". The lease_cmds library doesn't natively support querying
for leases by flexible identifier. However, when ``replace-client-id`` is
set to "true", it makes it possible to query for leases using a value
derived from the flexible identifier. In the DHCPv4 case, the query will
look similar to this:
::
{
"command": "lease4-get",
"arguments": {
"identifier-type": "client-id",
"identifier": "00:54:64:45:66",
"subnet-id": 44
}
}
where the hexadecimal value of "54:64:45:66" is a flexible identifier
computed for the client.
In the DHCPv6 case, the corresponding query will look similar to this:
::
{
"command": "lease6-get",
"arguments": {
"identifier-type": "duid",
"identifier": "00:00:54:64:45:66",
"subnet-id": 10
}
}
.. _host-cmds:
host_cmds: Host Commands
------------------------
This section describes a hook application that offers a number of new
commands used to query and manipulate host reservations. Kea provides a
way to store host reservations in a database. In many larger deployments
it is useful to be able to manage that information while the server is
running. This library provides management commands for adding, querying,
and deleting host reservations in a safe way without restarting the
server. In particular, it validates the parameters, so an attempt to
insert incorrect data - such as adding a host with a conflicting identifier in the
same subnet - will be rejected. Those commands are exposed via the command
channel (JSON over UNIX sockets) and the Control Agent (JSON over a RESTful
interface). Additional commands and capabilities related to host
reservations will be added in the future.
Currently this library is only available to ISC customers with a paid support
contract.
.. note::
This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
Currently, five commands are supported: reservation-add (which adds a new
host reservation), reservation-get (which returns an existing reservation
if specified criteria are matched), reservation-get-all (which returns
all reservations in a specified subnet), reservation-get-page (a variant
of reservation-get-all which returns all reservations in a specified
subnet by pages), and reservation-del (which attempts to delete a
reservation matching specified criteria). To use commands that change
the reservation information (currently these are reservation-add and
reservation-del, but this rule applies to other commands that may be
implemented in the future), the hosts database must be specified and it must not operate
in read-only mode (see
the hosts-databases descriptions in :ref:`hosts-databases-configuration4`
and :ref:`hosts-databases-configuration6`). If the hosts-databases are not specified or are
running in read-only mode, the host_cmds library will load, but any
attempts to use reservation-add or reservation-del will fail.
Additional host reservation commands are planned in future releases of Kea. For a
description of envisaged commands, see the `Control API
Requirements <https://gitlab.isc.org/isc-projects/kea/wikis/designs/commands>`__
document.
All commands use JSON syntax. They can be issued either using the
control channel (see :ref:`ctrl-channel`) or via the Control Agent (see
:ref:`kea-ctrl-agent`).
The library can be loaded similarly to other hook libraries. It
does not take any parameters, and it supports both DHCPv4 and DHCPv6
servers.
::
"Dhcp6": {
"hooks-libraries": [
{
"library": "/path/libdhcp_host_cmds.so"
}
...
]
}
The subnet-id Parameter
~~~~~~~~~~~~~~~~~~~~~~~
Prior to diving into the individual commands, it is worth discussing the
parameter, ``subnet-id``. Currently this parameter is mandatory for all of the
commands supplied by this library. In previous versions of Kea, reservations had
to belong to a specific subnet; as of Kea 1.5.0, reservations may
be specified globally. In other words, they are not specific to any
subnet. When reservations are supplied via the configuration file, the
ID of the containing subnet (or lack thereof) is implicit in the
configuration structure. However, when managing reservations using
host commands, it is necessary to explicitly identify the scope to which
the reservation belongs. This is done via the ``subnet-id`` parameter.
For global reservations, use a value of zero (0). For reservations
scoped to a specific subnet, use that subnet's ID.
.. _command-reservation-add:
The reservation-add Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-add`` allows for the insertion of a new host. It takes a
set of arguments that vary depending on the nature of the host
reservation. Any parameters allowed in the configuration file that
pertain to host reservation are permitted here. For details regarding
IPv4 reservations, see :ref:`host-reservation-v4`; for IPv6 reservations, see
:ref:`host-reservation-v6`. The ``subnet-id`` is mandatory. Use a
value of zero (0) to add a global reservation, or the id of the subnet
to which the reservation should be added. An example command can be as
simple as:
::
{
"command": "reservation-add",
"arguments": {
"reservation": {
"subnet-id": 1,
"hw-address": "1a:1b:1c:1d:1e:1f",
"ip-address": "192.0.2.202"
}
}
}
but it can also take many more parameters, for example:
::
{
"command": "reservation-add",
"arguments": {
"reservation":
{
"subnet-id":1,
"client-id": "01:0a:0b:0c:0d:0e:0f",
"ip-address": "192.0.2.205",
"next-server": "192.0.2.1",
"server-hostname": "hal9000",
"boot-file-name": "/dev/null",
"option-data": [
{
"name": "domain-name-servers",
"data": "10.1.1.202,10.1.1.203"
}
],
"client-classes": [ "special_snowflake", "office" ]
}
}
}
Here is an example of a complex IPv6 reservation:
::
{
"command": "reservation-add",
"arguments": {
"reservation":
{
"subnet-id":1,
"duid": "01:02:03:04:05:06:07:08:09:0A",
"ip-addresses": [ "2001:db8:1:cafe::1" ],
"prefixes": [ "2001:db8:2:abcd::/64" ],
"hostname": "foo.example.com",
"option-data": [
{
"name": "vendor-opts",
"data": "4491"
},
{
"name": "tftp-servers",
"space": "vendor-4491",
"data": "3000:1::234"
}
]
}
}
}
The command returns a status that indicates either a success (result 0)
or a failure (result 1). A failed command always includes a text parameter
that explains the cause of the failure. Example results:
::
{ "result": 0, "text": "Host added." }
Example failure:
::
{ "result": 1, "text": "Mandatory 'subnet-id' parameter missing." }
As ``reservation-add`` is expected to store the host, the hosts-databases
parameter must be specified in the configuration and databases must not
run in read-only mode. In future versions of Kea, it will be possible to
modify the reservations read from a configuration file. Interested parties are
encouraged to contact ISC for more information on developing this functionality.
.. _command-reservation-get:
The reservation-get Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-get`` can be used to query the host database and retrieve
existing reservations. There are two types of parameters this command
supports: (subnet-id, address) or (subnet-id, identifier-type,
identifier). The first type of query is used when the address (either
IPv4 or IPv6) is known, but the details of the reservation are not. One
common use case of this type of query is to find out whether a given
address is reserved. The second query uses identifiers. For
maximum flexibility, Kea stores the host identifying information as a
pair of values: the type and the actual identifier. Currently supported
identifiers are "hw-address", "duid", "circuit-id", "client-id", and
"flex-id", but additional types may be added in the future. If any new
identifier types are defined in the future, the reservation-get command will
support them automatically. The ``subnet-id`` is mandatory. Use a value
of zero (0) to fetch a global reservation, or the id of the subnet to
which the reservation belongs.
An example command for getting a host reservation by a (subnet-id,
address) pair looks as follows:
::
{
"command": "reservation-get",
"arguments": {
"subnet-id": 1,
"ip-address": "192.0.2.202"
}
}
An example query by (subnet-id, identifier-type, identifier) looks as
follows:
::
{
"command": "reservation-get",
"arguments": {
"subnet-id": 4,
"identifier-type": "hw-address",
"identifier": "01:02:03:04:05:06"
}
}
``reservation-get`` typically returns the result 0 when the query was
conducted properly. In particular, 0 is returned when the host was not
found. If the query was successful, a number of host parameters will be
returned. An example of a query that did not find the host looks as
follows:
::
{ "result": 0, "text": "Host not found." }
An example result returned when the host was found looks like this:
::
{
"arguments": {
"boot-file-name": "bootfile.efi",
"client-classes": [
],
"hostname": "somehost.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.100",
"next-server": "192.0.0.2",
"option-data": [
],
"server-hostname": "server-hostname.example.org"
},
"result": 0,
"text": "Host found."
}
An example result returned when the query was malformed might look like this:
::
{ "result": 1, "text": "No 'ip-address' provided and 'identifier-type'
is either missing or not a string." }
.. _command-reservation-get-all:
The reservation-get-all Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-get-all`` can be used to query the host database and
retrieve all reservations in a specified subnet. This command uses
parameters providing the mandatory subnet-id. Global host reservations
can be retrieved by using a subnet-id value of zero (0).
For instance, retrieving host reservations for the subnet 1:
::
{
"command": "reservation-get-all",
"arguments": {
"subnet-id": 1
}
}
returns some IPv4 hosts:
::
{
"arguments": {
"hosts": [
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "somehost.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.100",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org"
},
...
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "otherhost.example.org",
"hw-address": "01:02:03:04:05:ff",
"ip-address": "192.0.2.200",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org"
}
]
},
"result": 0,
"text": "72 IPv4 host(s) found."
}
The response returned by ``reservation-get-all`` can be very long. The
DHCP server does not handle DHCP traffic when preparing a response to
reservation-get-all, so if there are many reservations in a subnet, this
may be disruptive. Use with caution. For larger deployments, please
consider using ``reservation-get-page`` instead (see
:ref:`command-reservation-get-page`).
For a reference, see :ref:`command-reservation-get-all`.
.. _command-reservation-get-page:
The reservation-get-page command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-get-page`` can be used to query the host database and
retrieve all reservations in a specified subnet by pages. This command
uses parameters providing the mandatory subnet-id. Use a value of zero
(0) to fetch global reservations. The second mandatory parameter is the
page size limit. Optional source-index and from host id, both defaulting
to 0, are used to chain page queries.
The usage of from and source-index parameters requires additional
explanation. For the first call, those parameters should not be specified
(or specified as zeros). For any follow-up calls, they should be set to
the values returned in previous calls in a next map holding from and
source-index values. Subsequent calls should be issued until all
reservations are returned. The end is reached once the returned list is
empty, the count is 0, no next map is present, and result status 3 (empty) is
returned.
.. note::
The from and source-index parameters are reflecting the internal state of
the search. There is no need to understand what they represent; it is
simply a value that is supposed to be copied from one response to the
next query. However, for those who are curious, the from field represents a
64-bit representation of the host identifier used by a host backend. The
source-index is an internal representation of multiple host
backends: 0 is used to represent hosts defined in a configuration
file, and 1 represents the first database backend. In some uncommon cases
there may be more than one database backend configured, so
potentially there may be a 2. In any case, Kea will iterate over all
backends configured.
For instance, retrieving host reservations for the subnet 1 and
requesting the first page can be done by:
::
{
"command": "reservation-get-page",
"arguments": {
"subnet-id": 1,
"limit": 10
}
}
Since this is the first call, source-index and from should not be
specified. They will default to their zero default values.
Some hosts are returned with information to get the next page:
::
{
"arguments": {
"count": 72,
"hosts": [
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "somehost.example.org",
"hw-address": "01:02:03:04:05:06",
"ip-address": "192.0.2.100",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org"
},
...
{
"boot-file-name": "bootfile.efi",
"client-classes": [ ],
"hostname": "otherhost.example.org",
"hw-address": "01:02:03:04:05:ff",
"ip-address": "192.0.2.200",
"next-server": "192.0.0.2",
"option-data": [ ],
"server-hostname": "server-hostname.example.org"
}
],
"next": {
"from": 1234567,
"source-index": 1
}
},
"result": 0,
"text": "72 IPv4 host(s) found."
}
Note that the "from" and "source-index" fields were specified in the response in
the next map. Those two must be copied to the next command, so Kea
continues from the place where the last command finished. To get the
next page the following command can be sent:
::
{
"command": "reservation-get-page",
"arguments": {
"subnet-id": 1,
"source-index": 1,
"from": 1234567,
"limit": 10
}
}
The response will contain a list of hosts with updated source-index
and from fields. Continue calling the command until the last
page is received. Its response will look like this:
::
{
"arguments": {
"count": 0,
"hosts": [ ],
},
"result": 3,
"0 IPv4 host(s) found."
}
This command is more complex than ``reservation-get-all``, but lets
users retrieve larger host reservations lists in smaller chunks. For
small deployments with few reservations, it is easier to use
``reservation-get-all`` (see :ref:`command-reservation-get-all`.
.. note::
Currently ``reservation-get-page`` is not supported by the Cassandra
host backend.
.. _command-reservation-del:
The reservation-del Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-del`` can be used to delete a reservation from the host
database. There are two types of parameters this command supports:
(subnet-id, address) or (subnet-id, identifier-type, identifier). The
first type of query is used when the address (either IPv4 or IPv6) is
known, but the details of the reservation are not. One common use case of
this type of query is to remove a reservation (e.g. a specific
address should no longer be reserved). The second query uses identifiers.
For maximum flexibility, Kea stores the host identifying information as
a pair of values: the type and the actual identifier. Currently supported
identifiers are "hw-address", "duid", "circuit-id", "client-id", and
"flex-id", but additional types may be added in the future. If any new
identifier types are defined in the future, the reservation-get command will
support them automatically. The ``subnet-id`` is mandatory. Use a value
of zero (0) to delete a global reservation, or the id of the subnet from
which the reservation should be deleted.
An example command for deleting a host reservation by (subnet-id,
address) pair looks as follows:
::
{
"command": "reservation-del",
"arguments": {
"subnet-id": 1,
"ip-address": "192.0.2.202"
}
}
An example deletion by (subnet-id, identifier-type, identifier) looks as
follows:
::
{
"command": "reservation-del",
"arguments":
"subnet-id": 4,
"identifier-type": "hw-address",
"identifier": "01:02:03:04:05:06"
}
}
``reservation-del`` returns a result 0 when the host deletion was
successful or 1 if it was not. Descriptive text is provided in the event of
an error. Example results look as follows:
::
{
"result": 1,
"text": "Host not deleted (not found)."
}
::
{
"result": 0,
"text": "Host deleted."
}
::
{
"result": 1,
"text": "Unable to delete a host because there is no hosts-database
configured."
}
.. include:: hooks-lease-cmds.rst
.. _subnet-cmds:
subnet_cmds: Subnet Commands
----------------------------
This section describes a hook application that offers some new
commands used to query and manipulate subnet and shared network
configurations in Kea. This application is very useful in deployments
with a large number of subnets being managed by the DHCP servers,
when those subnets are frequently updated. The commands offer a lightweight
approach for manipulating subnets without a need to fully reconfigure
the server and without affecting existing servers' configurations. An
ability to manage shared networks (listing, retrieving details, adding
new ones, removing existing ones, and adding subnets to and removing them from
shared networks) is also provided.
Currently this library is only available to ISC customers with a paid support
contract.
.. note::
This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
The following commands are currently supported:
- ``subnet4-list/subnet6-list`` - lists all configured subnets.
- ``subnet4-get/subnet6-get`` - retrieves detailed information about a
specified subnet.
- ``subnet4-add/subnet6-add`` - adds a new subnet into the server's
configuration.
- ``subnet4-update/subnet6-update`` - updates a subnet in the server's
configuration.
- ``subnet4-del/subnet6-del`` - removes a subnet from the server's
configuration.
- ``network4-list/network6-list`` - lists all configured shared networks.
- ``network4-get/network6-get`` - retrieves detailed information about a
specified shared network.
- ``network4-add/network6-add`` - adds a new shared network to the
server's configuration.
- ``network4-del/network6-del`` - removes a shared network from the
server's configuration.
- ``network4-subnet-add/network6-subnet-add`` - adds an existing subnet to
an existing shared network.
- ``network4-subnet-del/network6-subnet-del`` - removes a subnet from
an existing shared network and demotes it to a plain subnet.
.. _command-subnet4-list:
The subnet4-list Command
~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to list all currently configured subnets. Each
subnet is returned with a subnet identifier and
subnet prefix. To retrieve
detailed information about the subnet, use the ``subnet4-get`` command.
This command has the simple structure:
::
{
"command": "subnet4-list"
}
The list of subnets is returned in the following format:
::
{
"result": 0,
"text": "2 IPv4 subnets found",
"arguments": {
"subnets": [
{
"id": 10,
"subnet": "10.0.0.0/8"
},
{
"id": 100,
"subnet": "192.0.2.0/24"
}
]
}
If no IPv4 subnets are found, an error code is returned along with the
error description.
.. _command-subnet6-list:
The subnet6-list Command
~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to list all currently configured subnets. Each
subnet is returned with a subnet identifier and
subnet prefix. To retrieve
detailed information about the subnet, use the ``subnet6-get`` command.
This command has the simple structure:
::
{
"command": "subnet6-list"
}
The list of subnets is returned in the following format:
::
{
"result": 0,
"text": "2 IPv6 subnets found",
"arguments": {
"subnets": [
{
"id": 11,
"subnet": "2001:db8:1::/64"
},
{
"id": 233,
"subnet": "3000::/16"
}
]
}
If no IPv6 subnets are found, an error code is returned along with the
error description.
.. _command-subnet4-get:
The subnet4-get Command
~~~~~~~~~~~~~~~~~~~~~~~
This command is used to retrieve detailed information about the
specified subnet. This command usually follows ``subnet4-list``,
which is used to discover available subnets with their respective subnet
identifiers and prefixes. Any of those parameters can be then used in
``subnet4-get`` to fetch subnet information:
::
{
"command": "subnet4-get",
"arguments": {
"id": 10
}
}
or
::
{
"command": "subnet4-get",
"arguments": {
"subnet": "10.0.0.0/8"
}
}
If the subnet exists the response will be similar to this:
::
{
"result": 0,
"text": "Info about IPv4 subnet 10.0.0.0/8 (id 10) returned",
"arguments": {
"subnets": [
{
"subnet": "10.0.0.0/8",
"id": 1,
"option-data": [
....
]
...
}
]
}
}
.. _command-subnet6-get:
The subnet6-get Command
~~~~~~~~~~~~~~~~~~~~~~~
This command is used to retrieve detailed information about the
specified subnet. This command usually follows ``subnet6-list``,
which is used to discover available subnets with their respective subnet
identifiers and prefixes. Any of those parameters can be then used in
``subnet6-get`` to fetch subnet information:
::
{
"command": "subnet6-get",
"arguments": {
"id": 11
}
}
or
::
{
"command": "subnet6-get",
"arguments": {
"subnet": "2001:db8:1::/64"
}
}
If the subnet exists the response will be similar to this:
::
{
"result": 0,
"text": "Info about IPv6 subnet 2001:db8:1::/64 (id 11) returned",
"arguments": {
"subnets": [
{
"subnet": "2001:db8:1::/64",
"id": 1,
"option-data": [
...
]
....
}
]
}
}
.. _command-subnet4-add:
The subnet4-add Command
~~~~~~~~~~~~~~~~~~~~~~~
This command is used to create and add a new subnet to the existing server
configuration. This operation has no impact on other subnets. The subnet
identifier must be specified and must be unique among all subnets. If
the identifier or a subnet prefix is not unique, an error is reported and
the subnet is not added.
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations must not be specified within
``subnet4-add``. The commands described in :ref:`host-cmds` should be used to
add, remove, and modify static reservations.
::
{
"command": "subnet4-add",
"arguments": {
"subnet4": [ {
"id": 123,
"subnet": "10.20.30.0/24",
...
} ]
}
}
The response to this command has the following structure:
::
{
"result": 0,
"text": "IPv4 subnet added",
"arguments": {
"subnet4": [
{
"id": 123,
"subnet": "10.20.30.0/24"
}
]
}
}
.. _command-subnet6-add:
The subnet6-add Command
~~~~~~~~~~~~~~~~~~~~~~~
This command is used to create and add a new subnet to the existing server
configuration. This operation has no impact on other subnets. The subnet
identifier must be specified and must be unique among all subnets. If
the identifier or a subnet prefix is not unique, an error is reported and
the subnet is not added.
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations must not be specified within
``subnet6-add``. The commands described in :ref:`host-cmds` should be used
to add, remove, and modify static reservations.
::
{
"command": "subnet6-add",
"arguments": {
"subnet6": [ {
"id": 234,
"subnet": "2001:db8:1::/64",
...
} ]
}
}
The response to this command has the following structure:
::
{
"result": 0,
"text": "IPv6 subnet added",
"arguments": {
"subnet6": [
{
"id": 234,
"subnet": "2001:db8:1::/64"
}
]
}
}
It is recommended, but not mandatory, to specify the subnet ID. If not
specified, Kea will try to assign the next subnet-id value. This
automatic ID value generator is simple; it returns a previously
automatically assigned value, increased by 1. This works well, unless
a subnet is manually created with a value bigger than one previously used. For
example, if subnet4-add is called five times, each without an ID, Kea will
assign IDs 1, 2, 3, 4, and 5 and it will work just fine. However, if
subnet4-add is called five times, with the first subnet having the
subnet-id of value 3 and the remaining ones having no subnet-id, the operation will
fail. The first command (with the explicit value) will use subnet-id 3; the
second command will create a subnet with id of 1; the third will use a
value of 2; and finally the fourth will have the subnet-id value
auto-generated as 3. However, since there is already a subnet with that
ID, the process will fail.
The general recommendation is either never use explicit values, so
the auto-generated values will always work; or always use explicit
values, so the auto-generation is never used. The two
approaches can be mixed only if the administrator understands how internal
automatic subnet-id generation works in Kea.
.. note::
Subnet IDs must be greater than zero and less than 4294967295.
.. _command-subnet4-update:
The subnet4-update Command
~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update a subnet in the existing server
configuration. This operation has no impact on other subnets. The subnet
identifier is used to identify the subnet to replace; it must be
specified and must be unique among all subnets. The subnet prefix should
not be updated.
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations must not be specified within
``subnet4-update``. The commands described in :ref:`host-cmds` should be used
to update, remove, and modify static reservations.
::
{
"command": "subnet4-update",
"arguments": {
"subnet4": [ {
"id": 123,
"subnet": "10.20.30.0/24",
...
} ]
}
}
The response to this command has the following structure:
::
{
"result": 0,
"text": "IPv4 subnet updated",
"arguments": {
"subnet4": [
{
"id": 123,
"subnet": "10.20.30.0/24"
}
]
}
}
.. _command-subnet6-update:
The subnet6-update Command
~~~~~~~~~~~~~~~~~~~~~~~~~~
This command is used to update a subnet in the existing server
configuration. This operation has no impact on other subnets. The subnet
identifier is used to identify the subnet to replace; it must be
specified and must be unique among all subnets. The subnet prefix should
not be updated.
The subnet information within this command has the same structure as the
subnet information in the server configuration file, with the exception
that static host reservations must not be specified within
``subnet6-update``. The commands described in :ref:`host-cmds` should be used
to update, remove, and modify static reservations.
::
{
"command": "subnet6-update",
"arguments": {
"subnet6": [ {
"id": 234,
"subnet": "2001:db8:1::/64",
...
} ]
}
}
The response to this command has the following structure:
::
{
"result": 0,
"text": "IPv6 subnet updated",
"arguments": {
"subnet6": [
{
"id": 234,
"subnet": "2001:db8:1::/64"
}
]
}
}
.. _command-subnet4-del:
The subnet4-del Command
~~~~~~~~~~~~~~~~~~~~~~~
This command is used to remove a subnet from the server's configuration.
This command has no effect on other configured subnets, but removing a
subnet has certain implications which the server's administrator should
be aware of.
In most cases the server has assigned some leases to the clients
belonging to the subnet. The server may also be configured with static
host reservations which are associated with this subnet. The current
implementation of the ``subnet4-del`` command removes neither the leases nor
the host reservations associated with a subnet. This is the safest approach
because the server doesn't lose track of leases assigned to the clients
from this subnet. However, removal of the subnet may still cause
configuration errors and conflicts. For example: after removal of the
subnet, the server administrator may update a new subnet with the ID
used previously for the removed subnet. This means that the existing
leases and static reservations will be in conflict with this new subnet.
Thus, we recommend that this command be used with extreme caution.
This command can also be used to completely delete an IPv4 subnet that
is part of a shared network. To simply remove the subnet
from a shared network and keep the subnet configuration, use the
``network4-subnet-del`` command instead.
The command has the following structure:
::
{
"command": "subnet4-del",
"arguments": {
"id": 123
}
}
The example successful response may look like this:
::
{
"result": 0,
"text": "IPv4 subnet 192.0.2.0/24 (id 123) deleted",
"arguments": {
"subnets": [
{
"id": 123,
"subnet": "192.0.2.0/24"
}
]
}
}
.. _command-subnet6-del:
The subnet6-del Command
~~~~~~~~~~~~~~~~~~~~~~~
This command is used to remove a subnet from the server's configuration.
This command has no effect on other configured subnets, but removing a
subnet has certain implications which the server's administrator should
be aware of.
In most cases the server has assigned some leases to the clients
belonging to the subnet. The server may also be configured with static
host reservations which are associated with this subnet. The current
implementation of the ``subnet6-del`` command removes neither the leases nor
the host reservations associated with a subnet. This is the safest approach
because the server doesn't lose track of leases assigned to the clients
from this subnet. However, removal of the subnet may still cause
configuration errors and conflicts. For example: after removal of the
subnet, the server administrator may add a new subnet with the ID used
previously for the removed subnet. This means that the existing leases
and static reservations will be in conflict with this new subnet. Thus,
we recommend that this command be used with extreme caution.
This command can also be used to completely delete an IPv6 subnet that
is part of a shared network. To simply remove the subnet
from a shared network and keep the subnet configuration, use the
``network6-subnet-del`` command instead.
The command has the following structure:
::
{
"command": "subnet6-del",
"arguments": {
"id": 234
}
}
The example successful response may look like this:
::
{
"result": 0,
"text": "IPv6 subnet 2001:db8:1::/64 (id 234) deleted",
"subnets": [
{
"id": 234,
"subnet": "2001:db8:1::/64"
}
]
}
.. _command-network4-list:
The network4-list, network6-list Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to retrieve the full list of currently configured
shared networks. The list contains only very basic information about
each shared network. If more details are needed, please use
``network4-get`` or ``network6-get`` to retrieve all information
available. This command does not require any parameters and its
invocation is very simple:
::
{
"command": "network4-list"
}
An example response for ``network4-list`` looks as follows:
::
{
"arguments": {
"shared-networks": [
{ "name": "floor1" },
{ "name": "office" }
]
},
"result": 0,
"text": "2 IPv4 network(s) found"
}
``network6-list`` follows exactly the same syntax for both the query and
the response.
.. _command-network4-get:
The network4-get, network6-get Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to retrieve detailed information about shared
networks, including subnets that are currently part of a given network.
Both commands take one mandatory parameter, ``name``, which specifies the
name of the shared network. An example command to retrieve details about
an IPv4 shared network with the name "floor13" looks as follows:
::
{
"command": "network4-get",
"arguments": {
"name": "floor13"
}
}
An example response could look as follows:
::
{
"result": 0,
"text": "Info about IPv4 shared network 'floor13' returned",
"arguments": {
"shared-networks": [
{
"match-client-id": true,
"name": "floor13",
"option-data": [ ],
"rebind-timer": 90,
"relay": {
"ip-address": "0.0.0.0"
},
"renew-timer": 60,
"reservation-mode": "all",
"subnet4": [
{
"subnet": "192.0.2.0/24",
"id": 5,
// many other subnet-specific details here
},
{
"id": 6,
"subnet": "192.0.3.0/31",
// many other subnet-specific details here
}
],
"valid-lifetime": 120
}
]
}
}
Note that the actual response contains many additional fields that are
omitted here for clarity. The response format is exactly the same as
used in ``config-get``, just limited to returning the shared network's
information.
.. _command-network4-add:
The network4-add, network6-add Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to add a new shared network, which must
have a unique name. This command requires one parameter,
``shared-networks``, which is a list and should contain exactly one
entry that defines the network. The only mandatory element for a network
is its name. Although it does not make operational sense, it is possible
to add an empty shared network that does not have any subnets in it.
That is allowed for testing purposes, but having empty networks (or with
only one subnet) is discouraged in production environments. For details
regarding syntax, see :ref:`shared-network4` and
:ref:`shared-network6`.
.. note::
As opposed to parameter inheritance during the processing of a full new
configuration, this command does not fully handle parameter inheritance.
Any missing parameters will be filled with default values, rather
than inherited from the global scope.
An example that showcases how to add a new IPv4 shared network looks as
follows:
::
{
"command": "network4-add",
"arguments": {
"shared-networks": [ {
"name": "floor13",
"subnet4": [
{
"id": 100,
"pools": [ { "pool": "192.0.2.2-192.0.2.99" } ],
"subnet": "192.0.2.0/24",
"option-data": [
{
"name": "routers",
"data": "192.0.2.1"
}
]
},
{
"id": 101,
"pools": [ { "pool": "192.0.3.2-192.0.3.99" } ],
"subnet": "192.0.3.0/24",
"option-data": [
{
"name": "routers",
"data": "192.0.3.1"
}
]
} ]
} ]
}
}
Assuming there was no shared network with a name "floor13" and no subnets
with IDs 100 and 101 previously configured, the command will be
successful and will return the following response:
::
{
"arguments": {
"shared-networks": [ { "name": "floor13" } ]
},
"result": 0,
"text": "A new IPv4 shared network 'floor13' added"
}
The ``network6-add`` command uses the same syntax for both the query and the
response. However, there are some parameters that are IPv4-only (e.g.
match-client-id) and some that are IPv6-only (e.g. interface-id). The same
applies to subnets within the network.
.. _command-network4-del:
The network4-del, network6-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to delete existing shared networks. Both
commands take exactly one parameter, ``name``, that specifies the name of
the network to be removed. An example invocation of the ``network4-del``
command looks as follows:
::
{
"command": "network4-del",
"arguments": {
"name": "floor13"
}
}
Assuming there was such a network configured, the response will look
similar to the following:
::
{
"arguments": {
"shared-networks": [
{
"name": "floor13"
}
]
},
"result": 0,
"text": "IPv4 shared network 'floor13' deleted"
}
The ``network6-del`` command uses exactly the same syntax for both the
command and the response.
If there are any subnets belonging to the shared network being deleted,
they will be demoted to a plain subnet. There is an optional parameter
called ``subnets-action`` that, if specified, takes one of two possible
values: ``keep`` (which is the default) and ``delete``. It controls
whether the subnets are demoted to plain subnets or removed. An example
usage in the ``network6-del`` command that deletes the shared network and all
subnets in it could look as follows:
::
{
"command": "network4-del",
"arguments": {
"name": "floor13",
"subnets-action": "delete"
}
}
Alternatively, to completely remove the subnets, it is possible to use the
``subnet4-del`` or ``subnet6-del`` commands.
.. _command-network4-subnet-add:
The network4-subnet-add, network6-subnet-add Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to add existing subnets to existing shared
networks. There are several ways to add a new shared network. The system
administrator can add the whole shared network at once, either by
editing a configuration file or by calling the ``network4-add`` or
``network6-add`` command with the desired subnets in it. This approach
works better for completely new shared subnets. However, there may be
cases when an existing subnet is running out of addresses and needs to
be extended with additional address space; in other words, another subnet
needs to be added on top of it. For this scenario, a system administrator
can use ``network4-add`` or ``network6-add``, and then add an existing
subnet to this newly created shared network using
``network4-subnet-add`` or ``network6-subnet-add``.
The ``network4-subnet-add`` and ``network6-subnet-add`` commands take
two parameters: ``id``, which is an integer and specifies the subnet-id of
an existing subnet to be added to a shared network; and ``name``, which
specifies the name of the shared network to which the subnet will be added. The
subnet must not belong to any existing network; to
reassign a subnet from one shared network to another, please use the
``network4-subnet-del`` or ``network6-subnet-del`` commands first.
An example invocation of the ``network4-subnet-add`` command looks as
follows:
::
{
"command": "network4-subnet-add",
"arguments": {
"name": "floor13",
"id": 5
}
}
Assuming there is a network named "floor13", and there is a subnet with
subnet-id 5 that is not a part of existing network, the command will
return a response similar to the following:
::
{
"result": 0,
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now part of shared network 'floor13'"
}
The ``network6-subnet-add`` command uses exactly the same syntax for
both the command and the response.
.. note::
As opposed to parameter inheritance during the processing of a full new
configuration or when adding a new shared network with new subnets,
this command does not fully handle parameter inheritance.
Any missing parameters will be filled with default values, rather
than inherited from the global scope or from the shared network.
.. _command-network4-subnet-del:
The network4-subnet-del, network6-subnet-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These commands are used to remove a subnet that is part of an existing
shared network and demote it to a plain, stand-alone subnet.
To remove a subnet completely, use the ``subnet4-del`` or ``subnet6-del``
commands instead. The ``network4-subnet-del`` and
``network6-subnet-del`` commands take two parameters: ``id``, which is
an integer and specifies the subnet-id of an existing subnet to be removed from
a shared network; and ``name``, which specifies the name of the shared
network from which the subnet will be removed.
An example invocation of the ``network4-subnet-del`` command looks as
follows:
::
{
"command": "network4-subnet-del",
"arguments": {
"name": "floor13",
"id": 5
}
}
Assuming there was a subnet with subnet-id equal to 5, that was part of a
shared network named "floor13", the response would look similar to the
following:
::
{
"result": 0,
"text": "IPv4 subnet 10.0.0.0/8 (id 5) is now removed from shared network 'floor13'"
}
The ``network6-subnet-del`` command uses exactly the same syntax for
both the command and the response.
.. include:: hooks-class-cmds.rst
.. include:: hooks-cb-cmds.rst
.. include:: hooks-ha.rst
.. include:: hooks-stat-cmds.rst
.. include:: hooks-radius.rst
.. include:: hooks-host-cache.rst
.. _user-context:
User Contexts
=============
Hooks libraries can have their own configuration parameters, which is
convenient if the parameter applies to the whole library. However,
sometimes it is very useful to extend certain configuration entities
with additional configuration data. This is where the concept
of user contexts comes in. A system administrator can define an arbitrary set of
data and attach it to Kea structures, as long as the data are specified
as a JSON map. In particular, it is possible to define fields that are
integers, strings, boolean, lists, or maps. It is possible to define
nested structures of arbitrary complexity. Kea does not use that data on
its own; it simply stores it and makes it available for the hooks libraries.
Another use case for user contexts may be storing comments and other
information that will be retained by Kea. Regular comments are discarded
when the configuration is loaded, but user contexts are retained. This is
useful if administrators want their comments to survive config-set or config-get
operations, for example.
If user context is supported in a given context, the parser translates
"comment" entries into user context with a "comment" entry. The pretty
print of a configuration does the opposite operation and puts "comment"
entries at the beginning of maps, as that seems to be the common usage.
As of Kea 1.3, the structures that allow user contexts are pools of all
types (addresses and prefixes) and subnets. Kea 1.4 extended user
context support to the global scope, interfaces config, shared networks,
subnets, client classes, option datas and definitions, host
reservations, control socket, dhcp ddns, loggers and server id. These
are supported in both DHCPv4 and DHCPv6, with the exception of server id
which is DHCPv6 only.
Reference in New Issue View Git Blame Copy Permalink