CAP_RECONFIG

Return to Home page

CAP_RECONFIG

The CAP_RECONFIG compiler-declaration enhances and extends the innate run-time reconfiguration capabilities of Syslogd2.

There are several aspects of Syslogd2 processing that can apply to the term "reconfiguration":

1. Periodically checking (and resetting) inputs (CheckSources)
2. Periodically checking (and resetting) outputs (CheckDestinations)
3, Periodically checking (and resetting) filters when they are updated.
4. Updating the name-cache-contents when the cache-file changes.
5. Periodically attempting to resolve previously-unresolved IP names and connections (both input and output).
6. Periodically checking to see if previously-missing input files (tailfiles) have become available due to newly-mounted filesystems or newly-started file-generation processes.
7. Periodically checking the network to see if interfaces have been brought up or disabled and re-evaluating address and port conflicts as necessary.
8. Periodically checking the primary configuration file for updates and implementing any changes found.

Items (1), (2) and (6) above are considered normal "connection maintenance" and are the purpose of the CheckSources and CheckDestinations routines. They are part of the base code.
br> Items (3), (4) and (5) above are also considered part of the base code but are run by the CheckReconfig routine that is controlled by its own schedule and run by the CheckSources and CheckDestinations routines.

Items (7) and (8) call for more more extensive work and much more complexity in the code to insure a smooth transition from what is effectively one configuration to another (potentially completely different) configuration. This is the purpose of the code and data-structures acivated by declaring and enabling CAP_RECONFIG.

When CAP_RECONFIG is declared, additional structures and code ae enabled into the binary, but they remain inactive unless the global reconfig variable is enabled. (It is disabled by default.) When the global boolean variable reconfig is enabled, startup is extended through the addition of additional startup phases.

The Argument for CAP_RECONFIG

One of the original goals for Syslogd2 was to provide a syslog daemon that would support Linux Laptops when they move from network-to-network (as Windows systems do). To do this properly, they need to be able to seemlessly integrate into one or more "primary" networks where they may become part of a set of managed hosts without causing undue user-delays and performance issues when those laptops "go mobile" and (perhaps) move from one network to another. Syslogd2's attempt to meet this goal has resulted in the CAP_NETWORK feature that can automatically identify the state of the network for use by the Delayed Resolution and other features and of the CAP_RECONFIG feature to re-parse / re-build (from scratch) the IP components of syslog reporting.

I envision that Syslogd2 will ultimately allow Linux to be able to be used in a "traveling" configuration where log entries are received and spooled when not on the "correct network" and get forwarded when the system detects a connection to its "home" network has been establisehd (either direct-wired, wireless or via VPN). This can allow for intermittant hardware status, application and security reporting of remote Linux machines (perhaps used for tele-workers or sales-staff) if system logs are spooled until they can be forwarded to reporting stations.

CAP_RECONFIG was born of the realization that as Linux "goes mobile", it needs to work on (and adapt to) different networks, but to retain a semblance of it's current reputation for security, it also needs to be more aware of its surroundings and have the ability to adapt to different networks even if it is not shut down when moved from one network to another.

Implementation Details of CAP_RECONFIG

The implementation of CAP_RECONFIG required a revision of the startup and operation of the entire Syslogd2 daemon.

-- All working variables, flags and structures had to be re-evaluated to determine whether they are considered "payload" (configuration-specific values) or "operational" (control elements). "Paylaod" elements are duplicated, providing one copy for current configuration and 2nd copy for the previous configuration.
-- All static arrays and structures becaome pointers to dynamic memory to facility reconfiguration.

---

During normal startup, Syslogd2 passes through 5 distinct phases of procesisng. Those phases are given internal names:

RCS_Parse: This phase reads the command-line and configuration file into a "parse-structure" that stores the raw (parsed) data.
RCS_Build: This phase makes a copy of the base configuration parsed by RCS_Parse, then queries the network and (based on the curent network state) applies any --network - specific parameters into a "staging" area. This "staging area" is then used as a source and destination to build the working configuration while deconflicting ports, resolving what can be resolved or storing what cannot be resolved immediately for later attempts.
RCS_Stage: This phase moves confguration elements from the "build-staging area" to the "staged configuration" in active data structures.
RCS_Execute: This phase is where all threadpool control and memory is allocated and where all except the reader-threads are actually started. All POSIX mutexes and semaphores are initialied here, FIFO queues are allocated, and threads are actually started. Each threadpool that has threads started waits for confirmation that the threadpool has done its own initialization and is awaiting FIFO input prior to moving to the next threadpool type. Threadpools are initialized in reverse-processing order: first the housekeeping-, output- and user- threadpools, then worker- threadpools.
RCS_Notify1: This step initializes all mutexes and other values required by reader threadpools. When this phase actually starts the reader threads and the first reader thread has initialized the threadpool and unblocked all other threads for that threadpool, they will immediately open their inputs and attempt to pass data to the "downstream" threadpools if they have been defined.

