[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: policy-rc.d

On Thu, 03 Jul 2003, Marc Singer wrote:
> > Take a look at invoke-rc.d and its policy program.
> OK.  I can tell that this feature is available, though obscured by the
> lack of a man page for policy-rc.d or even a reference to a package
> that implements it.  I *did* find a document through google, however.
> Reading it doesn't make it much clearer.

That's because nobody wrote a sample (or generic, whatever) policy-rc.d yet

Now, what happened to policy-rc.d(8), I don't know.  Let me search to see if
I ever wrote a sample one... 

/me notices in horror that projects/debian/initscripts is empty... ARGH!
google to the rescue... let me wget them right back!

> My search through a Contents file doesn't show an implementor for
> policy-rc.d.  Is there one or is it adhoc?

I wrote one for chroots a while back. It simply did an exit 101 :)

For reference, I am attaching the interface description of policy-rc.d.  I
(or someone else) should write a manpage for it one of these days...

  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh
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

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, 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.


     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.

     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 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.

     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.

     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.

     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.

     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.

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> ...]

     no error messages are generated.

     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

  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.

Reply to: