(debian-policy.info)Writing the scripts

---

Next: Interfacing with init systems Prev: Introduction<2> Up: System run levels and init d scripts

---

Enter node , (file) or (file)node

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

‘try-restart’

     restart the service if it’s already running, otherwise just report
     success.

‘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’

     report the current status of the service

The ‘start’, ‘stop’, ‘restart’, and ‘force-reload’ options should be
supported by all scripts in ‘/etc/init.d’.  Supporting ‘status’ is
recommended but not required.  The ‘reload’ and ‘try-restart’ options
are optional.

The ‘init.d’ scripts must ensure that they will behave sensibly (i.e.,
returning success and not starting multiple copies of a service) 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’ with the ‘--oknodo’ option.

Be careful of using ‘set -e’ in ‘init.d’ scripts.  Writing correct
‘init.d’ scripts requires accepting various error exit statuses when
daemons are already running or already stopped without aborting the
‘init.d’ script, and common ‘init.d’ function libraries are not safe to
call with ‘set -e’ in effect.  (1) For ‘init.d’ scripts, it’s often
easier to not use ‘set -e’ and instead check the result of each command
separately.

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 Note:
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 their 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 0

Often there are some variables in the ‘init.d’ scripts whose values
control the behavior 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.1-2017 ‘sh’
format.  It may either be a ‘conffile’ or a configuration file
maintained by the package maintainer scripts.  See Note: 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.

Files and directories under ‘/run’, including ones referred to via the
compatibility paths ‘/var/run’ and ‘/var/lock’, are normally stored on a
temporary filesystem and are normally not persistent across a reboot.
The ‘init.d’ scripts must handle this correctly.  This will typically
mean creating any required subdirectories dynamically when the ‘init.d’
script is run.  See Note: /run and /run/lock. for more information.

   ---------- Footnotes ----------

   (1) ‘/lib/lsb/init-functions’, which assists in writing LSB-compliant
init scripts, may fail if ‘set -e’ is in effect and echoing status
messages to the console fails, for example.