The last step in the RCS_Notify1 phase is to initialize any timer schedules that were configured (CheckSources, CheckDestinations, Mark, etc).
RCS_Wait1: At this point, Syslogd2 is up and running. If CAP_RECONFIG is not declared or not enabled, the startup process is complete and the system stays in this state until it is shut down.
br> If CAP_RECONFIG is declared and enabled the RCS_Wait1 state is just a "pause" to allow all traffic to settle into the "new" configuration. Once any old data (from non-existant previous configurations) has been flushed from the buffers, the system continues with initialization.

---

Because of the expected need to re-build and convert to an entirely new configuration "on-the-fly", the "staged" configuration that is currently running needs to be moved to a different "active" location (referred to as the "active configuration" so another configuration can be "staged" in its place.

RCS_CrossLink: This is the first step in "moving" an acively-running configuration. This step "cross-links" all data structure pointers between the current "staged" configuration and the (currently invalid) "active" configuration.

All global pointers to support structures and values are cross-linked.
Any existing (leftover) structures from any previous configurations are released back to the operating system at this time.
Any new (non-reader) threadpools are initialized and threads are started.
Threadpool control elements (thread-counts, buffer sizes, etc) are changed if they are to be shrunk. (Enlarging buffers, threadcounts, etc occurs in the RCS_Execute stage.) The purpose for only enlarging buffers / counts in Execute and shrinking them in Crosslink is to have the most resources available in the time between the two.

By the time RCS_CrossLink is complete, all (global) supporting values (whether accessed from the "active" or "staged" configuration will return the same values. All new support threadpools required by the new configuration will have been initialized and started. All pre-existing threadpools will have duplicated their settings as well so that all references from either configuration instance point to the same location.
RCS_Notify2: As in RCS_Notify1, this phase concentrates on the reader-threads. Reader threads start by updating themselves and their own values from "staged" values to "active" values. They do this by having one thread block all the others (very temporarily), make all the appropriate changes in configuration for that threadpool, then release all threads to continue operation.
As part of the "configuration" a boolean flag is flipped. This flag is then passed as an index into the 2-element arrays that represent the "Active" and "Staged" configurations throughout the environment. Because any declared "downstream threads" use the passed parameter as an "index", there will be a time when the queues contain both pre-conversion and post-conversion messages.
RCS_Wait2: The Wait2 phase allows the buffers to flush all messages that reference "staged" resources and to insure that all traffic is now using the alternative "actiive configuration" values. When this phase ends, all traffic will have been shifted to the (identical and crosslinked) "active configuration" from the "staged configuration" it was previously using.
RCS_Reset: This phase is the simple-sounding task of breaking all the cross-linked values and resetting all "staged configuration" values to NULL or initialized values.
RCS_SteadyState: Once the reset phase is complete, the system has finally finished it's startup and has entered the RCS_SteadyStage stage where it is prepared to restart the cycle by parsing, building and staging information into the "staged configuration" prior to initializing new threadpools and new threads in RCS_Execute and RCS_Notify1. It is understood that Execute and Notify1 only change threadpool parameters if buffers or thread-counts are growing (they will shrink during the RCS_Crosslink phase). ... and the cycle continues....

If CAP_RECONFIG is declared and enabled, CheckReconfig will add checks for a change in timestamp of the main configuration file and for the network state.

If the configuration file timestamp has changed since the last check, the parsing routines are re-scheduled to run. The various reconfiguration routines, their pre-conditions and conflict information is known to the parent's scheduling process, so if the configuration file is modified while the system is in the RCS_Wait1 state, execution of the parsing routines will be delayed until the system has completed the RCS_Reset phase and entered the RCS_SteadyState phase.

If the configuration file has not changed, but the network state has, the system will re-enter the "RCS_Build" phase. This will use the pre-parsed structures and the modified network state to rebuild and deconflict the new configuration, insuring that the configuration remains consistent with the "new" network state.

An example of how the network state can require a rebuild is the following:
--input 10.2.1.1, filter=filter1
--input *, filter=filter2
--input 127.0.0.1, filter=filter3
In this example:

When the network is in the "other" state, the input "10.2.1.1" is valid and precedes the input for " * " so " * " is in conflict. What is implemented will be: 1: 10.2.1.1 with filter of "filter1" and the (non-conflicting) 127.0.0.1 with filter of "filter3".
When the network is in the "local" state, the input "10.2.1.1" is invalid (the interface is down), but the input of " * " is valid with a filter of "filter2". The input of 127.0.0.1 is then in conflict with the input at " * " and is ignored.

By rebuilding (and de-conflicting) the configuration upon change of network state, Syslogd2 keeps the actual configuration aligned with the specifications and is prepared for future upgrades where it may need to change beween "work", "other", and "home" -- each with different (dhcp-supplied) addresses or wireless interfaces going up and down without being restarted between network changes. It's also prepared to support a laptop that is removed from its docking station and goes wireless to a conference room without being turned off.
Return to top


Return to Home page