Adding upstream version 1.66.upstream/1.66upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

2 files changed, 237 insertions, 0 deletions

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 <hmh@debian.org>
+
+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] <basename> <action> [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. <action> 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 <hmh@debian.org>
+
+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] <initscript ID> <actions> [<runlevel>]
+/usr/sbin/policy-rc.d [options] --list <initscript ID> [<runlevel> ...]
+
+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).
+
+<actions> 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.