Adding upstream version 2.4.1.upstream/2.4.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 80 insertions, 0 deletions

diff --git a/src/bin/lfc/lfc.dox b/src/bin/lfc/lfc.dox
new file mode 100644
index 0000000..769a3ff
--- /dev/null
+++ b/src/bin/lfc/lfc.dox
@@ -0,0 +1,80 @@
+// Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page lfc Lease File Cleanup Component
+
+The Lease File Cleanup component (kea-lfc) is a service process that removes redundant
+information from the files used to provide persistent storage for the memfile data base
+backend.
+
+When using the memfile database backend Kea servers store persistent lease information
+in lease files.  They add new lease information to the file by appending it to the end
+of the file.  In a typical lease file you might find several instances of the same lease,
+one for each time the client acquired or renewed the lease.  In order to remove this
+redundant information and to keep the lease files from growing without bound the
+Kea servers will periodically run kea-lfc.  This process will read the leases from
+the lease files and keep only the most recent instance of each lease.  When it finishes
+reading the leases it will write the unique leases to the output file.
+
+The design documentation for kea-lfc can be found here:
+<a href="https://gitlab.isc.org/isc-projects/kea/wikis/Lease-File-Cleanup-design"> LFC Design</a>
+
+While kea-lfc can be started externally, there is usually no need to do this as the
+Kea servers will run it on a periodic basis.
+
+@section lfcProcessing Processing
+kea-lfc 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.
+
+kea-lfc is built on the isc::lfc::LFCController class.  Effectively this provides
+a single external routine, isc::lfc::LFCController::launch, which is called with
+the arguments from the command line and proceeds to parse the arguments and
+then process the lease files.
+
+It uses isc::util::PIDFile to manipulate a PID file to mediate access to the
+leases.  When a new process is started it will check the PID file.  If the
+PID file exists and a process with that ID is still running already the new
+process will be terminated.  If no other process is running the PID of the
+new process is written to the file.
+
+It uses the isc::dhcp::LeaseFileLoader class to first read all of the leases
+into either isc::dhcp::Lease6Storage or isc::dhcp::Lease4Storage containers.
+The leases are read in the order they were written to the file and younger leases
+overwrite older leases for the same address.  When the process finishes reading
+the lease files there will be a single lease entry for each address used.  At
+this point the process again uses the isc::dhcp::LeaseFileLoader class to write
+an entry for each remaining lease into the output file.
+
+Lastly kea-lfc moves the files to indicate completion (see below) and removes
+the extra files then exits.
+
+@section lfcFiles File Manipulation
+
+This section is intended to provide a brief overview of how kea-lfc uses its
+files.  For a more in depth discussion of the design see
+<a href="https://gitlab.isc.org/isc-projects/kea/wikis/designs/Lease-File-Cleanup-design">LFC Design</a>
+
+There are four files used during the kea-lfc process: previous, input, output
+and finish.  They are used to both hold the leases and to indicate to the Kea
+servers and to other instances of kea-lfc what processing has been completed.
+
+The previous file is the result of a previous run of the kea-lfc process.
+
+The input (or copy) file is created by the kea server just before invoking
+the kea-lfc process.  The kea server will move it's current lease file to
+the input file and then start using a new current file.
+
+The output file is created by kea-lfc as it writes the leases to a file.  When
+kea-lfc finishes writing all the leases to the output file it renames the output
+file to be the finish file.  It then removes the previous and input files and
+renames the finish file to be the previous file.
+
+*/
+