Commit edfeb3f4 authored by Suzanne Goldlust's avatar Suzanne Goldlust Committed by Michal Nowikowski
Browse files

Converting from docbook to sphinx: fixing links, making content/grammar edits as needed

parent ce223933
This diff is collapsed.
......@@ -10,9 +10,9 @@ What is Congestion?
===================
Congestion occurs when servers are subjected to client queries faster
than they can be processed. As a result, the servers begin accumulating
than those queries can be processed. As a result, the servers begin accumulating
a backlog of pending queries. The longer the high rate of traffic
continues the farther behind the servers fall. Depending on the client
continues, the farther behind the servers fall. Depending on the client
implementations, those that fail to get leases either give up or simply
continue to retry forever. In the former case, the server may eventually
recover, but the latter case is a vicious cycle from which the server is
......@@ -30,12 +30,12 @@ The goal of congestion handling is to help servers mitigate the peak in
traffic by fulfilling as many of the most relevant requests as possible
until the congestion subsides.
Prior to Kea 1.5, kea-dhcp4 and kea-dhcp4 read inbound packets directly
Prior to Kea 1.5, kea-dhcp4 and kea-dhcp6 read inbound packets directly
from the interface sockets in the main application thread, which meant
that packets waiting to be processed were held in socket buffers
themselves. Once these buffers filled, any new packets were discarded.
Under swamped conditions, the servers ended up processing client packets
that were no longer relevant, or worse were redundant. In other words,
that were no longer relevant, or worse, were redundant. In other words,
the packets waiting in the FIFO socket buffers became increasingly
stale.
......@@ -54,15 +54,15 @@ configurable layer has been introduced which can make decisions on which
packets to process, how to store them, and the order in which they are
processed by the server.
The default packet queue implemenation for both kea-dhcp4 and kea-dhcp6
The default packet queue implementation for both kea-dhcp4 and kea-dhcp6
is a simple ring buffer. Once it reaches capacity, new packets get added
to the back of the queue by discarding packets from the front of the
queue. Rather than always discarding the newest packets, Kea now always
discards the oldest packets. The capacity of the buffer, i.e the maximum
number of packets the buffer can contain, is configurable. A reasonable
starting point would be to match the capacity to the number of leases
per second your installation of Kea can handle. Please note that this
figure varies widely depending on the specifics of your deployment.
per second a specific installation of Kea can handle. Please note that this
figure varies widely depending on the specifics of an individual deployment.
As there is no one algorithm that will best handle the dynamics of all
sites, and because over time new approaches will evolve, the packet
......@@ -74,7 +74,7 @@ isc::dhcp::PacketQueueMgr, described in the Kea Developer's Guide).
Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6
servers through an optional, top-level, configuration element,
'dhcp-queue-control'. Omitting this element disables packet queueing:
``dhcp-queue-control``. Omitting this element disables packet queueing:
::
......@@ -86,19 +86,19 @@ servers through an optional, top-level, configuration element,
where:
- ``enable-queue`` true|false. Enables or disables packet queueing.
- ``enable-queue`` true|false - enables or disables packet queueing.
When true, the server processes packets from the packet queue, which
is filled by a separate thread. When false, the server processes
packets directly from the socket buffers in the main thread. It is
disabled by default.
- ``queue-type`` name of the queue implementation to use. This value
exists so that custom implementations can be registered (via hook
- ``queue-type`` - name of the queue implementation to use. This value
exists so that custom implementations can be registered (via a hook
library) and then selected. There is a default packet queue
implementation that is pre-registered during server start up:
"kea-ring4" for kea-dhcp4 and "kea-ring6" for kea-dhcp6.
- ``capacity`` = n [packets]. This is the maximum number of packets the
- ``capacity`` = n [packets] - this is the maximum number of packets the
queue can hold before packets are discarded. The optimal value for
this is extremely site-dependent. The default value is 500 for both
kea-ring4 and kea-ring6.
......
......@@ -11,9 +11,9 @@ Overview
The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts
the client side of the Dynamic DNS protocol (DDNS, defined in `RFC
2136 <http://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4
2136 <https://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4
and DHCPv6 servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP
servers construct DDNS update requests, known as NameChangeRequests
servers construct DDNS update requests, known as Name Change Requests
(NCRs), based on DHCP lease change events and then post them to D2. D2
attempts to match each request to the appropriate DNS server(s) and
carries out the necessary conversation with those servers to update the
......@@ -31,7 +31,7 @@ are referred to as DDNS Domain Lists. Each list consists of one or more
named DDNS Domains. Further, each DDNS Domain has a list of one or more
DNS servers that publish the DNS data for that domain.
When conducting forward domain matching, D2 compares the fully-qualified
When conducting forward domain matching, D2 compares the fully qualified
domain name (FQDN) in the request against the name of each Forward DDNS
Domain in its catalog. The domain whose name matches the longest portion
of the FQDN is considered the best match. For example, if the FQDN is
......@@ -52,8 +52,8 @@ in the catalog, "1.16.172.in-addr.arpa." and "16.172.in-addr.arpa", the
former is the best match. As with forward matching, it may not find a
suitable match. Given the same two domains, there would be no match for
the lease address, "192.168.1.50", and the request would be rejected.
Finally, if there are no Reverse DDNS Domains defined, D2 will simply
disregard the reverse update portion of requests.
Finally, if there are no Reverse DDNS Domains defined, D2 simply
disregards the reverse update portion of requests.
.. _dhcp-ddns-conflict-resolution:
......@@ -61,7 +61,7 @@ Conflict Resolution
-------------------
D2 implements the conflict resolution strategy prescribed by `RFC
4703 <http://tools.ietf.org/html/rfc4703>`__. Conflict resolution is
4703 <https://tools.ietf.org/html/rfc4703>`__. Conflict resolution is
intended to prevent different clients from mapping to the same FQDN at
the same time. To make this possible, the RFC requires that forward DNS
entries for a given FQDN must be accompanied by a DHCID resource record
......@@ -82,14 +82,14 @@ Dual-Stack Environments
-----------------------
`RFC 4703, section
5.2, <http://tools.ietf.org/html/rfc4703#section-5.2>`__ describes
5.2, <https://tools.ietf.org/html/rfc4703#section-5.2>`__ describes
issues that may arise with dual-stack clients. These are clients that
wish to have have both IPv4 and IPv6 mappings for the same FQDN. For
this to work properly, the clients are required to embed their IPv6 DUID
within their IPv4 client identifier option as described in `RFC
4703 <http://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates
for both IPv4 and IPv6 can be managed under the same DHCID RR. Support
for this does not yet exist in Kea.
within their IPv4 client identifier option, as described in `RFC
4703 <https://tools.ietf.org/html/rfc4361>`__. In this way, DNS updates
for both IPv4 and IPv6 can be managed under the same DHCID RR. Kea does not
currently support this feature.
.. _dhcp-ddns-server-start-stop:
......@@ -99,7 +99,7 @@ Starting and Stopping the DHCP-DDNS Server
``kea-dhcp-ddns`` is the Kea DHCP-DDNS server and, due to the nature of
DDNS, it runs alongside either the DHCPv4 or DHCPv6 component (or both).
Like other parts of Kea, it is a separate binary that can be run on its
own or through ``keactrl`` (see `??? <#keactrl>`__). In normal
own or through ``keactrl`` (see :ref:`keactrl`). In normal
operation, controlling ``kea-dhcp-ddns`` with ``keactrl`` is
recommended; however, it is also possible to run the DHCP-DDNS server
directly. It accepts the following command-line switches:
......@@ -120,7 +120,7 @@ directly. It accepts the following command-line switches:
is a copy of the ``config.report`` file produced by ``./configure``;
it is embedded in the executable binary.
- ``-t file`` specifies the configuration file to be tested.
- ``-t file`` - specifies the configuration file to be tested.
Kea-dhcp-ddns will attempt to load it and will conduct sanity checks.
Note that certain checks are possible only while running the actual
server. The actual status is reported with an exit code (0 =
......@@ -137,18 +137,18 @@ example: ``kea/src/bin/d2/.libs/kea-dhcp-ddns``.
strings path/kea-dhcp-ddns | sed -n 's/;;;; //p'
Upon startup the module will load its configuration and begin listening
Upon startup, the module will load its configuration and begin listening
for NCRs based on that configuration.
During startup the server will attempt to create a PID file of the form:
During startup, the server will attempt to create a PID file of the form:
[localstatedir]/[conf name].kea-dhcp-ddns.pid where:
- ``localstatedir``: The value as passed into the build configure
- ``localstatedir`` - is the value as passed into the build configure
script; it defaults to "/usr/local/var". Note that this value may be
overridden at runtime by setting the environment variable
KEA_PIDFILE_DIR. This is intended primarily for testing purposes.
- ``conf name``: The configuration file name used to start the server,
- ``conf name`` - is the configuration file name used to start the server,
minus all preceding paths and the file extension. For example, given
a pathname of "/usr/local/etc/kea/myconf.txt", the portion used would
be "myconf".
......@@ -164,9 +164,9 @@ such a case it is necessary to manually delete the PID file.
Configuring the DHCP-DDNS Server
================================
Before starting ``kea-dhcp-ddns`` module for the first time, a
Before starting the ``kea-dhcp-ddns`` module for the first time, a
configuration file must be created. The following default configuration
is a template that can be customized to your requirements.
is a template that can be customized to individual requirements.
::
......@@ -188,7 +188,7 @@ is a template that can be customized to your requirements.
The configuration can be divided into the following sections, each of
which is described below:
- *Global Server Parameters* - values which control connectivity and
- *Global Server Parameters* - define values which control connectivity and
global server behavior.
- *Control Socket* - defines the Control Socket type and name.
......@@ -205,21 +205,21 @@ which is described below:
Global Server Parameters
------------------------
- ``ip-address`` - IP address on which D2 listens for requests. The
default is the local loopback interface at address 127.0.0.1. You may
specify either an IPv4 or IPv6 address.
- ``ip-address`` - the IP address on which D2 listens for requests. The
default is the local loopback interface at address 127.0.0.1.
Either an IPv4 or IPv6 address may be specified.
- ``port`` - Port on which D2 listens for requests. The default value
- ``port`` - the port on which D2 listens for requests. The default value
is 53001.
- ``dns-server-timeout`` - Maximum amount of time, in milliseconds,
- ``dns-server-timeout`` - the maximum amount of time, in milliseconds,
that D2 will wait for a response from a DNS server to a single DNS
update message.
- ``ncr-protocol`` - Socket protocol to use when sending requests to
- ``ncr-protocol`` - the socket protocol to use when sending requests to
D2. Currently only UDP is supported.
- ``ncr-format`` - Packet format to use when sending requests to D2.
- ``ncr-format`` - the packet format to use when sending requests to D2.
Currently only JSON format is supported.
D2 must listen for change requests on a known address and port. By
......@@ -243,7 +243,7 @@ illustrates how to change D2's global parameters so it will listen at
It is possible for a malicious attacker to send bogus
NameChangeRequests to the DHCP-DDNS server. Addresses other than the
IPv4 or IPv6 loopback addresses (127.0.0.1 or ::1) should only be
used for testing purposes, but note that local users may still
used for testing purposes; note that local users may still
communicate with the DHCP-DDNS server.
**Note**
......@@ -258,9 +258,9 @@ Management API for the D2 Server
The management API allows the issuing of specific management commands,
such as configuration retrieval or shutdown. For more details, see
`??? <#ctrl-channel>`__. Currently the only supported communication
:ref:`ctrl-channel`. Currently, the only supported communication
channel type is UNIX stream socket. By default there are no sockets
open. To instruct Kea to open a socket, the following entry in the
open; to instruct Kea to open a socket, the following entry in the
configuration file can be used:
::
......@@ -274,15 +274,16 @@ configuration file can be used:
}
The length of the path specified by the ``socket-name`` parameter is
restricted by the maximum length for the unix socket name on your
restricted by the maximum length for the UNIX socket name on the
operating system, i.e. the size of the ``sun_path`` field in the
``sockaddr_un`` structure, decreased by 1. This value varies on
different operating systems between 91 and 107 characters. Typical
values are 107 on Linux and 103 on FreeBSD.
Communication over control channel is conducted using JSON structures.
See the Control Channel section in the Kea Developer's Guide for more
details.
Communication over the control channel is conducted using JSON structures.
See the `Control Channel section in the Kea Developer's
Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/d2/d96/ctrlSocket.html>`__
for more details.
The D2 server supports the following operational commands:
......@@ -302,15 +303,15 @@ TSIG Key List
-------------
A DDNS protocol exchange can be conducted with or without TSIG (defined
in `RFC 2845 <http://tools.ietf/org/html/rfc2845>`__). This
in `RFC 2845 <https://tools.ietf/org/html/rfc2845>`__). This
configuration section allows the administrator to define the set of TSIG
keys that may be used in such exchanges.
To use TSIG when updating entries in a DNS Domain, a key must be defined
in the TSIG Key List and referenced by name in that domain's
To use TSIG when updating entries in a DNS domain, a key must be defined
in the TSIG Key list and referenced by name in that domain's
configuration entry. When D2 matches a change request to a domain, it
checks whether the domain has a TSIG key associated with it. If so, D2
will use that key to sign DNS update messages sent to and verify
uses that key to sign DNS update messages sent to and verify
responses received from the domain's DNS server(s). For each TSIG key
required by the DNS servers that D2 will be working with, there must be
a corresponding TSIG key in the TSIG Key list.
......@@ -320,7 +321,7 @@ configuration lists the TSIG keys. Each entry describes a TSIG key used
by one or more DNS servers to authenticate requests and sign responses.
Every entry in the list has three parameters:
- ``name`` - a unique text label used to identify this key within the
- ``name`` - is a unique text label used to identify this key within the
list. This value is used to specify which key (if any) should be used
when updating a specific domain. As long as the name is unique its
content is arbitrary, although for clarity and ease of maintenance it
......@@ -418,10 +419,10 @@ Adding Forward DDNS Domains
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A Forward DDNS Domain maps a forward DNS zone to a set of DNS servers
which maintain the forward DNS data (i.e. name-to- address mapping) for
which maintain the forward DNS data (i.e. name-to-address mapping) for
that zone. Each zone served needs one Forward DDNS Domain. It may very
well be that some or all of the zones are maintained by the same
servers, but you will still need one DDNS Domain per zone. Remember that
servers, but one DDNS Domain is still needed for each zone. Remember that
matching a request to the appropriate server(s) is done by zone and a
DDNS Domain only defines a single zone.
......@@ -434,7 +435,7 @@ the following parameters:
during forward matching. It must be unique within the catalog.
- ``key-name`` - if TSIG is used with this domain's servers, this value
should be the name of the key from within the TSIG Key List. If the
should be the name of the key from the TSIG Key list. If the
value is blank (the default), TSIG will not be used in DDNS
conversations with this domain's servers.
......@@ -443,8 +444,8 @@ the following parameters:
used in a first-to-last preference; in other words, when D2 begins to
process a request for this domain, it will pick the first server in
this list and attempt to communicate with it. If that attempt fails,
it will move to next one in the list and so on until either it
achieves success or the list is exhausted.
D2 will move to next one in the list and so on until either it
is successful or the list is exhausted.
To create a new Forward DDNS Domain, add a new domain element and set
its parameters:
......@@ -466,7 +467,7 @@ its parameters:
It is possible to add a domain without any servers; however, if that
domain matches a request, the request will fail. To make the domain
useful, we must add at least one DNS server to it.
useful, at least one DNS server must be added to it.
.. _add-forward-dns-servers:
......@@ -489,9 +490,9 @@ following parameters:
- ``port`` - the port on which the server listens for DDNS requests. It
defaults to the standard DNS service port of 53.
To create a new forward DNS Server, one must add a new server element to
the domain and fill in its parameters. If, for example, the service is
running at "172.88.99.10", then set the forward DNS Server as follows:
To create a new Forward DNS Server, a new server element must be added to
the domain and its parameters filled in. If, for example, the service is
running at "172.88.99.10", set the Forward DNS Server as follows:
::
......@@ -551,7 +552,7 @@ A Reverse DDNS Domain maps a reverse DNS zone to a set of DNS servers
which maintain the reverse DNS data (address-to-name mapping) for that
zone. Each zone served needs one Reverse DDNS Domain. It may very well
be that some or all of the zones are maintained by the same servers, but
you will still need one DDNS Domain entry for each zone. Remember that
one DDNS Domain entry is still needed for each zone. Remember that
matching a request to the appropriate server(s) is done by zone and a
DDNS Domain only defines a single zone.
......@@ -568,8 +569,8 @@ the following parameters:
2001:db8:1, the name should be "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa."
Whatever the name, it must be unique within the catalog.
- ``key-name`` - if TSIG should be used with this domain's servers,
this value should be the name of that key from the TSIG Key List. If
- ``key-name`` - if TSIG is used with this domain's servers,
this value should be the name of the key from the TSIG Key List. If
the value is blank (the default), TSIG will not be used in DDNS
conversations with this domain's servers. Currently this value is not
used as TSIG has not been implemented.
......@@ -579,11 +580,11 @@ the following parameters:
servers are used in a first-to-last preference; in other words, when
D2 begins to process a request for this domain, it will pick the
first server in this list and attempt to communicate with it. If that
attempt fails, it will move to the next one in the list and so on
until either it achieves success or the list is exhausted.
attempt fails, D2 will move to the next one in the list and so on
until either it is successful or the list is exhausted.
To create a new Reverse DDNS Domain, one must add a new domain element
and set its parameters. For example, to support subnet 2001:db8:1::, the
To create a new Reverse DDNS Domain, a new domain element must be added
and its parameters set. For example, to support subnet 2001:db8:1::, the
following configuration could be used:
::
......@@ -603,7 +604,7 @@ following configuration could be used:
It is possible to add a domain without any servers; however, if that
domain matches a request, the request will fail. To make the domain
useful, you must add at least one DNS server to it.
useful, at least one DNS server must be added to it.
.. _add-reverse-dns-servers:
......@@ -626,8 +627,8 @@ following parameters:
- ``port`` - the port on which the server listens for DDNS requests. It
defaults to the standard DNS service port of 53.
To create a new reverse DNS Server, one must first add a new server
element to the domain and fill in its parameters. If, for example, the
To create a new reverse DNS Server, a new server
element must be added to the domain and its parameters filled in. If, for example, the
service is running at "172.88.99.10", then set it as follows:
::
......@@ -667,12 +668,12 @@ User Contexts in DDNS
User contexts were designed for hook libraries, which are not yet
supported for DHCP-DDNS server configuration.
User contexts can store arbitrary data as long as it has valid JSON
syntax and its top level element is a map (i.e. the data must be
User contexts can store arbitrary data as long as the file has valid JSON
syntax and the top-level element is a map (i.e. the data must be
enclosed in curly brackets).
User contexts can be specified on global scope, ddns domain, dns server,
tsig key, and loggers. One other useful usage is the ability to store
User contexts can be specified on global scope, DDNS domain, DNS server,
TSIG key, and loggers. One other useful usage is the ability to store
comments or descriptions; the parser translates a "comment" entry into a
user context with the entry, which allows a comment to be attached
inside the configuration itself.
......@@ -688,17 +689,17 @@ domains, each with their own subnet.
.. table:: Our Example Network
+-----------------+-----------------+-----------------+-----------------+
| Domain | Subnet | Forward DNS | Reverse DNS |
| | | Servers | Servers |
+=================+=================+=================+=================+
| four.example.co | 192.0.2.0/24 | 172.16.1.5, | 172.16.1.5, |
| m | | 172.16.2.5 | 172.16.2.5 |
+-----------------+-----------------+-----------------+-----------------+
| six.example.com | 2001:db8:1::/64 | 3001:1::50 | 3001:1::51 |
+-----------------+-----------------+-----------------+-----------------+
| example.com | 192.0.0.0/16 | 172.16.2.5 | 172.16.2.5 |
+-----------------+-----------------+-----------------+-----------------+
+------------------+-----------------+-----------------+-----------------+
| Domain | Subnet | Forward DNS | Reverse DNS |
| | | Servers | Servers |
+==================+=================+=================+=================+
| four.example.com | 192.0.2.0/24 | 172.16.1.5, | 172.16.1.5, |
| | | 172.16.2.5 | 172.16.2.5 |
+------------------+-----------------+-----------------+-----------------+
| six.example.com | 2001:db8:1::/64 | 3001:1::50 | 3001:1::51 |
+------------------+-----------------+-----------------+-----------------+
| example.com | 192.0.0.0/16 | 172.16.2.5 | 172.16.2.5 |
+------------------+-----------------+-----------------+-----------------+
We need to construct three Forward DDNS Domains:
......@@ -814,5 +815,5 @@ DHCP-DDNS Server Limitations
The following are the current limitations of the DHCP-DDNS Server.
- Requests received from the DHCP servers are placed in a queue until
they are processed. Currently, all queued requests are lost when the
they are processed. Currently, all queued requests are lost if the
server shuts down.
......@@ -60,8 +60,8 @@ involves the following steps for each reclaimed lease:
number of reclaimed leases and decreasing the number of assigned
addresses or delegated prefixes.
Please refer to `??? <#dhcp-ddns-server>`__ to see how to configure DNS
updates in Kea, and to `??? <#hooks-libraries>`__ for information about
Please refer to :ref:`dhcp-ddns-server` to see how to configure DNS
updates in Kea, and to :ref:`hooks-libraries` for information about
using hooks libraries.
.. _lease-reclamation-defaults:
......@@ -72,42 +72,42 @@ Lease Reclamation Configuration Parameters
The following list presents all configuration parameters pertaining to
processing expired leases with their default values:
- ``reclaim-timer-wait-time`` - This parameter governs intervals
between completion of previous reclaimation cycle and a start of the
- ``reclaim-timer-wait-time`` - this parameter governs intervals
between the completion of the previous reclaimation cycle and the start of the
next one. Specified in seconds. The default value is 10 [seconds].
- ``flush-reclaimed-timer-wait-time`` - This parameter controls how
often the server initiates lease reclaimation procedure. Expressed in
- ``flush-reclaimed-timer-wait-time`` - this parameter controls how
often the server initiates the lease reclaimation procedure. Expressed in
seconds. The default value is 25 [seconds].
- ``hold-reclaimed-time`` - This parameter governs how long the lease
should be kept after it was reclaimed. This enables lease affinity
- ``hold-reclaimed-time`` - this parameter governs how long the lease
should be kept after it is reclaimed. This enables lease affinity
when set to a non-zero value. Expressed in seconds. The default value
is 3600 [seconds].
- ``max-reclaim-leases`` - This parameter specifies the maximum number
of reclaimed leases that can be processed in one go. Zero means
- ``max-reclaim-leases`` - this parameter specifies the maximum number
of reclaimed leases that can be processed at one time. Zero means
unlimited (i.e. process all reclaimed leases). The default value is
100.
- ``max-reclaim-time`` - This parameter specifies an upper bound of how
long a lease reclaimation procedure can take. Zero means no time
- ``max-reclaim-time`` - this parameter specifies an upper limit to the
length of time a lease reclamation procedure can take. Zero means no time
limit. Expressed in milliseconds. The default value is 250
[milliseconds].
- ``unwarned-reclaim-cycles`` - If lease reclaimation limits are
specifed (``max-reclaim-leases`` and/oor ``max-reclaim-time``), then
- ``unwarned-reclaim-cycles`` - if lease reclamation limits are
specified (``max-reclaim-leases`` and/or ``max-reclaim-time``), then
under certain circumstances the server may not be able to deal with
leases to be reclaimed fast enough. This parameter specifies how many
consecutive clean up cycles must end with remaining leases to be
the leases to be reclaimed fast enough. This parameter specifies how many
consecutive clean-up cycles must end with remaining leases to be
processed before a warning is printed. The default is 5 [cycles].
The parameters are explained in more detail in the rest of this chapter.
The default value for any parameter is used when this parameter is not
explicitly specified in the configuration. Also, the
``expired-leases-processing`` map may be omitted entirely in the
configuration, in which case the default values are used for all
The default value for any parameter is used when the parameter is not
explicitly specified in the configuration. If the
``expired-leases-processing`` map is omitted entirely in the
configuration, the default values are used for all
parameters listed above.
.. _lease-reclaim-config:
......@@ -125,7 +125,7 @@ will be sent once the lease-reclamation cycle is complete.
In deployments where response time is critical, administrators may wish
to minimize the interruptions in service caused by lease reclamation.
Toward this end, Kea provides configuration parameters to control the
To this end, Kea provides configuration parameters to control the
frequency of lease reclamation cycles, the maximum number of leases
processed in a single reclamation cycle, and the maximum amount of time
a single reclamation cycle is allowed to run before being interrupted.
......@@ -165,7 +165,7 @@ the interval between the cycles.
According to the ``reclaim-timer-wait-time``, the server keeps fixed
intervals of five seconds between the end of one cycle and the start of
the next cycle. This guarantees the presence of 5s-long periods during
the next cycle. This guarantees the presence of 5-second-long periods during
which the server remains responsive to DHCP queries and does not perform
lease reclamation. The ``max-reclaim-leases`` and ``max-reclaim-time``
are set to 0, which sets no restriction on the maximum number of leases
......@@ -219,7 +219,7 @@ more than 50ms, and thus is interrupted according to the value of the
``max-reclaim-time``. This results in equal durations of all reclamation
cycles over time. Note that in this example the limitation of the
maximum 100 leases is not reached. This may be the case when database
transactions are slow or callouts in the hook libraries attached to the
transactions or callouts in the hook libraries attached to the
server are slow. Regardless, the chosen values for either the maximum
number of leases or a maximum cycle time strongly depend on the
particular deployment, the lease database backend being used, and any
......@@ -231,7 +231,7 @@ risk that expired leases will accumulate faster than the server can
reclaim them. This should not be a problem if the server is dealing with
a temporary burst of expirations, because it should be able to
eventually deal with them over time. However, if leases expire at a high
rate for a longer period of time, the unreclaimed leases will pile up in
rate for a long period of time, the unreclaimed leases will pile up in
the database. To notify the administrator that the current configuration
does not satisfy the needs for reclamation of expired leases, the server
issues a warning message in the log if it is unable to reclaim all
......@@ -260,18 +260,18 @@ returning client is referred to as "lease affinity."
When lease affinity is enabled (i.e. when ``hold-reclaimed-time`` is
configured to a value greater than zero), the server will still reclaim
leases according to the parameters described in `Configuring Lease
Reclamation <#lease-reclaim-config>`__, but the reclaimed leases will be
held in the database (rather than removed) for a specified amount of
time. When the client returns, the server will first verify whether
leases according to the parameters described in :ref:`lease-reclaim-config`,
but the reclaimed leases will be
held in the database for a specified amount of
time rather than removed. When the client returns, the server will first verify whether
there are any reclaimed leases associated with this client and will
re-assign them if possible. However, it is important to note that any
reclaimed lease may be assigned to another client if that client
specifically asks for it. Therefore, lease affinity does not guarantee
that the reclaimed lease will be available for the client who used it
before; it merely increases the chances for the client to be assigned
the same lease. If the lease pool is small (this mostly applies to
DHCPv4 for which address space is small), there is an increased
before; it merely increases the chances of the client being assigned
the same lease. If the lease pool is small - namely, in
DHCPv4, for which address space is small - there is an increased
likelihood that the expired lease will be assigned to another client.
Consider the following configuration:
......@@ -295,28 +295,28 @@ a reclaimed lease should be held in the database for re-assignment to
the same client. In the example given above, reclaimed leases will be
held for 30 minutes (1800s) after their expiration. During this time,
the server will likely be able to re-assign the same lease to the
returning client, unless another client requests this lease and the
returning client, unless another client specifically requests this lease and the
server assigns it.
The server must periodically remove reclaimed leases for which the time
indicated by ``hold-reclaim-time`` has elapsed. The
``flush-reclaimed-timer-wait-time`` parameter controls how often the
server removes such leases. In the example provided above, the server
will initiate removal of such leases 5 seconds after the previous
will initiate removal of such leases five seconds after the previous
removal attempt was completed. Setting this value to 0 disables lease
affinity, in which case leases will be removed from the lease database
affinity, meaning leases will be removed from the lease database
when they are reclaimed. If lease affinity is enabled, it is recommended
that ``hold-reclaim-time`` be set to a value significantly higher than
the ``reclaim-timer-wait-time``, as timely removal of expired-reclaimed
leases is less critical than the removal process, which may impact
server responsiveness.
There is no guarantee that lease affinity will work every time. If a
There is no guarantee that lease affinity will work every time; if a
server is running out of addresses, it will reassign expired addresses
to new clients. Also, clients can request specific addresses and the
server will try to honor such a request if possible. If you want to
server will try to honor such requests if possible. Administrators who want to
ensure a client keeps its address, even after periods of inactivity,
consider using host reservations or leases with very long lifetimes.
should consider using host reservations or leases with very long lifetimes.
.. _leases-reclamation-using-command:
......@@ -324,5 +324,5 @@ Reclaiming Expired Leases with Command
======================================
The *leases-reclaim* command can be used to trigger lease reclamation at
any time. Please consult the `??? <#command-leases-reclaim>`__ section
any time. Please consult the :ref:`command-leases-reclaim` section
for details about using this command.
......@@ -10,11 +10,11 @@ Overview
========
``kea-lfc`` is a service process that removes redundant information from
the files used to provide persistent storage for the memfile database
the files used to provide persistent storage for the Memfile database
backend. This service is written to run as a standalone process.
While ``kea-lfc`` can be started externally, there is usually no need to
do this. ``kea-lfc`` is run on a periodic basis by the Kea DHCP servers.
do s. ``kea-lfc`` is run on a periodic basis by the Kea DHCP servers.
The process operates on a set of files, using them to receive input and
output of the lease entries and to indicate what stage the process is
......@@ -40,32 +40,32 @@ but is not currently used by the process.
The ``-p`` argument specifies the PID file. When the ``kea-lfc`` process
starts, it attempts to determine whether another instance of the process
is already running by examining the pid file. If one is already running,
the new process is terminated; if one is not running, Kea writes its pid
into the pid file.
is already running by examining the PID file. If one is already running,
the new process is terminated; if one is not running, Kea writes its PID
into the PID file.
The other filenames specify where the ``kea-lfc`` process should look
for input, write its output, and perform its bookkeeping:
- ``previous`` — When ``kea-lfc`` starts, this is the result of any
- ``previous`` — when ``kea-lfc`` starts, this is the result of any
previous run of ``kea-lfc``. When ``kea-lfc`` finishes, it is the
result of this run. If ``kea-lfc`` is interrupted before completing,
this file may not exist.