Commit c24fff36 authored by Wlodzimierz Wencel's avatar Wlodzimierz Wencel
Browse files

Merge branch 'master' of ssh://git.kea.isc.org/git/kea

parents edab4e40 e6e8921c
900. [doc] marcin
Documented configuration of the Lease File Cleanup (LFC) in
the Kea Administrator Reference.
(Trac #3672, git da3c676f009785204f9d84ca008890959bffcc18)
899. [func] tomek
reservation-mode parameter has been added to DHCPv6 server.
It controls what host reservation types are allowed and may
......
......@@ -253,7 +253,7 @@ url="http://jsonviewer.stack.hu/"/>.
Currently there are three database backends available:
memfile (which is the default backend), MySQL and PostgreSQL.</para>
<section>
<title>Memfile - Basic Storage for Leases</title>
<title>Memfile, Basic Storage for Leases</title>
<para>The server is able to store lease data in different repositories. Larger
deployments may elect to store leases in a database. <xref
......@@ -264,32 +264,113 @@ url="http://jsonviewer.stack.hu/"/>.
eliminates a dependency on third-party database software.</para>
<para>The configuration of the file backend (Memfile) is controlled through
the Dhcp4/lease-database parameters. <!-- @todo: we don't have default
parameters. Let's comment this out When default parameters are used, the
Memfile backend will write leases to a disk in the
[kea-install-dir]/var/kea/kea-leases4.csv. -->
The following configuration sets the name of the lease file to
<filename>/tmp/kea-leases4.csv</filename>:
the Dhcp4/lease-database parameters. The <command>type</command> parameter
is mandatory and it specifies which storage for leases the server should use.
The value of <userinput>"memfile"</userinput> indicates that the file should
be used as the storage. The following list presents the remaining, not mandatory
parameters, which can be used to configure the Memfile backend.
<itemizedlist>
<listitem>
<simpara><command>persist</command>: controls whether the new leases and
updates to existing leases are written to the file. It is strongly
recommended that the value of this parameter is set to
<userinput>true</userinput> at all times, during the server's normal
operation. Not writing leases to disk will mean that if a server is restarted
(e.g. after a power failure), it will not know what addresses have been
assigned. As a result, it may hand out addresses to new clients that are
already in use. The value of <userinput>false</userinput> is mostly useful
for performance testing purposes. The default value of the
<command>persist</command> parameter is <userinput>true</userinput>,
which enables writing lease updates
to the lease file.
</simpara>
</listitem>
<listitem>
<simpara><command>name</command>: specifies an absolute location of the lease
file in which new leases and lease updates will be recorded. The default value
for this parameter is <userinput>"[kea-install-dir]/var/kea/kea-leases4.csv"
</userinput>.</simpara>
</listitem>
<listitem>
<simpara><command>lfc-interval</command>: specifies the interval in seconds, at
which the server (Memfile backend) will perform a lease file cleanup (LFC),
which removes the redundant (historical) information from the lease file
and effectively reduces the lease file size. The cleanup process is described
in more detailed fashion further in this section. The default value of the
<command>lfc-interval</command> is <userinput>0</userinput>, which disables
the LFC.</simpara>
</listitem>
</itemizedlist>
</para>
<para>The example configuration of the Memfile backend is presented below:
<screen>
"Dhcp4": {
"lease-database": {
<userinput>"type": "memfile"</userinput>,
<userinput>"persist": true</userinput>,
<userinput>"name": "/tmp/kea-leases4.csv"</userinput>
<userinput>"name": "/tmp/kea-leases4.csv",</userinput>
<userinput>"lfc-interval": 1800</userinput>
}
...
}
</screen>
This configuration selects the <filename>/tmp/kea-leases4.csv</filename> as
the storage for lease information and enables persistence (writing lease updates
to this file). It also configures the backend perform the periodic cleanup
of the lease files, executed every 30 minutes.
</para>
<para>It is important to know how the lease file contents are organized
to understand why the periodic lease file cleanup is needed. Every time when
the server updates a lease or creates a new lease for the client, the new
lease information must be recorded in the lease file. For performance reasons,
the server does not supersede the existing client's lease, as it would require
the lookup of the specific lease entry, but simply appends the new lease
information at the end of the lease file. The previous lease entries for the
client are not removed. When the server loads leases from the lease file, e.g.
at the server startup, it assumes that the latest lease entry for the client
is the valid one. The previous entries are discarded. This means that the
server can re-construct the accurate information about the leases even though
there may be many lease entries for each client. However, storing many entries
for each client results in bloated lease file and impairs the performance of
the server's startup and reconfiguration, as it needs to process larger number
of lease entries.
</para>
<para>The lease file cleanup removes all previous entries for each client and
leaves only the latest ones. The interval at which the cleanup is performed
is configurable, and it should be selected according to the frequency of lease
renewals initiated by the clients. The more frequent renewals are, the lesser
value of the <command>lfc-interval</command> should be. Note however, that the
LFC takes time and thus it is possible (although unlikely) that new cleanup
is started while the previous cleanup instance is still running, if the
<command>lfc-interval</command> is too short. The server would recover from
this by skipping the new cleanup when it detects that the previous cleanup
is still in progress. But, this implies that the actual cleanups will be
triggered more rarely than configured. Moreover, triggering a new cleanup
adds an overhead to the server, which will not be able to respond to new
requests for a short period of time when the new cleanup process is spawned.
Therefore, it is recommended that the <command>lfc-interval</command> value
is selected in a way that would allow for completing the cleanup before the
new cleanup is triggered.
</para>
<para>The LFC is performed by a separate process (in background) to avoid
performance impact on the server process. In order to avoid the conflicts
between the two processes both using the same lease files, the LFC process
operates on the copy of the original lease file, rather than on the lease
file used by the server to record lease updates. There are also other files
being created as a side effect of the lease file cleanup. The detailed
description of the LFC is located on the Kea wiki:
<ulink url="http://kea.isc.org/wiki/LFCDesign"/>.
</para>
<para>The "persist" parameter controls whether the leases are written to disk.
It is strongly recommended that this parameter is set to
<command>true</command> at all times during the normal operation of the
server. (Not writing leases to disk will mean that if a server is restarted
(e.g. after a power failure), it will not know what addresses have been
assigned. As a result, it may hand out addresses to new clients that are
already in use.)</para>
</section>
<section id="database-configuration4">
......
......@@ -257,7 +257,7 @@ JSON validator is available at <ulink url="http://jsonviewer.stack.hu/"/>.
Currently there are three database backends available:
memfile (which is the default backend), MySQL and PostgreSQL.</para>
<section>
<title>Memfile - Basic Storage for Leases</title>
<title>Memfile, Basic Storage for Leases</title>
<para>The server is able to store lease data in different repositories. Larger
deployments may elect to store leases in a database. <xref
......@@ -268,32 +268,107 @@ JSON validator is available at <ulink url="http://jsonviewer.stack.hu/"/>.
eliminates a dependency on third-party database software.</para>
<para>The configuration of the file backend (Memfile) is controlled through
the Dhcp6/lease-database parameters. <!-- @todo: we don't have default
parameters. Let's comment this out When default parameters are used, the
Memfile backend will write leases to a disk in the
[kea-install-dir]/var/kea/kea-leases4.csv. -->
The following configuration sets the name of the lease file to
<filename>/tmp/kea-leases6.csv</filename>:
the Dhcp6/lease-database parameters. The <command>type</command> parameter
is mandatory and it specifies which storage for leases the server should use.
The value of <userinput>"memfile"</userinput> indicates that the file should
be used as the storage. The following list presents the remaining, not mandatory
parameters, which can be used to configure the Memfile backend.
<itemizedlist>
<listitem>
<simpara><command>persist</command>: controls whether the new leases and
updates to existing leases are written to the file. It is strongly
recommended that the value of this parameter is set to
<userinput>true</userinput> at all times, during the server's normal
operation. Not writing leases to disk will mean that if a server is restarted
(e.g. after a power failure), it will not know what addresses have been
assigned. As a result, it may hand out addresses to new clients that are
already in use. The value of <userinput>false</userinput> is mostly useful
for performance testing purposes. The default value of the
<command>persist</command> parameter is <userinput>true</userinput>,
which enables writing lease updates
to the lease file.
</simpara>
</listitem>
<listitem>
<simpara><command>name</command>: specifies an absolute location of the lease
file in which new leases and lease updates will be recorded. The default value
for this parameter is <userinput>"[kea-install-dir]/var/kea/kea-leases6.csv"
</userinput>.</simpara>
</listitem>
<listitem>
<simpara><command>lfc-interval</command>: specifies the interval in seconds, at
which the server (Memfile backend) will perform a lease file cleanup (LFC),
which removes the redundant (historical) information from the lease file
and effectively reduces the lease file size. The cleanup process is described
in more detailed fashion further in this section. The default value of the
<command>lfc-interval</command> is <userinput>0</userinput>, which disables
the LFC.</simpara>
</listitem>
</itemizedlist>
</para>
<para>The example configuration of the Memfile backend is presented below:
<screen>
"Dhcp6": {
"lease-database": {
<userinput>"type": "memfile"</userinput>,
<userinput>"persist": true</userinput>,
<userinput>"name": "/tmp/kea-leases6.csv"</userinput>
<userinput>"name": "/tmp/kea-leases6.csv"</userinput>,
<userinput>"lfc-interval": 1800</userinput>
}
...
}
</screen>
</para>
<para>The "persist" parameter controls whether the leases are written to disk.
It is strongly recommended that this parameter is set to true at all times
during the normal operation of the server. (Not writing leases to disk will
mean that if a server is restarted (e.g. after a power failure), it will not
know what addresses have been assigned. As a result, it may hand out addresses
to new clients that are already in use.)
</para>
<para>It is important to know how the lease file contents are organized
to understand why the periodic lease file cleanup is needed. Every time when
the server updates a lease or creates a new lease for the client, the new
lease information must be recorded in the lease file. For performance reasons,
the server does not supersede the existing client's lease, as it would require
the lookup of the specific lease entry, but simply appends the new lease
information at the end of the lease file. The previous lease entries for the
client are not removed. When the server loads leases from the lease file, e.g.
at the server startup, it assumes that the latest lease entry for the client
is the valid one. The previous entries are discarded. This means that the
server can re-construct the accurate information about the leases even though
there may be many lease entries for each client. However, storing many entries
for each client results in bloated lease file and impairs the performance of
the server's startup and reconfiguration, as it needs to process larger number
of lease entries.
</para>
<para>The lease file cleanup removes all previous entries for each client and
leaves only the latest ones. The interval at which the cleanup is performed
is configurable, and it should be selected according to the frequency of lease
renewals initiated by the clients. The more frequent renewals are, the lesser
value of the <command>lfc-interval</command> should be. Note however, that the
LFC takes time and thus it is possible (although unlikely) that new cleanup
is started while the previous cleanup instance is still running, if the
<command>lfc-interval</command> is too short. The server would recover from
this by skipping the new cleanup when it detects that the previous cleanup
is still in progress. But, this implies that the actual cleanups will be
triggered more rarely than configured. Moreover, triggering a new cleanup
adds an overhead to the server, which will not be able to respond to new
requests for a short period of time when the new cleanup process is spawned.
Therefore, it is recommended that the <command>lfc-interval</command> value
is selected in a way that would allow for completing the cleanup before the
new cleanup is triggered.
</para>
<para>The LFC is performed by a separate process (in background) to avoid
performance impact on the server process. In order to avoid the conflicts
between the two processes both using the same lease files, the LFC process
operates on the copy of the original lease file, rather than on the lease
file used by the server to record lease updates. There are also other files
being created as a side effect of the lease file cleanup. The detailed
description of the LFC is located on the Kea wiki:
<ulink url="http://kea.isc.org/wiki/LFCDesign"/>.
</para>
</section>
<section id="database-configuration6">
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment