Documentation - Controller - Specification - Entry
Author: Kevin Day
Description: Controller program entry specification.
Keywords: Kevin Day, Kevux, FLL, Featureless, Linux, Library, Controller, Open-Source, Specification

# Controller Entry Specification

The version date of this specification is `2024/07/10`.

The Entry files follow the `FSS-0005 (Somewhat Basic List)` format.

An Entry file name is expected to have the file extension `.entry`.

For each Entry file:

- The outer most part is a `FSS-0002 (Basic List)`.
- The Basic List Object is considered the `Item`.
- The Basic List Content are considered the `Actions`.
- The Actions are `FSS-0001 (Extended)`.
- Each Action Object is the `Action Name`.
- Each Action Content are the `Action Parameters`.

The Items:

- `main`: required.
- `settings`: optional, Actions may be one of:
  - `control`: One to two Content.
    - The first Content is a relative or absolute path to a socket file.
    - The second Content an optional "readonly".
  - `control_group`: Exactly one Content that is a group name or group id.
  - `control_mode`: Exactly one Content that is a valid file mode.
  - `control_user`: Exactly one Content that is a user name or user id.
  - `define`: Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits).
  - `mode`: Exactly one Content that is one of `program` or `service`.
  - `parameter`: Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value.
  - `pid`: Exactly one Content that is one of `disable`, `require`, or `ready`.
  - `pid_file`: Exactly one Content that is a relative or absolute path to a pid file.
  - `session`: Exactly one Content that is one of `new` or `same`.
  - `show`: Exactly one Content that is one of `normal` or `init`.
  - `timeout`: One or Two content with the first being one of `exit`, `start`, `stop`, or `kill` and the (optional) second Content being a positive whole number or 0.

The Entry file may have any other valid Item Objects, but only the above are reserved.

The Actions:

- `consider`: One or more Content.
  - The first Content is the relative file path (without any leading/trailing slashes and without file extension).
  - The second Content is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `execute`: One or more Content.
  - The first Content is the program name or full path to the program (the program may be a script).
  - All remaining Content are passed as parameters to the program being executed.
- `failsafe`: One Content that is a valid Object name, except for the reserved `main`.
- `freeze`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `item`: One Content that is a valid Object name, except for the reserved `main`.
- `kill`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `pause`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `ready`: Zero or One Content.
  - The first may only be one of:
    - wait
- `reload`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `restart`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `resume`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `start`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `stop`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `thaw`: Two or more Content.
  - The first Content that is the relative directory path (without any leading/trailing slashes).
  - The second Content that is the basename for a rule file.
  - The third and beyond may only be one of:
    - asynchronous
    - require
    - wait
- `timeout`: One or two Content.
  - The first being one of:
    - exit
    - start
    - stop
    - kill
- The (optional) second Content being a positive whole number or 0.

## Entry Documentation

This describes the intent and purpose of an Entry file.

An Entry file, such as `default.entry`, is intended to store a set of rules in which the controller will process on execution.
These are used to run some set of commands, such as booting a system.

The `main` Item Object is always executed first (Therefore `main` is both reserved and required).
All other Basic List Objects are not executed unless either an `item` or a `failsafe` specifies a valid Item name.
Execution of all Items is top-down.

The `settings` item Object:

