From 2ced7549e9d678576e653c9764712e37e976ade4 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Sat, 23 Oct 2021 16:45:55 -0500 Subject: [PATCH] Update: Implement "session new" and "session same", improve documentation, update simulate and validate display. The controller and init programs now support customizing their session as new or session as same state. A setting global to the entry and exit files is defined as "session new" and "session same". A setting specific to every rule item is appended to the "with" as either "session_new" or "session_same". Update the documentation with these changes. I noticed the documentation could use a little cleanup. When passing both simulate and validate parameters, the entries and exits (with all related parts) are displayed. The ordering can be more alphabetic. It will not be fully alphabetic because there still exists logic that supersedes this, such as: - "id", "name", and "type" values generally go first regardless of alphabetic ordering (and in that order). - The simple data is displayed first (ones not using '{' and '}' to display), which are within themselves alphabetic. - The complex data is displayed last, which are within themselves alphabetic. - Within the complex data, the "item"s are displayed last. Cleanup whitespace in execute-common.h. --- level_1/fl_execute/c/execute-common.h | 12 +- level_3/controller/c/private-common.c | 4 + level_3/controller/c/private-common.h | 30 ++- level_3/controller/c/private-controller.c | 4 +- level_3/controller/c/private-entry.c | 26 +++ level_3/controller/c/private-rule.c | 196 ++++++++++++------ .../data/settings/rules/maintenance/console.rule | 2 + level_3/controller/documents/entry.txt | 223 ++++++++++++--------- level_3/controller/documents/exit.txt | 197 ++++++++++-------- level_3/controller/documents/rule.txt | 36 ++-- level_3/controller/documents/simulate.txt | 23 ++- level_3/controller/specifications/entry.txt | 22 +- level_3/controller/specifications/exit.txt | 19 +- level_3/controller/specifications/rule.txt | 104 +++++----- 14 files changed, 553 insertions(+), 345 deletions(-) diff --git a/level_1/fl_execute/c/execute-common.h b/level_1/fl_execute/c/execute-common.h index 7aa4975..d13a6e4 100644 --- a/level_1/fl_execute/c/execute-common.h +++ b/level_1/fl_execute/c/execute-common.h @@ -34,12 +34,12 @@ extern "C" { * data: The data to pipe to the child process, set to 0 to not use. */ #ifndef _di_fl_execute_parameter_t_ - #define FL_execute_parameter_option_exit_d 0x1 - #define FL_execute_parameter_option_path_d 0x2 - #define FL_execute_parameter_option_return_d 0x4 - #define FL_execute_parameter_option_session_d 0x8 - #define FL_execute_parameter_option_terminal_d 0x10 - #define FL_execute_parameter_option_threadsafe_d 0x20 + #define FL_execute_parameter_option_exit_d 0x1 + #define FL_execute_parameter_option_path_d 0x2 + #define FL_execute_parameter_option_return_d 0x4 + #define FL_execute_parameter_option_session_d 0x8 + #define FL_execute_parameter_option_terminal_d 0x10 + #define FL_execute_parameter_option_threadsafe_d 0x20 typedef struct { uint8_t option; diff --git a/level_3/controller/c/private-common.c b/level_3/controller/c/private-common.c index 1e45f24..7d0c4e3 100644 --- a/level_3/controller/c/private-common.c +++ b/level_3/controller/c/private-common.c @@ -91,10 +91,14 @@ extern "C" { const f_string_t controller_rttime_s = CONTROLLER_rttime_s; const f_string_t controller_rule_s = CONTROLLER_rule_s; const f_string_t controller_rules_s = CONTROLLER_rules_s; + const f_string_t controller_same_s = CONTROLLER_same_s; const f_string_t controller_scheduler_s = CONTROLLER_scheduler_s; const f_string_t controller_script_s = CONTROLLER_script_s; const f_string_t controller_service_s = CONTROLLER_service_s; const f_string_t controller_setting_s = CONTROLLER_setting_s; + const f_string_t controller_session_s = CONTROLLER_session_s; + const f_string_t controller_session_new_s = CONTROLLER_session_new_s; + const f_string_t controller_session_same_s = CONTROLLER_session_same_s; const f_string_t controller_show_s = CONTROLLER_show_s; const f_string_t controller_sigpending_s = CONTROLLER_sigpending_s; const f_string_t controller_stack_s = CONTROLLER_stack_s; diff --git a/level_3/controller/c/private-common.h b/level_3/controller/c/private-common.h index 69bfa8b..cbb6cbe 100644 --- a/level_3/controller/c/private-common.h +++ b/level_3/controller/c/private-common.h @@ -101,9 +101,13 @@ extern "C" { #define CONTROLLER_rttime_s "rttime" #define CONTROLLER_rule_s "rule" #define CONTROLLER_rules_s "rules" + #define CONTROLLER_same_s "same" #define CONTROLLER_scheduler_s "scheduler" #define CONTROLLER_script_s "script" #define CONTROLLER_service_s "service" + #define CONTROLLER_session_s "session" + #define CONTROLLER_session_new_s "session_new" + #define CONTROLLER_session_same_s "session_same" #define CONTROLLER_setting_s "setting" #define CONTROLLER_sigpending_s "sigpending" #define CONTROLLER_show_s "show" @@ -209,9 +213,13 @@ extern "C" { #define controller_rttime_s_length 6 #define controller_rule_s_length 4 #define controller_rules_s_length 5 + #define controller_same_s_length 4 #define controller_scheduler_s_length 9 #define controller_script_s_length 6 #define controller_service_s_length 7 + #define controller_session_s_length 7 + #define controller_session_new_s_length 11 + #define controller_session_same_s_length 12 #define controller_setting_s_length 7 #define controller_show_s_length 4 #define controller_sigpending_s_length 10 @@ -317,9 +325,13 @@ extern "C" { extern const f_string_t controller_rttime_s; extern const f_string_t controller_rule_s; extern const f_string_t controller_rules_s; + extern const f_string_t controller_same_s; extern const f_string_t controller_scheduler_s; extern const f_string_t controller_script_s; extern const f_string_t controller_service_s; + extern const f_string_t controller_session_s; + extern const f_string_t controller_session_new_s; + extern const f_string_t controller_session_same_s; extern const f_string_t controller_setting_s; extern const f_string_t controller_show_s; extern const f_string_t controller_sigpending_s; @@ -1032,7 +1044,9 @@ extern "C" { * A set of codes representing different with flags. */ #ifndef _di_controller_with_defines_ - #define controller_with_full_path_d 0x1 + #define controller_with_full_path_d 0x1 + #define controller_with_session_new_d 0x2 + #define controller_with_session_same_d 0x4 #endif // _di_controller_with_defines_ /** @@ -1358,8 +1372,14 @@ extern "C" { * - normal: Do not print anything other than warnings and errors, but allow executed programs and scripts to output however they like. * - init: Print like an init program, printing status of entry and rules as they are being started, stopped, etc... * + * controller_entry_session_*: + * - none: No special session configuration specified, use built in defaults. + * - new: Designate the default to use a new session, ignoring built in defaults (passing FL_execute_parameter_option_session_d to the execute functions). + * - same: Designate the default to use a same session, ignoring built in defaults. + * * status: The overall status. * pid: The PID file generation setting. + * session: The default session settings (when NULL, no default is specified). * show: The show setting for controlling what to show when executing entry items and rules. * timeout_kill: The timeout to wait relating to using a kill signal. * timeout_start: The timeout to wait relating to starting a process. @@ -1378,10 +1398,17 @@ extern "C" { controller_entry_show_init, }; + enum { + controller_entry_session_none = 0, + controller_entry_session_new, + controller_entry_session_same, + }; + typedef struct { f_status_t status; uint8_t pid; + uint8_t session; uint8_t show; f_number_unsigned_t timeout_kill; @@ -1394,6 +1421,7 @@ extern "C" { #define controller_entry_t_initialize { \ F_known_not, \ controller_entry_pid_require, \ + controller_entry_session_none, \ controller_entry_show_normal, \ 0, \ 0, \ diff --git a/level_3/controller/c/private-controller.c b/level_3/controller/c/private-controller.c index 7ae82ba..c2d73a9 100644 --- a/level_3/controller/c/private-controller.c +++ b/level_3/controller/c/private-controller.c @@ -1196,8 +1196,8 @@ extern "C" { int result = 0; int option = FL_execute_parameter_option_path_d; - if (global->main->as_init) { - option |= FL_execute_parameter_option_session_d; // @todo need "session new" and "session same". + if (entry->session == controller_entry_session_new) { + option |= FL_execute_parameter_option_session_d; } status = fll_execute_into(0, entry_action->parameters, option, 0, (void *) &result); diff --git a/level_3/controller/c/private-entry.c b/level_3/controller/c/private-entry.c index e827bb7..3f3ebcb 100644 --- a/level_3/controller/c/private-entry.c +++ b/level_3/controller/c/private-entry.c @@ -796,6 +796,13 @@ extern "C" { entry->status = F_known_not; entry->items.used = 0; + if (global.main->as_init) { + entry->session = controller_entry_session_new; + } + else { + entry->session = controller_entry_session_same; + } + cache->action.line_action = 0; cache->action.line_item = 0; @@ -1225,6 +1232,25 @@ extern "C" { continue; } } + else if (fl_string_dynamic_compare_string(controller_session_s, cache->action.name_action, controller_session_s_length) == F_equal_to) { + if (cache->content_actions.array[i].used < 0 || cache->content_actions.array[i].used > 1) { + controller_entry_settings_read_print_setting_requires_exactly(is_entry, global, *cache, 1); + + continue; + } + + if (fl_string_dynamic_partial_compare_string(controller_new_s, cache->buffer_file, controller_new_s_length, cache->content_actions.array[i].array[0]) == F_equal_to) { + entry->session = controller_entry_session_new; + } + else if (fl_string_dynamic_partial_compare_string(controller_same_s, cache->buffer_file, controller_same_s_length, cache->content_actions.array[i].array[0]) == F_equal_to) { + entry->session = controller_entry_session_same; + } + else { + controller_entry_settings_read_print_setting_unknown_action_value(is_entry, global, *cache, i); + + continue; + } + } else if (fl_string_dynamic_compare_string(controller_show_s, cache->action.name_action, controller_show_s_length) == F_equal_to) { if (cache->content_actions.array[i].used < 0 || cache->content_actions.array[i].used > 1) { controller_entry_settings_read_print_setting_requires_exactly(is_entry, global, *cache, 1); diff --git a/level_3/controller/c/private-rule.c b/level_3/controller/c/private-rule.c index bfc81b1..0664f41 100644 --- a/level_3/controller/c/private-rule.c +++ b/level_3/controller/c/private-rule.c @@ -629,13 +629,28 @@ extern "C" { } // for } else if (type == controller_rule_action_type_with) { - item->with = 0; for (f_array_length_t i = 0; i < cache->content_action.used; ++i) { if (fl_string_dynamic_partial_compare_string(controller_full_path_s, cache->buffer_item, controller_full_path_s_length, cache->content_action.array[i]) == F_equal_to) { item->with |= controller_with_full_path_d; } + else if (fl_string_dynamic_partial_compare_string(controller_session_new_s, cache->buffer_item, controller_session_new_s_length, cache->content_action.array[i]) == F_equal_to) { + item->with |= controller_with_session_new_d; + + // "session_new" and "session_same" are mutually exclusive. + if (item->with & controller_with_session_same_d) { + item->with -= controller_with_session_same_d; + } + } + else if (fl_string_dynamic_partial_compare_string(controller_session_same_s, cache->buffer_item, controller_session_same_s_length, cache->content_action.array[i]) == F_equal_to) { + item->with |= controller_with_session_same_d; + + // "session_new" and "session_same" are mutually exclusive. + if (item->with & controller_with_session_new_d) { + item->with -= controller_with_session_new_d; + } + } else { if (global.main->error.verbosity != f_console_verbosity_quiet) { controller_print_lock(global.main->error.to, global.thread); @@ -1367,8 +1382,8 @@ extern "C" { execute_set.parameter.option |= FL_execute_parameter_option_path_d; } - if (global.main->as_init) { - execute_set.parameter.option |= FL_execute_parameter_option_session_d; // @todo need "session new" and "session same". + if (process->rule.items.array[i].with & controller_with_session_new_d) { + execute_set.parameter.option |= FL_execute_parameter_option_session_d; } if (process->rule.items.array[i].type == controller_rule_item_type_command) { @@ -3779,6 +3794,17 @@ extern "C" { } if (rule->items.array[rule->items.used].type) { + + // initialize the item with settings. + rule->items.array[rule->items.used].with = 0; + + if (entry->session == controller_entry_session_new) { + rule->items.array[rule->items.used].with |= controller_with_session_new_d; + } + else { + rule->items.array[rule->items.used].with |= controller_with_session_same_d; + } + status = controller_rule_item_read(is_normal, global, cache, &rule->items.array[rule->items.used]); if (F_status_is_error(status)) break; @@ -5820,9 +5846,11 @@ extern "C" { controller_print_lock(main->output.to, global.thread); fl_print_format("%cRule %[%Q%] {%c", main->output.to.stream, f_string_eol_s[0], main->context.set.title, rule.alias, main->context.set.title, f_string_eol_s[0]); + + // name. fl_print_format(" %[%s%] %Q%c", main->output.to.stream, main->context.set.important, controller_name_s, main->context.set.important, rule.name, f_string_eol_s[0]); - fl_print_format(" %[%s%] %s%c", main->output.to.stream, main->context.set.important, controller_how_s, main->context.set.important, options & controller_process_option_asynchronous_d ? controller_asynchronous_s : controller_synchronous_s, f_string_eol_s[0]); - fl_print_format(" %[%s%] %s%c", main->output.to.stream, main->context.set.important, controller_wait_s, main->context.set.important, options & controller_process_option_wait_d ? controller_yes_s : controller_no_s, f_string_eol_s[0]); + + // capability. fl_print_format(" %[%s%] ", main->output.to.stream, main->context.set.important, controller_capability_s, main->context.set.important); if (f_capability_supported()) { @@ -5837,9 +5865,10 @@ extern "C" { f_print_terminated(f_string_eol_s, main->output.to.stream); } else { - fl_print_format("%[(unsupported)%]%c", main->output.to.stream, main->context.set.warning, controller_capability_s, main->context.set.warning, f_string_eol_s[0]); + fl_print_format("%[(unsupported)%]%c", main->output.to.stream, main->context.set.warning, main->context.set.warning, f_string_eol_s[0]); } + // control group. fl_print_format(" %[%s%]", main->output.to.stream, main->context.set.important, controller_control_group_s, main->context.set.important); if (rule.has & controller_rule_has_control_group_d) { @@ -5853,13 +5882,22 @@ extern "C" { } // for } - fl_print_format("%c %[%s%]", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_nice_s, main->context.set.important); + f_print_terminated(f_string_eol_s, main->output.to.stream); + + // how. + fl_print_format(" %[%s%] %s%c", main->output.to.stream, main->context.set.important, controller_how_s, main->context.set.important, options & controller_process_option_asynchronous_d ? controller_asynchronous_s : controller_synchronous_s, f_string_eol_s[0]); + + // nice. + fl_print_format(" %[%s%]", main->output.to.stream, main->context.set.important, controller_nice_s, main->context.set.important); if (rule.has & controller_rule_has_nice_d) { fl_print_format(" %i", main->output.to.stream, rule.nice); } - fl_print_format("%c %[%s%]", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_scheduler_s, main->context.set.important); + f_print_terminated(f_string_eol_s, main->output.to.stream); + + // scheduler. + fl_print_format(" %[%s%]", main->output.to.stream, main->context.set.important, controller_scheduler_s, main->context.set.important); if (rule.has & controller_rule_has_scheduler_d) { f_string_t policy = ""; @@ -5886,19 +5924,31 @@ extern "C" { fl_print_format(" %s %i", main->output.to.stream, policy, rule.scheduler.priority); } - fl_print_format("%c %[%s%] %Q%c", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_script_s, main->context.set.important, rule.script, f_string_eol_s[0]); + f_print_terminated(f_string_eol_s, main->output.to.stream); + + // script. + fl_print_format(" %[%s%] %Q%c", main->output.to.stream, main->context.set.important, controller_script_s, main->context.set.important, rule.script, f_string_eol_s[0]); + + // user. fl_print_format(" %[%s%]", main->output.to.stream, main->context.set.important, controller_user_s, main->context.set.important); if (rule.has & controller_rule_has_user_d) { fl_print_format(" %i", main->output.to.stream, rule.user); } - fl_print_format("%c %[%s%] {%c", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_affinity_s, main->context.set.important, f_string_eol_s[0]); + f_print_terminated(f_string_eol_s, main->output.to.stream); + + // wait. + fl_print_format(" %[%s%] %s%c", main->output.to.stream, main->context.set.important, controller_wait_s, main->context.set.important, options & controller_process_option_wait_d ? controller_yes_s : controller_no_s, f_string_eol_s[0]); + + // affinity. + fl_print_format(" %[%s%] {%c", main->output.to.stream, main->context.set.important, controller_affinity_s, main->context.set.important, f_string_eol_s[0]); for (i = 0; i < rule.affinity.used; ++i) { fl_print_format(" %i%c", main->output.to.stream, rule.affinity.array[i], f_string_eol_s[0]); } // for + // define. fl_print_format(" }%c %[%s%] {%c", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_define_s, main->context.set.important, f_string_eol_s[0]); for (i = 0; i < rule.define.used; ++i) { @@ -5908,6 +5958,7 @@ extern "C" { } } // for + // environment. fl_print_format(" }%c %[%s%] {%c", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_environment_s, main->context.set.important, f_string_eol_s[0]); for (i = 0; i < rule.environment.used; ++i) { @@ -5919,6 +5970,7 @@ extern "C" { fl_print_format(" }%c %[%s%] {%c", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_parameter_s, main->context.set.important, f_string_eol_s[0]); + // parameter. for (i = 0; i < rule.parameter.used; ++i) { if (rule.parameter.array[i].name.used && rule.parameter.array[i].value.used) { @@ -5926,6 +5978,7 @@ extern "C" { } } // for + // group. fl_print_format(" }%c %[%s%] {%c", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_group_s, main->context.set.important, f_string_eol_s[0]); if (rule.has & controller_rule_has_group_d) { @@ -5936,12 +5989,14 @@ extern "C" { } // for } + // limit. fl_print_format(" }%c %[%s%] {%c", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_limit_s, main->context.set.important, f_string_eol_s[0]); for (i = 0; i < rule.limits.used; ++i) { fl_print_format(" %Q %[=%] %un %un%c", main->output.to.stream, controller_rule_setting_limit_type_name(rule.limits.array[i].type), main->context.set.important, main->context.set.important, rule.limits.array[i].value.rlim_cur, rule.limits.array[i].value.rlim_max, f_string_eol_s[0]); } // for + // on. fl_print_format(" }%c %[%s%] {%c", main->output.to.stream, f_string_eol_s[0], main->context.set.important, controller_on_s, main->context.set.important, f_string_eol_s[0]); for (i = 0; i < rule.ons.used; ++i) { @@ -6014,6 +6069,7 @@ extern "C" { fl_print_format(" }%c", main->output.to.stream, f_string_eol_s[0]); + // items. if (rule.items.used) { controller_rule_action_t *action = 0; controller_rule_item_t *item = 0; @@ -6028,8 +6084,74 @@ extern "C" { item = &rule.items.array[i]; fl_print_format(" %[%s%] {%c", main->output.to.stream, main->context.set.important, controller_item_s, main->context.set.important, f_string_eol_s[0]); + + // type. fl_print_format(" %[%s%] %Q%c", main->output.to.stream, main->context.set.important, controller_type_s, main->context.set.important, controller_rule_item_type_name(item->type), f_string_eol_s[0]); + // pid_file. + fl_print_format(" %[%s%]", main->output.to.stream, main->context.set.important, controller_pid_file_s, main->context.set.important); + if (item->pid_file.used) { + fl_print_format(" %Q", main->output.to.stream, item->pid_file); + } + f_print_terminated(f_string_eol_s, main->output.to.stream); + + // with. + fl_print_format(" %[%s%]", main->output.to.stream, main->context.set.important, controller_with_s, main->context.set.important); + if (item->with & controller_with_full_path_d) { + fl_print_format(" %s", main->output.to.stream, controller_full_path_s); + } + if (item->with & controller_with_session_new_d) { + fl_print_format(" %s", main->output.to.stream, controller_session_new_s); + } + if (item->with & controller_with_session_same_d) { + fl_print_format(" %s", main->output.to.stream, controller_session_same_s); + } + f_print_terminated(f_string_eol_s, main->output.to.stream); + + // actions. + for (j = 0; j < item->actions.used; ++j) { + + action = &item->actions.array[j]; + + fl_print_format(" %[%s%] {%c", main->output.to.stream, main->context.set.important, controller_action_s, main->context.set.important, f_string_eol_s[0]); + fl_print_format(" %[%s%] %q%c", main->output.to.stream, main->context.set.important, controller_type_s, main->context.set.important, controller_rule_action_type_name(action->type), f_string_eol_s[0]); + + if (item->type == controller_rule_item_type_script || item->type == controller_rule_item_type_utility) { + fl_print_format(" %[%s%] {%c", main->output.to.stream, main->context.set.important, controller_parameter_s, main->context.set.important, f_string_eol_s[0]); + + parameter = &action->parameters.array[0]; + + if (parameter->used) { + f_print_terminated(" ", main->output.to.stream); + + for (k = 0; k < parameter->used; ++k) { + + if (parameter->string[k] == f_fss_eol_s[0]) { + if (k + 1 < parameter->used) { + f_print_terminated(f_string_eol_s, main->output.to.stream); + f_print_terminated(" ", main->output.to.stream); + } + } + else { + f_print_character_safely(parameter->string[k], main->output.to.stream); + } + } // for + + f_print_terminated(f_string_eol_s, main->output.to.stream); + } + + fl_print_format(" }%c", main->output.to.stream, f_string_eol_s[0]); + } + else { + for (k = 0; k < action->parameters.used; ++k) { + fl_print_format(" %[%s%] %Q%c", main->output.to.stream, main->context.set.important, controller_parameter_s, main->context.set.important, action->parameters.array[k], f_string_eol_s[0]); + } // for + } + + fl_print_format(" }%c", main->output.to.stream, f_string_eol_s[0]); + } // for + + // rerun. fl_print_format(" %[%s%] {%c", main->output.to.stream, main->context.set.important, controller_rerun_s, main->context.set.important, f_string_eol_s[0]); for (j = 0; j < controller_rule_action_type_execute__enum_size; ++j) { @@ -6099,60 +6221,6 @@ extern "C" { } // for fl_print_format(" }%c", main->output.to.stream, f_string_eol_s[0]); - fl_print_format(" %[%s%]", main->output.to.stream, main->context.set.important, controller_pid_file_s, main->context.set.important); - if (item->pid_file.used) { - fl_print_format(" %Q", main->output.to.stream, item->pid_file); - } - f_print_terminated(f_string_eol_s, main->output.to.stream); - - fl_print_format(" %[%s%]", main->output.to.stream, main->context.set.important, controller_with_s, main->context.set.important); - if (item->with & controller_with_full_path_d) { - fl_print_format(" %s", main->output.to.stream, controller_full_path_s); - } - f_print_terminated(f_string_eol_s, main->output.to.stream); - - for (j = 0; j < item->actions.used; ++j) { - - action = &item->actions.array[j]; - - fl_print_format(" %[%s%] {%c", main->output.to.stream, main->context.set.important, controller_action_s, main->context.set.important, f_string_eol_s[0]); - fl_print_format(" %[%s%] %q%c", main->output.to.stream, main->context.set.important, controller_type_s, main->context.set.important, controller_rule_action_type_name(action->type), f_string_eol_s[0]); - - if (item->type == controller_rule_item_type_script || item->type == controller_rule_item_type_utility) { - fl_print_format(" %[%s%] {%c", main->output.to.stream, main->context.set.important, controller_parameter_s, main->context.set.important, f_string_eol_s[0]); - - parameter = &action->parameters.array[0]; - - if (parameter->used) { - f_print_terminated(" ", main->output.to.stream); - - for (k = 0; k < parameter->used; ++k) { - - if (parameter->string[k] == f_fss_eol_s[0]) { - if (k + 1 < parameter->used) { - f_print_terminated(f_string_eol_s, main->output.to.stream); - f_print_terminated(" ", main->output.to.stream); - } - } - else { - f_print_character_safely(parameter->string[k], main->output.to.stream); - } - } // for - - f_print_terminated(f_string_eol_s, main->output.to.stream); - } - - fl_print_format(" }%c", main->output.to.stream, f_string_eol_s[0]); - } - else { - for (k = 0; k < action->parameters.used; ++k) { - fl_print_format(" %[%s%] %Q%c", main->output.to.stream, main->context.set.important, controller_parameter_s, main->context.set.important, action->parameters.array[k], f_string_eol_s[0]); - } // for - } - - fl_print_format(" }%c", main->output.to.stream, f_string_eol_s[0]); - } // for - fl_print_format(" }%c", main->output.to.stream, f_string_eol_s[0]); } // for } diff --git a/level_3/controller/data/settings/rules/maintenance/console.rule b/level_3/controller/data/settings/rules/maintenance/console.rule index d230821..babf4a7 100644 --- a/level_3/controller/data/settings/rules/maintenance/console.rule +++ b/level_3/controller/data/settings/rules/maintenance/console.rule @@ -9,3 +9,5 @@ setting: command: #start setsid -c bash --login start bash --login + + with session diff --git a/level_3/controller/documents/entry.txt b/level_3/controller/documents/entry.txt index 326e41d..aa24989 100644 --- a/level_3/controller/documents/entry.txt +++ b/level_3/controller/documents/entry.txt @@ -10,105 +10,130 @@ Entry Documentation: All other Basic List Objects are not executed unless either an "item" or a "failsafe" specifies a valid Item name. Execution of all Items are top-down. - The "setting" Item Object represents settings and is not an "item" that can be executed. - A number of settings are supported, but if this Item Object is not specified, then defaults are used. - The following settings are available: "mode", "pid", and "show". - - The "mode" setting represents the mode in which the Entry is operating in. - The following modes are supported: "program" and "service". - - The "program" mode\: - Designates that the Entry operates as a program and exits when complete. - Will call the "exit" with the same name as this Entry, but with the extension "exit", such as "default.exit". - Supports the Item Action "execute" to execute a program (switching the "controller" program entirely with the executed process). - - The "service" mode\: - Designates that the Entry operates as a service and will sit and wait for control commands when complete. - Will call the "exit" with the same name as this Entry, but with the extension "exit", such as "default.exit". - Does not support the Item Action "execute". - This is the default mode. - - The "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 "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. - - Each "item" supports the following Action Names: "consider", "execute", "failsafe", "freeze", "item", "kill", "pause", "reload", "restart", "ready", "resume", "start", "stop", and "timeout". - Of those types, the following are considered a "rule" Action: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", and "thaw". - - The "consider" Item Action is a special case of a "rule" Action. - All Action Parameters are the same as with the "rule" Action Parameters. - The difference is that "consider" is only processed (instead of being processed and executed) and when some "rule" Action designates that this consideration is required (via "need"), wanted (via "want"), or wished for (via "wish") from the within the Rule file. - If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as "asynchronous", for example). - If this is determined not to be executed, then this "consider" is ignored as if it was never there in the first place. - - The "execute" Item Action well execute into the specified program. - On successfull execution, the controller program will no longer be running and will be replaced with the designated program. - This Item Action is only supported when operating in "program" mode. - - The "failsafe" Item Action accepts only a valid Item Name in which will be executed when a failure is detected. - Only a single "failsafe" Item Action may function at a time. - Each successive "failsafe" Item Action specified replaces the previously defined "failsafe" Item Action (in a top-down manner). - When operating in "failsafe", the "require" Item Action is ignored (given that it is meaningless once operating in "failsafe" mode). - - The "freeze" Item Action is a "rule" Action for freezing some Control Group. - This Item Action will process the "freeze" inner Content of the named Rule. - This is specific to Control Groups and is not yet fully implemented. - Once implemented this documentation will need to be updated and clarified. - - The "item" Item Action accepts only a valid Item Name in which will be immediately executed. - Any valid Item Name, except for the reserved "main", may be used. - - The "kill" Item Action is a "rule" Action for forcibly terminating some process. - This Item Action will process the "kill" inner Content of the named Rule. - - The "pause" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "pause" inner Content of the named Rule. - - The "reload" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "reload" inner Content of the named Rule. - - The "restart" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "restart" inner Content of the named Rule. - - The "resume" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "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. - 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 filesystem 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 is a "rule" Action for pausing some process. - This Item Action will process the "start" inner Content of the named Rule. - - The "stop" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "stop" inner Content of the named Rule. - - The "thaw" Item Action is a "rule" Action for unfreezing some Control Group. - This Item Action will process the "thaw" inner Content of the named Rule. - This is specific to Control Groups and is not yet fully implemented. - Once implemented this documentation will need to be updated and clarified. - - In the case of "timeout"\: - The "timeout" Item Action provides default global 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", one "stop", and one "wait"). - 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). - Each of these accepts a single Action Parameter that is 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. - A value of 0 disables this (prevents the timeout action). + The "setting" item Object\: + Represents settings and is not an "item" that can be executed. + A number of settings are supported, but if this Item Object is not specified, then defaults are used. + The following settings are available: "mode", "pid", "session", and "show". + + The "mode" setting\: + Represents the mode in which the Entry is operating in. + The following modes are supported: "program" and "service". + + The "program" mode\: + Designates that the Entry operates as a program and exits when complete. + Will call the "exit" with the same name as this Entry, but with the extension "exit", such as "default.exit". + Supports the Item Action "execute" to execute a program (switching the "controller" program entirely with the executed process). + + The "service" mode\: + Designates that the Entry operates as a service and will sit and wait for control commands when complete. + Will call the "exit" with the same name as this Entry, but with the extension "exit", such as "default.exit". + Does not support the Item Action "execute". + This is the default mode. + + The "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 "session" setting\: + Represents the default way in which child processes are executed. + This default can be overriden by individual Rules. + For "new", Execute rule processes in a new session setting the process group to the executed process' id (making the executed process a "controlling terminal"). + For "same", Execute rule processes in the same session where the process group is set to the parent process id. + + The "show" setting\: + Represents the way entry processing presents information to the screen. + This applies only to the entry and rule processing itself and does not handle the output of programs and scripts being executed by some entry or rule. + The following show options are supported: "normal" and "init". + For "normal", will not report the start or stop of some entry or rule execution but will report any errors or warnings as appropriate. + For "init", will report when starting programs and may include reporting success and failure status. + + The "item" item Object\: + Each "item" supports the following Action Names: "consider", "execute", "failsafe", "freeze", "item", "kill", "pause", "reload", "restart", "ready", "resume", "start", "stop", and "timeout". + Of those types, the following are considered a "rule" Action: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", and "thaw". + + The "consider" Item Action\: + A special case of a "rule" Action. + All Action Parameters are the same as with the "rule" Action Parameters. + The difference is that "consider" is only processed (instead of being processed and executed) and when some "rule" Action designates that this consideration is required (via "need"), wanted (via "want"), or wished for (via "wish") from the within the Rule file. + If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as "asynchronous", for example). + If this is determined not to be executed, then this "consider" is ignored as if it was never there in the first place. + + The "execute" Item Action\: + Execute into the specified program. + On successfull execution, the controller program will no longer be running and will be replaced with the designated program. + This Item Action is only supported when operating in "program" mode. + + The "failsafe" Item Action\: + Accepts only a valid Item Name in which will be executed when a failure is detected. + Only a single "failsafe" Item Action may function at a time. + Each successive "failsafe" Item Action specified replaces the previously defined "failsafe" Item Action (in a top-down manner). + When operating in "failsafe", the "require" Item Action is ignored (given that it is meaningless once operating in "failsafe" mode). + + The "freeze" Item Action\: + A "rule" Action for freezing some Control Group. + This Item Action will process the "freeze" inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + The "item" Item Action\: + Accepts only a valid Item Name in which will be immediately executed. + Any valid Item Name, except for the reserved "main", may be used. + + The "kill" Item Action\: + A "rule" Action for forcibly terminating some process. + This Item Action will process the "kill" inner Content of the named Rule. + + The "pause" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "pause" inner Content of the named Rule. + + The "reload" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "reload" inner Content of the named Rule. + + The "restart" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "restart" inner Content of the named Rule. + + The "resume" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "resume" inner Content of the named Rule. + + The "ready" Item Action\: + Instructs the controller program when it is safe to perform normal tasks, such as creating the pid file. + When not specified, the state is always assumed to be ready. + For example, the controller program may be used as a full blown "init" replacement and therefore may need to mount the /var/run/ directory. + If the pid file is created at program start, then the /var/run/controller.pid would be written before the /var/run/ directory is ready. + This could be a problem, such as on a read-only filesystem the pid creation fails and controller bails out on error. + Adding "ready" essentially specifies a point in time in the Entry in which things are expected to be safe for such basic operations. + When the optional "wait" is provided, then "ready" will wait for all currently started asynchronous processes to complete before operating. + + The "start" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "start" inner Content of the named Rule. + + The "stop" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "stop" inner Content of the named Rule. + + The "thaw" Item Action\: + A "rule" Action for unfreezing some Control Group. + This Item Action will process the "thaw" inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + The "timeout" Item Action\: + Provides default global 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", one "stop", and one "wait"). + 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). + Each of these accepts a single Action Parameter that is 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. + A value of 0 disables this (prevents the timeout action). Entry Rule Documentation: There are multiple Entry Actions that are considered "rule" Actions. diff --git a/level_3/controller/documents/exit.txt b/level_3/controller/documents/exit.txt index 6af2c94..ce18e9c 100644 --- a/level_3/controller/documents/exit.txt +++ b/level_3/controller/documents/exit.txt @@ -6,95 +6,114 @@ Exit Documentation: An Exit file, such as "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. - The "main" Item Object is always executed first (Therefore "main" is both reserved and required). - All other Basic List Objects are not executed unless either an "item" or a "failsafe" specifies a valid Item name. - Execution of all Items are top-down. - - The "setting" Item Object represents settings and is not an "item" that can be executed. - A number of settings are supported, but if this Item Object is not specified, then defaults are used. - The following settings are available: "pid" and "show". - - 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 "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. - - Each "item" supports the following Action Names: "consider", "execute", "failsafe", "freeze", "item", "kill", "pause", "reload", "restart", "ready", "resume", "start", "stop", and "timeout". - Of those types, the following are considered a "rule" Action: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", and "thaw". - - The "consider" Item Action is a special case of a "rule" Action. - All Action Parameters are the same as with the "rule" Action Parameters. - The difference is that "consider" is only processed (instead of being processed and executed) and when some "rule" Action designates that this consideration is required (via "need"), wanted (via "want"), or wished for (via "wish") from the within the Rule file. - If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as "asynchronous", for example). - If this is determined not to be executed, then this "consider" is ignored as if it was never there in the first place. - - The "execute" Item Action well execute into the specified program. - On successfull execution, the controller program will no longer be running and will be replaced with the designated program. - This Item Action is only supported when operating in "program" mode. - - The "failsafe" Item Action accepts only a valid Item Name in which will be executed when a failure is detected. - Only a single "failsafe" Item Action may function at a time. - Each successive "failsafe" Item Action specified replaces the previously defined "failsafe" Item Action (in a top-down manner). - When operating in "failsafe", the "require" Item Action is ignored (given that it is meaningless once operating in "failsafe" mode). - - The "freeze" Item Action is a "rule" Action for freezing some Control Group. - This Item Action will process the "freeze" inner Content of the named Rule. - This is specific to Control Groups and is not yet fully implemented. - Once implemented this documentation will need to be updated and clarified. - - The "item" Item Action accepts only a valid Item Name in which will be immediately executed. - Any valid Item Name, except for the reserved "main", may be used. - - The "kill" Item Action is a "rule" Action for forcibly terminating some process. - This Item Action will process the "kill" inner Content of the named Rule. - - The "pause" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "pause" inner Content of the named Rule. - - The "reload" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "reload" inner Content of the named Rule. - - The "restart" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "restart" inner Content of the named Rule. - - The "resume" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "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. - 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 filesystem 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 is a "rule" Action for pausing some process. - This Item Action will process the "start" inner Content of the named Rule. - - The "stop" Item Action is a "rule" Action for pausing some process. - This Item Action will process the "stop" inner Content of the named Rule. - - The "thaw" Item Action is a "rule" Action for unfreezing some Control Group. - This Item Action will process the "thaw" inner Content of the named Rule. - This is specific to Control Groups and is not yet fully implemented. - Once implemented this documentation will need to be updated and clarified. - - The "timeout" Item Action provides default global settings for each of the three special situations: "start", "stop", and "kill". - Each of these may only have a single one exist at a time (one "start", one "stop", and one "kill"). - Each successive "timeout" Item Action, specific to each Action Name (such as "start"), specified replaces the previously defined "timeout" Action (in a top-down manner). - Each of these accepts a single Action Parameter that is a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds). - 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 "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). - The timeouts are generally only valid for services such as daemon services. - A value of 0 disables this (prevents any action). + The "setting" Item Object\: + Represents settings and is not an "item" that can be executed. + A number of settings are supported, but if this Item Object is not specified, then defaults are used. + The following settings are available: "pid" and "show". + + 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 "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 "main" Item Object\: + Is always executed first (Therefore "main" is both reserved and required). + All other Basic List Objects are not executed unless either an "item" or a "failsafe" specifies a valid Item name. + Execution of all Items 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". + + The "consider" Item Action\: + A special case of a "rule" Action. + All Action Parameters are the same as with the "rule" Action Parameters. + The difference is that "consider" is only processed (instead of being processed and executed) and when some "rule" Action designates that this consideration is required (via "need"), wanted (via "want"), or wished for (via "wish") from the within the Rule file. + If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as "asynchronous", for example). + If this is determined not to be executed, then this "consider" is ignored as if it was never there in the first place. + + The "execute" Item Action\: + Execute into the specified program. + On successfull execution, the controller program will no longer be running and will be replaced with the designated program. + This Item Action is only supported when operating in "program" mode. + + The "failsafe" Item Action\: + Accepts only a valid Item Name in which will be executed when a failure is detected. + Only a single "failsafe" Item Action may function at a time. + Each successive "failsafe" Item Action specified replaces the previously defined "failsafe" Item Action (in a top-down manner). + When operating in "failsafe", the "require" Item Action is ignored (given that it is meaningless once operating in "failsafe" mode). + + The "freeze" Item Action\: + A "rule" Action for freezing some Control Group. + This Item Action will process the "freeze" inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + The "item" Item Action\: + Accepts only a valid Item Name in which will be immediately executed. + Any valid Item Name, except for the reserved "main", may be used. + + The "kill" Item Action\: + A "rule" Action for forcibly terminating some process. + This Item Action will process the "kill" inner Content of the named Rule. + + The "pause" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "pause" inner Content of the named Rule. + + The "reload" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "reload" inner Content of the named Rule. + + The "restart" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "restart" inner Content of the named Rule. + + The "resume" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "resume" inner Content of the named Rule. + + The "ready" Action\: + Instructs the controller program when it is safe to perform normal tasks, such as creating the pid file. + When not specified, the state is always assumed to be ready. + For example, the controller program may be used as a full blown "init" replacement and therefore may need to mount the /var/run/ directory. + If the pid file is created at program start, then the /var/run/controller.pid would be written before the /var/run/ directory is ready. + This could be a problem, such as on a read-only filesystem the pid creation fails and controller bails out on error. + Adding "ready" essentially specifies a point in time in the Entry in which things are expected to be safe for such basic operations. + When the optional "wait" is provided, then "ready" will wait for all currently started asynchronous processes to complete before operating. + + The "start" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "start" inner Content of the named Rule. + + The "stop" Item Action\: + A "rule" Action for pausing some process. + This Item Action will process the "stop" inner Content of the named Rule. + + The "thaw" Item Action\: + A "rule" Action for unfreezing some Control Group. + This Item Action will process the "thaw" inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + The "timeout" Item Action\: + Provides default global settings for each of the three special situations: "start", "stop", and "kill". + Each of these may only have a single one exist at a time (one "start", one "stop", and one "kill"). + Each successive "timeout" Item Action, specific to each Action Name (such as "start"), specified replaces the previously defined "timeout" Action (in a top-down manner). + Each of these accepts a single Action Parameter that is a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds). + 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 "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). + The timeouts are generally only valid for services such as daemon services. + A value of 0 disables this (prevents any action). Exit Rule Documentation: There are multiple Entry Actions that are considered "rule" Actions. diff --git a/level_3/controller/documents/rule.txt b/level_3/controller/documents/rule.txt index fc0edd5..661993b 100644 --- a/level_3/controller/documents/rule.txt +++ b/level_3/controller/documents/rule.txt @@ -9,22 +9,22 @@ Rule Documentation: Multiple outer most list Objects may be specified and they are executed as provided, in a top-down manner. The "setting" 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"). - "control_group": Define a control group (cgroup) in which everything within this rule executes under. - "define": Define a custom environment variable with a given variable, and automatically expose it to processes executed within this rule. @todo make sure this is implemented. - "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": A statically defined IKI name and its associated value for use in this rule file. @todo make sure this is implemented and make sure to perform iki substitutions (with "define" being a reserved iki parameter name for environment variable usage, such as define:"PATH"). - "path": A single Content used to set a custom PATH environment variable value. - "script": An executable name of a script, such as "bash", to use for the "script" Rule Type (which likely defaults to "bash" if not specified). - "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. + - "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"). + - "control_group": Define a control group (cgroup) in which everything within this rule executes under. + - "define": Define a custom environment variable with a given variable, and automatically expose it to processes executed within this rule. @todo make sure this is implemented. + - "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": A statically defined IKI name and its associated value for use in this rule file. @todo make sure this is implemented and make sure to perform iki substitutions (with "define" being a reserved iki parameter name for environment variable usage, such as define:"PATH"). + - "path": A single Content used to set a custom PATH environment variable value. + - "script": An executable name of a script, such as "bash", to use for the "script" Rule Type (which likely defaults to "bash" if not specified). + - "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. In the case of "capability"\: If the user the controller program is run as does not have the desired capabilities already, they cannot be added. @@ -121,5 +121,7 @@ Rule Documentation: The "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"). + - "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. diff --git a/level_3/controller/documents/simulate.txt b/level_3/controller/documents/simulate.txt index d900623..cf0b41d 100644 --- a/level_3/controller/documents/simulate.txt +++ b/level_3/controller/documents/simulate.txt @@ -3,20 +3,23 @@ Simulate Documentation: This describes the intent and purpose of the simulation and validation parameters. - The "controller" program is design to support being run as an alternative to an init program (such as Sysvinit or SystemD). + The "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, 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 "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 "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. + The "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. - The "simulate" functionality, when specified along with the "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 "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. 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. This allows for testing the designated permissions and other settings that would be applied when calling some program. diff --git a/level_3/controller/specifications/entry.txt b/level_3/controller/specifications/entry.txt index 267b2ac..1e8c3f6 100644 --- a/level_3/controller/specifications/entry.txt +++ b/level_3/controller/specifications/entry.txt @@ -15,10 +15,12 @@ Entry Specification: The Items: "main": required. + "setting": optional, Actions may be one of: - - "mode": either "program" or "service". - - "pid": either "disable", "require", or "ready". - - "show": either "normal" or "init". + - "mode": Exactly one Content that is one of "program" or "service". + - "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". The Entry file may have any other valid Item Objects, but only the above are reserved. @@ -30,10 +32,13 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "execute": One or more Content. The first Content is the program name or full path to the program (the program may be a script). All remaining Content are passed as parameters to the program being executed. + "failsafe": One Content that is a valid Object name, except for the reserved "main". + "freeze": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -41,7 +46,9 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "item": One Content that is a valid Object name, except for the reserved "main". + "kill": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -49,6 +56,7 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "pause": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -56,9 +64,11 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "ready": Zero or One Content. The first may only be one of\: - "wait" + "reload": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -66,6 +76,7 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "restart": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -73,6 +84,7 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "resume": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -80,6 +92,7 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "start": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -87,6 +100,7 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "stop": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -94,6 +108,7 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "thaw": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -101,6 +116,7 @@ Entry Specification: - "asynchronous" - "require" - "wait" + "timeout": Two Content. The first being one of\: - "start" diff --git a/level_3/controller/specifications/exit.txt b/level_3/controller/specifications/exit.txt index 978bf50..08fedc9 100644 --- a/level_3/controller/specifications/exit.txt +++ b/level_3/controller/specifications/exit.txt @@ -15,9 +15,11 @@ Exit Specification: The Items: "main": required. + "setting": optional, Actions may be one of: - - "pid": either "disable", "optional", or "require". - - "show": either "normal" or "init". + - "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". The Exit file may have any other valid Item Objects, but only the above are reserved. @@ -29,7 +31,9 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "failsafe": One Content that is a valid Object name, except for the reserved "main". + "freeze": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -37,7 +41,9 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "item": One Content that is a valid Object name, except for the reserved "main". + "kill": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -45,6 +51,7 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "pause": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -52,9 +59,11 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "ready": Zero or One Content. The first may only be one of\: - "wait" + "reload": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -62,6 +71,7 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "restart": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -69,6 +79,7 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "resume": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -76,6 +87,7 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "start": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -83,6 +95,7 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "stop": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -90,6 +103,7 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "thaw": Two or more Content. The first Content that is the relative directory path (without any leading/trailing slashes). The second Content that is the basename for a rule file. @@ -97,6 +111,7 @@ Exit Specification: - "asynchronous" - "require" - "wait" + "timeout": Two Content. The first being one of\: - "start" diff --git a/level_3/controller/specifications/rule.txt b/level_3/controller/specifications/rule.txt index 2ab539c..d41b6ac 100644 --- a/level_3/controller/specifications/rule.txt +++ b/level_3/controller/specifications/rule.txt @@ -18,72 +18,72 @@ Rule Specification: - Each Setting Content are the "Setting Values". The Rule Types\: - "command": FSS-0003 (Extended List) or FSS-0001 (Extended). - "script": FSS-0003 (Extended List) or FSS-0001 (Extended). - "service": FSS-0003 (Extended List) or FSS-0001 (Extended). - "setting": (Required) FSS-0001 (Extended). - "utility": FSS-0003 (Extended List) or FSS-0001 (Extended). + - "command": FSS-0003 (Extended List) or FSS-0001 (Extended). + - "script": FSS-0003 (Extended List) or FSS-0001 (Extended). + - "service": FSS-0003 (Extended List) or FSS-0001 (Extended). + - "setting": (Required) FSS-0001 (Extended). + - "utility": FSS-0003 (Extended List) or FSS-0001 (Extended). For the above Rule Types, "setting" may be specified only once whereas the others may be specifed multiple times. The "setting" Rule Type is always processed first, regardless of position. The other Rule Types are processed top-down. The "setting" 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. - "control_group": Two or more Content, the first Content being either "existing" or "new" and the remaining representing a valid control group (cgroup) name, must have at least 1 graph character (non-whitespace printing character) (leading and trailing whitespace 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). - "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-whitespace printing character) (leading and trailing whitespace 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). - "script": One Content representing a valid program name or path (such as "bash" or "/bin/bash"). - "user": One Content representing a user name or user id. + - "affinity": One or more Content, each must be a 0 or greater whole number. + - "capability": One Content representing capabilities. + - "control_group": Two or more Content, the first Content being either "existing" or "new" and the remaining representing a valid control group (cgroup) name, must have at least 1 graph character (non-whitespace printing character) (leading and trailing whitespace 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). + - "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-whitespace printing character) (leading and trailing whitespace 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). + - "script": One Content representing a valid program name or path (such as "bash" or "/bin/bash"). + - "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. + - "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 "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 representing special options for the Rule Type. + - "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 "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. + - "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 "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. + - "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 "rerun" Rule Type Content has the following structure\: The first Content represents one of: "freeze", "kill", "pause", "reload", "restart", "resume", "start", "stop", or "thaw". -- 1.8.3.1