From 618e47799afdfc2783d8469ca909aafa4acfa7b6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 19:29:54 +0200 Subject: Adding upstream version 1.66. Signed-off-by: Daniel Baumann --- doc/README.invoke-rc.d | 135 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/README.policy-rc.d | 102 +++++++++++++++++++++++++++++++++++++ 2 files changed, 237 insertions(+) create mode 100644 doc/README.invoke-rc.d create mode 100644 doc/README.policy-rc.d (limited to 'doc') diff --git a/doc/README.invoke-rc.d b/doc/README.invoke-rc.d new file mode 100644 index 0000000..473fd2d --- /dev/null +++ b/doc/README.invoke-rc.d @@ -0,0 +1,135 @@ + + +This is the internal documentation for invoke-rc.d, as +written by Henrique M Holschuh + +This document can be found on the web as well at +http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt + +There is also the Debian BTS entry for the invoke-rc.d policy change at +http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=76868 + + +INVOKE-RC.D (/usr/sbin/invoke-rc.d) interface: +============================================== + +The interface for all implementations of invoke-rc.d is mandated by the base +implementation in the sysvinit package, just like it is done for +update-rc.d. + +There is a provision for a "local initscript policy layer" (read: a call to +/usr/sbin/policy-rc.d if this executable is present in the local system), +which allows the local system administrator to control the behaviour of +invoke-rc.d for every initscript id and action. It is assumed that this +script is OPTIONAL and will by written and provided by packages other than +the initscript system (sysvinit and file-rc packages). + +The basic interface for all implementations of policy-rc.d is mandated by +the requirements of the base implementation of invoke-rc.d. This interface +will be described either in the manpage of invoke-rc.d, and in a text file +stored in /usr/share/doc/sysvinit/ by package sysvinit (which will host the +base implementation of invoke-rc.d). + +Proposed script interfaces: + +invoke-rc.d [options] [extra initscript parameters...] + + basename - Initscript ID, as per update-rc.d(8) + action - Initscript action. Known actions are: + start, [force-]stop, [try-]restart, + [force-]reload, status + (status is there because of the LSB. Debian does not use it). + + extra initscript parameters: These parameters are passed to the initscript + as is, after the action parameter. is always the first paramenter + to the initscript, and may be modified by fallback actions or policy-rc.d + requests. Note, however, that the extra parameters are not dropped or + modified even if the action (first parameter) is modified. + +Options: + + --quiet + Quiet mode, no error messages are generated by invoke-rc.d; policy-rc.d + is also called with --quiet if this option is in effect. + + --force + Try to run init script regardless of policy and non-fatal errors. Use + of this option in automated scripts is severely discouraged as it + bypasses integrity checks. If the initscript cannot be executed, error + status 102 is returned. Do note that the policy layer call + (policy-rc.d) is NOT skipped, although its results are ignored. + + --try-anyway + Try to run the initscript even if a non-fatal subsystem error is + detected (e.g: bad rc.d symlinks). A 102 status exit code will result + if init script fails to execute anyway). Unlike --force, policy is + still enforced with --try-anyway. + + --disclose-deny + Return status code 101 instead of status code 0 if initscript action is + denied by local policy rules or runlevel constrains. An warning is + generated if the action is denied. + + --query + Returns one of status codes 100-106, does not execute the init.d + script. Implies --disclose-deny and --nofallback. Status codes 104-106 + are only generated by this option. + + Note many messages are still sent to stderr in --query mode, including + those regarding policy overrides and subsystem errors. Use --quiet if + silent --query operation is desired. + + --no-fallback + The policy layer (policy-rc.d) may return fallback actions to be run + instead of the requested action. If this option is active, a fallback + action request will be ignored and a "action not allowed" reply used in + its place. This is probably a BAD idea unless you know exactly what + you're doing. + + --help + Outputs help message to stdout + +Unknown actions may generate warnings, but are passed to the underlying +initscript anyway. The reason for the warning is simple: It is very unlikely +that an unknown action (by invoke-rc.d) will be known to the policy layer +(policy-rc.d), and therefore it may cause an initscript to execute an action +which the local system administrator would have not allowed had he known +about it. If policy-rc.d is not present, no warnings for unknown actions +are generated. + +Should an initscript be executed, invoke-rc.d ALWAYS returns the status code +returned by the initscript. Initscripts should not return status codes in +the 100+ range (this is also a LSB requirement). + +Exit status codes (LSB compatible): + 0 : success + either the init script was run and returned exit status 0 (note + that a fallback action may have been run instead of the one given + in the command line), or it was not run because of runlevel/local + policy constrains and --disclose-deny is not in effect. + 1 - 99 : reserved for init.d script + 100 : init script ID (basename) unknown + init script not registered sucessfully through + update-rc.d or init script does not exist. + This error is fatal for most initscript systems. + 101 : action not allowed + requested action will not be performed because of + runlevel or local policy constrains, and + --disclose-deny is in effect. Note that a fallback + action is NOT considered "action not allowed", + unless --nofalback is in effect. + 102 : subsystem error + initscript (or policy) subsystem malfuncion. + (e.g. broken /sbin/runlevel). + Also, forced initscript execution due to + --try-anyway or --force failed. + 103 : syntax error + 104 : action allowed + --query is in effect; init script would be run if + not for --query. + 105 : behaviour uncertain + cannot determine if action should be carried out or + not, and --query in effect. + 106 : fallback action requested + the policy layer denied the requested action, and + supplied an allowed fallback action. diff --git a/doc/README.policy-rc.d b/doc/README.policy-rc.d new file mode 100644 index 0000000..232ebb6 --- /dev/null +++ b/doc/README.policy-rc.d @@ -0,0 +1,102 @@ + + +This is the internal documentation for policy-rc.d, as +written by Henrique M Holschuh + +This document can be found on the web as well at +http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt + +There is also the Debian BTS entry for the invoke-rc.d policy change at +http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=76868 + + +POLICY-RC.D Policy layer (/usr/sbin/policy-rc.d) interface: +============================================================= + +Most Debian systems will not have this script as the need for a policy layer +is not very common. Most people using chroot jails just need an one-line +script which returns an exit status of 101 as the jailed +/usr/sbin/policy-rc.d script. + +The /usr/sbin/policy-rc.d file *must* be managed through the alternatives +system (/usr/sbin/update-alternatives) by any packages providing it. + +/usr/sbin/policy-rc.d [options] [] +/usr/sbin/policy-rc.d [options] --list [ ...] + +Options: + --quiet + no error messages are generated. + + --list + instead of verifying policy, list (in a "human parseable" way) all + policies defined for the given initscript id (for all runlevels if no + runlevels are specified; otherwise, list it only for the runlevels + specified), as well as all known actions and their fallbacks for the + given initscript id (note that actions and fallback actions might be + global and not particular to a single initscript id). + + is a space-separated list of actions (usually only one). Note that +the list is passed in a single parameter and not as multiple parameters. + +The following actions are always known (even if specifying a policy for them +is not supported by whatever policy-rc.d system is in use): start, +[force-]stop, restart, [force-]reload, status. + +If an out-of-runlevel start or restart attempt is detected by invoke-rc.d, +the "start" or "restart" action will be changed to "(start)" or "(restart)" +respectively. This allows policy-rc.d to differentiate an out-of-runlevel +start/restart from a normal one. + +The runlevel parameters are optional. If a runlevel is not specified, it is +considered to be unknown/undefined. Note that for sysv-like initscript +systems, an undefined runlevel is very likely to cause a 105 exit status. + +A runlevel for update-rc.d is defined as a character string, of which the +usual INIT one-character runlevels are only a subset. It may contain +embedded blanks. + + stdout is used to output a single line containing fallback actions, + or to output --list results. + stderr is used to output error messages + stdin is not to be used, this is not an interactive interface. + + Exit status codes: + 0 - action allowed + 1 - unknown action (therefore, undefined policy) + 100 - unknown initscript id + 101 - action forbidden by policy + 102 - subsystem error + 103 - syntax error + 104 - [reserved] + 105 - behaviour uncertain, policy undefined. + 106 - action not allowed. Use the returned fallback actions + (which are implied to be "allowed") instead. + +When in doubt (policy-rc.d returned status 105 or status 1), invoke-rc.d +will assume an action is allowed, but it will warn the user of the problem. + +Returning fallback information: + +Fallback actions are returned in the first line sent to stdout (other lines +will be discarded). Multiple actions to be tried are allowed, and must be +separated by spaces. Multiple actions are carried out one at a time, until +one is sucessful. + +e.g.: returning status 106 and "restart stop" in stdout (without +the quotes) will cause invoke-rc.d to attempt action "restart", +and then only if "restart" failed, attempt action "stop". + +invoke-rc.d built-in policy rules: + +To shield policy-rc.d of the underlying initscript system (file-rc, links in +/etc/rc?.d or something else), invoke-rc.d implements the following built-in +rules: + + 1. action "start" out of runlevel is denied, + (policy-rc.d receives action "(start)" instead of "start"); + 2. action "restart" out of runlevel is denied, + (policy-rc.d receives action "(restart)" instead of "restart"); + 3. any action for a non-executable initscript is denied. + +Rule 3 is absolute, policy-rc.d cannot override it. -- cgit v1.2.3