[3720] Add documentation about LFC to Kea administrator reference manual

doc/guide/Makefile.am

@@ -7,7 +7,7 @@ dist_html_DATA = $(HTMLDOCS) kea-guide.css
 
 DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml
 DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml logging.xml ddns.xml hooks.xml
-DOCBOOK += libdhcp.xml
+DOCBOOK += libdhcp.xml lfc.xml
 
 EXTRA_DIST = $(DOCBOOK)
 DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml

doc/guide/intro.xml

@@ -148,6 +148,17 @@
 
           <listitem>
             <simpara>
+              <command>kea-lfc</command> &mdash;
+              This process removes redundant information from the files used
+              to provide persistent storage for the memfile data base backend.
+              The service is written to run as a stand alone process.  While it
+              can be started externally it should be started by the Kea DHCP
+              servers.
+            </simpara>
+          </listitem>
+
+          <listitem>
+            <simpara>
               <command>perfdhcp</command> &mdash;
               DHCP benchmarking tool which simulates multiple clients to
               test both DHCPv4 and DHCPv6 servers performance.

doc/guide/kea-guide.xml

@@ -69,6 +69,8 @@
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml" />
 
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lfc.xml" />
+
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks.xml" />
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdhcp.xml" />

doc/guide/lfc.xml

@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash  "&#x2014;" >
+]>
+
+  <chapter id="kea-lfc">
+    <title>The LFC process</title>
+
+    <section id="kea-lfc-overview">
+      <title>Overview</title>
+      <para><command>kea-lfc</command> is a service process that removes
+      redundant infomation from the files used to provide persistent storage
+      for the memfile data base backend. This service is written to run as a
+      stand alone process.  
+      </para>
+      <para>While <command>kea-lfc</command> can be started externally it should
+      be started by the Kea DHCP servers.
+      </para>
+      <para>The process operates on a set of files, using them for input and output
+      of the lease entries and to indicate where it is in the process in case of an
+      interruption.  Currently the caller must supply names for all of the files, in
+      the future this requirement may be relaxed with the process getting the names
+      from either the config file or from defaults.
+      </para>
+    </section>
+
+    <section id="kea-lfc-usage">
+      <title>Command Line Options</title>
+      <para><command>kea-lfc</command> is run as follows:
+<screen>
+kea-lfc [-4 | -6] -c config-file -p pid-file -x previous-file -i copy-file -o output-file -f finish-file
+</screen>
+      </para>
+
+      <para>The argument <command>-4</command> or <command>-6</command> selects the protocol
+      version of the lease files.
+      </para>
+
+      <para>The <command>-c</command> argument specifies the configuration file.  This is
+      required, but not currently used by the process.
+      </para>
+
+      <para>The <command>-p</command> argument specifies the PID file. When the
+      <command>kea-lfc</command> process starts it attempts to determine if another
+      instance of the process is already running by examining the pid file.  If one
+      is running it aborts the new process.  If one isn't running it writes its
+      pid into the pid file.
+      </para>
+
+      <para>The other filenames specify where the <command>kea-lfc</command> process
+      should look for input, write its output and use for bookkeeping.
+
+        <itemizedlist>
+          <listitem><simpara>
+            <command>previous</command> &mdash;
+            When <command>kea-lfc</command> starts this
+            is the result of any previous run of <command>kea-lfc</command>.
+            When <command>kea-lfc</command> finishes it is the result of this run.
+            If <command>kea-lfc</command> is interrupted before compelting
+            this file may not exist.
+          </simpara></listitem>
+
+          <listitem><simpara>
+            <command>input</command> &mdash;
+            Before the DHCP server invokes <command>kea-lfc</command> it will
+            copy the current lease file here and then call <command>kea-lfc</command>
+            with this file.
+          </simpara></listitem>
+
+          <listitem><simpara>
+            <command>output</command> &mdash;
+            The temporary file <command>kea-lfc</command> should use to write the leases.
+            Upon completion of writing this this file it will be moved to the finish file
+           (see below).
+          </simpara></listitem>
+
+          <listitem><simpara>
+            <command>finish</command> &mdash;
+            Another temporary file <command>kea-lfc</command> uses for bookkeeping.  When
+            <command>kea-lfc</command> completes writing the outputfile it moves it to this
+            file name.  After <command>kea-lfc</command> finishes deleting the other files
+            (previous and input) it moves this file to previous lease file.  By moving the
+            files in this fashion the <command>kea-lfc</command> and the DHCP server
+            processes can determine the correct file to use even if one of the
+            processes was interrupted before completing its task.
+          </simpara></listitem>
+
+        </itemizedlist>
+      </para>
+
+      <para>There are several additional arguments mostly for debugging purposes.
+      <command>-d</command> Sets the logging level to debug. <command>-v</command> and
+      <command>-V</command> print out version stamps with <command>-V</command> providing
+      a longer form.  <command>-h</command> prints out the usage string.
+      </para>
+
+    </section>
+  </chapter>

src/bin/lfc/kea-lfc.xml

@@ -62,7 +62,7 @@
     <title>DESCRIPTION</title>
     <para>
       The <command>kea-lfc</command> service process removes redundant
-      information for the files used to provide persistent storage for
+      information from the files used to provide persistent storage for
       the memfile data base backend.  The service is written to run as
       a stand alone process.  While it can be started externally it
       should be started by the Kea DHCP servers as desired and required.