This RFC addresses bugs #20373 and #60979, as well as a recent subthread in
debian-policy.
Hello Developers,
The main body of this message is only a "why the heck do we need this stuff"
clarification and overview of the issue and proposal itself... the real
goodies are in attachments.
Please read the attached proposal, and comment on it. If you use chroot
environments to test packages, or dislike services starting up automatically
on package [first] installs, this proposal is very likely to be of some
interest to you.
WHAT?
This policy proposal tries to better define the behaviour of initscripts in
Debian, as well as fixing bugs #60979 and #20373. It also defines two
mandatory interfaces for the packaging system (in the form of programs the
postinst, prerm and other maintainer-written scripts will have to use
instead of directly calling /etc/init.d scripts) to interact with the
initscript system in a (hopefully) non-broken way.
It does not intend to fully define the initscript system, only to clarify
the meaning of "restart" (#60979), introduce the notion of "maybe-restart"
(optional -- you won't need to change your initscript to add this option if
you don't want to) and fix the issue of daemons starting/stopping in
undesired circunstances.
WHY?
Due to the good handling of 'conf files' by the package system, and the
reasonable way most packages implement their initscripts, Debian is usually
a very well behaved distribution when it comes down to keeping itself out of
the local sysadmin toes in the initscript area. The update-rc.d program and
its mandatory usage is in no small way responsible for this Good Thing.
However, there are still some rough points in need of fixing. Currently, one
may have to fight the packaging system during daemon upgrades or when
dealing with chrooted environments, as the large majority (all?) of the
package scripts do not pay any sort of attention to the current runlevel.
This is not readly apparent if one never needs to custom-configure his
runlevels, so many people never notices the problem.
I am aware there are more important issues to address in Debian, but in true
"if it bothers you, fix it yourself" fashion, I've decided to try to do all
of the needed polishing work and put an end to at least this lesser one.
While I haven't coded everything yet (the file-rc compatibility scripts and
manpages are not finished), I am fully prepared to do so should this
proposal be accepted :-)
This proposal adds new flexibility to the already outstanding initscript
system in Debian, and fixes the borderline cases where one needs to do
horrible hacks to get the system to behave.
HOW?
An interface script to call the /etc/init.d/ scripts is provided and its use
by maintainer scripts is made mandatory. This script acts as a screen to
allow not only different initscript schemes to be deployed, but it also
takes care to block attempts to start (or stop, restart, reload... it's
configurable) an initscript if the local system configuration denies such an
attempt.
Unless the local system administrator takes specific action to do so, *the
current behaviour of the initscript system is not modified* except in the
two following cases:
1. Initscripts are not allowed to start out of their intended runlevel.
(we simply force the packaging system to obey what the initsystem
itself already does). Requests to restart a service are also subject
to this control, and are converted into stop requests if the service
is not allowed to start.
2. Instead of returning errors (and possibly aborting a script),
non-executable /etc/init.d/ scripts are handled gracefully.
(I have seen at least one complain from a user regarding this issue).
IMPACT:
The interface scripts would needed to be added to file-rc and sysvinit. I'll
write all the code needed to do so (it is mostly done already, anyway), and
supply BTS patches to the two packages if the proposal is approved. A
working version of the sysvinit code is attached.
All packages which call an initscript in their maintainer scripts would need
to (gradually) change their maintainer scripts so as all
"/etc/init.d/<initscript> <something>" instances are replaced by
"invoke-rc.d <initscript> <something>" if pre-dependencies to the new
sysvinit package (which contains invoke-rc.d) are added, or by "if [ -x
/usr/sbin/invoke-rc.d ] ; then invoke-rc.d initscript <something> ; else
/etc/init.d/initscript <something> ; fi" to handle backwards compatibility
if you don't want to add a pre-dependency to sysvinit (all this crap is
much better formatted in the policy proposal :-) ).
BENEFITS:
We'll finally have the work started by update-rc.d brought to completion,
and be the first distribution (AFAIK) to have the concept of an fine-grained
**optional** local system administrator policy control over what the
initscript system is alowed to do.
The long standing bug of out-of-runlevel daemon starts on package upgrades
will be finally fixed.
The wishlist bug (and past flamewar material, I guess) of whether to start
or not daemons on package installs can finally be addressed in a sane way
(which doesn't touch the system of those it doesn't bother).
--
"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
--- policy.text.old Sat Oct 28 13:49:39 2000
+++ policy.text Sat Oct 28 13:56:07 2000
@@ -1041,7 +1041,12 @@
stop the service,
`restart'
- stop and restart the service,
+ stop and restart the service (note that the service may be
+ started even if it was not running before),
+
+ `maybe-restart'
+ stop the service, and if the service was running before being
+ stopped by maybe-restart, restart it,
`reload'
cause the configuration of the service to be reloaded without
@@ -1052,8 +1057,8 @@
this, otherwise restart the service.
The `start', `stop', `restart', and `force-reload' options should be
- supported by all scripts in `/etc/init.d', the `reload' option is
- optional.
+ supported by all scripts in `/etc/init.d', the `reload' and
+ `maybe-restart' options are optional.
The `init.d' scripts should ensure that they will behave sensibly if
invoked with `start' when the service is already running, or with
@@ -1076,8 +1081,19 @@
test -f <program-executed-later-in-script> || exit 0
-3.3.3. Managing the links
--------------------------
+3.3.3. Interfacing with the initscript system
+---------------------------------------------
+
+ Maintainers should use the abstraction layer provided by the
+ `update-rc.d' and `invoke-rc.d' programs to deal with initscripts in
+ their packages' scripts such as `postinst', 'prerm' and `postrm'.
+
+ Directly managing the /etc/rc?.d links and directly invoking the
+ /etc/init.d/ initscripts should be done only by packages providing the
+ initscript subsystem (such as `sysvinit' and `file-rc').
+
+3.3.3.1. Managing the links
+---------------------------
The program `update-rc.d' is provided to make it easier for package
maintainers to arrange for the proper creation and removal of
@@ -1118,6 +1134,44 @@
For more information about using `update-rc.d', please consult its
manpage update-rc.d(8).
+
+3.3.3.2. Running initscripts
+----------------------------
+
+ The program `invoke-rc.d' is provided to make it easier for package
+ maintainers to properly invoke an initscript, obeying runlevel and
+ other locally-defined constrains that might limit a package's right to
+ start, stop and otherwise manage services. This program may be used by
+ maintainers in their packages' scripts.
+
+ You must use `invoke-rc.d' to invoke the `/etc/init.d/*'
+ initscripts. Package scripts must not call /etc/init.d scripts
+ directly.
+
+ By default, `invoke-rc.d' will pass any action requests (start, stop,
+ reload, restart...) to the /etc/init.d script, filtering out requests
+ to start a service out of its intended runlevels as defined by
+ `update-rc.d' and the system administrator. Also, requests to restart a
+ service out of its intended runlevels are changed to a stop request.
+
+ Most packages will simply need to change:
+
+ /etc/init.d/<package> <action>
+
+ in their `postinst' and `prerm' scripts to:
+
+ if [ -x /usr/sbin/invoke-rc.d ] ; then
+ invoke-rc.d <package> <action>
+ else
+ /etc/init.d/<package> <action>
+ fi
+
+ A package should register its initscript services using `update-rc.d'
+ before it tries to invoke them using `invoke-rc.d'. Invocation of
+ unregistered services may fail.
+
+ For more information about using `invoke-rc.d', please consult its
+ manpage invoke-rc.d(8).
3.3.4. Boot-time initialization
-------------------------------
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, or in a text file
stored in /usr/share/doc/sysvinit/ by package sysvinit (which will host the
base implementation of invoke-rc.d).
If you dislike any of the names (policy-rc.d, invoke-rc.d, "local initscript
policy layer" or anything else), go ahead and send me a better suggestion
:-) And yes, I know my english is not up to literary levels. Fell free to
correct any mistakes, especially in the policy diff.
PS: I tried to get away of very long names such as "invoke-initscript",
which is the reason I went along with the '*-rc.d' scheme.
Proposed script interfaces (to be rewritten as manpages):
invoke-rc.d [options] <basename> <action>
basename - Initscript ID, as per update-rc.d(8)
action - Initscript action. Known actions are:
start, [force-]stop, [maybe-]restart,
[force-]reload, status
(status is there because of the LSB. Debian does not use it).
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.
--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.
--nofallback
The policy layer (policy-rc.d) may return a fallback action 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 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 (but cannot
forbid without editing the initscript).
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 (I didn't add this to the policy diff because the LSB will
cause us to add it later anyway).
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 layer (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 a 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).
/usr/sbin/policy-rc.d [options] <initscript ID> <action> [<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).
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, [maybe-]restart, [force-]reload, status.
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.
stdout is used to output a single line containing a fallback action,
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 action
(which is implied to be "allowed") instead. (returns
fallback action in stdout).
#!/bin/sh
#
# invoke-rc.d.sysvinit - Executes initscript actions
# $Id: invoke-rc.d,v 1.5 2000/10/31 13:31:12 hmh Exp $
#
# SysVinit /etc/rc?.d version for Debian's sysvinit package
#
# invoke-rc.d.sysvinit - Executes initscript actions
# Copyright (C) 2000 Henrique de Moraes Holschuh <hmh@rcm.org.br>
#
# This program is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the Free
# Software Foundation; either version 2 of the License, or (at your option)
# any later version.
#
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, write to the Free Software Foundation, Inc., 59
# Temple Place, Suite 330, Boston, MA 02111-1307 USA
# Constants
RUNLEVEL=/sbin/runlevel
POLICYHELPER=/usr/sbin/policy-rc.d
INITDPREFIX=/etc/init.d/
RCDPREFIX=/etc/rc
# Options
BEQUIET=
MODE=
ACTION=
FALLBACK=
NOFALLBACK=
FORCE=
RETRY=
RETURNFAILURE=
RC=
dohelp () {
#
# outputs help and usage
#
cat <<EOF
invoke-rc.d, Debian/SysVinit (/etc/rc?.d) initscript subsystem.
Copyright (c) 2000 Henrique de Moraes Holschuh
Usage:
invoke-rc.d [options] <basename> <action>
basename - Initscript ID, as per update-rc.d(8)
action - Initscript action. Known actions are:
start, [force-]stop, [maybe-]restart,
[force-]reload, status
WARNING: not all initscripts implement all of the above actions.
Options:
--quiet
Quiet mode, no error messages are generated.
--force
Try to run the initscript regardless of policy and subsystem
non-fatal errors.
--try-anyway
Try to run init script even if a non-fatal error is found.
--disclose-deny
Return status code 101 instead of status code 0 if
initscript action is denied by local policy rules or
runlevel constrains.
--query
Returns one of status codes 100-106, does not run
the initscript. Implies --disclose-deny and --no-fallback.
--no-fallback
Ignores any fallback action requests by the policy layer.
Warning: this is usually a very *bad* idea for any actions
other than "start".
--help
Outputs help message to stdout
EOF
}
printerror () {
#
# prints an error message
# $* - error message
#
if test x${BEQUIET} = x ; then
echo `basename $0`: "$*" >&2
fi
}
querypolicy () {
#
# queries policy database
# returns: $RC = 104 - ok, run
# $RC = 101 - ok, do not run
# other - exit with status $RC, maybe run if $RETRY
#
if test "x${POLICYHELPER}" != x -a -x "${POLICYHELPER}" ; then
FALLBACK=`${POLICYHELPER} ${BEQUIET} ${INITSCRIPTID} ${ACTION} ${RL}`
RC=$?
case ${RC} in
0|1) RC=104
;;
101) if test x${FORCE} != x ; then
printerror policy-rc.d denied execution of \"${ACTION}\".
printerror Overriding because of --force.
RC=104
fi
;;
esac
if test x${MODE} != xquery ; then
case ${RC} in
105) printerror policy-rc.d query returned \"behaviour undefined\",
printerror assuming \"${ACTION}\" is allowed.
RC=104
;;
106) if test x${FORCE} = x ; then
if test x${NOFALLBACK} = x ; then
ACTION=${FALLBACK}
printerror executing action \"${ACTION}\" instead due to policy-rc.d request.
RC=104
else
printerror ignoring policy-rc.d fallback request to \"${FALLBACK}\".
RC=101
fi
else
printerror ignoring policy-rc.d fallback request to \"${FALLBACK}\".
RC=104
fi
;;
esac
fi
case ${RC} in
100|101|102|103|104|105|106) ;;
*) printerror WARNING: policy-rc.d returned unexpected error status ${RC}, 102 used instead.
RC=102
;;
esac
else
RC=104
fi
return
}
verifyparameter () {
#
# Verifies if $1 is not null, and $# = 1
#
if test $# -eq 0 ; then
printerror syntax error: invalid empty parameter
exit 103
elif test $# -ne 1 ; then
printerror syntax error: embedded blanks are not allowed in \"$*\"
exit 103
fi
return
}
##
## main
##
## Verifies command line arguments
if test $# -eq 0 ; then
printerror syntax error: missing required parameter, --help assumed
dohelp
exit 103
fi
state=I
for i in "$@" ; do
verifyparameter $i
case $i in
--help) dohelp
exit 0
;;
--quiet) BEQUIET=--quiet
;;
--force) FORCE=yes
RETRY=yes
;;
--try-anyway)
RETRY=yes
;;
--disclose-deny)
RETURNFAILURE=yes
;;
--query) MODE=query
RETURNFAILURE=yes
;;
--no-fallback)
NOFALLBACK=yes
;;
--*) printerror syntax error: unknown option \"$i\"
exit 103
;;
*) case ${state} in
I) INITSCRIPTID=$i
;;
II) ACTION=$i
;;
*) printerror syntax error: extra parameter $i
exit 103
;;
esac
state=${state}I
;;
esac
done
if test ${state} != III ; then
printerror syntax error: missing required parameter
exit 103
fi
## sanity checks and just-in-case warnings.
case ${ACTION} in
start|stop|force-stop|restart|maybe-restart|reload|force-reload|status)
;;
*)
printerror action ${ACTION} is unknown, but proceeding anyway.
;;
esac
#attempt to detect *active* file-rc subsystem
#we actually should use dpkg-divert --list here but that could be slow.
if test -f ${INITDPREFIX}/rc.links ; then
printerror WARNING: Detected out-of-date file-rc initscript subsystem installed;
printerror system is using incorrect version of invoke-rc.d !
printerror Please upgrade the file-rc package as soon as possible.
printerror --force enabled to bypass incompatible version of invoke-rc.d,
printerror please ignore any further errors from invoke-rc.d
FORCE=yes
RETRY=yes
POLICYHELPER=
fi
## Verifies if the given initscript ID is known
## For sysvinit, this error is critical
if test ! -f "${INITDPREFIX}${INITSCRIPTID}" ; then
printerror unknown initscript, ${INITDPREFIX}${INITSCRIPTID} not found.
exit 100
fi
## Queries sysvinit for the current runlevel
RL=`${RUNLEVEL} | sed 's/.*\ //'`
if test ! $? ; then
printerror "could not determine current runlevel"
if test x${RETRY} = x ; then
exit 102
fi
RL=
fi
## Handles shutdown sequences VERY safely
## i.e.: forget about policy, and do all we can to run the script.
## BTW, why the heck are we being run in a shutdown runlevel?!
if test x${RL} = x0 -o x${RL} = x6 ; then
FORCE=yes
RETRY=yes
POLICYHELPER=
BEQUIET=
printerror ----------------------------------------------------
printerror WARNING: invoke-rc.d called during shutdown sequence
printerror enabling safe mode: initscript policy layer disabled
printerror ----------------------------------------------------
fi
## Verifies the existance of proper S??initscriptID and K??initscriptID
## *links* in the proper /etc/rc?.d/ directory
verifyrclink () {
#
# verifies if parameters are non-dangling symlinks
# all parameters are verified
#
doexit=
while test $# -gt 0 ; do
if test ! -L "$1" ; then
printerror not a symlink: $1
doexit=102
fi
if test ! -f "$1" ; then
printerror dangling symlink: $1
doexit=102
fi
shift
done
if test x${doexit} != x -a x${RETRY} = x; then
exit ${doexit}
fi
return 0
}
# we do handle multiple links per runlevel
# but we don't handle embedded blanks in link names :-(
if test x${RL} != x ; then
SLINK=`ls -d -Q ${RCDPREFIX}${RL}.d/S[0-9][0-9]${INITSCRIPTID} 2>/dev/null | xargs`
KLINK=`ls -d -Q ${RCDPREFIX}${RL}.d/K[0-9][0-9]${INITSCRIPTID} 2>/dev/null | xargs`
SSLINK=`ls -d -Q ${RCDPREFIX}S.d/S[0-9][0-9]${INITSCRIPTID} 2>/dev/null | xargs`
verifyrclink ${SLINK} ${KLINK} ${SSLINK}
fi
testexec () {
#
# returns true if any of the parameters is
# executable (after following links)
#
while test $# -gt 0 ; do
if test -x "$1" ; then
return 0
fi
shift
done
return 1
}
RC=
###
### LOCAL INITSCRIPT POLICY: Enforce need of a Sxx link
### in either rcS.d or current runlevel to allow start
### or restart.
###
case ${ACTION} in
start|restart)
if testexec ${SLINK} ; then
RC=104
elif testexec ${KLINK} ; then
RC=101
elif testexec ${SSLINK} ; then
RC=104
fi
;;
esac
###
### LOCAL INITSCRIPT POLICY: Restart is downgraded to
### stop if restart is not allowed.
###
if test ${ACTION} = restart -a x${RC} = x101 -a x${FORCE} = x ; then
if test x${NOFALLBACK} != x ; then
printerror fallback request to action \"stop\" ignored.
RC=101
else
printerror using fallback action \"stop\" instead.
ACTION=stop
if test x${MODE} = xquery ; then
RC=106
else
RC=104
fi
fi
fi
# test if /etc/init.d/initscript is actually executable
if testexec "${INITDPREFIX}${INITSCRIPTID}" ; then
if test x${RC} = x -a x${MODE} = xquery ; then
RC=105
fi
# call policy layer
if test x${RC} = x104 -o x${RC} = x; then
querypolicy
case ${RC} in
101|104)
;;
*) if test x${MODE} != xquery ; then
printerror policy-rc.d returned error status ${RC}
if test x${RETRY} = x ; then
exit ${RC}
else
RC=102
fi
fi
;;
esac
fi
else
###
### LOCAL INITSCRIPT POLICY: non-executable initscript; deny exec.
### (this is common sense, actually :^P )
###
RC=101
fi
## Handles --query
if test x${MODE} = xquery ; then
exit ${RC}
fi
## Executes initscript
if test x${FORCE} != x -o ${RC} -eq 104 ; then
if testexec "${INITDPREFIX}${INITSCRIPTID}" ; then
# does not return if sucessful
exec "${INITDPREFIX}${INITSCRIPTID}" ${ACTION}
fi
exit 102
fi
printerror initscript action \"${ACTION}\" not executed.
## Handles --disclose-deny
if test ${RC} -eq 101 -a x${RETURNFAILURE} = x ; then
RC=0
fi
exit ${RC}
Attachment:
pgpzI_O9HkYPP.pgp
Description: PGP signature