|
|
@@ -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 storge 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">
|
Marcin Siodelski