Kea: Lease File Cleanup Component

| Kea 3.2.0-git

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: LFC Design

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.

# 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. Since kea 3.1.3 this part of the code was moved to the memfile lease manager which acquires the file lock, checks running lfc, spawn lfc, write the lfc pid to the PID file and release the lock. The lfc process waits for the lock and is prepared to an already existing PID file containing its own pid. Note the lfc process is still responsible to delete the PID file before existing even this is not critical.

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.

# 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 LFC Design

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.