--- Begin Message ---
Package: debian-policy
Version: 3.6.1.0
Severity: wishlist
Tags: patch
This proposal aims to synchronize the Debian Policy, section 9.3, with
the LSB 1.3.0, chapter 24 [1]. Attached is a patch and the resulting
plain text for better reading.
Notes:
* I suggest merging the "reserved for..." items, but left them
separated for the moment.
* What is log_failure_msg? Does this make sense on a Debian system?
Replace it or skip it?
Kind regards,
Martin
[1] http://www.linuxbase.org/spec/refspecs/LSB_1.3.0/gLSB/gLSB/iniscrptact.html
--- debian-policy-3.6.1.0.orig/policy.sgml Tue Aug 19 14:32:23 2003
+++ debian-policy-3.6.1.0/policy.sgml Sun Aug 31 13:04:48 2003
@@ -5362,13 +5362,16 @@
<tag><tt>force-reload</tt></tag>
<item>cause the configuration to be reloaded if the
service supports this, otherwise restart the
- service.</item>
+ service,</item>
+
+ <tag><tt>status</tt></tag>
+ <item>print the current status of the service.</item>
</taglist>
- The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, and
- <tt>force-reload</tt> options should be supported by all
- scripts in <file>/etc/init.d</file>, the <tt>reload</tt>
- option is optional.
+ The <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>,
+ <tt>force-reload</tt>, and <tt>status</tt> options should
+ be supported by all scripts in <file>/etc/init.d</file>,
+ the <tt>reload</tt> option is optional.
</p>
<p>
@@ -5416,10 +5419,72 @@
should include a <tt>test</tt> statement at the top of the
script, like this:
<example compact="compact">
-test -f <var>program-executed-later-in-script</var> || exit 0
+test -f <var>program-executed-later-in-script</var> || exit 5
</example>
</p>
+ <p>
+ In the case of init script commands other than <tt>status</tt> (i.e.,
+ <tt>start</tt>, <tt>stop</tt>, <tt>restart</tt>, <tt>reload</tt>, and
+ <tt>force-reload</tt>), the init script should return an exit status
+ of zero if the action described by the argument has been successful.
+ Otherwise, the init script should print an error message and return
+ one of the following non-zero exit status codes.
+ <taglist>
+ <tag>1</tag>
+ <item>generic or unspecified error,</item>
+ <tag>2</tag>
+ <item>invalid or excess argument(s),</item>
+ <tag>3</tag>
+ <item>unimplemented feature (for example, <tt>reload</tt>),</item>
+ <tag>4</tag>
+ <item>user had insufficient privilege,</item>
+ <tag>5</tag>
+ <item>program is not installed,</item>
+ <tag>6</tag>
+ <item>program is not configured,</item>
+ <tag>7</tag>
+ <item>program is not running,</item>
+ <tag>8-99</tag>
+ <item>reserved for future LSB use,</item>
+ <tag>100-149</tag>
+ <item>reserved for distribution use,</item>
+ <tag>150-199</tag>
+ <item>reserved for application use,</item>
+ <tag>200-254</tag>
+ <item>reserved.</item>
+ </taglist>
+ All error messages should be printed on standard error. All status
+ messages should be printed on standard output. (This does not prevent
+ scripts from calling the logging functions such as
+ <tt>log_failure_msg</tt>).
+ </p>
+
+ <p>
+ If the status command is given, the init script should return the
+ following exit status codes.
+ <taglist>
+ <tag>0</tag>
+ <item>program is running or service is OK,</item>
+ <tag>1</tag>
+ <item>program is dead and /var/run pid file exists,</item>
+ <tag>2</tag>
+ <item>program is dead and /var/lock lock file exists,</item>
+ <tag>3</tag>
+ <item>program is stopped,</item>
+ <tag>4</tag>
+ <item>program or service status is unknown,</item>
+ <tag>5-99</tag>
+ <item>reserved for future LSB use,</item>
+ <tag>100-149</tag>
+ <item>reserved for distribution use,</item>
+ <tag>150-199</tag>
+ <item>reserved for application use,</item>
+ <tag>200-254</tag>
+ <item>reserved.</item>
+ </taglist>
+ </p>
+
<p>
Often there are some variables in the <file>init.d</file>
scripts whose values control the behaviour of the scripts,
@@ -5640,7 +5705,7 @@
# Original version by Robert Leslie
# <[email protected]>, edited by iwj and cs
-test -x /usr/sbin/named || exit 0
+test -x /usr/sbin/named || exit 5
# Source defaults file.
PARAMS=''
@@ -5648,6 +5713,14 @@
. /etc/default/bind
fi
+help () {
+ echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
+}
+
+if [ "$2" ]; then
+ help
+ exit 2
+fi
case "$1" in
start)
@@ -5676,10 +5749,13 @@
--pidfile /var/run/named.pid --exec /usr/sbin/named
echo "."
;;
+status)
+ help
+ exit 4
+ ;;
*)
- echo "Usage: /etc/init.d/bind " \
- " {start|stop|restart|reload|force-reload}" >&2
- exit 1
+ help
+ exit 2
;;
esac
9.3. System run levels and `init.d' scripts
-------------------------------------------
9.3.1. Introduction
-------------------
The `/etc/init.d' directory contains the scripts executed by `init' at
boot time and when the init state (or "runlevel") is changed (see
init(8)).
There are at least two different, yet functionally equivalent, ways of
handling these scripts. For the sake of simplicity, this document
describes only the symbolic link method. However, it must not be
assumed by maintainer scripts that this method is being used, and any
automated manipulation of the various runlevel behaviours by
maintainer scripts must be performed using `update-rc.d' as described
below and not by manually installing or removing symlinks. For
information on the implementation details of the other method,
implemented in the `file-rc' package, please refer to the
documentation of that package.
These scripts are referenced by symbolic links in the `/etc/rc<n>.d'
directories. When changing runlevels, `init' looks in the directory
`/etc/rc<n>.d' for the scripts it should execute, where `<n>' is the
runlevel that is being changed to, or `S' for the boot-up scripts.
The names of the links all have the form `S<mm><script>' or
`K<mm><script>' where <mm> is a two-digit number and <script> is the
name of the script (this should be the same as the name of the actual
script in `/etc/init.d').
When `init' changes runlevel first the targets of the links whose
names start with a `K' are executed, each with the single argument
`stop', followed by the scripts prefixed with an `S', each with the
single argument `start'. (The links are those in the `/etc/rc<n>.d'
directory corresponding to the new runlevel.) The `K' links are
responsible for killing services and the `S' link for starting
services upon entering the runlevel.
For example, if we are changing from runlevel 2 to runlevel 3, init
will first execute all of the `K' prefixed scripts it finds in
`/etc/rc3.d', and then all of the `S' prefixed scripts in that
directory. The links starting with `K' will cause the referred-to
file to be executed with an argument of `stop', and the `S' links with
an argument of `start'.
The two-digit number <mm> is used to determine the order in which to
run the scripts: low-numbered links have their scripts run first. For
example, the `K20' scripts will be executed before the `K30' scripts.
This is used when a certain service must be started before another.
For example, the name server `bind' might need to be started before
the news server `inn' so that `inn' can set up its access lists. In
this case, the script that starts `bind' would have a lower number
than the script that starts `inn' so that it runs first:
/etc/rc2.d/S17bind
/etc/rc2.d/S70inn
The two runlevels 0 (halt) and 6 (reboot) are slightly different. In
these runlevels, the links with an `S' prefix are still called after
those with a `K' prefix, but they too are called with the single
argument `stop'.
Also, if the script name ends `.sh', the script will be sourced in
runlevel `S' rather that being run in a forked subprocess, but will be
explicitly run by `sh' in all other runlevels.
9.3.2. Writing the scripts
--------------------------
Packages that include daemons for system services should place scripts
in `/etc/init.d' to start or stop services at boot time or during a
change of runlevel. These scripts should be named
`/etc/init.d/<package>', and they should accept one argument, saying
what to do:
`start'
start the service,
`stop'
stop the service,
`restart'
stop and restart the service if it's already running, otherwise
start the service
`reload'
cause the configuration of the service to be reloaded without
actually stopping and restarting the service,
`force-reload'
cause the configuration to be reloaded if the service supports
this, otherwise restart the service,
`status'
print the current status of the service.
The `start', `stop', `restart', `force-reload', and `status' options
should be supported by all scripts in `/etc/init.d', the `reload'
option is optional.
The `init.d' scripts should ensure that they will behave sensibly if
invoked with `start' when the service is already running, or with
`stop' when it isn't, and that they don't kill unfortunately-named
user processes. The best way to achieve this is usually to use
`start-stop-daemon'.
If a service reloads its configuration automatically (as in the case
of `cron', for example), the `reload' option of the `init.d' script
should behave as if the configuration has been reloaded successfully.
The `/etc/init.d' scripts must be treated as configuration files,
either (if they are present in the package, that is, in the .deb file)
by marking them as `conffile's, or, (if they do not exist in the .deb)
by managing them correctly in the maintainer scripts (see Section
10.7, `Configuration files'). This is important since we want to give
the local system administrator the chance to adapt the scripts to the
local system, e.g., to disable a service without de-installing the
package, or to specify some special command line options when starting
a service, while making sure her changes aren't lost during the next
package upgrade.
These scripts should not fail obscurely when the configuration files
remain but the package has been removed, as configuration files remain
on the system after the package has been removed. Only when `dpkg' is
executed with the `--purge' option will configuration files be
removed. In particular, as the `/etc/init.d/<package>' script itself
is usually a `conffile', it will remain on the system if the package
is removed but not purged. Therefore, you should include a `test'
statement at the top of the script, like this:
test -f <program-executed-later-in-script> || exit 5
In the case of init script commands other than `status' (i.e.,
`start', `stop', `restart', `reload', and `force-reload'), the init
script should return an exit status of zero if the action described by
the argument has been successful. Otherwise, the init script should
print an error message and return one of the following non-zero exit
status codes.
1
generic or unspecified error,
2
invalid or excess argument(s),
3
unimplemented feature (for example, `reload'),
4
user had insufficient privilege,
5
program is not installed,
6
program is not configured,
7
program is not running,
8-99
reserved for future LSB use,
100-149
reserved for distribution use,
150-199
reserved for application use,
200-254
reserved.
All error messages should be printed on standard error. All status
messages should be printed on standard output. (This does not prevent
scripts from calling the logging functions such as `log_failure_msg').
If the status command is given, the init script should return the
following exit status codes.
0
program is running or service is OK,
1
program is dead and /var/run pid file exists,
2
program is dead and /var/lock lock file exists,
3
program is stopped,
4
program or service status is unknown,
5-99
reserved for future LSB use,
100-149
reserved for distribution use,
150-199
reserved for application use,
200-254
reserved.
Often there are some variables in the `init.d' scripts whose values
control the behaviour of the scripts, and which a system administrator
is likely to want to change. As the scripts themselves are frequently
`conffile's, modifying them requires that the administrator merge in
their changes each time the package is upgraded and the `conffile'
changes. To ease the burden on the system administrator, such
configurable values should not be placed directly in the script.
Instead, they should be placed in a file in `/etc/default', which
typically will have the same base name as the `init.d' script. This
extra file should be sourced by the script when the script runs. It
must contain only variable settings and comments in POSIX `sh' format.
It may either be a `conffile' or a configuration file maintained by
the package maintainer scripts. See Section 10.7, `Configuration
files' for more details.
To ensure that vital configurable values are always available, the
`init.d' script should set default values for each of the shell
variables it uses, either before sourcing the `/etc/default/' file or
afterwards using something like the `: ${VAR:=default}' syntax. Also,
the `init.d' script must behave sensibly and not fail if the
`/etc/default' file is deleted.
9.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 `sysv-rct' and `file-rc').
9.3.3.1. Managing the links
---------------------------
The program `update-rc.d' is provided for package maintainers to
arrange for the proper creation and removal of `/etc/rc<n>.d' symbolic
links, or their functional equivalent if another method is being used.
This may be used by maintainers in their packages' `postinst' and
`postrm' scripts.
You must not include any `/etc/rc<n>.d' symbolic links in the actual
archive or manually create or remove the symbolic links in maintainer
scripts; you must use the `update-rc.d' program instead. (The former
will fail if an alternative method of maintaining runlevel information
is being used.) You must not include the `/etc/rc<n>.d' directories
themselves in the archive either. (Only the `sysvinit' package may do
so.)
By default `update-rc.d' will start services in each of the multi-user
state runlevels (2, 3, 4, and 5) and stop them in the halt runlevel
(0), the single-user runlevel (1) and the reboot runlevel (6). The
system administrator will have the opportunity to customize runlevels
by simply adding, moving, or removing the symbolic links in
`/etc/rc<n>.d' if symbolic links are being used, or by modifying
`/etc/runlevel.conf' if the `file-rc' method is being used.
To get the default behavior for your package, put in your `postinst'
script
update-rc.d <package> defaults
and in your `postrm'
if [ "$1" = purge ]; then
update-rc.d <package> remove
fi
. Note that if your package changes runlevels or priority, you may
have to remove and recreate the links, since otherwise the old links
may persist. Refer to the documentation of `update-rc.d'.
This will use a default sequence number of 20. If it does not matter
when or in which order the `init.d' script is run, use this default.
If it does, then you should talk to the maintainer of the `sysvinit'
package or post to `debian-devel', and they will help you choose a
number.
For more information about using `update-rc.d', please consult its
manpage update-rc.d(8).
9.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 constraints 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.
The use of `invoke-rc.d' to invoke the `/etc/init.d/*' initscripts is
strongly recommended[1], instead of calling them 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 or restart a service out of its intended runlevels.
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).
[1] In the future, the use of invoke-rc.d to invoke initscripts shall be
made mandatory. Maintainers are advised to switch to invoke-rc.d as
soon as possible.
9.3.4. Boot-time initialization
-------------------------------
There used to be another directory, `/etc/rc.boot', which contained
scripts which were run once per machine boot. This has been
deprecated in favour of links from `/etc/rcS.d' to files in
`/etc/init.d' as described in Section 9.3.1, `Introduction'. Packages
must not place files in `/etc/rc.boot'.
9.3.5. Example
--------------
The `bind' DNS (nameserver) package wants to make sure that the
nameserver is running in multiuser runlevels, and is properly shut
down with the system. It puts a script in `/etc/init.d', naming the
script appropriately `bind'. As you can see, the script interprets
the argument `reload' to send the nameserver a `HUP' signal (causing
it to reload its configuration); this way the system administrator can
say `/etc/init.d/bind reload' to reload the name server. The script
has one configurable value, which can be used to pass parameters to
the named program at startup; this value is read from
`/etc/default/bind' (see below).
#!/bin/sh
#
# Original version by Robert Leslie
# <[email protected]>, edited by iwj and cs
test -x /usr/sbin/named || exit 5
# Source defaults file.
PARAMS=''
if [ -f /etc/default/bind ]; then
. /etc/default/bind
fi
help () {
echo "Usage: /etc/init.d/bind {start|stop|restart|reload|force-reload}" >&2
}
if [ "$2" ]; then
help
exit 2
fi
case "$1" in
start)
echo -n "Starting domain name service: named"
start-stop-daemon --start --quiet --exec /usr/sbin/named \
-- $PARAMS
echo "."
;;
stop)
echo -n "Stopping domain name service: named"
start-stop-daemon --stop --quiet \
--pidfile /var/run/named.pid --exec /usr/sbin/named
echo "."
;;
restart)
echo -n "Restarting domain name service: named"
start-stop-daemon --stop --quiet --oknodo \
--pidfile /var/run/named.pid --exec /usr/sbin/named
start-stop-daemon --start --verbose --exec /usr/sbin/named \
-- $PARAMS
echo "."
;;
force-reload|reload)
echo -n "Reloading configuration of domain name service: named"
start-stop-daemon --stop --signal 1 --quiet \
--pidfile /var/run/named.pid --exec /usr/sbin/named
echo "."
;;
status)
help
exit 4
;;
*)
help
exit 2
;;
esac
exit 0
Complementing the above init script is a configuration file
`/etc/default/bind', which contains configurable parameters used by
the script. This would be created by the `postinst' script if it was
not already present, and removed on purge by the `postrm' script.
# Specified parameters to pass to named. See named(8).
# You may uncomment the following line, and edit to taste.
#PARAMS="-u nobody"
Another example on which you can base your `/etc/init.d' scripts is
found in `/etc/init.d/skeleton'.
If this package is happy with the default setup from `update-rc.d',
namely an ordering number of 20 and having named running in all
runlevels, it can say in its `postinst':
update-rc.d bind defaults >/dev/null
And in its `postrm', to remove the links when the package is purged:
if [ "$1" = purge ]; then
update-rc.d bind remove >/dev/null
fi
pgpKilOQFirBK.pgp
Description: PGP signature
--- End Message ---
