From 0092a9a53938bac0ab3b3bd5ce778961aa305abe Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Wed, 11 Nov 2020 22:43:31 -0600 Subject: [PATCH] Progress: begin adding the controller program, starting with the specification and relating documentation. 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. --- level_3/controller/documents/entry.txt | 48 +++++++++++++++++++++++++++++ level_3/controller/documents/rule.txt | 43 ++++++++++++++++++++++++++ level_3/controller/specifications/entry.txt | 30 ++++++++++++++++++ level_3/controller/specifications/rule.txt | 34 ++++++++++++++++++++ specifications/fss-000D.txt | 7 +++++ specifications/fss-000E.txt | 7 +++++ specifications/fss.txt | 2 ++ 7 files changed, 171 insertions(+) create mode 100644 level_3/controller/documents/entry.txt create mode 100644 level_3/controller/documents/rule.txt create mode 100644 level_3/controller/specifications/entry.txt create mode 100644 level_3/controller/specifications/rule.txt create mode 100644 specifications/fss-000D.txt create mode 100644 specifications/fss-000E.txt diff --git a/level_3/controller/documents/entry.txt b/level_3/controller/documents/entry.txt new file mode 100644 index 0000000..454440d --- /dev/null +++ b/level_3/controller/documents/entry.txt @@ -0,0 +1,48 @@ +# 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). diff --git a/level_3/controller/documents/rule.txt b/level_3/controller/documents/rule.txt new file mode 100644 index 0000000..d2b5693 --- /dev/null +++ b/level_3/controller/documents/rule.txt @@ -0,0 +1,43 @@ +# 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. diff --git a/level_3/controller/specifications/entry.txt b/level_3/controller/specifications/entry.txt new file mode 100644 index 0000000..3f4fa4c --- /dev/null +++ b/level_3/controller/specifications/entry.txt @@ -0,0 +1,30 @@ +# 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. diff --git a/level_3/controller/specifications/rule.txt b/level_3/controller/specifications/rule.txt new file mode 100644 index 0000000..0f80de0 --- /dev/null +++ b/level_3/controller/specifications/rule.txt @@ -0,0 +1,34 @@ +# 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. diff --git a/specifications/fss-000D.txt b/specifications/fss-000D.txt new file mode 100644 index 0000000..402a66e --- /dev/null +++ b/specifications/fss-000D.txt @@ -0,0 +1,7 @@ +# 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. diff --git a/specifications/fss-000E.txt b/specifications/fss-000E.txt new file mode 100644 index 0000000..cf43591 --- /dev/null +++ b/specifications/fss-000E.txt @@ -0,0 +1,7 @@ +# 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. diff --git a/specifications/fss.txt b/specifications/fss.txt index 331bade..535d249 100644 --- a/specifications/fss.txt +++ b/specifications/fss.txt @@ -131,3 +131,5 @@ Featureless Settings Specifications: - fss-000A: Extended Reverse Mapping - fss-000B: Simple List - fss-000C: Iki Text + - fss-000D: Basic Rule + - fss-000E: Extended Rule -- 1.8.3.1