:ref:`d2-ctrl-channel` to learn how the socket configuration is
specified for the DHCPv4, DHCPv6, and D2 services.
- **Warning**
+ .. warning::
"dhcp4-server", "dhcp6-server", and "d2-server" were renamed to
"dhcp4", "dhcp6", and "d2" respectively in Kea 1.2. If you are
..
- **Note**
+ .. note::
Note that the configuration snippet provided above is for testing
purposes only. It should be modified according to the security
..
- **Note**
+ .. note::
Client classes in Kea follow the order in which they are specified in
the configuration (vs. alphabetical order). Required classes follow
chooses only one of the values for the reply; the class from which the
value is obtained is unspecified.
- **Note**
+ .. note::
Care should be taken with client classification, as it is easy for
clients that do not meet any class criteria to be denied service
..
- **Note**
+ .. note::
The expression for each class is executed on each packet received. If
the expressions are overly complex, the time taken to execute them
..
- **Note**
+ .. note::
The debug logging may be quite verbose if there are a number of
expressions to evaluate; that is intended as an aid in helping
..
- **Note**
+.. note::
We strongly recommend against duplication of the configuration information
in the file and the database. For example, when specifying subnets
so it is possible that parts of the configuration specified in the
file may be overridden if contradicted by information in the database.
- **Note**
+.. note::
It is recommended that the ``subnet_cmds`` hooks library not be used to
manage the subnets when the configuration backend is used as a source
libraries must be installed, as explained in
:ref:`DHCP Database Installation and Configuration <dhcp-install-configure>`.
- **Note**
+.. note::
Any existing MySQL schema must be upgraded to the latest schema
required by the particular Kea version using the ``kea-admin`` tool,
More examples are available in the installed ``share/doc/kea/examples``
directory.
- **Note**
+ .. note::
The "Logging" element is removed in Kea 1.6.0 and its contents (the
"loggers" object) moved inside the configuration objects (maps) for the
which are specific to the command issued. The map may be present, but
that depends on the specific command.
- **Note**
+.. note::
When sending commands via the Control Agent, it is possible to specify
multiple services at which the command is targeted. CA forwards this
..
- **Warning**
+.. warning::
It is possible for a malicious attacker to send bogus
NameChangeRequests to the DHCP-DDNS server. Addresses other than the
used for testing purposes; note that local users may still
communicate with the DHCP-DDNS server.
- **Note**
+.. note::
If the ip-address and port are changed, the corresponding values in
the DHCP servers' "dhcp-ddns" configuration section must be changed.
..
- **Note**
+.. note::
Since "hostname" is not yet supported, the parameter "ip-address"
must be set to the address of the DNS server.
..
- **Note**
+.. note::
Since "hostname" is not yet supported, the parameter "ip-address"
must be set to the address of the DNS server.
User Contexts in DDNS
---------------------
- **Note**
+.. note::
User contexts were designed for hook libraries, which are not yet
supported for DHCP-DDNS server configuration.
specifying the configuration of the Kea module using it. In the example
above this object is called ``Dhcp4``.
- **Note**
+.. note::
In the current Kea release it is possible to specify configurations
of multiple modules within a single configuration file, but this is
(also in seconds) that define T1 and T2 timers that govern when the
client will begin the renewal and rebind procedures.
- **Note**
+.. note::
Both ``renew-timer`` and ``rebind-timer``
are optional. The server will only send ``rebind-timer`` to the client,
Lease Database Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **Note**
+.. note::
Lease database access information must be configured for the DHCPv4
server, even if it has already been configured for the DHCPv6 server.
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.
- **Note**
+.. note::
Automatic reconnection to database backends is configured
individually per backend. This allows users to tailor the recovery
..
- **Note**
+.. note::
Note that the host parameter is used by the MySQL and PostgreSQL backends.
Cassandra has a concept of contact points that can be used to
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.
- **Note**
+.. note::
Automatic reconnection to database backends is configured
individually per backend. This allows users to tailor the recovery
operate in "read-write" mode, which is also the default configuration if
the parameter is not specified.
- **Note**
+.. note::
The ``readonly`` parameter is currently only supported for MySQL and
PostgreSQL databases.
that link. To use a single address on such interface, the
"interface-name/address" notation should be used.
- **Note**
+.. note::
Specifying the value ``raw`` as the socket type doesn't guarantee
that the raw sockets will be used! The use of raw sockets to handle
unexpected consequences. The only remedy for this issue at present is to
manually specify a unique identifier for each subnet.
- **Note**
+.. note::
Subnet IDs must be greater than zero and less than 4294967295.
..
- **Note**
+.. note::
In the event that both explicit values are specified and
calculate-tee-times is true, the server will use the explicit values.
The new option content is one IPv4 address followed by one or more 16-
bit unsigned integers.
- **Note**
+.. note::
In general, boolean values are specified as ``true`` or ``false``,
without quotes. Some specific boolean parameters may also accept
..
- **Note**
+.. note::
Numbers can be specified in decimal or hexadecimal format. The
hexadecimal format can be either plain (e.g. abcd) or prefixed with
..
- **Note**
+.. note::
This last-resort definition for the Vendor-Specific Information
option (code 43) is not compatible with a raw binary value. When
matching these cases and an option definition for the VSI option with
a binary type and no encapsulation.
- **Note**
+.. note::
Option definitions in client classes are allowed only for this
limited option set (codes 43 and from 224 to 254), and only for
evaluated for each packet. If the result is "true", the packet is a
member of the class.
- **Note**
+.. note::
Care should be taken with client classification, as it is easy for
clients that do not meet class criteria to be denied all service.
If there are multiple classes defined and an incoming packet is matched
to multiple classes, the class that is evaluated first is used.
- **Note**
+.. note::
The classes are ordered as specified in the configuration.
"docsis3.0" and as a result the packet will belong to class
"VENDOR_CLASS_docsis3.0".
- **Note**
+.. note::
Certain special actions for clients in VENDOR_CLASS_docsis3.0 can be
achieved by defining VENDOR_CLASS_docsis3.0 and setting its
..
- **Note**
+.. note::
Note that in early versions of Kea, this parameter was a boolean and permitted only
values of ``true`` and ``false``. Boolean values have been deprecated
name supplied by the client, and it is performed before applying a
qualifying suffix (if one is defined and needed).
- **Note**
+.. note::
The following are some considerations to keep in mind:
Name sanitizing is meant to catch the more common cases of invalid
configuration of the DHCPv4 side (the DHCPv6 side is described in
:ref:`dhcp6-dhcp4o6-config`).
- **Note**
+.. note::
DHCPv4-over-DHCPv6 support is experimental and the details of the
inter-process communication may change; both the DHCPv4 and DHCPv6
to reserve hostnames for clients which may move from one subnet to
another.
- **Note**
+.. note::
Global reservations, while useful in certain circumstances, have aspects
that must be given due consideration when using them, please see
out-of-pool reservations. If the reserved address does not belong to a
pool, there is no way that other clients can get it.
- **Note**
+.. note::
The conflict-resolution mechanism does not work for global
reservations. Although the global address reservations feature may be useful
class is added to the packet and any class depending on it (directly or
indirectly) and not only-if-required is evaluated.
- **Note**
+.. note::
To force the evaluation of a class expression after the
host reservation lookup, for instance because of a dependency on
provides some examples of how to conduct common host reservation
operations.
- **Note**
+.. note::
In Kea, the maximum length of an option specified per-host is
arbitrarily set to 4096 bytes.
subnet, or the client has reservations in a subnet other than the
default.
- **Note**
+.. note::
Deployments should not assume that Kea waits until it has allocated
all the addresses from the first subnet in a shared network before
It can be used to match incoming packets into a subnet in uncommon
configurations, e.g. shared networks. See :ref:`dhcp4-relay-override` for details.
- **Note**
+.. note::
The subnet selection mechanism described in this section is based on
the assumption that client classification is not used. The
If "relay" is specified, the "ip-addresses" parameter within it is
mandatory.
- **Note**
+.. note::
The current version of Kea uses the "ip-addresses" parameter, which
supports specifying a list of addresses.
Statistics in the DHCPv4 Server
===============================
- **Note**
+.. note::
This section describes DHCPv4-specific statistics. For a general
overview and usage of statistics, see :ref:`stats`.
available for this server from the database. This configuration is
merged into the configuration read from the configuration file.
- **Note**
+.. note::
Whenever there is a conflict between the parameters specified in the
configuration file and the database, the parameters from the database
specifying the configuration of the Kea module using it. In the example
above this object is called ``Dhcp6``.
- **Note**
+.. note::
In the current Kea release it is possible to specify configurations
of multiple modules within a single configuration file, but this is
Lease Database Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **Note**
+.. note::
Lease database access information must be configured for the DHCPv6
server, even if it has already been configured for the DHCPv4 server.
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.
- **Note**
+.. note::
Automatic reconnection to database backends is configured
individually per backend. This allows users to tailor the recovery
..
- **Note**
+.. note::
Note that the host parameter is used by the MySQL and PostgreSQL backends.
Cassandra has a concept of contact points that can be used to
recovery and causes the server to exit immediately upon detecting the
loss of connectivity. The default value for Cassandra is 2000 ms.
- **Note**
+.. note::
Automatic reconnection to database backends is configured
individually per backend. This allows users to tailor the recovery
operate in "read-write" mode, which is also the default configuration if
the parameter is not specified.
- **Note**
+.. note::
The ``readonly`` parameter is currently only supported for MySQL and
PostgreSQL databases.
unexpected consequences. The only remedy for this issue at present is to
manually specify a unique identifier for each subnet.
- **Note**
+.. note::
Subnet IDs must be greater than zero and less than 4294967295.
..
- **Note**
+.. note::
The value for the setting of the "data" element is split across two
lines in this example for clarity; when entering the command, the
The new option content is one IPv6 address followed by one or more 16-
bit unsigned integers.
- **Note**
+ .. note::
In general, boolean values are specified as ``true`` or ``false``,
without quotes. Some specific boolean parameters may accept also
..
- **Note**
+ .. note::
In the event that both explicit values are specified and
calculate-tee-times is true, the server will use the explicit values.
evaluated for each packet. If the result is "true", the packet is a
member of the class.
- **Note**
+ .. note::
Care should be taken with client classification, as it is easy for
clients that do not meet class criteria to be denied all service.
influence this decision. It assumes that the ``enable-updates``
parameter is true.
- **Note**
+ .. note::
Currently the interface between kea-dhcp6 and D2 only supports
requests which update DNS entries for a single IP address. If a lease
..
- **Note**
+ .. note::
Note that in early versions of Kea, this parameter was a boolean and
permitted only values of ``true`` and ``false``.
name supplied by the client, and it is performed before applying a
qualifying suffix (if one is defined and needed).
- **Note**
+ .. note::
The following are some considerations to keep in mind:
Name sanitizing is meant to catch the more common cases of invalid
configuration of the DHCPv6 side (the DHCPv4 side is described in
:ref:`dhcp4-dhcp4o6-config`).
- **Note**
+ .. note::
DHCPv4-over-DHCPv6 support is experimental and the details of the
inter-process communication may change; both the DHCPv4 and DHCPv6
..
- **Note**
+ .. note::
Relayed DHCPv4-QUERY DHCPv6 messages are not supported.
to reserve hostnames for clients which may move from one subnet to
another.
- **Note**
+ .. note::
Global reservations, while useful in certain circumstances, have aspects
that must be given due consideration when using them, please see
out-of-pool reservations. If the reserved address does not belong to a
pool, there is no way that other clients can get it.
- **Note**
+ .. note::
The conflict-resolution mechanism does not work for global
reservations. Although the global address reservations feature may be useful
class is added to the packet and any class depending on it (directly or
indirectly) and not only-if-required is evaluated.
- **Note**
+ .. note::
To force the evaluation of a class expression after the
host reservation lookup, for instance because of a dependency on
provides some examples of how to conduct common host reservations
operations.
- **Note**
+ .. note::
In Kea, the maximum length of an option specified per-host is
arbitrarily set to 4096 bytes.
when the client provides a hint that belongs to another subnet, or the client has
reservations in a subnet other than the default.
- **Note**
+ .. note::
Deployments should not assume that Kea waits until it has allocated
all the addresses from the first subnet in a shared network before
replaces any existing DUID in the file. The server then uses the new
server identifier in all future interactions with the clients.
- **Note**
+ .. note::
If the new server identifier is created after some clients have
obtained their leases, the clients using the old identifier are not
If "relay" is specified, the "ip-addresses" parameter within it is
mandatory.
- **Note**
+ .. note::
The current version of Kea uses the "ip-addresses" parameter, which
supports specifying a list of addresses.
Statistics in the DHCPv6 Server
===============================
- **Note**
+ .. note::
This section describes DHCPv6-specific statistics. For a general
overview and usage of statistics, see :ref:`stats`.
and ISC cannot guarantee its proper operation. If you decide to use it,
please do so with care.
- **Note**
+ .. note::
Use of this tool is completely optional. Everything it does can be
done manually.
The basic scope can be extended by: mysql, pgsql, cql, native-pkg,
radius, shell, and forge.
- **Note**
+ .. note::
To build Kea locally, Hammer dependencies like Vagrant are
not needed.
..
- **Note**
+ .. note::
ccache is currently only supported for LXC in Hammer; support
for VirtualBox may be added later.
The ``cb_cmds`` library is only available to ISC customers with a paid
support contract.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
will use the first backend listed in the ``config-control`` map within
the configuration of the server receiving the command.
- **Note**
+.. note::
As of the Kea 1.6.0 release, it is possible to configure the Kea server
to use only one configuration backend. Strictly speaking, it is
values for unspecified parameters or, if the global values are not
specified, the default values will be used.
- **Note**
+.. note::
As with other "set" commands, this command replaces all the
information about the given shared network in the database, if the
The ``shared-network-name`` parameter is mandatory for the
``remote-subnet4-set`` command.
- **Note**
+.. note::
As with other "set" commands, this command replaces all the
information about the particular subnet in the database, if the
servers. Using these commands it is possible to add, update, delete, and
list client classes configured for a given server.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
This library was previously only available to ISC's paid subscribers,
but is now part of the open source Kea, available to all users.
- **Note**
+ .. note::
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
..
- **Note**
+ .. note::
Currently, restarting the HA service from the ``terminated`` state
requires restarting the DHCP server or reloading its configuration.
``terminated`` states because the server never transitions out of these
states anyway.
- **Note**
+ .. note::
In the ``syncing`` state the server is paused before it makes an
attempt to synchronize the lease database with a partner. To pause
..
- **Note**
+ .. note::
The state of the HA state machine depends on the state of the
cooperating server. Therefore, it must be taken into account that
caching, i.e. the ability to remember that there is no client
information in the database.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
provides a non-programmatic way to manage user contexts associated with
leases.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or the
``kea-dhcp6`` process.
..
- **Warning**
+.. warning::
The ``lease4-get-all`` and ``lease6-get-all`` commands may result in
very large responses. This may have a negative impact on the DHCP
DHCP server to talk to RADIUS directly. That is the goal this library
intends to fulfill.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or the
``kea-dhcp6`` process.
of subnets. Finally, this library was constructed to provide commands
for retrieving these statistics.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
Installing Hook Packages
========================
- **Note**
+.. note::
For more details about installing the Kea Premium Hooks package, please read
`this Knowledgebase article <https://kb.isc.org/docs/aa-01587>`__.
..
- **Note**
+.. 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**
+.. note:
In all versions of Kea since 1.1.0, libraries
are reloaded even if their lists have not changed,
- An empty list has the same effect as omitting the ``hooks-libraries``
configuration element altogether.
- **Note**
+ .. 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
to a subset of Kea users. To this end, ISC has created some hooks
libraries, discussed in the following sections.
- **Note**
+.. note::
Some of these libraries are available with the base code, while
others will be shared with organizations supporting development of
from ISC does not work as expected, please make sure that it has been
loaded by the correct process per the table below.
- **Warning**
+.. 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
their details are added to the known clients file and they get a proper
address after their device is restarted.
- **Note**
+.. note::
This library was developed several years before the host reservation
mechanism became available. Host reservation is much
Currently this library is only
available to ISC customers with a paid support contract.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
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**
+.. note::
When running Kea servers for both DHCPv4 and DHCPv6, the log names
must be distinct. See the examples in :ref:`forensic-log-configuration`.
Currently this library is only available to ISC customers with a paid support
contract.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
]
}
-Note that 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.
+.. 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
Currently this library is only available to ISC customers with a paid support
contract.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
empty, the count is 0, no next map is present, and result status 3 (empty) is
returned.
- **Note**
+.. 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
"text": "72 IPv4 host(s) found."
}
-Note that the from and source-index fields were specified in the response in
+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:
small deployments with few reservations, it is easier to use
``reservation-get-all`` (see :ref:`command-reservation-get-all`.
- **Note**
+.. note::
Currently ``reservation-get-page`` is not supported by the Cassandra
host backend.
Currently this library is only available to ISC customers with a paid support
contract.
- **Note**
+.. note::
This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
process.
approaches can be mixed only if the administrator understands how internal
automatic subnet-id generation works in Kea.
- **Note**
+.. note::
Subnet IDs must be greater than zero and less than 4294967295.
regarding syntax, see :ref:`shared-network4` and
:ref:`shared-network6`.
- **Note**
+.. note::
As opposed to parameter inheritance during the processing of a full new
configuration, this command does not fully handle parameter inheritance.
The ``network6-subnet-add`` command uses exactly the same syntax for
both the command and the response.
- **Note**
+.. note::
As opposed to parameter inheritance during the processing of a full new
configuration or when adding a new shared network with new subnets,
-.. _installation:
+.. note::.. _installation:
************
Installation
:ref:`required-software`), building Kea from source code requires
various development include headers and program development tools.
- **Note**
+.. note::
Some operating systems have split their distribution packages into a
run-time and a development package. You will need to install the
or advanced users. Using development code in a production environment is
not recommended.
- **Note**
+.. note::
When building from source code retrieved via git, additional software
will be required: automake (v1.11 or later), libtoolize, and autoconf
..
- **Note**
+.. note::
For instructions concerning the installation and configuration of
database backends for Kea, see :ref:`dhcp-install-configure`.
make's ``-j`` option) when performing this step; doing so may cause
errors.
- **Note**
+.. note::
The install step may require superuser privileges.
..
- **Note**
+.. note::
If you do not run ``ldconfig`` where it is required, you may see
errors like the following:
is built. This section covers the building of Kea with one of the
optional backends and the creation of the lease database.
- **Note**
+.. note::
When unit tests are built with Kea (i.e. the --with-gtest configuration
option is specified), the databases must be manually pre-configured
..
- **Note**
+ .. note::
In the example above, strings of the form @something@ are replaced by
the appropriate values when Kea is installed.
Kea configuration file. If no logging configuration is specified, the
default settings will be used.
- **Note**
+ .. note::
The verbosity for the server is set when it is started. Once started,
the verbosity can be only changed by stopping the server and starting
..
- **Note**
+ .. note::
NETCONF is an optional feature that is disabled by default and can be
enabled during compilation. If Kea was compiled without NETCONF
the keactrl.conf file, but NETCONF status will not be shown and other
commands will ignore it.
- **Note**
+ .. note::
Currently ``keactrl`` does not report configuration failures when the
server is started or reconfigured. To check if the server's
severity may also be set to NONE, in which case all messages from that
logger are inhibited.
- **Note**
+ .. note::
The ``keactrl`` tool, described in :ref:`keactrl`, can be configured
to start the servers in verbose mode. If this is the case, the
specified without disabling rotation is 204800. Any value less than
this, including 0, disables rotation.
- **Note**
+ .. note::
Due to a limitation of the underlying logging library (log4cplus),
rolling over the log files (from ".1" to ".2", etc) may show odd
will no longer be reported. Please note that the server code may add
it back if there is a reason to record it.
- **Note**
+.. note::
The following sections describe commands that can be sent to the
server; the examples are not fragments of a configuration file. For
projects / thirdparty / kea.git / commitdiff
