Documentation - Controller
Author: Kevin Day
Description: Controller program documentation.
Keywords: Kevin Day, Kevux, FLL, Featureless, Linux, Library, Controller, Open-Source

# Controller Documentation

The init program is a tool for booting up a system.

This program is a variation of the `controller`: program.
See the controller documentation for details.

## Standard Parameters

Short | Long | Description
--- | --- | ---
`-h` | `--help` | Print the help message.
`+C` | `++copyright` | Print the copyright.
`+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).