Controller Documentation

The controller program is a tool for controller other programs.

This tool is designed to configured to perform and execute any tasks given across multiple languages and it also has support for operating as an init program. There are special compile-time configurations needed to make this properly operate as an init program.

This tool operates similar to the fake program and can even be seen as an evolution to the fake program. The controller program, however is not a replacement to the fake program as it is more generalized.

This tool also provides additional features for making it easierr to test and write controller instructions. These features include partial simulation and validation modes.

In partial simulation mode, anything that the controller program has full control over and can simulate is simulated. Actual programs and scripts themselves, therefore, cannot be simulated. However, it may be possible to use an environment variables or similar and pass settings to the called program or script if the called program or script is simulation and testing aware.

The validation mode is for making this tool more scriptable. By providing validation, the controller instructions can be validated, in which case a success or failure result is returned and any problems or warnings may be printed to the caller of this tool.

This tool is not currently fully functional as an init program replacement because the networking aspects are not yet written or fully hashed out. The contol program is also another key part to the contoller program in getting this to work as an init program. Ideally, once this support is complete, it should be possible to replace init programs, such as SystemD, with the controller program.

Further development will be made on this once the controller program is updated. The next development series is planned to focus on networking, which will include support for this.

Standard Parameters

Short	Long	Description
`-h`	`--help`	Print the help message.
`+d`	`++dark`	Output using colors that show up better on dark backgrounds.
`+l`	`++light`	Output using colors that show up better on light backgrounds.
`+n`	`++no_color`	Do not print using color.
`+Q`	`++quiet`	Decrease verbosity, silencing most output.
`+E`	`++error`	Decrease verbosity, using only error output.
`+N`	`++normal`	Set verbosity to normal.
`+V`	`++verbose`	Increase verbosity beyond normal output.
`+D`	`++debug`	Enable debugging, significantly increasing verbosity beyond normal output.
`+v`	`++version`	Print only the version number.

The +Q/++quiet parameter silences all output that is not the intent and purpose of the program. For example, the purpose of the utf8 program is to print the Unicode code point or the UTF-8 byte code. The +Q/++quiet will not suppress this output. The new line printed at the end of the program, is however, not printed. The +Q/++quiet is ideal for using in scripting to help guarantee more consistent and controlled output.

The +N/++no_color simplifies the output to avoid the special color character codes. The special color character codes tend to take up a lot of extra space and may slow down printing performance.

Program Parameters

Short	Long	Description
`-c`	`--cgroup`	Specify a custom control group file path, such as '/sys/fs/cgroup/'.
`-d`	`--daemon`	Run in daemon only mode (do not process the entry).
`-I`	`--init`	The program will run as an init replacement.
`-i`	`--interruptible`	Designate that this program can be interrupted by a signal.
`-p`	`--pid`	Specify a custom pid file path, such as 'controller/run/default.pid'.
`-s`	`--settings`	Specify a custom settings path, such as 'controller/'.
`-S`	`--simulate`	Run as a simulation.
`-k`	`--socket`	Specify a custom socket file path, such as 'controller/run/default.socket'.
`-U`	`--uninterruptible`	Designate that this program cannot be interrupted by a signal.
`-v`	`--validate`	Validate the settings (entry and rules) without running (does not simulate).

When both the --simulate parameter and the --validate parameter are specified, then additional information on each would be executed rule is printed but no simulation is performed.

The default interrupt behavior is to operate as if the --interruptible parameter is passed.

Specify an empty string for the --pid parameter to disable pid file creation for this program.

Simulate Documentation

This describes the intent and purpose of the simulation and validation parameters.

The controller program is designed to support being run as an alternative to an init program (such as Sysvinit or SystemD). To help prevent problems, simulation and validation functionality is provided.

The validate functionality:

By itself will simply check the syntax of the Entry and Rule files (for Rule files specified in the Entry or Exit file). Errors are reported and nothing is executed. The controller program will return 0 on validation success and 1 on validation failure.
The simulate functionality:

By itself will perform a simulated execution of all Rules designated by an Entry or Exit file. The simulation is not a true simulation in that no program is ever called to perform any operations. Furthermore, any script specified inside a Rule is only simulated as a whole and not its individual parts. Once the Entry file is finished executing, the simulate will continue to run waiting on control commands.
The simulate with validate functionality:

Will perform similar to validate functionality except that additional information of the Rules to be executed will be printed. There will be neither execution nor simulated execution of any Rule when both simulate and validate are used together.

When a Rule is simulated, an empty script command (generally defaulting to bash) is executed in place of the actual program being executed for each program or script in the Rule file that is to be executed. This allows for testing the designated permissions and other settings that would be applied when calling some program. Control Groups are not simulated but are actually created and the simulating process will actually be placed within the Control Group.

Time Documentation

The controller program utilizes the unit of measurement called a Time, represented with uppercase T. For comparison, a unit of Time is equivalent to a nanosecond, or 10^-9 seconds. A MegaTime (MT) is therefore equivalent to a millisecond such that a millisecond is 10^-3 seconds.

A unit of Time is intended to represent some unit of Time such that a single 64-bit integer may hold all units of Time for a single calendar year. This unit of Time does not and must not include Years (unlike Unixtime). To convert from Time to Unixtime, one must have a year (which could be assumed to be the current year) and then calculate all of those calendar oddities.

A unit of Time by default is assumed to be in UTC.

1 (Earth) year ~= 31536000000000000 Time or 31536000 GT (GigaTime).
1 (Earth) day = 86400000000000 Time or 86400 GT (GigaTime).
1 (Earth) hour = 3600000000000 Time or 3600 GT (GigaTime).
1 (Earth) minute = 60000000000 Time or 60 GT (GigaTime).
1 (Earth) second = 1000000000 Time or 1 GT (GigaTime).

Consequentially, 1 day in units of Time is easily represented as 86.4 TT (TeraTime).

The Time may be stored in its year string format. In this format, a Year may be prepended to the Time followed by a single colon ':' to associate a year with the Time. This Year has no minimum or maximum but may not have decimals. For example, 2020:86400000000000 would represent: January 02, 2020 0:00 UTC. For example, 2020:86.4 TT would represent: January 02, 2020 0:00 UTC.

A second unit of Time, called EpochTime, works the same way as Time except it represents seconds. This unit is designated E. The format is similar to Time, except there are two colons: 1970::1620874738 would represent: May 13, 2021 2:58:58 UTC. When the year is not specified, then this is identical to UNIX Epoch.

A unit of EpochTime by default is assumed to be in UTC.

1 (Earth) year ~= 31536000 EpochTime or 31.536 GE (GigaEpochTime).
1 (Earth) day = 86400 EpochTime
1 (Earth) hour = 3600 EpochTime
1 (Earth) minute = 60 EpochTime
1 (Earth) second = 1 EpochTime
1 GT (GigaTime) = 1 EpochTime

Consequentially, 1 day in units of EpochTime is easily represented as 86.4 KE (KiloEpochTime).