- Represents Entry settings and is not an `item` that can be executed.
- A number of settings are supported, but if this Item Object is not specified, then defaults are used.
- The following settings are available: `control`, `control_group`, `control_mode`, `control_user`, `define`, `mode`, `parameter`, `pid`, `pid_file`, `session`, `show`.

  The `control` setting:

  - Represents the path to the socket file in which the Controller uses to communicate over with clients such as a Control program.
  - A relative path is relative to the Controller PID directory.
  - An absolute path is treated exactly as the path given.
  - If no socket setting is specified, then no socket will be made available.
  - This socket file is only created once `ready` mode is achieved.
  - Providing `readonly` after the socket path instructs the Controller program not to create or delete the Socket file because the file system is assumed to be readonly.
  - The socket file itself must therefore already exist.
  - This should be possible in the cases of file systems that have pre-created a socket file at the designated path.
  - When `readonly`, the group, mode, and user are also not processed effectively resulting in the `control_group`, `control_mode`, and `control_user` settings being ignored.
  - Future versions might expand this into supporting network addresses in addition to socket files.

  The `control_group` setting:

  - Represents the group name or group ID to assign to the socket file as the group.

  The `control_mode` setting:

  - Represents the file mode assigned to the socket file.
  - This could either be the string version that might look like `u+rw-x,g+r-wx,o-rwx` or a numeric value like `0750`.

  The `define` setting:

  - Use this to define an environment variable (this overwrites any existing environment variable with this name).
  - A define is both exported as an environment variable as well as exposed as an IKI variable.
  - Example IKI variable substitution: for `define PATH /bin:/sbin`, the associated IKI variable would look like: `define:"PATH"`.
  - All environment variables, including those defined using this, must be in the `environment` list in any given Rule to be exported to the executed process.
  - Environment variables added here that are not added to the environment are still exposed as an IKI variable.
  - This is only expanded within any Rule operated on by this Entry.

  The `mode` setting:

  - Represents the mode in which the Entry is operating in.
  - The following modes are supported: `program` and `service`.

    The `program` mode:

    - Designates that the Entry operates as a program and exits when complete.
    - Will call the `exit` with the same name as this Entry, but with the extension `exit`, such as `default.exit`.
    - Supports the Item Action `execute` to execute a program (switching the `controller` program entirely with the executed process).

    The `service` mode:

    - Designates that the Entry operates as a service and will sit and wait for control commands when complete.
    - Will call the `exit` with the same name as this Entry, but with the extension `exit`, such as `default.exit`.
    - Does not support the Item Action `execute`.
    - This is the default mode.

  The `parameter` setting:

  - Use this to define an IKI variable name and value.
  - These do not conflict with environment variables and are not exposed as environment variables.
  - Example IKI variable substitution: for `parameter hello world`, the associated IKI variable would look like: `parameter:"hello"`.
  - This is only expanded within any Rule operated on by this Entry.

  The `pid` setting:

  - Represents how the Entry PID file is generated or not.
  - The following modes are supported: `disable`, `require`, and `ready`.
  - For `disable`, not PID file representing the Entry is created.
  - For `require`, check to see if the PID file exists for an Entry at startup and then when `ready` create a PID file, display error on PID file already exists or on failure and then fail.
  - For `ready`, when `ready` create a PID file, display error on failure and then fail (does not check if PID file exists).

  The `pid_file` setting:

  - When `pid` is not disabled this represents the path to the PID file.
  - If `-p` or `--pid` is passed to the controller program, then this value is ignored in favor of the value passed along the command line.

  The `session` setting:

  - Represents the default way in which child processes are executed.
  - This default can be overridden by individual Rules.
  - For `new`, Execute Rule processes in a new session setting the process group to the executed process' id (making the executed process a `controlling terminal`).
  - For `same`, Execute Rule processes in the same session where the process group is set to the parent process id.

  The `show` setting:

  - Represents the way Entry processing presents information to the screen.
  - This applies only to the Entry and Rule processing itself and does not handle the output of programs and scripts being executed by some Entry or Rule.
  - The following show options are supported: `normal` and `init`.
  - For `normal`, will not report the start or stop of some Entry or Rule execution but will report any errors or warnings as appropriate.
  - For `init`, will report when starting programs and may include reporting success and failure status.

  The `timeout` setting:

  - Represents the default timeouts for the Entry.
  - See the `timeout` Action below for details.

The `main` item Object:

- Each `item` supports the following Action Names: `consider`, `execute`, `failsafe`, `freeze`, `item`, `kill`, `pause`, `reload`, `restart`, `ready`, `resume`, `start`, `stop`, and `timeout`.
- Of those types, the following are considered a `rule` Action: `freeze`, `kill`, `pause`, `reload`, `restart`, `resume`, `start`, `stop`, and `thaw`.

