Changes between Version 31 and Version 32 of LFCDesign


Ignore:
Timestamp:
Feb 6, 2015, 3:52:35 AM (3 years ago)
Author:
sar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • LFCDesign

    v31 v32  
    66There was a discussion on the kea-dev mailing list in November 2014 about the possible approaches to implement the LFC. This discussion was initiated by Nicolas Chaigneau (Thanks!) and is available [https://lists.isc.org/pipermail/kea-dev/2014-November/000185.html here].
    77
    8 As a result, ISC has created the [wiki:LeaseFileCompressionRequirements LFC Requirements] document and asked for the feedback on the list. The document has been updated according to the feedback obtained. Please refer to this [https://lists.isc.org/pipermail/kea-dev/2014-December/000211.html thread] for details.
     8As a result, ISC has created the [wiki:LeaseFileCompressionRequirements LFC Requirements] document and asked for feedback on the list. The document has been updated according to the feedback obtained. Please refer to this [https://lists.isc.org/pipermail/kea-dev/2014-December/000211.html thread] for details.
    99
    1010The most recent updates to this document are a result of reviews by Stephen Morris and Tomek Mrugalski, as well as a result of the discussions over the phone between Marcin and Shawn. The reviews can be found in the kea-dev mailing list archives:
     
    2828|| Lease File || <lease-file-name> specified in the Kea configuration ||  A file being used by the server to record updates to the leases as a result of processing DHCP messages from the clients. The actual file name (including an absolute path) is specified in the Kea configuration file. This file may be created when the server starts up or is reconfigured. This file is re-created (without any leases) when the LFC begins. The LFC doesn't process this file. It is merely used by the server to write updates to leases. ||
    2929|| Previous Lease File || <lease-file-name>.2 || Lease file holding the supplementary information about leases. It is a product of the previous LFC run, i.e. it holds the information from the LFC Output File created during the previous LFC. The lack of this file indicates that no LFC has been performed since the server started to use the Lease File. ||
    30 || Lease File Copy || <lease-file-name>.1 || This file is created as a result of moving (renaming) the <lease-file-name> to <lease-file-name>.1 at the beginning of the LFC by the DHCP server process. This is used as one of the input files to the ''kea-lfc'' application performing the cleanup of lease files. ||
     30|| Lease File Copy || <lease-file-name>.1 || This file is created as a result of moving (renaming) <lease-file-name> to <lease-file-name>.1 at the beginning of the LFC by the DHCP server process. This is used as one of the input files to the ''kea-lfc'' application performing the cleanup of lease files. ||
    3131|| LFC Output File || <lease-file-name>.output || This file is created by the ''kea-lfc'' application and it combines the cleaned-up lease information from the Previous Lease File and the Lease File Copy. ||
    32 || LFC Finish File || <lease-file-name>.completed || This file is created by the ''kea-lfc'' application by moving the <lease-file-name>.output to <lease-file-name>.completed. This move is performed right after the lease files are processed and it indicates that the clean-up has completed. ||
     32|| LFC Finish File || <lease-file-name>.completed || This file is created by the ''kea-lfc'' application by moving <lease-file-name>.output to <lease-file-name>.completed. This move is performed right after the lease files are processed and it indicates that the clean-up has completed. ||
    3333
    3434
    3535== LFC Process Overview ==
    36 The LFC is initiated by the DHCP server process when the specific trigger (e.g. timer) kicks in. The server checks for the presence of the Lease File Copy. If this file is not found, the server ceases DHCP message processing and creates the Lease File Copy by renaming the Lease File. The server then re-creates the Lease File with no lease entries (having only a header) with the same name as the one that the server had been using before the LFC was started. The server resumes the processing of the DHCP messages using this new Lease File. Note that the DHCP server doesn't rename the Lease File to Lease File Copy when it finds that the Lease File Copy exists, because its presence indicates that the previous LFC was not successful (perhaps crashed) and replacing the existing file could cause a data loss.
     36The LFC is initiated by the DHCP server process when a specific trigger (e.g. timer) kicks in. The server checks for the presence of the Lease File Copy. If this file is not found, the server ceases DHCP message processing and creates the Lease File Copy by renaming the Lease File. The server then re-creates the Lease File with no lease entries (having only a header) with the same name as the one that the server had been using before the LFC was started. The server resumes the processing of the DHCP messages using this new Lease File. Note that the DHCP server doesn't rename the Lease File to Lease File Copy when it finds that the Lease File Copy exists, because its presence indicates that the previous LFC was not successful (perhaps crashed) and replacing the existing file could cause a data loss.
    3737
    38 Regardless if the Lease File Copy existed or not, the server spawns a new process which executes the external program ''kea-lfc'' performing the actual "cleanup" of the Lease File Copy and the Previous Lease File (if exists). Both files are processed by the application and the output is stored in the LFC Output File. When the program completes the cleanup of both files, it replaces the LFC Output File with LFC Finish File to indicate that both files have been processed. The program then removes both processed files, i.e. Lease File Copy and the Previous Lease File as all useful information from these files has been stored in the LFC Finish File. When files are deleted, the LFC Finish File is moved to the Previous Lease File.
     38Regardless if the Lease File Copy existed or not, the server spawns a new process which executes the external program ''kea-lfc'' performing the actual "cleanup" of the Lease File Copy and the Previous Lease File (if it exists). Both files are processed by the application and the output is stored in the LFC Output File. When the program completes the cleanup of both files, it moves the LFC Output File to the LFC Finish File to indicate that both files have been processed. The program then removes both processed files, i.e. Lease File Copy and the Previous Lease File as all useful information from these files has been stored in the LFC Finish File. When the files are deleted, the LFC Finish File is moved to the Previous Lease File.
    3939
    4040By checking the presence/absence of the specific files, the ''kea-lfc'' application and the DHCP server may determine the state of the previously executed LFC when it terminated (including crashes).
     
    6666The <configuration-file> usually contains the path to the current Lease File and this information could be used by the ''kea-lfc'' to generate names for other files. This would eliminate the need for additional parameters. However, as a result of the discussions about the design it has been decided that the command line parameters will be implemented as it gives more flexibility. For example: it is considered to be easier to test the application without the need to generate the Kea configuration file. It is also easier for the administrator run LFC manually by just specifying the location of the files.
    6767
    68 In the first versions of the LFC it will only be possible to specify the lease files using the command line options. In the future versions, it will also be possible to use the Kea configuration file (and not specify other parameters) in which case the ''kea-lfc'' will parse the lease file name from the configuration file and generate other names internally. In that case, the values specified with the command line options will always take precedence over the values in the Kea configuration file. If the values are neither specified in the command line nor in the configuration file, the default values are used.
     68In the first versions of the LFC it will only be possible to specify the lease files using the command line options. In future versions, it will also be possible to use the Kea configuration file (and not specify other parameters) in which case the ''kea-lfc'' will parse the lease file name from the configuration file and generate other names internally. In that case, the values specified with the command line options will always take precedence over the values in the Kea configuration file. If the values are neither specified in the command line nor in the configuration file, the default values are used.
    6969
    70 The design discussions considered two approaches for the ''kea-lfc'' to perform the lease file cleanup. First approach assumed that the program walks through the lease entries in the input file and rewrites those entries to the output file, for which expiration time was not reached (when comparing with a current system time). This approach wouldn't require loading all leases to memory before writing them to the output file. It would also allow for preserving "unparsable" information found in the processed file by rewriting this information to the output file as is. The second consider approach was that the ''kea-lfc'' first loads all lease entries into the memory and for each client replaces previous entries for the lease with later entries. When all leases are loaded into memory, the program dumps them into the output file. The down side of this approach is that it consumes memory for holding all lease information during LFC. It also makes it troublesome to preserve "unparsable" data found in the input file, because by loading all leases from the file into memory, the location of the unparsable data in the input file is lost. The benefit of using the latter approach is that it guarantees that exactly one (the most recent) lease entry is held for each client in the output file, which may significantly reduce the lease file size and makes the LFC process more effective. Therefore, this approach has been chosen.
     70The design discussions considered two approaches for the ''kea-lfc'' to perform the lease file cleanup. The first approach assumed that the program walks through the lease entries in the input file and rewrites those entries to the output file, for which expiration time was not reached (when comparing with a current system time). This approach wouldn't require loading all leases to memory before writing them to the output file. It would also allow for preserving "unparsable" information found in the processed file by rewriting this information to the output file as is. The second approach considered was that ''kea-lfc'' first loads all lease entries into memory and for each client replaces previous entries for the lease with later entries. When all leases are loaded into memory, the program dumps them into the output file. The down side of this approach is that it consumes memory for holding all lease information during LFC. It also makes it troublesome to preserve "unparsable" data found in the input file, because by loading all leases from the file into memory, the location of the unparsable data in the input file is lost. The benefit of using the latter approach is that it guarantees that exactly one (the most recent) lease entry is held for each client in the output file, which may significantly reduce the lease file size and makes the LFC process more effective. Therefore, this approach has been chosen.
    7171
    7272The ''kea-lfc'' should be written in C++ and should make use of (link with) the Kea libraries to manage the lease files in the CSV format. The state diagram of the ''kea-lfc'' application is depicted on the picture in the next section.
     
    9494
    9595=== Preventing Concurrent Runs ===
    96 The LFC is started periodically and it can be triggered by the timer expiration or any other trigger that may be implemented in the future, e.g. triggered manually by the server administrator using the Kea command control mechanism (TBI). Typically, the duration of the LFC is much shorter than the period between startup of two subsequent LFCs. However, the duration of the LFC depends on different factors, e.g. hard drive speed, lease file size, number of expired leases in the lease file, frequency of the renewals etc. In addition, the period between LFC startups is controlled by the administrator depending on his needs. Therefore, it is possible that the LFC is triggered while the previously started LFC is still in progress. It is possible to implement restrictions on the Kea configuration mechanism to prevent configuration of a "too short" period between LFC startups, but it doesn't address the case when two overlapping LFCs are started using the manual methods.
     96The LFC is started periodically and it can be triggered by the timer expiration or any other trigger that may be implemented in the future, e.g. triggered manually by the server administrator using the Kea command control mechanism (TBI). Typically, the duration of the LFC is much shorter than the period between the startup of two subsequent LFCs. However, the duration of the LFC depends on different factors, e.g. hard drive speed, lease file size, number of expired leases in the lease file, frequency of the renewals etc. In addition, the period between LFC startups is controlled by the administrator depending on his needs. Therefore, it is possible that the LFC may be triggered while a previously started LFC is still in progress. It is possible to implement restrictions on the Kea configuration mechanism to prevent configuration of a "too short" period between LFC startups, but that doesn't address the case when two overlapping LFCs are started using the manual methods.
    9797
    98 The ''kea-lfc'' implements locking using the PID file to prevent concurrent runs. When the ''kea-lfc'' is started, it checks for the presence of the PID file. If the file exists, it checks if the process with a PID from the PID file is running. If the process is running, the application terminates. If the PID file doesn't exist or the process with a given PID is not running, the ''kea-lfc'' creates a new PID file with its own PID and continues to run.
     98The ''kea-lfc'' implements locking using a PID file to prevent concurrent runs. When ''kea-lfc'' is started, it checks for the presence of the PID file. If the file exists, it checks if the process with a PID from the PID file is running. If the process is running, the application terminates. If the PID file doesn't exist or no process with a given PID is running, ''kea-lfc'' creates a new PID file with its own PID and continues to run.
    9999
    100 The server instance which runs the ''kea-lfc'' installs a SIGCHLD signal handler to monitor when the ''kea-lfc'' terminates. The server doesn't spawn a new ''kea-lfc'' process as long as the previously started process is running. In case if the server is restarted while the ''kea-lfc'' process is running, the server looses the information about the state of the child processes. When the server starts up it is possible that the LFC process is (still) running and thus it is possible that the LFC process is currently using files which the server needs to load leases from. The server must use the appropriate PID file to check the LFC process ID and make sure that the ''kea-lfc'' process has terminated before leases are loaded. The server has several options in this case:
     100The server instance which runs ''kea-lfc'' installs a SIGCHLD signal handler to monitor when ''kea-lfc'' terminates. The server doesn't spawn a new ''kea-lfc'' process as long as the previously started process is running. In case if the server is restarted while the ''kea-lfc'' process is running, the server loses the information about the state of the child processes. When the server starts up it is possible that the LFC process is (still) running and thus it is possible that the LFC process is currently using files which the server needs to load leases from. The server must use the appropriate PID file to check the LFC process ID and make sure that the ''kea-lfc'' process has terminated before leases are loaded. The server has several options in this case:
    101101- kill the running kea-lfc process - which is dangerous in case some other process "hijacked" the pid used previously by the kea-lfc,
    102102- wait for the process to finish (no matter how long) and then load leases - which may cause an infinite hang of the server in case the process doesn't finish,
     
    106106The last two approaches seem to be the most feasible. Ultimately, we should support the third approach, as it avoids manual intervention by the administrator. However, as a first step, the fourth approach is good enough.
    107107
    108 The server startup and reconfiguration are the two times when there is a potential conflict between the DHCP server process loading leases from files and the ''kea-lfc'' writing to these files or otherwise modifying it. In those cases, the server process is responsible for avoiding the conflicts, as described above. In all other cases, the server leaves it up to the ''kea-lfc'' to check for other running instances and exit if required. This assures that the concurrency checks are performed in background and have no impact on processing DHCP messages by the server.
     108The server startup and reconfiguration are the two times when there is a potential conflict between the DHCP server process loading leases from files and ''kea-lfc'' writing to these files or otherwise modifying it. In those cases, the server process is responsible for avoiding the conflicts, as described above. In all other cases, the server leaves it up to ''kea-lfc'' to check for other running instances and exit if required. This assures that the concurrency checks are performed in background and have no impact on processing DHCP messages by the server.
    109109
    110110=== Logging ===