..
- .. 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
than one appear. For the vendor.enterprise and vendor-class.enterprise
expressions, the value from the first instance is returned. Please
submit a feature request on the
- `Kea GitLab site <https://gitlab.isc.org/isc-projects/kea>`__ if you need
+ `Kea GitLab site <https://gitlab.isc.org/isc-projects/kea>`__ to request
support for multiple instances.
.. table:: List of Classification Expressions
..
- .. 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
assigned to members of this class.
The option definition is for DHCPv4 option 43
-(:ref:`dhcp4-vendor-opts` and DHCPv4 private options
+(:ref:`dhcp4-vendor-opts`) and DHCPv4 private options
(:ref:`dhcp4-private-opts`).
Usually the test expression is evaluated before subnet selection, but in
::
- 2016-05-19 13:35:04.163 DEBUG [kea.eval/44478] EVAL_DEBUG_OPTION Pushing option 61 with value 0x666F6F626172
- 2016-05-19 13:35:04.164 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '0'
- 2016-05-19 13:35:04.165 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '3'
- 2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F
- 2016-05-19 13:35:04.167 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string 'foo'
- 2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true'
+ 2016-05-19 13:35:04.163 DEBUG [kea.eval/44478] EVAL_DEBUG_OPTION Pushing option 61 with value 0x666F6F626172
+ 2016-05-19 13:35:04.164 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '0'
+ 2016-05-19 13:35:04.165 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string '3'
+ 2016-05-19 13:35:04.166 DEBUG [kea.eval/44478] EVAL_DEBUG_SUBSTRING Popping length 3, start 0, string 0x666F6F626172 pushing result 0x666F6F
+ 2016-05-19 13:35:04.167 DEBUG [kea.eval/44478] EVAL_DEBUG_STRING Pushing text string 'foo'
+ 2016-05-19 13:35:04.168 DEBUG [kea.eval/44478] EVAL_DEBUG_EQUAL Popping 0x666F6F and 0x666F6F pushing result 'true'
..
- .. 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
Congestion Handling in DHCPv4 and DHCPv6
****************************************
-.. _congeston-handling-background:
+.. _congestion-handling-background:
What is Congestion?
===================
the packets waiting in the FIFO socket buffers became increasingly
stale.
-.. _congeston-handling-solution:
+.. _congestion-handling-solution:
Configuring Congestion Handling
===============================
implementation via a hook library. This should make it straightforward
for interested parties to experiment with their own solutions.
(Developers can refer to isc::dhcp::PacketQueue and
-isc::dhcp::PacketQueueMgr, described in the Kea Developer's Guide).
+isc::dhcp::PacketQueueMgr, described in the
+`Kea Developer's Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/index.html>`__.)
Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6
servers through an optional, top-level, configuration element,
for NCRs based on that configuration.
During startup, the server will attempt to create a PID file of the form:
-[localstatedir]/[conf name].kea-dhcp-ddns.pid where:
+[**localstatedir**]/[**conf name**].kea-dhcp-ddns.pid where:
- ``localstatedir`` - is the value as passed into the build configure
script; it defaults to "/usr/local/var". Note that this value may be
steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain has
the following parameters:
-- ``name`` - the fully qualified reverse zone that this DDNS Domain can
+- ``name`` - the fully qualified reverse zone that this DDNS domain can
update. This is the value used during reverse matching, which will
compare it with a reversed version of the request's lease address.
The zone name should follow the appropriate standards; for example,
requires root access. This daemon must be run as root.
During startup, the server will attempt to create a PID file of the
-form: localstatedir]/[conf name].kea-dhcp6.pid where:
+form: [**localstatedir**]/[**conf name**].kea-dhcp6.pid where:
- ``localstatedir``: The value as passed into the build configure
script; it defaults to "/usr/local/var". Note that this value may be
Next, the name of the database to hold the reservations must be set;
this is the name used when the lease database was created (see
-`:ref:`supported-databases` for instructions on how to set up the
+:ref:`supported-databases` for instructions on how to set up the
desired database type):
::
...
}
-The new option content is one IPv6 address followed by one or more 16-
-bit unsigned integers.
+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``.
When qualifying a partial name, kea-dhcp6 will construct the name in the
format:
-[candidate-name].[qualifying-suffix].
+[**candidate-name**].[**qualifying-suffix**].
-where candidate-name is the partial name supplied in the DHCPREQUEST.
+where **candidate-name** is the partial name supplied in the DHCPREQUEST.
For example, if the FQDN domain name value is "some-computer" and the
qualifying-suffix "example.com", the generated FQDN is:
-some-computer.example.com.
+**some-computer.example.com.**
When generating the entire name, kea-dhcp6 will construct the name in
the format:
-[generated-prefix]-[address-text].[qualifying-suffix].
+[**generated-prefix**]-[**address-text**].[**qualifying-suffix**].
-where address-text is simply the lease IP address converted to a
+where **address-text** is simply the lease IP address converted to a
hyphenated string. For example, if the lease address is 3001:1::70E, the
qualifying suffix "example.com", and the default value is used for
``generated-prefix``, the generated FQDN is:
-myhost-3001-1--70E.example.com.
+**myhost-3001-1--70E.example.com.**
.. _host-name-sanitization:
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
+ that must be given due consideration. Please see
:ref:`reservation6-conflict` for more details.
.. _reservation6-conflict:
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`.
- *Dynamic Host Configuration Protocol for IPv6 (DHCPv6)*, `RFC
8415 <https://tools.ietf.org/html/rfc8415>`__: New DHCPv6 protocol
specification which obsoletes RFC 3315, RFC 3633, RFC 3736, RFC 4242,
- RFC 7083, RFC 7283, and RFC 7550
+ RFC 7083, RFC 7283, and RFC 7550.
.. _dhcp6-limit:
"text": "Class 'ipxe_efi_x64' deleted."
}
-If the class doesn't exist, the result of 3 is returned.
+If the class does not exist, the result of 3 is returned.
.. _command-class-list:
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.
The scope names can be used to associate pools, subnets, and networks
with certain servers, so only these servers can allocate addresses or
prefixes from those pools, subnets, or networks. This is done via the
-client classification mechanism (see below).
+client classification mechanism (see :ref:`ha-load-balancing-advanced-config`
+for more details).
.. _ha-scope-transition:
}]
}
-Two hook libraries must be loaded to enable HA:
+Two hooks libraries must be loaded to enable HA:
``libdhcp_lease_cmds.so`` and ``libdhcp_ha.so``. The latter implements
the HA feature, while the former enables control commands required by HA
to fetch and manipulate leases on the remote servers. In the example
provided above, it is assumed that Kea libraries are installed in the
``/usr/lib`` directory. If Kea is not installed in the /usr directory,
-the hook libraries locations must be updated accordingly.
+the hooks libraries locations must be updated accordingly.
The HA configuration is specified within the scope of ``libdhcp_ha.so``.
Note that the top-level parameter ``high-availability`` is a list, even
.. _ha-syncing-timeouts:
-Discussion About Timeouts
--------------------------
+Timeouts
+--------
In deployments with a large number of clients connected to the network,
lease-database synchronization after a server failure may be a
.. _ha-pause-state-machine:
-Pausing HA State Machine
-------------------------
+Pausing the HA State Machine
+----------------------------
-The high availability state machine includes many different states
+The high-availability state machine includes many different states
described in detail in :ref:`ha-server-states`. The server
enters each state when certain conditions are met, most often taking
into account the partner server's state. In some states the server
``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
}
} ]
-Once loaded, the Host Cache hook library provides a number of new
+Once loaded, the Host Cache hooks library provides a number of new
commands which can be used either over the control channel (see
:ref:`ctrl-channel-client`) or the RESTful API (see
:ref:`agent-overview`). An example RESTful API client is described in
This command will remove 1000 hosts. To delete all cached
hosts, please use cache-clear instead. The hosts are stored in FIFO
-order, so the oldest entries are always removed.
+(first-in, first-out) order, so the oldest entries are always removed.
.. _command-cache-clear:
radius: RADIUS Server Support
=============================
-The RADIUS hook library allows Kea to interact with two types of RADIUS
+The RADIUS hooks library allows Kea to interact with two types of RADIUS
servers: access and accounting. Although the most common DHCP and RADIUS
integration is done on the DHCP relay-agent level (DHCP clients send
DHCP packets to DHCP relays; those relays contact the RADIUS server and
later when sending accounting messages.
This mechanism is implemented based on user context in host
-reservations. (See :ref:`user-context` for details about user
-context). The host cache mechanism allows the information retrieved by
+reservations. (See :ref:`user-context` for details.)
+The host cache mechanism allows the information retrieved by
RADIUS to be stored and later used for sending accounting and access
queries to the RADIUS server. In other words, the host-cache mechanism
is mandatory, unless administrators do not want RADIUS communication for messages
requires extra switches for FreeRADIUS. Please consult later sections of
this chapter for details.
-6. Rebuild Kea
+6. Rebuild Kea.
::
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
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
+"client-id". The lease_cmds library does not 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
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`.
+``reservation-get-all`` (see :ref:`command-reservation-get-all`).
.. note::
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
+because the server does not 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
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
+because the server does not 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
`Google <https://www.google.com/>`__, `RIPE
NCC <https://www.ripe.net/>`__, `Registro.br <https://registro.br/>`__,
`.nz Registry Services <https://nzrs.net.nz/>`__, and `Technical Center
-of Internet <https://www.tcinet.ru/>`__ .
+of Internet <https://www.tcinet.ru/>`__.
.. |image0| image:: kea-logo-100x70.png
| c1 | | c2 | |c3| | c4 |
- |<---->|<---------->|<-->|<---------->|<>|<---------->|<-->|
- ---------------------------------------------------------------->
+ |<---->|<---------->|<-->|<---------->|<>|<---------->|<-->|<--
+ ------------------------------------------------------------------>
| | 5s | | 5s | | 5s | | time
This diagram shows four lease-reclamation cycles (c1 through c4) of
.. _leases-reclamation-using-command:
-Reclaiming Expired Leases with Command
-======================================
+Reclaiming Expired Leases via Command
+=====================================
-The *leases-reclaim* command can be used to trigger lease reclamation at
+The ``leases-reclaim`` command can be used to trigger lease reclamation at
any time. Please consult the :ref:`command-leases-reclaim` section
for details about using this command.
projects / thirdparty / kea.git / commitdiff
