From c617468a72c34ceba7416be1e1fe71325cb317a8 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Sun, 8 Jan 2023 09:54:02 -0600 Subject: [PATCH] Cleanup: Apply IKI formatting to controller specifications and documentation. --- level_3/controller/documents/actions.txt | 36 ++-- level_3/controller/documents/entry.txt | 246 +++++++++++++------------- level_3/controller/documents/exit.txt | 200 ++++++++++----------- level_3/controller/documents/packet.txt | 58 +++--- level_3/controller/documents/rule.txt | 252 ++++++++++++++------------- level_3/controller/documents/simulate.txt | 28 +-- level_3/controller/specifications/entry.txt | 154 ++++++++-------- level_3/controller/specifications/exit.txt | 134 +++++++------- level_3/controller/specifications/packet.txt | 72 ++++---- level_3/controller/specifications/rule.txt | 162 ++++++++--------- level_3/controller/specifications/task.txt | 9 +- 11 files changed, 710 insertions(+), 641 deletions(-) diff --git a/level_3/controller/documents/actions.txt b/level_3/controller/documents/actions.txt index 8fffb08..bbe70f5 100644 --- a/level_3/controller/documents/actions.txt +++ b/level_3/controller/documents/actions.txt @@ -1,7 +1,13 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named actions.txt) can be more easily read using the following iki_read commands: +# iki_read actions.txt +Q -w -W code '"' '"' +# +# To read the "Actions Documentation" section of this file, use this command sequence: +# fss_basic_list_read actions.txt +Q -cn "Actions Documentation" | iki_read +Q -w -W code '"' '"' +# Actions Documentation: This describes the intent and purpose of the actions provided for individual Rules (or things related to a Rule). @@ -10,25 +16,25 @@ Actions Documentation: One should expect an Action to operate as described here but the system administrator or distributor is fully capable of doing something different. For those doing something different, appropriate documentation is suggested. - These actions should be usable by any "control" program that communicates with this "controller" program. - Should any "control" or "controller" program implementation not support any particular Action for any reason, one should report that the Action is unsupported. + These actions should be usable by any code:"control" program that communicates with this code:"controller" program. + Should any code:"control" or code:"controller" program implementation not support any particular Action for any reason, one should report that the Action is unsupported. - Freeze Action\: The Freeze Action is an extension of a Control Group. - This is internal to the "controller" program and is not customizable via any Rule file. - For a customizable "freeze"-like capability, look into the Pause and Resume Actions. + This is internal to the code:"controller" program and is not customizable via any Rule file. + For a customizable code:"freeze"-like capability, look into the Pause and Resume Actions. This is the complement of the Thaw Action. This designates that a processes Control Group is to be frozen. - All Rules (or any process not controlled by the "controller") that is within the same Control Group will be frozen. - (@todo consider instead designing this around the Control Groups instead of a "rule".) + All Rules (or any process not controlled by the code:"controller") that is within the same Control Group will be frozen. + (@todo consider instead designing this around the Control Groups instead of a code:"rule".) (This documentation will likely change with consideration to the above @todo once this gets implemented.) - This must not attempt to freeze (or unfreeze) the Control Group that the "controller" belongs to. + This must not attempt to freeze (or unfreeze) the Control Group that the code:"controller" belongs to. Therefore, if a Rule does not specify a Control Group, then it is likely that the Freeze Action will be unsupported for that Rule/Control Group. - Kill Action\: - Forcefully terminate some process controlled by the "controller". + Forcefully terminate some process controlled by the code:"controller". This action cannot be blocked and it is recommended to use a Stop Action instead for a more proper termination. - Pause Action\: @@ -48,7 +54,7 @@ Actions Documentation: - Reload Action\: The Reload Action will perform the Reload Action designated in some Rule file. Ideally this should inform some process to perform its own reload routines. - Many programs often differentiate the concept "reload" from the concept "restart" in that the program remains running during a "reload". + Many programs often differentiate the concept code:"reload" from the concept "restart" in that the program remains running during a code:"reload". - Start Action\: The Start Action will perform the Start Action designated in some Rule file. @@ -64,14 +70,14 @@ Actions Documentation: - Thaw Action\: The Thaw Action is an extension of a Control Group. - This is internal to the "controller" program and is not customizable via any Rule file. - For a customizable "thaw"-like capability, look into the "pause" and "resume" Actions. + This is internal to the code:"controller" program and is not customizable via any Rule file. + For a customizable code:"thaw"-like capability, look into the code:"pause" and code:"resume" Actions. This is complemented by the Freeze Action. This designates that a processes Control Group is to be unfrozen. - All Rules (or any process not controlled by the "controller") that is within the same Control Group will be unfrozen. - (@todo consider instead designing this around the Control Groups instead of a "rule".) + All Rules (or any process not controlled by the code:"controller") that is within the same Control Group will be unfrozen. + (@todo consider instead designing this around the Control Groups instead of a code:"rule".) (This documentation will likely change with consideration to the above @todo once this gets implemented.) - This must not attempt to thaw (or unthaw) the Control Group that the "controller" belongs to. + This must not attempt to thaw (or unthaw) the Control Group that the code:"controller" belongs to. Therefore, if a Rule does not specify a Control Group, then it is likely that the Thaw Action will be unsupported for that Rule/Control Group. diff --git a/level_3/controller/documents/entry.txt b/level_3/controller/documents/entry.txt index 602cf78..891a134 100644 --- a/level_3/controller/documents/entry.txt +++ b/level_3/controller/documents/entry.txt @@ -1,203 +1,209 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named entry.txt) can be more easily read using the following iki_read commands: +# iki_read entry.txt +Q -r PID PID -w -WW code '"' '"' +# +# To read the "Entry Documentation" section of this file, use this command sequence: +# fss_basic_list_read entry.txt +Q -cn "Entry Documentation" | iki_read +Q -r PID PID -w -W code '"' '"' +# 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. + An Entry file, such as code:"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. + The code:"main" Item Object is always executed first (Therefore code:"main" is both reserved and required). + All other Basic List Objects are not executed unless either an code:"item" or a code:"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. + - The code:"settings" item Object\: + Represents Entry settings and is not an code:"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 following settings are available: code:"control", code:"control_group", code:"control_mode", code:"control_user", code:"define", code:"mode", code:"parameter", code:"pid", code:"pid_file", code:"session", code:"show". - - The "control" setting\: + - The code:"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. + A relative path is relative to the Controller PID:"Process Identifier" 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. + This socket file is only created once code:"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. + Providing code:"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. + When code:"readonly", the group, mode, and user are also not processed effectively resulting in the code:"control_group", code:"control_mode", and code:"control_user" settings being ignored. Future versions might expand this into supporting network addresses in addition to socket files. - - The "control_group" setting\: + - The code:"control_group" setting\: Represents the group name or group ID to assign to the socket file as the group. - - The "control_mode" setting\: + - The code:"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". + This could either be the string version that might look like code:"u+rw-x,g+r-wx,o-rwx" or a numeric value like code:"0750". - - The "control_user" setting\: + - The code:"control_user" setting\: Represents the user name or user ID to assign to the socket file as the owner. - - The "define" setting\: + - The code:"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". + Example IKI variable substitution: for code:"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. + All environment variables, including those defined using this, must be in the code:"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\: + - The code:"mode" setting\: Represents the mode in which the Entry is operating in. - The following modes are supported: "program" and "service". + The following modes are supported: code:"program" and code:"service". - - The "program" mode\: + - The code:"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). + Will call the code:"exit" with the same name as this Entry, but with the extension code:"exit", such as code:"default.exit". + Supports the Item Action code:"execute" to execute a program (switching the code:"controller" program entirely with the executed process). - - The "service" mode\: + - The code:"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". + Will call the code:"exit" with the same name as this Entry, but with the extension code:"exit", such as code:"default.exit". + Does not support the Item Action code:"execute". This is the default mode. - - The "parameter" setting\: + - The code:"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". + Example IKI variable substitution: for code:"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 code:"pid" setting\: + Represents how the Entry PID:"Process Identifier" file is generated or not. + The following modes are supported: code:"disable", code:"require", and code:"ready". + For code:"disable", not PID:"Process Identifier" file representing the Entry is created. + For code:"require", check to see if the PID:"Process Identifier" file exists for an Entry at startup and then when code:"ready" create a PID:"Process Identifier" file, display error on PID:"Process Identifier" file already exists or on failure and then fail. + For code:"ready", when code:"ready" create a PID:"Process Identifier" file, display error on failure and then fail (does not check if PID:"Process Identifier" 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 code:"pid_file" setting\: + When code:"pid" is not disabled this represents the path to the PID:"Process Identifier" file. + If code:"-p" or code:"--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\: + - The code:"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. + For code:"new", Execute Rule processes in a new session setting the process group to the executed process' id (making the executed process a code:"controlling terminal"). + For code:"same", Execute Rule processes in the same session where the process group is set to the parent process id. - - The "show" setting\: + - The code:"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 following show options are supported: code:"normal" and code:"init". + For code:"normal", will not report the start or stop of some Entry or Rule execution but will report any errors or warnings as appropriate. + For code:"init", will report when starting programs and may include reporting success and failure status. - - The "timeout" setting\: + - The code:"timeout" setting\: Represents the default timeouts for the Entry. - See the "timeout" Action below for details. + See the code:"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 code:"main" item Object\: + Each code:"item" supports the following Action Names: code:"consider", code:"execute", code:"failsafe", code:"freeze", code:"item", code:"kill", code:"pause", code:"reload", code:"restart", code:"ready", code:"resume", code:"start", code:"stop", and code:"timeout". + Of those types, the following are considered a code:"rule" Action: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"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 code:"consider" Item Action\: + A special case of a code:"rule" Action. + All Action Parameters are the same as with the code:"rule" Action Parameters. + The difference is that code:"consider" is only processed (instead of being processed and executed) and when some code:"rule" Action designates that this consideration is required (via code:"need"), wanted (via code:"want"), or wished for (via code:"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 code:"asynchronous", for example). + If this is determined not to be executed, then this code:"consider" is ignored as if it was never there in the first place. - - The "execute" Item Action\: + - The code:"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. + This Item Action is only supported when operating in code:"program" mode. - - The "failsafe" Item Action\: + - The code:"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). + Only a single code:"failsafe" Item Action may function at a time. + Each successive code:"failsafe" Item Action specified replaces the previously defined code:"failsafe" Item Action (in a top-down manner). + When operating in code:"failsafe", the code:"require" Item Action is ignored (given that it is meaningless once operating in code:"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. + - The code:"freeze" Item Action\: + A code:"rule" Action for freezing some Control Group. + This Item Action will process the code:"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\: + - The code:"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. + Any valid Item Name, except for the reserved code:"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 code:"kill" Item Action\: + A code:"rule" Action for forcibly terminating some process. + This Item Action will process the code:"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 code:"pause" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"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 code:"reload" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"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 code:"restart" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"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 code:"resume" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"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. + - The code:"ready" Item Action\: + Instructs the controller program when it is safe to perform normal tasks, such as creating the PID:"Process Identifier" 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. + For example, the controller program may be used as a full blown code:"init" replacement and therefore may need to mount the /var/run/ directory. + If the PID:"Process Identifier" 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:"Process Identifier" creation fails and controller bails out on error. + Adding code:"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 code:"wait" is provided, then code:"ready" will wait for all currently started asynchronous processes to complete before operating. + + - The code:"start" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"start" inner Content of the named Rule. + + - The code:"stop" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"stop" inner Content of the named Rule. + + - The code:"thaw" Item Action\: + A code:"rule" Action for unfreezing some Control Group. + This Item Action will process the code:"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 code:"timeout" Item Action\: + (This is not currently fully implemented, only code:"exit" is implemented.) + Provides default global settings for each of the four special situations: code:"exit", code:"kill", code:"start", and code:"stop". + Each of these may only have a single one exist at a time (one code:"exit", one code:"kill", one code:"start", and one code:"stop"). + Each successive code:"timeout" Item Action, specific to each Action Name (such as code:"start"), specified replaces the previously defined code:"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. + For code:"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 code:"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 code:"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). + For code:"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. + The code:"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. + The code:"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". + There are multiple Entry Actions that are considered code:"rule" Actions. + These are: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw". - The "rule" Actions immediately execute a named Rule file. + The code:"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. @@ -206,13 +212,13 @@ Entry Rule Documentation: - 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). + - code:"asynchronous": Designates that execution will not block (wait). + - code:"require": Designates that this Rule must succeed or trigger execution of failsafe. + - code:"wait": Designates that this Rule will not execute until all other Actions before this (including code:"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". + The full path to the code:"rule" is relative to the settings, such that if the controller Rule settings are found in code:"/etc/controller/rules/", then for a directory called code:"[directory]" and a Rule base name of code:"[base_name]", the resulting path would be: code:"/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). + It is important to note that for any given code:"rule", execution within that code:"rule" may be internally asynchronous (even if the code:"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. diff --git a/level_3/controller/documents/exit.txt b/level_3/controller/documents/exit.txt index 0ac3123..bfa4372 100644 --- a/level_3/controller/documents/exit.txt +++ b/level_3/controller/documents/exit.txt @@ -1,157 +1,163 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named exit.txt) can be more easily read using the following iki_read commands: +# iki_read exit.txt +Q -w -r PID PID -w -W code '"' '"' +# +# To read the "Exit Documentation" section of this file, use this command sequence: +# fss_basic_list_read exit.txt +Q -cn "Exit Documentation" | iki_read +Q -r PID PID -w -W code '"' '"' +# Exit Documentation: This describes the intent and purpose of an Exit file. - An Exit file, such as "default.exit", is intended to store a set of rules in which the controller will process on execution. + An Exit file, such as code:"default.exit", 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 shutting down a system. An Exit is a special variation or subset of an Entry. - - The "settings" Item Object\: - Represents Exit settings and is not an "item" that can be executed. + - The code:"settings" Item Object\: + Represents Exit settings and is not an code:"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: "pid" and "show". + The following settings are available: code:"pid" and code:"show". - - The "define" setting\: + - The code:"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". + Example IKI variable substitution: for code:"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. + All environment variables, including those defined using this, must be in the code:"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 Exit. - - The "parameter" setting\: + - The code:"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". + Example IKI variable substitution: for code:"parameter hello world", the associated IKI variable would look like: parameter:"hello". This is only expanded within any Rule operated on by this Exit. - - The "pid" setting\: - Represents how the Exit PID file is generated or not. - The following modes are supported: "disable", "require", and "ready". - For "disable", not PID file representing the Exit is created. - For "require", check to see if the PID file exists for an Exit 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 code:"pid" setting\: + Represents how the Exit PID:"Process Identifier" file is generated or not. + The following modes are supported: code:"disable", code:"require", and code:"ready". + For code:"disable", not PID:"Process Identifier" file representing the Exit is created. + For code:"require", check to see if the PID:"Process Identifier" file exists for an Exit at startup and then when code:"ready" create a PID:"Process Identifier" file, display error on PID:"Process Identifier" file already exists or on failure and then fail. + For code:"ready", when code:"ready" create a PID:"Process Identifier" file, display error on failure and then fail (does not check if PID:"Process Identifier" file exists). - - The "show" setting\: + - The code:"show" setting\: Represents the way Exit processing presents information to the screen. This applies only to the Exit and Rule processing itself and does not handle the output of programs and scripts being executed by some Exit or Rule. - The following show options are supported: "normal" and "init". - For "normal", will not report the start or stop of some Exit 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 following show options are supported: code:"normal" and code:"init". + For code:"normal", will not report the start or stop of some Exit or Rule execution but will report any errors or warnings as appropriate. + For code:"init", will report when starting programs and may include reporting success and failure status. - - The "timeout" setting\: + - The code:"timeout" setting\: Represents the default timeouts for the Exit. - See the "timeout" Action below for details. + See the code:"timeout" Action below for details. - - 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. + - The code:"main" Item Object\: + Is always executed first (Therefore code:"main" is both reserved and required). + All other Basic List Objects are not executed unless either an code:"item" or a code:"failsafe" specifies a valid Item name. Execution of all Items are top-down. - 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". + Each code:"item" supports the following Action Names: code:"consider", code:"execute", code:"failsafe", code:"freeze", code:"item", code:"kill", code:"pause", code:"reload", code:"restart", code:"ready", code:"resume", code:"start", code:"stop", and code:"timeout". + Of those types, the following are considered a code:"rule" Action: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"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 code:"consider" Item Action\: + A special case of a code:"rule" Action. + All Action Parameters are the same as with the code:"rule" Action Parameters. + The difference is that code:"consider" is only processed (instead of being processed and executed) and when some code:"rule" Action designates that this consideration is required (via code:"need"), wanted (via code:"want"), or wished for (via code:"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 code:"asynchronous", for example). + If this is determined not to be executed, then this code:"consider" is ignored as if it was never there in the first place. - - The "execute" Item Action\: + - The code:"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. + This Item Action is only supported when operating in code:"program" mode. - - The "failsafe" Item Action\: + - The code:"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). + Only a single code:"failsafe" Item Action may function at a time. + Each successive code:"failsafe" Item Action specified replaces the previously defined code:"failsafe" Item Action (in a top-down manner). + When operating in code:"failsafe", the code:"require" Item Action is ignored (given that it is meaningless once operating in code:"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. + - The code:"freeze" Item Action\: + A code:"rule" Action for freezing some Control Group. + This Item Action will process the code:"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\: + - The code:"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. + Any valid Item Name, except for the reserved code:"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 code:"kill" Item Action\: + A code:"rule" Action for forcibly terminating some process. + This Item Action will process the code:"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 code:"pause" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"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 code:"reload" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"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 code:"restart" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"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 code:"resume" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"resume" inner Content of the named Rule. - - The "ready" Action\: - Instructs the controller program when it is safe to perform normal tasks, such as creating the PID file. + - The code:"ready" Action\: + Instructs the controller program when it is safe to perform normal tasks, such as creating the PID:"Process Identifier" 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 Exit 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. + For example, the controller program may be used as a full blown code:"init" replacement and therefore may need to mount the /var/run/ directory. + If the PID:"Process Identifier" 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:"Process Identifier" creation fails and controller bails out on error. + Adding code:"ready" essentially specifies a point in time in the Exit in which things are expected to be safe for such basic operations. + When the optional code:"wait" is provided, then code:"ready" will wait for all currently started asynchronous processes to complete before operating. + + - The code:"start" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"start" inner Content of the named Rule. + + - The code:"stop" Item Action\: + A code:"rule" Action for pausing some process. + This Item Action will process the code:"stop" inner Content of the named Rule. + + - The code:"thaw" Item Action\: + A code:"rule" Action for unfreezing some Control Group. + This Item Action will process the code:"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 code:"timeout" Item Action\: + (This is not currently fully implemented, only code:"exit" is implemented.) + Provides default global settings for each of the four special situations: code:"exit", code:"kill", code:"start", and code:"stop". + Each of these may only have a single one exist at a time (one code:"exit", one code:"kill", one code:"start", and one code:"stop"). + Each successive code:"timeout" Item Action, specific to each Action Name (such as code:"start"), specified replaces the previously defined code:"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. + For code:"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 code:"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 code:"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). + For code:"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. + The code:"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. + The code:"exit" timeout does not get applied to any Rule. Exit Rule Documentation: - There are multiple Exit Actions that are considered "rule" Actions. - These are: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", and "thaw". + There are multiple Exit Actions that are considered code:"rule" Actions. + These are: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw". - The "rule" Actions immediately execute a named Rule file. + The code:"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. @@ -160,13 +166,13 @@ Exit Rule Documentation: - 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). + - code:"asynchronous": Designates that execution will not block (wait). + - code:"require": Designates that this Rule must succeed or trigger execution of failsafe. + - code:"wait": Designates that this Rule will not execute until all other Actions before this (including code:"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" + The full path to the code:"rule" is relative to the settings, such that if the controller Rule settings are found in code:"/etc/controller/rules/", then for a directory called code:"[directory]" and a Rule base name of code:"[base_name]", the resulting path would be: code:"/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). + It is important to note that for any given code:"rule", execution within that code:"rule" may be internally asynchronous (even if the code:"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. diff --git a/level_3/controller/documents/packet.txt b/level_3/controller/documents/packet.txt index 9e8eee3..3a0038d 100644 --- a/level_3/controller/documents/packet.txt +++ b/level_3/controller/documents/packet.txt @@ -1,13 +1,19 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named packet.txt) can be more easily read using the following iki_read commands: +# iki_read packet.txt +Q -w -W code '"' '"' +# +# To read the "Packet Documentation" section of this file, use this command sequence: +# fss_basic_list_read packet.txt +Q -cn "Packet Documentation" | iki_read +Q -w -W code '"' '"' +# Packet Documentation: Describes how a packet is designed and intended to be used. - The "packet" is the general category in which multiple types of packets belong. - This describes the different packets based on their "type". + The code:"packet" is the general category in which multiple types of packets belong. + This describes the different packets based on their code:"type". Each packet begins with a control block and a size block followed by a payload block. @@ -21,11 +27,13 @@ Packet Documentation: This number is a single 32-bit unsigned integer. Example packet structure\: + block:" [ Control Block ] [ Size Block ] [ Payload Block ] [ 0b10000000 ] [ 0b00000000 0b00000000 0b00000100 0b11010010 ] [ size: 1229 (1234 - 5) ] + " The payload block\: - This block is represented by the FSS-000E payload specification and its structure ad use is described in the next sections. + This block is represented by the code:"FSS-000E (Payload)" specification and its structure ad use is described in the next sections. The following types of payload are received or sent\: 1) controller payload. @@ -33,41 +41,41 @@ Packet Documentation: 3) init payload. The controller payload\: - Commands being sent to the controller and their respective responses utilize a "controller" payload. + Commands being sent to the controller and their respective responses utilize a code:"controller" payload. These are pre-defined commands to rules or the controller program itself. Commands such as starting or stopping some rule, for example. A controller payload is also sent in response to a controller payload request to represent a success. - The "now" condition designates that the kexec, reboot, or shutdown is to begin immediately. - The "at" condition designates that the kexec, reboot, or shutdown is to begin once a specific date and time is reached by the system clock. - The "in" condition designates that the kexec, reboot, or shutdown is to begin once a specific amount of time is passed by the system clock since the execution of this command started. + The code:"now" condition designates that the kexec, reboot, or shutdown is to begin immediately. + The code:"at" condition designates that the kexec, reboot, or shutdown is to begin once a specific date and time is reached by the system clock. + The code:"in" condition designates that the kexec, reboot, or shutdown is to begin once a specific amount of time is passed by the system clock since the execution of this command started. - For these "time" conditions, different units of time should be supported, such as "seconds", "days", "years" as standard time, Time, or UNIX Time (Epoch Time). + For these code:"time" conditions, different units of time should be supported, such as code:"seconds", code:"days", code:"years" as standard time, Time, or UNIX Time (Epoch Time). - The normal "controller" payload commands are any valid Rule Action that performs some action. - This does not include Actions that provide some setting or configuration (such as "with_pid"). - Some of the supported commands are: "freeze", "kill", "pause", "reload", "rerun", "restart", "resume", "start", "stop", or "thaw". - Multiple commands may be sent multiple "action" headers. - The "action" headers are order sensitive, executing from top to bottom, and one does not start until the previous successfully completes. + The normal code:"controller" payload commands are any valid Rule Action that performs some action. + This does not include Actions that provide some setting or configuration (such as code:"with_pid"). + Some of the supported commands are: code:"freeze", code:"kill", code:"pause", code:"reload", code:"rerun", code:"restart", code:"resume", code:"start", code:"stop", or code:"thaw". + Multiple commands may be sent multiple code:"action" headers. + The code:"action" headers are order sensitive, executing from top to bottom, and one does not start until the previous successfully completes. - Multiple "status" headers may exist in the response so long as they each match an "action" in the request. + Multiple code:"status" headers may exist in the response so long as they each match an code:"action" in the request. - The "payload" is expected to be empty and have a length of 0 for a request. - The "payload" may have an FSS-0000 (Basic) format containing a single Object "message" to represent a message associated with an action. - Multiple "message" may exist in the response so long as they each match an "action" in the request. + The code:"payload" is expected to be empty and have a length of 0 for a request. + The code:"payload" may have an code:"FSS-0000 (Basic)" format containing a single Object code:"message" to represent a message associated with an action. + Multiple code:"message" may exist in the response so long as they each match an code:"action" in the request. The error payload\: The error payload is intended to communicate some sort of failure. The error payload is only sent in response to some request (and not in response to another response). The control (the client) is not expected to send error payloads and the controller (the service) should send an error in response to an error payload or ignore it entirely. - The "status" from the "header" designates the status code as either a status code name string or a status code number (where a number may have error and warning bits). - The "payload" will contain a NULL terminated string representing the message used to describe the error. + The code:"status" from the code:"header" designates the status code as either a status code name string or a status code number (where a number may have error and warning bits). + The code:"payload" will contain a NULL terminated string representing the message used to describe the error. The init payload\: - The init payload is intended exclusively for the "init" operation mode and is expected to only be available when running as "init". - This is used to provide special actions, namely "kexec", "reboot", and "shutdown". + The init payload is intended exclusively for the code:"init" operation mode and is expected to only be available when running as code:"init". + This is used to provide special actions, namely code:"kexec", code:"reboot", and code:"shutdown". - The "kexec" is for booting into another kernel, which may effectively be the same as a "reboot" ("kexec" is currently neither supported nor implemented). - The "reboot" is for rebooting the machine (currently not implemented). - The "shutdown" is for shutting down the machine (currently not implemented). + The code:"kexec" is for booting into another kernel, which may effectively be the same as a code:"reboot" ("kexec" is currently neither supported nor implemented). + The code:"reboot" is for rebooting the machine (currently not implemented). + The code:"shutdown" is for shutting down the machine (currently not implemented). These three commands are configurable to fire off based on conditions. diff --git a/level_3/controller/documents/rule.txt b/level_3/controller/documents/rule.txt index 892924d..8d9e1c5 100644 --- a/level_3/controller/documents/rule.txt +++ b/level_3/controller/documents/rule.txt @@ -1,147 +1,153 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named rule.txt) can be more easily read using the following iki_read commands: +# iki_read rule.txt +Q -r PID PID -w -W code '"' '"' +# +# To read the "Rule Documentation" section of this file, use this command sequence: +# fss_basic_list_read rule.txt +Q -cn "Rule Documentation" | iki_read +Q -r PID PID -w -W code '"' '"' +# Rule Documentation: This describes the intent and purpose of a Rule file. - A Rule file, such as "ssh.rule", is intended to designate what to execute. + A Rule file, such as code:"ssh.rule", is intended to designate what to execute. - The rule file is read top-down, except for the outer most list "settings", which is intended to store setting data for this rule. + The rule file is read top-down, except for the outer most list code:"settings", which is intended to store setting 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" Rule Type has the following FSS-0001 (Extended) Content\: - - "affinity": Define one or more processors to restrict this rule by with each number representing a specific processor by its id (starting at 0). - - "capability": Define a set of capabilities in which to use, using the capability "text" format (such as "= cap_chown+ep"). - - "cgroup": Define a cgroup (control group) in which everything within this rule executes under. - - "define": A single environment variable name and its associated value that is automatically exposed to processes executed within this rule. - - "engine": An executable name of a script, such as "bash", to use for the "script" Rule Type (which likely defaults to "bash" if not specified). - - "environment": A set of environment variables to expose to the processes executed within this rule (PATH is always exposed). - - "group": A set of group names or IDs to execute as with the first group being the primary group and all remaining being supplementary groups. - - "limit": Define a resource limit to use (multiple limits may be specified, but only once for each type). - - "name": A name used to represent this rule, which is printed to the user, screen, logs, etc... - - "nice": A single niceness value to run all processes executed within this rule as (-20 gets to be greediest in CPU usage and 19 being the nicest in CPU usage). - - "on": Define a Rule Action in which a specified dependency is needed, wanted, or wished for. - - "parameter": An IKI name and its associated value for use in this rule file. - - "path": A single Content used to set a custom PATH environment variable value. - - "scheduler": A valid name of a scheduler to use followed by an optional priority number. - - "timeout": A set of timeouts to wait for in which to perform a set action or to consider failure. - - "user": A single user name or ID to execute as. - - - The "capability" setting\: + - The code:"settings" Rule Type has the following code:"FSS-0001 (Extended)" Content\: + - code:"affinity": Define one or more processors to restrict this rule by with each number representing a specific processor by its id (starting at 0). + - code:"capability": Define a set of capabilities in which to use, using the capability code:"text" format (such as code:"= cap_chown+ep"). + - code:"cgroup": Define a cgroup (control group) in which everything within this rule executes under. + - code:"define": A single environment variable name and its associated value that is automatically exposed to processes executed within this rule. + - code:"engine": An executable name of a script, such as code:"bash", to use for the code:"script" Rule Type (which likely defaults to code:"bash" if not specified). + - code:"environment": A set of environment variables to expose to the processes executed within this rule (PATH is always exposed). + - code:"group": A set of group names or IDs to execute as with the first group being the primary group and all remaining being supplementary groups. + - code:"limit": Define a resource limit to use (multiple limits may be specified, but only once for each type). + - code:"name": A name used to represent this rule, which is printed to the user, screen, logs, etc... + - code:"nice": A single niceness value to run all processes executed within this rule as (-20 gets to be greediest in CPU usage and 19 being the nicest in CPU usage). + - code:"on": Define a Rule Action in which a specified dependency is needed, wanted, or wished for. + - code:"parameter": An IKI name and its associated value for use in this rule file. + - code:"path": A single Content used to set a custom PATH environment variable value. + - code:"scheduler": A valid name of a scheduler to use followed by an optional priority number. + - code:"timeout": A set of timeouts to wait for in which to perform a set action or to consider failure. + - code:"user": A single user name or ID to execute as. + + - The code:"capability" setting\: If the user the controller program is run as does not have the desired capabilities already, they cannot be added. This essentially maintains or reduces the capabilities already available. - Due to capabilities only being a draft in the POSIX standard, one may expect "capabilities" support may not be available and in such a case this setting will do nothing. + Due to capabilities only being a draft in the POSIX standard, one may expect code:"capabilities" support may not be available and in such a case this setting will do nothing. If the dependent project (f_capability) does not have libcap support enabled, then capabilities will be unsupported by the compilation of this project. - - The "control" setting\: - The first argument is either "existing" or "new", where for "existing" the process is run inside the existing control used by the parent and when "new" the process is executed within a new control group namespace entirely. + - The code:"control" setting\: + The first argument is either code:"existing" or code:"new", where for code:"existing" the process is run inside the existing control used by the parent and when code:"new" the process is executed within a new control group namespace entirely. - - The "define" setting\: + - The code:"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". + Example IKI variable substitution: for code:"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 to be exported to the executed process. + All environment variables, including those defined using this, must be in the code:"environment" list 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. - - The "engine" setting\: - This engine is used for both "script" and "utility" Rule Types. + - The code:"engine" setting\: + This engine is used for both code:"script" and code:"utility" Rule Types. The program that engine refers to must accept a standard input pipe to be supported. Additional parameters may be passed to the engine. - - The "group" and "user" settings\: + - The code:"group" and code:"user" settings\: Only users and groups that the user the controller program is being run as is allowed to use may be used. - - The "limit" setting\: - The first parameter must be one of: "as", "core", "cpu", "data", "fsize", "locks", "memlock", "msgqueue", "nice", "nofile", "nproc", "rss", "rtprio", "rttime", "sigpending", or "stack". + - The code:"limit" setting\: + The first parameter must be one of: code:"as", code:"core", code:"cpu", code:"data", code:"fsize", code:"locks", code:"memlock", code:"msgqueue", code:"nice", code:"nofile", code:"nproc", code:"rss", code:"rtprio", code:"rttime", code:"sigpending", or code:"stack". The second parameter represents the soft limit. The third parameter represents the hard limit. This may be specified multiply times, but only once for each type. - - The "on" setting\: - The first parameter represents the Action the dependency exists under and must be one of: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", or "thaw". - The second parameter represents how the dependency is required and must be one of: "need", "want", or "wish". + - The code:"on" setting\: + The first parameter represents the Action the dependency exists under and must be one of: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", or code:"thaw". + The second parameter represents how the dependency is required and must be one of: code:"need", code:"want", or code:"wish". The third parameter is a partial path to the rule file. The fourth parameter represents the name of the rule file. - In the case of the second parameter\: - - A "need" designates that the dependent rule is required to be executed (must exist and must succeed). - - A "want" designates that the dependent rule is to be executed (may exist and if it does, then it must succeed). - - A "wish" designates that the dependent rule is to be executed (may exist and if it does, but it does not need to succeed). + - A code:"need" designates that the dependent rule is required to be executed (must exist and must succeed). + - A code:"want" designates that the dependent rule is to be executed (may exist and if it does, then it must succeed). + - A code:"wish" designates that the dependent rule is to be executed (may exist and if it does, but it does not need to succeed). - In the case of "want" and "wish", if the desired rule is either not found or is otherwise disabled, then this will not fail or otherwise block the wanting or wishing rule. + In the case of code:"want" and code:"wish", if the desired rule is either not found or is otherwise disabled, then this will not fail or otherwise block the wanting or wishing rule. - - The "path" setting\: - When specified, the PATH environment variable is automatically added to the "environment" setting. + - The code:"path" setting\: + When specified, the code:"PATH" environment variable is automatically added to the code:"environment" setting. - - The "parameter" setting\: + - The code:"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". + Example IKI variable substitution: for code:"parameter hello world", the associated IKI variable would look like: parameter:"hello". - - The "scheduler" setting\: + - The code:"scheduler" setting\: The valid range of the priority number is dependent on the scheduler. - For example, non-real-time schedulers (such as "idle") only support a value of 0 whereas real-time schedulers (such as "fifo") only support an inclusive range of 1 to 99. - Supported non-real-time schedulers are: "batch", "idle", and "other" (aka: normal/default). - Supported real-time schedulers are: "deadline", "fifo", "round_robin". + For example, non-real-time schedulers (such as code:"idle") only support a value of 0 whereas real-time schedulers (such as code:"fifo") only support an inclusive range of 1 to 99. + Supported non-real-time schedulers are: code:"batch", code:"idle", and code:"other" (aka: normal/default). + Supported real-time schedulers are: code:"deadline", code:"fifo", code:"round_robin". - - The "timeout" setting\: + - The code:"timeout" setting\: (This is not currently implemented.) - Provides settings for each of the three special situations: "kill", "start", and "stop". - Each of these may only have a single one exist at a time (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). + Provides settings for each of the three special situations: code:"kill", code:"start", and code:"stop". + Each of these may only have a single one exist at a time (one code:"kill", one code:"start", and one code:"stop"). + Each successive code:"timeout" Item Action, specific to each Action Name (such as code:"start"), specified replaces the previously defined code:"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. + For code:"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 code:"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 code:"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). - There are four available Rule Types to choose from: "command", "service", "script", and "utility". + There are four available Rule Types to choose from: code:"command", code:"service", code:"script", and code:"utility". - The "command" Rule Type provides a simple command to run under the different circumstances: "start", "stop", "restart", and "reload". - A "command" always operates in the foreground. + The code:"command" Rule Type provides a simple command to run under the different circumstances: code:"start", code:"stop", code:"restart", and code:"reload". + A code:"command" always operates in the foreground. - The "service" Rule Type provides a "command" accompanied with a PID file (Process Identifier file). + The code:"service" Rule Type provides a code:"command" accompanied with a PID:"Process Identifier" file (Process Identifier file). - The "script" Rule Type provides a series of lines to be executed by some engine, such as GNU Bash. - This "script" operates in the foreground, but individual things done within the script may operate in foreground or background. + The code:"script" Rule Type provides a series of lines to be executed by some engine, such as GNU Bash. + This code:"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. - A "script" is assumed to be in GNU Bash, which is the default expected behavior, but the specification does not explicitly require this. + Therefore passing code:"exit 1" would return as an error and passing code:"exit 0" would return as a success. + A code:"script" is assumed to be in GNU Bash, which is the default expected behavior, but the specification does not explicitly require this. Another scripting language can be used but changing this incurs the responsibility to ensure all rules are updated to the appropriate scripting language. - The "utility" Rule Type provides a "script" accompanied with a PID file (Process Identifier file). + The code:"utility" Rule Type provides a code:"script" accompanied with a PID:"Process Identifier" file (Process Identifier file). - There are nine Rule Actions used to execute ("freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", and "thaw")\: - When "restart" Object's 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" Object's Content are not provided, then no respective Action is performed. + There are nine Rule Actions used to execute ("freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw")\: + When code:"restart" Object's Content is not provided, then code:"start" and code:"stop" is called when the rule is executed using the restart Action, if both code:"start" and code:"stop" are provided. + When code:"reload", code:"start", or code:"stop" Object's Content are not provided, then no respective Action is performed. - Commands are conditionally available depending on the presence of these, such as if "stop" is not provided then "stop" (and "restart") will not be available for the "control" program(s) to use. + Commands are conditionally available depending on the presence of these, such as if code:"stop" is not provided then code:"stop" (and code:"restart") will not be available for the code:"control" program(s) to use. - Thee are additional Rule Actions not used to execute ("pid_file", "rerun", and "with")\: - - The "pid_file" Object's Content designates the path to the PID file created by the called program. + Thee are additional Rule Actions not used to execute ("pid_file", code:"rerun", and code:"with")\: + - The code:"pid_file" Object's Content designates the path to the PID:"Process Identifier" file created by the called program. - - The "rerun" Object's Content designates how to re-run a given execution Rule type. - - The first Content represents the execution type, which may be one of: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", and "thaw". + - The code:"rerun" Object's Content designates how to re-run a given execution Rule type. + - The first Content represents the execution type, which may be one of: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", and code:"thaw". - - The second Content represents when to run this re-run is triggered, which is either "success" (return code of 0) or "failure" (return code is not 0). + - The second Content represents when to run this re-run is triggered, which is either code:"success" (return code of 0) or code:"failure" (return code is not 0). - The third Content and more represent additional options for fine tuning how the re-run is Performed\: - When "delay", followed by a number of MegaTime (MT) (equivalent to milliseconds) in which to wait before attempting the re-run. - When "max", followed by a positive number or the number 0 designating the maximum number of re-runs to perform. - When "reset", the "max" re-run counter is reset for the opposite re-run when this re-run is triggered, such as\: - A "rerun start success reset" and a "rerun failure max 10", the failure counter would reset to 0 when the "success" re-run is performed and not when the "failure" re-run is performed. + When code:"delay", followed by a number of MegaTime (MT) (equivalent to milliseconds) in which to wait before attempting the re-run. + When code:"max", followed by a positive number or the number 0 designating the maximum number of re-runs to perform. + When code:"reset", the code:"max" re-run counter is reset for the opposite re-run when this re-run is triggered, such as\: + A code:"rerun start success reset" and a code:"rerun failure max 10", the failure counter would reset to 0 when the code:"success" re-run is performed and not when the code:"failure" re-run is performed. - A "max" of 0 designates that the re-run will happen infinitely. + A code:"max" of 0 designates that the re-run will happen infinitely. - - The "with" Object's Content designates special flags designating very specific behavior to be applied to any single Rule Type. + - The code:"with" Object's Content designates special flags designating very specific behavior to be applied to any single Rule Type. The following flags are supported: - - "full_path": Used only by Rule Types that execute something, wherein the entire full path is used for execution and is assigned as argument[0] (such as "/bin/bash"). - When not specified, the path provided is used and the argument[0] will be the base name (such as "bash"). - - "session_new": Execute in a new session setting the process group to the executed process' id (making the executed process a "controlling terminal"). - - "session_same": Execute in the same session where the process group is set to the parent process id. + - code:"full_path": Used only by Rule Types that execute something, wherein the entire full path is used for execution and is assigned as argument[0] (such as code:"/bin/bash"). + When not specified, the path provided is used and the argument[0] will be the base name (such as code:"bash"). + - code:"session_new": Execute in a new session setting the process group to the executed process' id (making the executed process a code:"controlling terminal"). + - code:"session_same": Execute in the same session where the process group is set to the parent process id. IKI Variables\: All Rule Actions support IKI variable substitution. @@ -152,81 +158,81 @@ Rule Documentation: - parameter - program - The "define" IKI variables, such as define:"PATH", expand environment variables. + The code:"define" IKI variables, such as define:"PATH", expand environment variables. - The "parameter" IKI variables, such as parameter:"hello", expand IKI variables defined using the "parameter" Setting Rule Type. + The code:"parameter" IKI variables, such as parameter:"hello", expand IKI variables defined using the code:"parameter" Setting Rule Type. - The "program" IKI variables, such as program:"verbose:option", expand program arguments (where "verbose:option" might expand into "-v" ). + The code:"program" IKI variables, such as program:"verbose:option", expand program arguments (where code:"verbose:option" might expand into code:"-v" ). - Only the following "program" IKI variables are supported\: + Only the following code:"program" IKI variables are supported\: - dark\: - This variable holds the "dark" program parameters, such as "+d". - This supports ":option". + This variable holds the code:"dark" program parameters, such as code:"+d". + This supports code:":option". - light\: - This variable holds the "light" program parameters, such as "+l". - This supports ":option". + This variable holds the code:"light" program parameters, such as code:"+l". + This supports code:":option". - no_color\: - This variable holds the "no_color" program parameters, such as "+n". - This supports ":option". + This variable holds the code:"no_color" program parameters, such as code:"+n". + This supports code:":option". - quiet\: - This variable holds the "quiet" program parameters, such as "+Q". - This supports ":option". + This variable holds the code:"quiet" program parameters, such as code:"+Q". + This supports code:":option". - error\: - This variable holds the "error" program parameters, such as "+E". - This supports ":option". + This variable holds the code:"error" program parameters, such as code:"+E". + This supports code:":option". - normal\: - This variable holds the "normal" program parameters, such as "+N". - This supports ":option". + This variable holds the code:"normal" program parameters, such as code:"+N". + This supports code:":option". - verbose\: - This variable holds the "verbose" program parameters, such as "+V". - This supports ":option". + This variable holds the code:"verbose" program parameters, such as code:"+V". + This supports code:":option". - debug\: - This variable holds the "debug" program parameters, such as "+D". - This supports ":option". + This variable holds the code:"debug" program parameters, such as code:"+D". + This supports code:":option". - cgroup\: - This variable holds the "cgroup" program parameters, such as "-c /sys/fs/cgroup/". - This supports both ":option" and ":value". + This variable holds the code:"cgroup" program parameters, such as code:"-c /sys/fs/cgroup/". + This supports both code:":option" and code:":value". - daemon\: - This variable holds the "daemon" program parameters, such as "-d". - This supports ":option". + This variable holds the code:"daemon" program parameters, such as code:"-d". + This supports code:":option". - init\: - This variable holds the "init" program parameters, such as "-I". - This supports ":option". + This variable holds the code:"init" program parameters, such as code:"-I". + This supports code:":option". - interruptible\: - This variable holds the "interruptible" program parameters, such as "-i". - This supports ":option". + This variable holds the code:"interruptible" program parameters, such as code:"-i". + This supports code:":option". - pid\: - This variable holds the "pid" program parameters, such as "-p controller/run/default.pid". - This supports both ":option" and ":value". + This variable holds the code:"pid" program parameters, such as code:"-p controller/run/default.pid". + This supports both code:":option" and code:":value". - settings\: - This variable holds the "settings" program parameters, such as "-s controller/". - This supports both ":option" and ":value". + This variable holds the code:"settings" program parameters, such as code:"-s controller/". + This supports both code:":option" and code:":value". - simulate\: - This variable holds the "simulate" program parameters, such as "-S". - This supports ":option". + This variable holds the code:"simulate" program parameters, such as code:"-S". + This supports code:":option". - socket\: - This variable holds the "socket" program parameters, such as "-k controller/run/default.socket". - This supports both ":option" and ":value". + This variable holds the code:"socket" program parameters, such as code:"-k controller/run/default.socket". + This supports both code:":option" and code:":value". - uninterruptible\: - This variable holds the "uninterruptible" program parameters, such as "-U". - This supports ":option". + This variable holds the code:"uninterruptible" program parameters, such as code:"-U". + This supports code:":option". - validate\: - This variable holds the "validate" program parameters, such as "-v". - This supports ":option". + This variable holds the code:"validate" program parameters, such as code:"-v". + This supports code:":option". diff --git a/level_3/controller/documents/simulate.txt b/level_3/controller/documents/simulate.txt index ce34648..2dae70d 100644 --- a/level_3/controller/documents/simulate.txt +++ b/level_3/controller/documents/simulate.txt @@ -1,29 +1,35 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named simulate.txt) can be more easily read using the following iki_read commands: +# iki_read simulate.txt +Q -w -W code '"' '"' +# +# To read the "Simulate Documentation" section of this file, use this command sequence: +# fss_basic_list_read simulate.txt +Q -cn "Simulate Documentation" | iki_read +Q -w -W code '"' '"' +# 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). + The code:"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\: + - The code:"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 code:"controller" program will return 0 on validation success and 1 on validation failure. - - The "simulate" functionality\: + - The code:"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. + Furthermore, any code:"script" specified inside a Rule is only simulated as a whole and not its individual parts. + Once the Entry file is finished executing, the code:"simulate" will continue to run waiting on code:"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. + - The code:"simulate" with code:"validate" functionality\: + Will perform similar to code:"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 code:"simulate" and code:"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. + When a Rule is simulated, an empty script command (generally defaulting to code:"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. diff --git a/level_3/controller/specifications/entry.txt b/level_3/controller/specifications/entry.txt index 00fbfdd..ef38cdf 100644 --- a/level_3/controller/specifications/entry.txt +++ b/level_3/controller/specifications/entry.txt @@ -1,139 +1,145 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named entry.txt) can be more easily read using the following iki_read commands: +# iki_read entry.txt +Q -w -W code '"' '"' +# +# To read the "Entry Specification" section of this file, use this command sequence: +# fss_basic_list_read entry.txt +Q -cn "Entry Specification" | iki_read +Q -w -W code '"' '"' +# Entry Specification: - The Entry files follow the FSS-0005 (Somewhat Basic List) format. + The Entry files follow the code:"FSS-0005 (Somewhat Basic List)" format. - An Entry file name is expected to have the file extension ".entry". + An Entry file name is expected to have the file extension code:".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 outer most part is a code:"FSS-0002 (Basic List)". + - The Basic List Object is considered the code:"Item". + - The Basic List Content are considered the code:"Actions". + - The code:"Actions" are code:"FSS-0001 (Extended)". + - Each Action Object is the code:"Action Name". + - Each Action Content are the code:"Action Parameters". The Items\: - - "main": required. + - code:"main": required. - - "settings": optional, Actions may be one of\: - - "control": One to two Content. + - code:"settings": optional, Actions may be one of\: + - code:"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 second Content an optional code:"readonly". + - code:"control_group": Exactly one Content that is a group name or group id. + - code:"control_mode": Exactly one Content that is a valid file mode. + - code:"control_user": Exactly one Content that is a user name or user id. + - code:"define": Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). + - code:"mode": Exactly one Content that is one of code:"program" or code:"service". + - code:"parameter": Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value. + - code:"pid": Exactly one Content that is one of code:"disable", code:"require", or code:"ready". + - code:"pid_file": Exactly one Content that is a relative or absolute path to a pid file. + - code:"session": Exactly one Content that is one of code:"new" or code:"same". + - code:"show": Exactly one Content that is one of code:"normal" or code:"init". + - code:"timeout": One or two content with the first being one of code:"exit", code:"start", code:"stop", or code:"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. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "execute": One or more Content. + - code:"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". + - code:"failsafe": One Content that is a valid Object name, except for the reserved code:"main". - - "freeze": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "item": One Content that is a valid Object name, except for the reserved "main". + - code:"item": One Content that is a valid Object name, except for the reserved code:"main". - - "kill": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "pause": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "ready": Zero or One Content. + - code:"ready": Zero or One Content. The first may only be one of\: - - "wait" + - code:"wait" - - "reload": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "restart": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "resume": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "start": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "stop": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "thaw": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "timeout": One or two Content. + - code:"timeout": One or two Content. The first being one of\: - - "exit" - - "start" - - "stop" - - "kill" + - code:"exit" + - code:"start" + - code:"stop" + - code:"kill" The (optional) second Content being a positive whole number or 0. diff --git a/level_3/controller/specifications/exit.txt b/level_3/controller/specifications/exit.txt index 3fbd63f..83ab08f 100644 --- a/level_3/controller/specifications/exit.txt +++ b/level_3/controller/specifications/exit.txt @@ -1,125 +1,131 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named exit.txt) can be more easily read using the following iki_read commands: +# iki_read exit.txt +Q -w -W code '"' '"' +# +# To read the "Exit Specification" section of this file, use this command sequence: +# fss_basic_list_read exit.txt +Q -cn "Exit Specification" | iki_read +Q -w -W code '"' '"' +# Exit Specification: - The Exit files follow the FSS-0005 (Somewhat Basic List) format. + The Exit files follow the code:"FSS-0005 (Somewhat Basic List)" format. - An Exit file name is expected to have the file extension ".exit". + An Exit file name is expected to have the file extension code:".exit". For each Exit 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 outer most part is a code:"FSS-0002 (Basic List)". + - The Basic List Object is considered the code:"Item". + - The Basic List Content are considered the code:"Actions". + - The code:"Actions" are code:"FSS-0001 (Extended)". + - Each Action Object is the code:"Action Name". + - Each Action Content are the code:"Action Parameters". The Items\: - - "main": required. + - code:"main": required. - - "settings": optional, Actions may be one of\: - - "pid": Exactly one Content that is one of "disable", "require", or "ready". - - "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. + - code:"settings": optional, Actions may be one of\: + - code:"pid": Exactly one Content that is one of code:"disable", code:"require", or code:"ready". + - code:"session": Exactly one Content that is one of code:"new" or code:"same". + - code:"show": Exactly one Content that is one of code:"normal" or code:"init". + - code:"timeout": One or Two content with the first being one of code:"exit", code:"start", code:"stop", or code:"kill" and the (optional) second Content being a positive whole number or 0. The Exit file may have any other valid Item Objects, but only the above are reserved. The Actions\: - - "consider": One or more Content. + - code:"consider": One or more Content. The first Content that is the relative file path (without any leading/trailing slashes and without file extension). The second Content that is the basename for a rule file. The third and beyond may only be one of\: - - "asynchronous" - - "require" - - "wait" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "failsafe": One Content that is a valid Object name, except for the reserved "main". + - code:"failsafe": One Content that is a valid Object name, except for the reserved code:"main". - - "freeze": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "item": One Content that is a valid Object name, except for the reserved "main". + - code:"item": One Content that is a valid Object name, except for the reserved code:"main". - - "kill": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "pause": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "ready": Zero or One Content. + - code:"ready": Zero or One Content. The first may only be one of\: - - "wait" + - code:"wait" - - "reload": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "restart": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "resume": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "start": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "stop": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "thaw": Two or more Content. + - code:"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" + - code:"asynchronous" + - code:"require" + - code:"wait" - - "timeout": Two Content. + - code:"timeout": Two Content. The first being one of\: - - "exit" - - "start" - - "stop" - - "kill" + - code:"exit" + - code:"start" + - code:"stop" + - code:"kill" The (optional) second Content being a positive whole number or 0. diff --git a/level_3/controller/specifications/packet.txt b/level_3/controller/specifications/packet.txt index a290d20..91d2bb6 100644 --- a/level_3/controller/specifications/packet.txt +++ b/level_3/controller/specifications/packet.txt @@ -1,55 +1,61 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named packet.txt) can be more easily read using the following iki_read commands: +# iki_read packet.txt +Q -w -W code '"' '"' +# +# To read the "Packet Specification" section of this file, use this command sequence: +# fss_basic_list_read packet.txt +Q -cn "Packet Specification" | iki_read +Q -w -W code '"' '"' +# Packet Specification: - The controller program communicates use the FSS-000F (Packet). - This specification declares how the Payload Block, which is in FSS-000E (Payload) format, is required to be used. + The controller program communicates use the code:"FSS-000F (Packet)". + This specification declares how the Payload Block, which is in code:"FSS-000E (Payload)" format, is required to be used. - Only a single "header" is allowed. - Only a single "payload" is allowed. + Only a single code:"header" is allowed. + Only a single code:"payload" is allowed. Packet Structure\: Packet is grouped into the following blocks\: - - control: A single 1-byte block representing control codes. - - size: A single 4-byte block representing the size of the entire packet, including the control block. + - code:"control": A single 1-byte block representing control codes. + - code:"size": A single 4-byte block representing the size of the entire packet, including the control block. - The "header" Object contains the following FSS-0001 Extended Objects (depending on "type")\: - - action: A valid action type: "freeze", "kexec", "kill", "pause", "reboot", "reload", "rerun", "restart", "resume", "shutdown", "start", "stop", or "thaw". - - length: A positive whole number inclusively between 0 and 4294965248 representing the length of the "payload" (may be in binary, octal, decimal, duodecimal, or hexidecimal). - - status: The status code name or number representing an FSS status code, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal). - - type: The packet type that is one of "controller", "error", or "init". + The code:"header" Object contains the following code:"FSS-0001 (Extended)" Objects (depending on code:"type")\: + - code:"action": A valid action type: code:"freeze", code:"kexec", code:"kill", code:"pause", code:"reboot", code:"reload", code:"rerun", code:"restart", code:"resume", code:"shutdown", code:"start", code:"stop", or code:"thaw". + - code:"length": A positive whole number inclusively between 0 and 4294965248 representing the length of the code:"payload" (may be in binary, octal, decimal, duodecimal, or hexidecimal). + - code:"status": The status code name or number representing an FSS status code, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal). + - code:"type": The packet type that is one of code:"controller", code:"error", or code:"init". - When there are multiple Objects of the same name inside the "header"\: - - action: The order represents the order in which the actions are performed. - - length: There may only be one length Object, all others after the first are ignored (may be in binary, octal, decimal, duodecimal, or hexidecimal). - - status: A status for each action, in the same order as the order of the action, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal). - - type: The first represent the type and all others represents a sub-type. + When there are multiple Objects of the same name inside the code:"header"\: + - code:"action": The order represents the order in which the actions are performed. + - code:"length": There may only be one length Object, all others after the first are ignored (may be in binary, octal, decimal, duodecimal, or hexidecimal). + - code:"status": A status for each action, in the same order as the order of the action, such as F_none, F_failure, or 200 (where a number may have error and warning bits and may be in binary, octal, decimal, duodecimal, or hexidecimal). + - code:"type": The first represent the type and all others represents a sub-type. - There are different headers and payload properties based on the "type". + There are different headers and payload properties based on the code:"type". - The "controller" type\: - Supports the following headers: "action", "length", "status", and "type". + The code:"controller" type\: + Supports the following headers: code:"action", code:"length", code:"status", and code:"type". - Only a single "action" may be provided and must exist for request and response packets. - Only a single "status" may be provided and must exist for response packets. + Only a single code:"action" may be provided and must exist for request and response packets. + Only a single code:"status" may be provided and must exist for response packets. - The "payload" is dependent on the "action". + The code:"payload" is dependent on the code:"action". - The "error" type\: - Supports the following headers: "length", "status", and "type". + The code:"error" type\: + Supports the following headers: code:"length", code:"status", and code:"type". - Only a single "status" may be provided and must exist for request and response packets. + Only a single code:"status" may be provided and must exist for request and response packets. - The "payload" is a NULL terminated string whose length is defined by the "length" "header" Content. + The code:"payload" is a NULL terminated string whose length is defined by the code:"length" code:"header" Content. - There are different headers and payload properties based on the "type". + There are different headers and payload properties based on the code:"type". - The "init" type\: - Supports the following headers: "action", "length", "status", and "type". + The code:"init" type\: + Supports the following headers: code:"action", code:"length", code:"status", and code:"type". - Only a single "action" may be provided and must exist for request and response packets. - Only a single "status" may be provided and must exist for response packets. + Only a single code:"action" may be provided and must exist for request and response packets. + Only a single code:"status" may be provided and must exist for response packets. - The "payload" is dependent on the "action". + The code:"payload" is dependent on the code:"action". diff --git a/level_3/controller/specifications/rule.txt b/level_3/controller/specifications/rule.txt index d02f601..8ea846e 100644 --- a/level_3/controller/specifications/rule.txt +++ b/level_3/controller/specifications/rule.txt @@ -1,96 +1,102 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named rule.txt) can be more easily read using the following iki_read commands: +# iki_read rule.txt +Q -w -W code '"' '"' +# +# To read the "Rule Specification" section of this file, use this command sequence: +# fss_basic_list_read rule.txt +Q -cn "Rule Specification" | iki_read +Q -w -W code '"' '"' +# Rule Specification: - The Rule files follow the FSS-000D (Basic Rule) format with IKI-0000 (Unrestricted). + The Rule files follow the code:"FSS-000D (Basic Rule)" format with bold:"IKI-0000 (Unrestricted)". - A Rule file name is expected to have the file extension ".rule". + A Rule file name is expected to have the file extension code:".rule". For each Rule file\: - - The outer most part is a FSS-0002 (Basic List). - - The Basic List Object is considered the "Rule Type". - - The Basic List Content is determined by the specific "Rule Type". - - The Content for each "Rule Type" is called the "Item". - - Each Item Object is the "Item Name". - - Each Item Content is either the "Action" or the "Setting". - - Each Action Object is the "Action Name". - - Each Action Content are the "Action Parameters". - - Each Setting Object is the "Setting Name". - - Each Setting Content are the "Setting Values". + - The outer most part is a code:"FSS-0002 (Basic List)". + - The Basic List Object is considered the code:"Rule Type". + - The Basic List Content is determined by the specific code:"Rule Type". + - The Content for each code:"Rule Type" is called the code:"Item". + - Each Item Object is the code:"Item Name". + - Each Item Content is either the code:"Action" or the code:"Setting". + - Each Action Object is the code:"Action Name". + - Each Action Content are the code:"Action Parameters". + - Each Setting Object is the code:"Setting Name". + - Each Setting Content are the code:"Setting Values". The Rule Types\: - - "command": Follows either FSS-0003 (Extended List) or FSS-0001 (Extended). - - "script": Follows either FSS-0003 (Extended List) or FSS-0001 (Extended). - - "service": Follows either FSS-0003 (Extended List) or FSS-0001 (Extended). - - "settings": Is required and follows either FSS-0001 (Extended). - - "utility": Follows either FSS-0003 (Extended List) or FSS-0001 (Extended). + - code:"command": Follows either code:"FSS-0003 (Extended List)" or code:"FSS-0001 (Extended)". + - code:"script": Follows either code:"FSS-0003 (Extended List)" or code:"FSS-0001 (Extended)". + - code:"service": Follows either code:"FSS-0003 (Extended List)" or code:"FSS-0001 (Extended)". + - code:"settings": Is required and follows either code:"FSS-0001 (Extended)". + - code:"utility": Follows either code:"FSS-0003 (Extended List)" or code:"FSS-0001 (Extended)". - For the above Rule Types, "settings" may be specified only once whereas the others may be specifed multiple times. - The "settings" Rule Type is always processed first, regardless of position. + For the above Rule Types, code:"settings" may be specified only once whereas the others may be specifed multiple times. + The code:"settings" Rule Type is always processed first, regardless of position. The other Rule Types are processed top-down. - The "settings" Rule Type has the following FSS-0001 (Extended)\: - - "affinity": One or more Content, each must be a 0 or greater whole number. - - "capability": One Content representing capabilities. - - "cgroup": Two or more Content, the first Content being either "existing" or "new" and the remaining representing a valid cgroup (control group) name, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off). - - "define": Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). - - "engine": One or more Content representing a valid program name or path (such as "bash" or "/bin/bash") and any optional arguments. - - "environment": Zero or more Content, each must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). - - "group": One or more Content representing group names or group ids. - - "limit": Three Content, with the first representing a valid resource type and the second and third being a valid resource limit number (positive whole number or 0). - - "name": One Content, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off). - - "nice": One Content, must be a valid number for process "niceness" (Any whole number inclusively between -20 to 19). - - "on": Four Content, the first being a Rule Action, the second being "need", "want", or "wish", the third being a partial path, and the fourth being a Rule file name without ".rule" extension. - - "parameter": Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value. - - "path": One Content representing a valid PATH environment string (such as "/bin:/sbin:/usr/bin"). - - "scheduler": One or two Content representing a scheduler name and the optional numeric priority (Any whole number inclusively between 0 and 99). - - "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. - - "user": One Content representing a user name or user id. + The code:"settings" Rule Type has the following code:"FSS-0001 (Extended)"\: + - code:"affinity": One or more Content, each must be a 0 or greater whole number. + - code:"capability": One Content representing capabilities. + - code:"cgroup": Two or more Content, the first Content being either code:"existing" or code:"new" and the remaining representing a valid cgroup (control group) name, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off). + - code:"define": Two Content, the first Content must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). + - code:"engine": One or more Content representing a valid program name or path (such as code:"bash" or code:"/bin/bash") and any optional arguments. + - code:"environment": Zero or more Content, each must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). + - code:"group": One or more Content representing group names or group ids. + - code:"limit": Three Content, with the first representing a valid resource type and the second and third being a valid resource limit number (positive whole number or 0). + - code:"name": One Content, must have at least 1 graph character (non white space printing character) (leading and trailing white space are trimmed off). + - code:"nice": One Content, must be a valid number for process code:"niceness" (Any whole number inclusively between -20 to 19). + - code:"on": Four Content, the first being a Rule Action, the second being code:"need", code:"want", or code:"wish", the third being a partial path, and the fourth being a Rule file name without code:".rule" extension. + - code:"parameter": Two Content, the first Content must be a case-sensitive valid IKI name and the second being an IKI value. + - code:"path": One Content representing a valid code:"PATH" environment string (such as code:"/bin:/sbin:/usr/bin"). + - code:"scheduler": One or two Content representing a scheduler name and the optional numeric priority (Any whole number inclusively between 0 and 99). + - code:"timeout": One or two content with the first being one of code:"exit", code:"start", code:"stop", or code:"kill" and the (optional) second Content being a positive whole number or 0. + - code:"user": One Content representing a user name or user id. - The "command" and "script" Rule Types allow the following the FSS-0001 (Extended)\: - - "freeze": One or more Content representing a program being executed and its arguments. - - "kill": One or more Content representing a program being executed and its arguments. - - "pause": One or more Content representing a program being executed and its arguments. - - "reload": One or more Content representing a program being executed and its arguments. - - "rerun": Two or more Content representing a Rule type that executes and its properties. - - "restart": One or more Content representing a program being executed and its arguments. - - "resume": One or more Content representing a program being executed and its arguments. - - "start": One or more Content representing a program being executed and its arguments. - - "stop": One or more Content representing a program being executed and its arguments. - - "thaw": One or more Content representing a program being executed and its arguments. - - "with": One or more Content representing special options for the Rule Type. + The code:"command" and code:"script" Rule Types allow the following the code:"FSS-0001 (Extended)"\: + - code:"freeze": One or more Content representing a program being executed and its arguments. + - code:"kill": One or more Content representing a program being executed and its arguments. + - code:"pause": One or more Content representing a program being executed and its arguments. + - code:"reload": One or more Content representing a program being executed and its arguments. + - code:"rerun": Two or more Content representing a Rule type that executes and its properties. + - code:"restart": One or more Content representing a program being executed and its arguments. + - code:"resume": One or more Content representing a program being executed and its arguments. + - code:"start": One or more Content representing a program being executed and its arguments. + - code:"stop": One or more Content representing a program being executed and its arguments. + - code:"thaw": One or more Content representing a program being executed and its arguments. + - code:"with": One or more Content representing special options for the Rule Type. - The "service" and "utility" Rule Types allow the following the FSS-0001 (Extended)\: - - "pid_file": One Content representing the path to a PID file. - - "rerun": Two or more Content representing a Rule type that executes and its properties. - - "with": One or more Content being one of "full_path", "session_new", or "session_same". + The code:"service" and code:"utility" Rule Types allow the following the code:"FSS-0001 (Extended)"\: + - code:"pid_file": One Content representing the path to a PID file. + - code:"rerun": Two or more Content representing a Rule type that executes and its properties. + - code:"with": One or more Content being one of code:"full_path", code:"session_new", or code:"session_same". - The "command" and "service" Rule Types allow the following the FSS-0003 (Extended List)\: - - "freeze": A list repesenting multiple programs and their respective arguments to execute. - - "kill": A list repesenting multiple programs and their respective arguments to execute. - - "pause": A list repesenting multiple programs and their respective arguments to execute. - - "reload": A list repesenting multiple programs and their respective arguments to execute. - - "restart": A list repesenting multiple programs and their respective arguments to execute. - - "resume": A list repesenting multiple programs and their respective arguments to execute. - - "start": A list repesenting multiple programs and their respective arguments to execute. - - "stop": A list repesenting multiple programs and their respective arguments to execute. - - "thaw": A list repesenting multiple programs and their respective arguments to execute. + The code:"command" and code:"service" Rule Types allow the following the code:"FSS-0003 (Extended List)"\: + - code:"freeze": A list repesenting multiple programs and their respective arguments to execute. + - code:"kill": A list repesenting multiple programs and their respective arguments to execute. + - code:"pause": A list repesenting multiple programs and their respective arguments to execute. + - code:"reload": A list repesenting multiple programs and their respective arguments to execute. + - code:"restart": A list repesenting multiple programs and their respective arguments to execute. + - code:"resume": A list repesenting multiple programs and their respective arguments to execute. + - code:"start": A list repesenting multiple programs and their respective arguments to execute. + - code:"stop": A list repesenting multiple programs and their respective arguments to execute. + - code:"thaw": A list repesenting multiple programs and their respective arguments to execute. - The "script" and "utility" Rule Types allow the following the FSS-0003 (Extended List)\: - - "freeze": A list repesenting the contents of a script, such as a GNU Bash shell. - - "kill": A list repesenting the contents of a script, such as a GNU Bash shell. - - "pause": A list repesenting the contents of a script, such as a GNU Bash shell. - - "reload": A list repesenting the contents of a script, such as a GNU Bash shell. - - "restart": A list repesenting the contents of a script, such as a GNU Bash shell. - - "resume": A list repesenting the contents of a script, such as a GNU Bash shell. - - "start": A list repesenting the contents of a script, such as a GNU Bash shell. - - "stop": A list repesenting the contents of a script, such as a GNU Bash shell. - - "thaw": A list repesenting the contents of a script, such as a GNU Bash shell. + The code:"script" and code:"utility" Rule Types allow the following the code:"FSS-0003 (Extended List)"\: + - code:"freeze": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"kill": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"pause": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"reload": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"restart": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"resume": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"start": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"stop": A list repesenting the contents of a script, such as a GNU Bash shell. + - code:"thaw": A list repesenting the contents of a script, such as a GNU Bash shell. - The "rerun" Rule Type Content has the following structure\: - The first Content represents one of: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", or "thaw". - The second Content represents one of: "success" or "failure". - The third and more Content represents one of: "delay", "max", or "reset". - Where "delay" and "max" must be followed by a positive number or the number 0. + The code:"rerun" Rule Type Content has the following structure\: + The first Content represents one of: code:"freeze", code:"kill", code:"pause", code:"reload", code:"restart", code:"resume", code:"start", code:"stop", or code:"thaw". + The second Content represents one of: code:"success" or code:"failure". + The third and more Content represents one of: code:"delay", code:"max", or code:"reset". + Where code:"delay" and code:"max" must be followed by a positive number or the number 0. diff --git a/level_3/controller/specifications/task.txt b/level_3/controller/specifications/task.txt index 5c974ae..8175aa4 100644 --- a/level_3/controller/specifications/task.txt +++ b/level_3/controller/specifications/task.txt @@ -1,7 +1,14 @@ -# fss-0002 +# fss-0002 iki-0000 # # license: open-standard-license-1.0 # +# This file (assumed to be named task.txt) can be more easily read using the following iki_read commands: +# iki_read task.txt +Q -w -W code '"' '"' +# +# To read the "Task Specification" section of this file, use this command sequence: +# fss_basic_list_read task.txt +Q -cn "Task Specification" | iki_read +Q -w -W code '"' '"' +# # A "Task" is not fully implemented but is provided as a proposal for consideration and is subject to completion or removal. +# Task Specification: -- 1.8.3.1