- The `consider` Item Action:

  - A special case of a `rule` Action.
  - All Action Parameters are the same as with the `rule` Action Parameters.
  - The difference is that `consider` is only processed (instead of being processed and executed) and when some `rule` Action designates that this consideration is required (via `need`), wanted (via `want`), or wished for (via `wish`) from the within the Rule file.
  - If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as `asynchronous`, for example).
  - If this is determined not to be executed, then this `consider` is ignored as if it was never there in the first place.

  The `execute` Item Action:

  - Execute into the specified program.
  - On successful execution, the controller program will no longer be running and will be replaced with the designated program.
  - This Item Action is only supported when operating in `program` mode.

  The `failsafe` Item Action:

  - Accepts only a valid Item Name in which will be executed when a failure is detected.
  - Only a single `failsafe` Item Action may function at a time.
  - Each successive `failsafe` Item Action specified replaces the previously defined `failsafe` Item Action (in a top-down manner).
  - When operating in `failsafe`, the `require` Item Action is ignored (given that it is meaningless once operating in `failsafe` mode).

  The `failsafe` Item Action:

  - Accepts only a valid Item Name in which will be executed when a failure is detected.
  - Only a single `failsafe` Item Action may function at a time.
  - Each successive `failsafe` Item Action specified replaces the previously defined `failsafe` Item Action (in a top-down manner).
  - When operating in `failsafe`, the `require` Item Action is ignored (given that it is meaningless once operating in `failsafe` mode).

  The `freeze` Item Action:

  - A `rule` Action for freezing some Control Group.
  - This Item Action will process the `freeze` inner Content of the named Rule.
  - This is specific to Control Groups and is not yet fully implemented.
  - Once implemented this documentation will need to be updated and clarified.

  The `item` Item Action:

  - Accepts only a valid Item Name in which will be immediately executed.
  - Any valid Item Name, except for the reserved `main`, may be used.

  The `kill` Item Action:

  - A `rule` Action for forcibly terminating some process.
  - This Item Action will process the `kill` inner Content of the named Rule.

  The `pause` Item Action:

  - A `rule` Action for pausing some process.
  - This Item Action will process the `pause` inner Content of the named Rule.

  The `reload` Item Action:

  - A `rule` Action for pausing some process.
  - This Item Action will process the `reload` inner Content of the named Rule.

  The `restart` Item Action:

  - A `rule` Action for pausing some process.
  - This Item Action will process the `restart` inner Content of the named Rule.

  The `resume` Item Action:

  - A `rule` Action for pausing some process.
  - This Item Action will process the `resume` inner Content of the named Rule.

  The `ready` Item Action:

  - Instructs the controller program when it is safe to perform normal tasks, such as creating the PID file.
  - When not specified, the state is always assumed to be ready.
  - For example, the controller program may be used as a full blown `init` replacement and therefore may need to mount the `/var/run/` directory.
  - If the PID file is created at program start, then the `/var/run/`controller.pid would be written before the `/var/run/` directory is ready.
  - This could be a problem, such as on a read-only file system the PID creation fails and controller bails out on error.
  - Adding `ready` essentially specifies a point in time in the Entry in which things are expected to be safe for such basic operations.
  - When the optional `wait` is provided, then `ready` will wait for all currently started asynchronous processes to complete before operating.

  The `start` Item Action:

  - A `rule` Action for pausing some process.
  - This Item Action will process the `start` inner Content of the named Rule.

  The `stop` Item Action:

  - A `rule` Action for pausing some process.
  - This Item Action will process the `stop` inner Content of the named Rule.

  The `thaw` Item Action:

  - A `rule` Action for unfreezing some Control Group.
  - This Item Action will process the `thaw` inner Content of the named Rule.
  - This is specific to Control Groups and is not yet fully implemented.
  - Once implemented this documentation will need to be updated and clarified.

  The `timeout` Item Action:

  - (This is not currently fully implemented, only `exit` is implemented.)
  - Provides default global settings for each of the four special situations: `exit`, `kill`, `start`, and `stop`.
  - Each of these may only have a single one exist at a time (one `exit`, one `kill`, one `start`, and one `stop`).
  - Each successive `timeout` Item Action, specific to each Action Name (such as `start`), specified replaces the previously defined `timeout` Action (in a top-down manner).
  - The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds).
  - For `kill`, this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule).
  - For `start`, this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed.
  - For `stop`, this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed.
  - If the second Content is not specified, then this disables the type (prevents the specified timeout action).
  - For `exit`, this represents the number of MegaTime to wait when the Controller program is exiting (such as having received a terminate signal).
  - In this case, a terminate signal is sent to all child processes.
  - The `exit` timeout represents the amount of time to wait after sending the terminate signal before sending a kill signal to each child process still running.
  - When disabled, the program will not send a kill signal will continue running until all child processes to terminate.
  - The `exit` timeout does not get applied to any Rule.

## Entry Rule Documentation

There are multiple Entry Actions that are considered `rule` Actions. These are: `freeze`, `kill`, `pause`, `reload`, `restart`, `resume`, `start`, `stop`, and `thaw`.

The `rule` Actions immediately execute a named Rule file.

- The first Action Parameter represents the Rule directory, which is a relative directory path the Rule file is to be found.

  - Do not include leading or trailing slashes.
  - This is relative to the settings rules directory.

- The second Action Parameter represents the base name for the Rule file, without the file extension.

  - This must not have any directory paths.

- The remaining Action Parameters may be specified in any order\:

  - `asynchronous`: Designates that execution will not block (wait).
  - `require`: Designates that this Rule must succeed or trigger execution of failsafe.
  - `wait`: Designates that this Rule will not execute until all other Actions before this (including `asynchronous` ones) finish executing (in a top-down manner).

The full path to the `rule` is relative to the settings, such that if the controller Rule settings are found in `/etc/controller/rules/`, then for a directory called `[directory]` and a Rule base name of `[base_name]`, the resulting path would be: `/etc/controller/rules/[directory]/[base_name].rule`.

It is important to note that for any given `rule`, execution within that `rule` may be internally asynchronous (even if the `rule` is synchronous). For example, a service that is often called a daemon will execute in the background. Until that execution succeeds and the daemon goes into the background the representing Rule will block. After the daemon goes into the background, then the representing Rule will no longer block and be fully executed.