This is the first pass at the specification, based off of the previous "init" implicit specification.
Two new FSS specifications added but not yet documented.
--- /dev/null
+# fss-0002
+
+Entry Documentation:
+ This describes the intent and purpose of the entry file settings.
+
+ 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 almost always meant for booting a system.
+
+ The "main" Basic List Object is always executed first (Therefore "main" is required).
+ All other Basic List Objects are not executed unless either a "category" or a "failsafe" specifies the Object.
+ Execution of all Basic List Objects is top-down.
+
+ Inside each list there are additional commands: "category", "failsafe", "rule", and "timeout".
+
+ The "category" command accepts only a valid Basic List Object in which will be immediately executed.
+
+ The "failsafe" command accepts only a valid Basic List Object in which will be executed when a failure is detected.
+ Only a single "failsafe" command may exist at a time so when specified multiple times.
+ Each time a "failsafe" command is specified, it replaces the previous "failsafe" command.
+
+ The "only" command represents a list of directory names that are allowed to be "controlled" by the "control" program from user-space.
+ To allow all rules in all directories, do not specify the "omit" command.
+ To disallow all rules in all directories, specify this command and provide no directoies.
+ Each directory is relative to the settings, such that if the controller rule settings are found in "/etc/controller/rules/", then for a directory called "[directory]" would have a resulting path of: "/etc/controller/rules/[directory]/".
+
+ The "rule" command immediately executes a given rule file.
+ The first Content represents the directory in which the rule is to be found (do not include leading or trailing slashes in the name).
+ The second Content represents the basename for the file representing the desired rule.
+ The directory 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 basename of "[filename]", the resulting path would be: "/etc/controller/rules/[directory]/[filename].rule"
+ The remaining Content 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 existing "asynchronous" executions complete.
+
+ It is important to note that for any given rule, execution within that rule may be internally asynchronous.
+ 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 return success.
+
+ The "timeout" command provides default global settings for each of the three special situations: "start", "stop", and "kill".
+ Each of these may only have a single one exist at a time (one "start", one "stop", and one "kill").
+ Each of these will replace any previously specified setting.
+ Each of these accepts a single Content that is a 0 or greater whole number representing the number of milliseconds.
+ For "start", this represents the number of milliseconds 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 milliseconds to wait after stopping some rule before assuming something went wrong and the rule is returned as failed.
+ For "kill", this represents the number of milliseconds to wait after stopping some rule and that rule has not yet stopped to forcefully stop the rule (aka kill the rule).
+ The timeouts are generally only valid for services such as daemon services.
+ A value of 0 disables this (prevents any action).
--- /dev/null
+# fss-0002
+
+Rule Documentation:
+ This describes the intent and purpose of the rule file settings.
+
+ A rule file, such as "ssh.rule", is intended to desginate what to execute.
+
+ The rule file is read top-down, except for the outer most list "settings", which is intended to store settings data for this rule.
+ Multiple outer most list Objects may be specified and they are executed as provided, in a top-down manner.
+
+ The "settings" outer most list Object has the following FSS-0001 (Extended) Content:
+ "name": A name used to represent this rule, which is printing to the user, screen, logs, etc...
+ "pid": A path to a directory where the PID file is expected to be stored in.
+ @todo: consider adding "path" to allow specifying a custom environment PATH variable (or even go a step further and instead provide "environment" or "variable").
+
+ The "command" outer most part provides a simple command to run under the different circumstances: "start", "stop", "restart", and "reload".
+ A "command" always operates in the foreground.
+
+ The "service" outer most part provides a "command" accompanied with a PID file (Process Identifier file).
+ Unlike the "command", a "service" always operates in the background.
+
+ The "script" outer most part provides a series of lines to be executed by a (Bash) script.
+ This "script" operates in the foreground, but individual things done within the script may operate in foreground or background.
+ The last return state is treated as an error, so be sure to finish the script with a return code of 0 to designate no error and any other whole number, such a 1, to designate an error.
+ Therefore passing "exit 1" would return as an error and passing "exit 0" would return as a success.
+
+ There are four primary inner Content to perform: "restart", "reload", "start", and "stop".
+
+ The "start" Content is performed whenever this rule is executed using the start action.
+ The "stop" Content is performed whenever this rule is executed using the stop action.
+ The "restart" Content is performed whenever this rule is executed using the restart action.
+ The "reload" Content is performed whenever this rule is executed using the reload action.
+
+ When "restart" Content is not provided, then "start" and "stop" is called when the rule is executed using the restart action, if both "start" and "stop" are provided.
+ When "reload", "start", or "stop" Content are not provided, then no respective action is peformed.
+
+ The "group" inner Content, an associated "command", "service", or "script" are executed with that group ID or group name.
+ The "user" inner Content, an associated "command", "service", or "script" are executed with that user ID or user name.
+ The "group" and "user" can only be switched to if the user this controller program being operated under is allowed to switch to.
+
+ The "create" Content designates that this controller program to create the PID file after successfully starting the service.
+ The "program" Content designates that the called program will provide the PID file after successfully starting the service.
+ For both "create" and "program" the PID file is expected to only exist on success or failure and the existence thereof designates the success or failure rate.
--- /dev/null
+# fss-0002
+
+Entry Specification:
+ The "rule" files follow the FSS-0005 (Somewhat Basic List) format.
+
+ An entry file name is expected to have the file extension ".entry".
+
+ The outer most part, which is essentially FSS-0002 (Basic List), has the following Objects\:
+ "main": required.
+
+ The entry file may have any other valid Object, only the above have reserved uses.
+
+ Inside each Basic List are essentially the following, FSS-0001 (Extended), Objects\:
+ "category": One Content that is a valid Object name, except for the reserved "main".
+ "controlled": One Content that is a valid Object name, except for the reserved "main".
+ "failsafe": One Content that is a valid relative rule file name without the ".rule" extension.
+ "only": Zero or more Content.
+ "rule": One 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": Two Content.
+ The first being one of\:
+ - start
+ - stop
+ - kill
+ The second being a positive whole number or 0.
--- /dev/null
+# fss-0002
+
+Rule Specification:
+ The "rule" files follow the FSS-000D (Basic Rule) format.
+
+ A rule file name is expected to have the file extension ".rule".
+
+ The outer most part, which is essentially FSS-0002 (Basic List), has the following Objects\:
+ "settings": Required.
+ "command": A Basic List of FSS-0001 (Extended) Object and Content, supporting the following Objects: "group", "restart", "reload", "start", "stop", and "user".
+ "script": A Basic List of FSS-0003 (Extended List) Object and Content, supporting the following Objects: "restart", "reload", "start", and "stop" and A Basic List of FSS-0001 (Extended) Object and Content, supporting the following: "group" and "user".
+ "service": A Basic List of FSS-0001 (Extended) Object and Content, supporting the following Objects: ""create", "group", "program", "restart", "reload", "start", "stop", "timeout", and "user".
+
+ For the above Basic List Objects, "main" may be specified only once whereas the others may be specifed multiple times.
+
+ The "settings" outer most list Object has the following FSS-0001 (Extended) Content:
+ "name": One Content, must have at least 1 non-whitespace printing character.
+ "pid": One Content representing the path to a PID file directory.
+
+ For the inner parts, these are the Extended Objects\:
+ "create": One Content representing the path to a PID file.
+ "program": One Content representing the path to a PID file.
+ "group": One Content representing a group name or group id.
+ "restart": One or more Content representing a program to and its arguments.
+ "reload": One or more Content representing a program to and its arguments.
+ "start": One or more Content representing a program to and its arguments.
+ "stop": One or more Content representing a program to and its arguments.
+ "user": One Content representing a user name or user id.
+
+ For the inner parts, these are the Extended List Objects\:
+ "restart": A list repesenting the contents of a (Bash) shell script.
+ "reload": A list repesenting the contents of a (Bash) shell script.
+ "start": A list repesenting the contents of a (Bash) shell script.
+ "stop": A list repesenting the contents of a (Bash) shell script.
--- /dev/null
+# fss-0002
+
+Featureless Settings Specification: 000D - Basic Rule:
+ @todo: document this.
+ This should be a special case that has an FSS Basic List on the outside and conditional types on the inside.
+ The conditional types are context-specific and not defined by this specification.
+ This specification only defines that they exist and not when/how they exist.
--- /dev/null
+# fss-0002
+
+Featureless Settings Specification: 000E - Extended Rule:
+ @todo: document this.
+ This should be a special case that has an FSS Extended List on the outside and conditional types on the inside.
+ The conditional types are context-specific and not defined by this specification.
+ This specification only defines that they exist and not when/how they exist.
- fss-000A: Extended Reverse Mapping
- fss-000B: Simple List
- fss-000C: Iki Text
+ - fss-000D: Basic Rule
+ - fss-000E: Extended Rule
projects / fll / commitdiff