diff --git a/policy.sgml b/policy.sgml
index 6eac491..574a8ca 100644
--- a/policy.sgml
+++ b/policy.sgml
@@ -7362,389 +7362,537 @@ rmdir /usr/local/share/emacs 2>/dev/null || true
-
- System run levels and init.d scripts
+
+ Init systems
+
+
+ The default init system in Debian with Linux kernels is systemd, run when
+ systemd-sysv is installed.
+ A number of other init systems are available in Debian, including
+ in particular System V init, run when sysvinit-core
+ is installed (and also the default for non-Linux kernels).
+ Both of these packages provide the init
+ metapackage.
+
-
- Introduction
+
+ Packages must integrate with the default init system and may integrate
+ with others as well.
+
+ -
+
+ To integrate with systemd, packages provide so-called unit files
+ (described at [) or init.d scripts.
+ ]
+
+ -
+
+ To integrate with upstart, packages provide so-called job files
+ (described at [) or init.d scripts.
+ ]
+
+ -
+
+ To integrate with System V init, packages provide init.d
+ scripts (described at [).
+ ]
+
+ -
+
+ Integration with other init systems in Debian, most of which do not
+ use init.d scripts, is not covered here; and Debian
+ Policy has no interface or usage contracts for those init systems.
+
+
+
+ These files provide init-system-specific information about how and when to
+ run services, about boot-time and shutdown-time "milestones" or "targets",
+ and about tasks that run as part of the boot-up or shutdown procedures.
+ For packages that do not require any of these things, integration is
+ a no-op, of course.
+
+
+
+ The least common denominator of these are the init.d
+ scripts.
+ systemd places restrictions upon them, forbidding some of the more esoteric
+ possible mechanisms that System V init historically allowed.
+ However, a script that is compliant with this Policy should be
+ usable with systemd. Many of the things that systemd prohibits are
+ inherently problematic, irrespective of systemd.
+
+
+
+ Packages should use the same names for files across different init systems.
+ However, this is not always possible. For example, an init.d
+ script can start and manage several services, whereas one would have
+ individual systemd unit files for each of the individual services (and
+ possibly more unit files for sockets if the services are socket-activated).
+ Similarly, packages may be constrained by what upstream does.
+ It is recommended that packages adopt the same names, though; not the least
+ because this enables a package to take advantage of the fact that a systemd
+ unit file that shares a name with a init.d script will be used
+ in preference to that script. Note that the Alias= setting
+ in systemd unit files can be used to alleviate some problematic cases.
+
+
+
+ systemd unit files
- The /etc/init.d directory contains the scripts
- executed by init at boot time and when the
- init state (or "runlevel") is changed (see ).
+ The /usr/lib/systemd/system directory contains (package-supplied)
+ systemd unit files that define systemd-managed services, sockets,
+ mount points, automount entries, and other items.
+ Administrators do not make local modifications to these files.
-
- 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 behaviors 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.
+
+ Instead, local modifications made by administrators take the form of files
+ in the /etc/systemd/system directory, which override
+ package-supplied units entirely, and files in *.conf
+ subdirectories of that directory, which override parts of the package-supplied
+ units. (See .)
+ Conversely, packages must not make modifications to these files.
-
- These scripts are referenced by symbolic links in the
- /etc/rcn.d directories. When changing
- runlevels, init looks in the directory
- /etc/rcn.d for the scripts it should
- execute, where n is the runlevel that
- is being changed to, or S for the boot-up
+
+ A limited exception to this rule is that packages are permitted to make
+ once-off conversions, during an upgrade, from information in a
+ /etc/defaults/package file to systemd unit
+ override snippets in /etc/systemd/system/*/*.conf
+ files.
+ This has the disadvantage of creating two separate and not
+ synchronized sets of administrator-defined service parameterization
+ information, one for systemd units and one for init.d
scripts.
+
-
- The names of the links all have the form
- Smmscript or
- Kmmscript 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).
+
+ The requirements of [ apply to unit files under
+ /run/systemd of course.
]
-
- 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/rcn.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
-
+
+ For details of unit files please consult the man pages
+ ,
+ ,
+ ,
+ ,
+ and
+ .
+
+
+
+ constraints upon unit files
+
+
+
+ -
+
+ The Type= setting in a service unit file describes the readiness
+ notification mechanism employed by the daemon.
+ Readiness protocols are a communication mechanism between daemons and
+ systemd that allow systemd to delay starting client processes until a server
+ process is ready to service their requests. systemd supports several such
+ protocols.
+ fork()ing at startup and then exit()ing the main process
+ is one such readiness protocol, denoted by Type=forking.
+ Unit files should not use this unless the daemon is genuinely using this as
+ a readiness signal and main process exit() is genuinely a readiness
+ notification.
+ Most daemons are not in fact signalling readiness with this.
+ Rather, they are operating in a convenience mode used when daemons are run from an
+ /etc/rc script. No Debian init system uses the
+ /etc/rc mechanism. Such daemons should be run with whatever
+ configuration options or command-line options instruct them not to
+ gratuitously fork(); and the service unit files should use a more
+ appropriate Type= setting that denotes the readiness protocol that
+ they actually employ, if any.
+
+
+ -
+
+ Service unit files must not (directly or indirectly) run commands to mask, unmask,
+ enable, disable, start, or stop either themselves or other services in their
+ Exec...= settings.
+ Such actions must rather be properly expressed with dependency descriptions.
+
+
+ Services also must not (directly or indirectly) invoke other init.d
+ scripts in their Exec...= settings, as this can cause incorrect
+ init system operation.
+ (See [ for one way that this can cause service
+ control commands to be indirectly executed.)
+ If an init.d script provides additional verbs, that functionality
+ must be factored out of the script and placed elsewhere before it can be used
+ by a service unit file.
+ ]
+
+ -
+
+ Unit files must not install to specific run level ([) targets,
+ because their meanings are the province of local administrators;
+ but must instead use the standard targets such as multi-user.target and
+ graphical.target.
+ ]
+
+
+
+
+
+
+ recommendations for unit files
+
+
+
+ -
+
+ Restart=always should be avoided for socket-activated services,
+ as it prevents them from being able to deactivate when idle.
+ For such services, prefer Restart=on-failure or Restart=on-abort.
+
+
+ -
+
+ Sockets and their associated services can be started and stopped independently.
+ When upgrading a package, it is important to account for this in maintainer
+ scripts, and if appropriate stop both.
+ Otherwise, a client connecting to the socket could cause systemd to on-demand
+ activate the service right at the point of the maintainer script where the service
+ is deactivated for upgrading and in an intermediate state where it is not correctly
+ configured for running.
+
+
+ The same consideration applies to D-Bus activated services.
+
+
+ Please note that the update-rc.d and invoke-rc.d
+ in the sysv-rc package (See [.)
+ only operate upon service units and not on the associated socket units.
+ ]
+
+ -
+
+ Service units should, whereever the daemons do not require privileged access,
+ run services as an unprivileged user and group.
+ Optimally, that user should not own any files and directories to which
+ the daemon does not strictly need ownership access.In other words,
+ the user should not be able to change any access permissions except where
+ that is a part of the daemon's function. This means not running services
+ with the accounts of real, human, users, of course.
+ Maintainer scripts should of course add and delete any such users and groups
+ that are specific to the package, at package installation and removal.
+
+
+
+
+
+
+
+
+
+ non-unit systemd-related package files
+
+
+ Packages can ship additional items for systemd, including tmpfiles.d
+ files, sysctl.d files, and binfmt.d files amonst others.
+ Packages must not ship any such files under /etc, nor may they make any
+ modifications to such files under /etc.
+ The files in that subtree are the province of the local system administrator.
+ All such files must be shipped in the appropriate subdirectories of /usr/lib.
- 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.
+ These or work-alike mechanisms may not be available with other init systems.
+ However, Policy does not exclude packages from using, and depending upon, a
+ (hypothetical example) upstart-tmpfilesd for achieving the
+ same ends when integrated with the upstart init system.
+
-
- Writing the scripts
+
+ upstart job files
- 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:
+ The /etc/init directory contains job files used by the
+ the upstart init system.
+
-
- start
- - start the service,
+
+ Dependency-based boot managers for init.d scripts, such as
+ startpar, may avoid running a given script
+ entirely when an equivalent upstart job is present, to avoid
+ unnecessary forking of no-op init scripts. In this case, the
+ boot manager should integrate with upstart to detect when the
+ upstart job in question is started or stopped to know when the
+ dependency has been satisfied.
+
+
+
+ Other interactions between init.d scripts and upstart are described at
+ [.
+ ]
+
- stop
- - stop the service,
+
+ runlevels and /etc/inittab
- restart
- - stop and restart the service if it's already running,
- otherwise start the service
+
+ System V init's configuration file is /etc/inittab, which
+ describes a set of "runlevels" and the default runlevel that the system
+ boots into.
+ systemd has a mechanism that emulates System V init runlevels, but no init
+ system other than Systemm V init uses or supplies the /etc/inittab
+ file itself. In order to operate correctly with the (Linux) default and indeed
+ all but one of the init systems, packages must not use
+ /etc/inittab.
+
- reload
- cause the configuration of the service to be
- reloaded without actually stopping and restarting
- the service,
+
+ Maintainer scripts may not assume that a distinct current run level can be
+ determined; because this is not necessarily the case with the default
+ init system.
+ In general, maintainer scripts should avoid any mention of run levels at all.
+
+ update-rc.d no longer has the ability to explicitly configure
+ run levels on the command line. They must instead be part of the LSB Header
+ in an init.d script ([).
+ ]
+
+
- force-reload
- - cause the configuration to be reloaded if the
- service supports this, otherwise restart the
- service.
-
+
+ BSD-style rc: rc.boot and rc.local
- The start, stop, restart, and
- force-reload options should be supported by all
- scripts in /etc/init.d, the reload
- option is 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
- /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.
- . 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
- conffiles, or, (if they do not exist in the .deb)
- by managing them correctly in the maintainer scripts (see
- [). 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
-
+
+ Two Debian bootstrap mechanisms have their roots in non-System-V bootstrap
+ mechanisms, the /etc/rc.local file and the /etc/rc.boot
+ directory.
+ The latter was a place where scripts to be run at boot-up could be placed.
+ On BSD operating systems, /etc/rc.boot is a file.
+ It is entirely deprecated and packages must not use it.
+ No Debian init system now supports this mechanism.
- 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
- conffiles, 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 SUSv3
- sh format. It may either be a
- conffile or a configuration file maintained by
- the package maintainer scripts. See [
- 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 [ for more information.
+ Packages must not use the former; as the name suggests it is for local
+ administrator bootstrap tasks.
+ Both systemd and System V init will run an rc.local
+ file if it exists and is executable as a program. This is a
+ subtle difference from some historical systems, where rc.local
+ need only be sourceable by the default shell.
]
+
-
- Interfacing with the initscript system
+
+ System V rc
- 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.
+ System V init implements changing between run levels
+ through one of several rc programs
+ which in turn invoke init.d
+ scripts (described in [).
+ Packages that wish to provide the System V rc
+ interface to the System V init system must provide
+ the following programs:
+ ]
+ -
+
+ /etc/init.d/rcS,
+ a program that runs startup elements of the rc system.
+
+
+ -
+
+ /etc/init.d/rc,
+ a program that init invokes to enter/leave
+ each run level.
+
+
+ -
+
+ /usr/sbin/invoke-rc.d,
+ a program used by maintainer scripts to start, stop, enable,
+ and disable scripts, subject to local policy overrides.
+ (See [.)
+ ]
+
+ -
+
+ /usr/sbin/update-rc.d
+ a program that is used to set/change what scripts run as
+ each run level is entered and left, and in what order.
+ (See [.)
+ ]
+
+
- 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-rc and
- file-rc).
+ All init systems must provide the latter two, either themselves
+ or through cooperation with an rc package.
+ Only System V init itself also requires the former two from rc
+ packages.
-
- Managing the links
+
+ There are three different rc packages in Debian,
+ sysv-rc, file-rc, and
+ openrc.
+ These record what scripts are enabled in each runlevel in
+ differing ways. Please refer to their documentation for the
+ details.
+ systemd has a fourth mechanism that is largely compatible with
+ sysv-rc, but which has several differences,
+ such as masking and the overriding priority that is given to service units.
+
+
+
+ In general, therefore, maintainer scripts must not assume that
+ the symbolic link mechanisms (described in previous editions of
+ the Debian Policy Manual) take effect or even exist at all.
+ Maintainer scripts scripts such as postinst,
+ prerm and postrm. must use only the
+ supplied update-rc.d and invoke-rc.d
+ programs for interacting with the init.d script system.
+
+
+
+ Only the rc packages themselves, and their various adjunct
+ packages, have any business (in maintainer scripts) with the
+ /etc/rcn.d directories (of
+ openrc and sysv-rc) or the
+ /etc/runlevel.conf file (of file-rc).
+
+
+
+ systemd and upstart and rc
- The program update-rc.d is provided for
- package maintainers to arrange for the proper creation and
- removal of /etc/rcn.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.
+ In Debian 8, systemd and upstart do not provide their own
+ invoke-rc.d and update-rc.d.
+ The commands in the sysv-rc package have been
+ augmented to detect the running init system and take the appropriate
+ actions for enabling, disabling, starting, and stopping services.
+ These augmentations do not exist in the
+ invoke-rc.d and update-rc.d
+ in the file-rc and openrc packages.
+
+
+
+ Administrators are encouraged to prefer the service command
+ to invoking init.d scripts directly,
+ because it attempts to minimize (even though it cannot totally
+ eradicate) the amount of login session state, including settings that can
+ potentially break service operations, that leaks from the administrator's
+ shell running the service command to the daemon process(es)
+ started by the init.d script.
+ Better still is to use the systemctl or initctl
+ commands, of course.
- You must not include any /etc/rcn.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/rcn.d directories themselves
- in the archive either. (Only the sysvinit
- package may do so.)
+ init.d scripts for which
+ an equivalent upstart job is available must query the output of
+ the command initctl version for the string
+ upstart and avoid running in favor of the native
+ upstart job, using a test such as this:
+
+if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
+then
+ exit 1
+fi
+
- 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/rcn.d if
- symbolic links are being used, or by modifying
- /etc/runlevel.conf if the file-rc method
- is being used.
+ Avoiding running in favour of a native systemd unit is slightly simpler.
+ If an init.d script sources /lib/lsb/init-functions,
+ the script will automatically redirect invocations to systemctl.
+
+
+
+ Enabling and disabling scripts with update-rc.d
+
- To get the default behavior for your package, put in your
- postinst script
+ The program update-rc.d is provided (by each
+ init/rc system) for package maintainers to arrange for
+ enabling and disabling the running of init.d scripts.
+ This may be used by maintainers in their packages'
+ postinst and postrm scripts.
+ Maintainer scripts must not attempt to enable and disable
+ scripts directly.
+
+
+
+ By default update-rc.d will enable services in the
+ multi-user state, meaning that they will be started in that state
+ and stopped in the halt, rescue, poweroff, and reboot states.
+
+
+
+ To get the default behavior for your package, put
update-rc.d package defaults
- and in your postrm
+ in your postinst script and put
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.
+
+ in your postrm.
For more information about using update-rc.d,
- please consult its man page .
+ please consult its man page
+ .
-
- 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.
-
+
+ Starting and stopping scripts with invoke-rc.d
- The package maintainer scripts must use
- invoke-rc.d to invoke the
- /etc/init.d/* initscripts, instead of
- calling them directly.
+ The program invoke-rc.d is provided for properly
+ invoking an init.d script, obeying runlevels, masks, and
+ other init-system-defined and locally-defined constraints that might
+ limit a package's right to start, stop and otherwise manage services.
+ Maintainer scripts must use this program and must not attempt to enable
+ and disable 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 or restart a service out of its intended
- runlevels.
+ For compatibility with the default init system, maintainer scripts
+ must not run invoke-rc.d with any action requests other
+ than the conventional start, stop, reload, force-reload, and restart.
- Most packages will simply need to change:
- /etc/init.d/<package>
- <action> in their postinst
- and prerm scripts to:
+ Instead of using:
+ /etc/init.d/<package> <action>
+ in a package's postinst and prerm scripts
+ packages must have something like:
- if which invoke-rc.d >/dev/null 2>&1; then
- invoke-rc.d package <action>
- else
- /etc/init.d/package <action>
- fi
+if which invoke-rc.d >/dev/null 2>&1; then
+ invoke-rc.d package <action>
+else
+ /etc/init.d/package <action>
+fi
- A package should register its initscript services using
+ A package should register its init.d services using
update-rc.d before it tries to invoke them
- using invoke-rc.d. Invocation of
- unregistered services may fail.
+ using invoke-rc.d.
+ Invocation of unregistered services may fail on some init systems.
@@ -7755,225 +7903,374 @@ test -f program-executed-later-in-script || exit 0
-
- Boot-time initialization
+
+ init.d scripts
-
- 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 [. Packages must not
- place files in /etc/rc.boot.
+ ]
+ The /etc/init.d directory contains scripts that are executed
+ directly by systemd and upstart, and indirectly by System V init by way
+ of one of several rc systems (described in
+ [).
]
-
-
- Example
+
+ Writing the scripts
-
- An example on which you can base your
- /etc/init.d scripts is found in
- /etc/init.d/skeleton.
-
+
+ Packages that include daemons for system services may
+ 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.
+
-
-
+ The start, stop, restart, and
+ force-reload options should be supported by all
+ scripts in /etc/init.d, the reload
+ option is optional.
+
-
- Console messages from init.d scripts
+
+ An example on which you can base your
+ /etc/init.d scripts is found in
+ /etc/init.d/skeleton.
+
-
- This section describes the formats to be used for messages
- written to standard output by the /etc/init.d
- scripts. The intent is to improve the consistency of
- Debian's startup and shutdown look and feel. For this
- reason, please look very carefully at the details. We want
- the messages to have the same format in terms of wording,
- spaces, punctuation and case of letters.
-
+
+ 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 to switch from
+ an init.d script to a service unit
+ ([) or a job file (][)
+ of course. Whilst remaining an init.d script
+ however, the best usually for achieving this is to use
+ start-stop-daemon with the --oknodo
+ option.
+ ]
-
- Here is a list of overall rules that should be used for
- messages generated by /etc/init.d scripts.
-
+
+ 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
+ /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.
+ . For init.d scripts, it's often easier
+ to not use set -e and instead check the result of
+ each command separately.
+
-
-
- -
- The message should fit in one line (fewer than 80
- characters), start with a capital letter and end with
- a period (.) and line feed ("\n").
-
+
+ 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.
+
- -
- If the script is performing some time consuming task in
- the background (not merely starting or stopping a
- program, for instance), an ellipsis (three dots:
- ...) should be output to the screen, with no
- leading or tailing whitespace or line feeds.
-
+
+ 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
+ conffiles, or, (if they do not exist in the .deb)
+ by managing them correctly in the maintainer scripts (see
+ [). 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.
+ ]
- -
- The messages should appear as if the computer is telling
- the user what it is doing (politely :-), but should not
- mention "it" directly. For example, instead of:
-
+
+ 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
+ conffiles, 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 SUSv3
+ sh format. It may either be a
+ conffile or a configuration file maintained by
+ the package maintainer scripts. See [
+ 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 [ for more information.
+ ]
+
+
+
+ Console messages from init.d scripts
+
+
+ This section describes the formats to be used for messages
+ written to standard output by the /etc/init.d
+ scripts. The intent is to improve the consistency of
+ Debian's startup and shutdown look and feel. For this
+ reason, please look very carefully at the details. We want
+ the messages to have the same format in terms of wording,
+ spaces, punctuation and case of letters.
+
+
+
+ Here is a list of overall rules that should be used for
+ messages generated by /etc/init.d scripts.
+
+
+
+
+ -
+ The message should fit in one line (fewer than 80
+ characters), start with a capital letter and end with
+ a period (.) and line feed ("\n").
+
+
+ -
+ If the script is performing some time consuming task in
+ the background (not merely starting or stopping a
+ program, for instance), an ellipsis (three dots:
+ ...) should be output to the screen, with no
+ leading or tailing whitespace or line feeds.
+
+
+ -
+ The messages should appear as if the computer is telling
+ the user what it is doing (politely :-), but should not
+ mention "it" directly. For example, instead of:
+
I'm starting network daemons: nfsd mountd.
-
- the message should say
-
+
+ the message should say
+
Starting network daemons: nfsd mountd.
-
-
-
-
+
+
+
+
-
- init.d script should use the following standard
- message formats for the situations enumerated below.
-
+
+ init.d script should use the following standard
+ message formats for the situations enumerated below.
+
-
-
- -
-
When daemons are started
+
+
+ -
+
When daemons are started
-
- If the script starts one or more daemons, the output
- should look like this (a single line, no leading
- spaces):
-
+
+ If the script starts one or more daemons, the output
+ should look like this (a single line, no leading
+ spaces):
+
Starting description: daemon-1 ... daemon-n.
-
- The description should describe the
- subsystem the daemon or set of daemons are part of,
- while daemon-1 up to daemon-n
- denote each daemon's name (typically the file name of
- the program).
-
+
+ The description should describe the
+ subsystem the daemon or set of daemons are part of,
+ while daemon-1 up to daemon-n
+ denote each daemon's name (typically the file name of
+ the program).
+
-
- For example, the output of /etc/init.d/lpd
- would look like:
-
+
+ For example, the output of /etc/init.d/lpd
+ would look like:
+
Starting printer spooler: lpd.
-
-
+
+
-
- This can be achieved by saying
-
+
+ This can be achieved by saying
+
echo -n "Starting printer spooler: lpd"
start-stop-daemon --start --quiet --exec /usr/sbin/lpd
echo "."
-
- in the script. If there are more than one daemon to
- start, the output should look like this:
-
+
+ in the script. If there are more than one daemon to
+ start, the output should look like this:
+
echo -n "Starting remote file system services:"
echo -n " nfsd"; start-stop-daemon --start --quiet nfsd
echo -n " mountd"; start-stop-daemon --start --quiet mountd
echo -n " ugidd"; start-stop-daemon --start --quiet ugidd
echo "."
-
- This makes it possible for the user to see what is
- happening and when the final daemon has been started.
- Care should be taken in the placement of white spaces:
- in the example above the system administrators can
- easily comment out a line if they don't want to start
- a specific daemon, while the displayed message still
- looks good.
-
-
+
+ This makes it possible for the user to see what is
+ happening and when the final daemon has been started.
+ Care should be taken in the placement of white spaces:
+ in the example above the system administrators can
+ easily comment out a line if they don't want to start
+ a specific daemon, while the displayed message still
+ looks good.
+
+
- -
-
When a system parameter is being set
+ -
+
When a system parameter is being set
-
- If you have to set up different system parameters
- during the system boot, you should use this format:
-
+
+ If you have to set up different system parameters
+ during the system boot, you should use this format:
+
Setting parameter to "value".
-
-
+
+
-
- You can use a statement such as the following to get
- the quotes right:
-
+
+ You can use a statement such as the following to get
+ the quotes right:
+
echo "Setting DNS domainname to \"$domainname\"."
-
-
+
+
-
- Note that the same symbol (") is used
- for the left and right quotation marks. A grave accent
- (`) is not a quote character; neither is an
- apostrophe (').
-
-
+
+ Note that the same symbol (") is used
+ for the left and right quotation marks. A grave accent
+ (`) is not a quote character; neither is an
+ apostrophe (').
+
+
- -
-
When a daemon is stopped or restarted
+ -
+
When a daemon is stopped or restarted
-
- When you stop or restart a daemon, you should issue a
- message identical to the startup message, except that
- Starting is replaced with Stopping
- or Restarting respectively.
-
+
+ When you stop or restart a daemon, you should issue a
+ message identical to the startup message, except that
+ Starting is replaced with Stopping
+ or Restarting respectively.
+
-
- For example, stopping the printer daemon will look like
- this:
-
+
+ For example, stopping the printer daemon will look like
+ this:
+
Stopping printer spooler: lpd.
-
-
-
+
+
+
- -
-
When something is executed
+ -
+
When something is executed
-
- There are several examples where you have to run a
- program at system startup or shutdown to perform a
- specific task, for example, setting the system's clock
- using netdate or killing all processes
- when the system shuts down. Your message should look
- like this:
-
+
+ There are several examples where you have to run a
+ program at system startup or shutdown to perform a
+ specific task, for example, setting the system's clock
+ using netdate or killing all processes
+ when the system shuts down. Your message should look
+ like this:
+
Doing something very useful...done.
-
- You should print the done. immediately after
- the job has been completed, so that the user is
- informed why they have to wait. You can get this
- behavior by saying
-
+
+ You should print the done. immediately after
+ the job has been completed, so that the user is
+ informed why they have to wait. You can get this
+ behavior by saying
+
echo -n "Doing something very useful..."
do_something
echo "done."
-
- in your script.
-
-
+
+ in your script.
+
+
- -
-
When the configuration is reloaded
+ -
+
When the configuration is reloaded
-
- When a daemon is forced to reload its configuration
- files you should use the following format:
-
+
+ When a daemon is forced to reload its configuration
+ files you should use the following format:
+
Reloading description configuration...done.
-
- where description is the same as in the
- daemon starting message.
-
-
-
-
+
+ where description is the same as in the
+ daemon starting message.
+
+
+
+
+
+
+
@@ -8383,74 +8680,6 @@ exec /usr/lib/foo/foo "$@"
-
- Alternate init systems
-
- A number of other init systems are available now in Debian that
- can be used in place of sysvinit. Alternative
- init implementations must support running SysV init scripts as
- described at [ for compatibility.
- ]
-
- Packages may integrate with these replacement init systems by
- providing implementation-specific configuration information about
- how and when to start a service or in what order to run certain
- tasks at boot time. However, any package integrating with other
- init systems must also be backwards-compatible with
- sysvinit by providing a SysV-style init script
- with the same name as and equivalent functionality to any
- init-specific job, as this is the only start-up configuration
- method guaranteed to be supported by all init implementations. An
- exception to this rule is scripts or jobs provided by the init
- implementation itself; such jobs may be required for an
- implementation-specific equivalent of the /etc/rcS.d/
- scripts and may not have a one-to-one correspondence with the init
- scripts.
-
-
- Event-based boot with upstart
-
-
- Packages may integrate with the upstart event-based
- boot system by installing job files in the
- /etc/init directory. SysV init scripts for which
- an equivalent upstart job is available must query the output of
- the command initctl version for the string
- upstart and avoid running in favor of the native
- upstart job, using a test such as this:
-
-if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
-then
- exit 1
-fi
-
-
-
- Because packages shipping upstart jobs may be installed on
- systems that are not using upstart, maintainer scripts must
- still use the common update-rc.d and
- invoke-rc.d interfaces for configuring runlevels
- and for starting and stopping services. These maintainer
- scripts must not call the upstart start,
- restart, reload, or stop
- interfaces directly. Instead, implementations of
- invoke-rc.d must detect when upstart is running and
- when an upstart job with the same name as an init script is
- present, and perform the requested action using the upstart job
- instead of the init script.
-
-
- Dependency-based boot managers for SysV init scripts, such as
- startpar, may avoid running a given init script
- entirely when an equivalent upstart job is present, to avoid
- unnecessary forking of no-op init scripts. In this case, the
- boot manager should integrate with upstart to detect when the
- upstart job in question is started or stopped to know when the
- dependency has been satisfied.
-
-
-
-