Controller Entry Specification

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.

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.