1 files changed, 102 insertions, 0 deletions
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.