debian/src/sysv-rc/doc/README.policy-rc.d

   1
   2
   3 This is the internal documentation for policy-rc.d, as
   4 written by Henrique M Holschuh <hmh@debian.org>
   5
   6 This document can be found on the web as well at
   7 http://people.debian.org/~hmh/invokerc.d-policyrc.d-specification.txt
   8
   9 There is also the Debian BTS entry for the invoke-rc.d policy change at
  10 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=76868
  11
  12
  13 POLICY-RC.D   Policy layer (/usr/sbin/policy-rc.d) interface:
  14 =============================================================
  15
  16 Most Debian systems will not have this script as the need for a policy layer
  17 is not very common. Most people using chroot jails just need an one-line
  18 script which returns an exit status of 101 as the jailed
  19 /usr/sbin/policy-rc.d script.
  20
  21 The /usr/sbin/policy-rc.d file *must* be managed through the alternatives
  22 system (/usr/sbin/update-alternatives) by any packages providing it.
  23
  24 /usr/sbin/policy-rc.d [options] <initscript ID> <actions> [<runlevel>]
  25 /usr/sbin/policy-rc.d [options] --list <initscript ID> [<runlevel> ...]
  26
  27 Options:
  28  --quiet
  29      no error messages are generated.
  30
  31  --list
  32      instead of verifying policy, list (in a "human parseable" way) all
  33      policies defined for the given initscript id (for all runlevels if no
  34      runlevels are specified; otherwise, list it only for the runlevels
  35      specified), as well as all known actions and their fallbacks for the
  36      given initscript id (note that actions and fallback actions might be
  37      global and not particular to a single initscript id).
  38
  39 <actions> is a space-separated list of actions (usually only one). Note that
  40 the list is passed in a single parameter and not as multiple parameters.
  41
  42 The following actions are always known (even if specifying a policy for them
  43 is not supported by whatever policy-rc.d system is in use): start,
  44 [force-]stop, restart, [force-]reload, status.
  45
  46 If an out-of-runlevel start or restart attempt is detected by invoke-rc.d,
  47 the "start" or "restart" action will be changed to "(start)" or "(restart)"
  48 respectively. This allows policy-rc.d to differentiate an out-of-runlevel
  49 start/restart from a normal one.
  50
  51 The runlevel parameters are optional. If a runlevel is not specified, it is
  52 considered to be unknown/undefined. Note that for sysv-like initscript
  53 systems, an undefined runlevel is very likely to cause a 105 exit status.
  54
  55 A runlevel for update-rc.d is defined as a character string, of which the
  56 usual INIT one-character runlevels are only a subset. It may contain
  57 embedded blanks.
  58
  59  stdout is used to output a single line containing fallback actions,
  60            or to output --list results.
  61  stderr is used to output error messages
  62  stdin  is not to be used, this is not an interactive interface.
  63
  64  Exit status codes:
  65   0 - action allowed
  66   1 - unknown action (therefore, undefined policy)
  67  100 - unknown initscript id
  68  101 - action forbidden by policy
  69  102 - subsystem error
  70  103 - syntax error
  71  104 - [reserved]
  72  105 - behaviour uncertain, policy undefined.
  73  106 - action not allowed. Use the returned fallback actions
  74        (which are implied to be "allowed") instead.
  75
  76 When in doubt (policy-rc.d returned status 105 or status 1), invoke-rc.d
  77 will assume an action is allowed, but it will warn the user of the problem.
  78
  79 Returning fallback information:
  80
  81 Fallback actions are returned in the first line sent to stdout (other lines
  82 will be discarded). Multiple actions to be tried are allowed, and must be
  83 separated by spaces. Multiple actions are carried out one at a time, until
  84 one is sucessful.
  85
  86 e.g.: returning status 106 and "restart stop" in stdout (without
  87 the quotes) will cause invoke-rc.d to attempt action "restart",
  88 and then only if "restart" failed, attempt action "stop".
  89
  90 invoke-rc.d built-in policy rules:
  91
  92 To shield policy-rc.d of the underlying initscript system (file-rc, links in
  93 /etc/rc?.d or something else), invoke-rc.d implements the following built-in
  94 rules:
  95
  96   1. action "start" out of runlevel is denied,
  97      (policy-rc.d receives action "(start)" instead of "start");
  98   2. action "restart" out of runlevel is denied,
  99      (policy-rc.d receives action "(restart)" instead of "restart");
 100   3. any action for a non-executable initscript is denied.
 101
 102 Rule 3 is absolute, policy-rc.d cannot override it.