Bug#948115: Revise init script Policy based on GR result
Package: debian-policy
Version: 4.4.1.2
Severity: important
Per recent (non-BTS) discussion, this patch is a first draft at
reconciling Policy with the recent GR result. Summary of changes:
* Change section headings and anchors to reflect the more general topic
* Add recommended naming convention for service units
* Encourage including an init script if there is no service unit
* Describe including an init script alongside a service unit as optional
* Recommend appropriate naming of an init script alongside a service unit
* Remove recommendation to include an init script
* Use init script rather than initscript consistently
* Move some things around that belong more naturally in other sections
* Be consistent about saying update-rc.d is a requirement
* Remove the section on alternate init systems, which is now not relevant
Policy itself has no links to the previous anchors. This might
break external links; let me know if you feel like that's a larger
issue than I thought it was and we can look at keeping the old
(but pretty wildly inaccurate) anchors.
diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 4551196..47d9fe4 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -315,46 +315,53 @@ set to this value.
The Debian autobuilders set HOME to ``/nonexistent`` so that packages
which try to write to a home directory will fail to build.
-.. _s-sysvinit:
+.. _s-services:
-System run levels and ``init.d`` scripts
-----------------------------------------
+Starting system services
+------------------------
-.. _s-etc-init.d:
+.. _s-services-intro:
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
-:manpage:`init(8)`).
-
-``systemd`` uses dependency information contained within the init
-scripts and symlinks in ``/etc/rcn.d`` to decide which scripts to run
-and in which order. The ``sysv-rc`` runlevel system uses symlinks in
-``/etc/rcn.d`` to decide which scripts to run and in which order; see
-the ``README.runlevels`` file shipped with ``sysv-rc`` for
-implementation details. Other alternatives might exist.
-
-Maintainer scripts must use ``update-rc.d`` as described below to
-interact with the service manager for requests such as enabling or
-disabling services. They should use ``invoke-rc.d`` as described below
-to invoke initscripts for requests such as starting and stopping
-service.
+Packages that include system services should include ``systemd`` service
+units to start or stop those services. See :manpage:`systemd.service(5)`
+for details on the syntax of a service unit file. In the common case that
+a package includes a single system service, the service unit should have
+the same name as the package plus the ``.service`` extension.
+
+If the package does not include a service unit (if, for example, no one
+has yet written one), including an init script, as described below, to
+start the service is encouraged.
+
+Packages including a service unit may optionally include an init script to
+support other init systems. In this case, the init script should have the
+same name as the ``systemd`` service unit so that ``systemd`` will ignore
+it and use the service unit instead. Packages may also support other init
+systems by including configuration in the native format of those init
+systems.
+
+If a service unit is not present, ``systemd`` uses dependency information
+contained within the init scripts and symlinks in ``/etc/rcn.d`` to decide
+which scripts to run and in which order. The ``sysv-rc`` runlevel system
+for ``sysvinit`` uses the same symlinks in ``/etc/rcn.d`` to decide which
+scripts to run and in which order at boot time and when the init state (or
+"runlevel") is changed. See the ``README.runlevels`` file shipped with
+``sysv-rc`` for implementation details. Other alternatives might exist.
+
+The sections below describe how to write those scripts and configure those
+symlinks.
.. _s-writing-init:
Writing the scripts
~~~~~~~~~~~~~~~~~~~
-Packages that include system services should include ``systemd`` service
-units to start or stop those services. See :manpage:`systemd.service(5)`.
-
-To support other init systems, packages that include daemons for system
-services should place scripts in ``/etc/init.d`` to start or stop those
-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:
+Init scripts are placed in ``/etc/init.d``. In the common case that a
+package starts a single service, they should be named
+``/etc/init.d/package``. They should accept one argument, saying what to
+do:
``start``
start the service,
@@ -381,10 +388,9 @@ saying what to do:
``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 ``start``, ``stop``, ``restart``, and ``force-reload`` options should
+be supported by all init scripts. 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
@@ -464,13 +470,15 @@ information.
Interfacing with init systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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``.
+Maintainer scripts for packages including init scripts must use
+``update-rc.d`` as described below to interact with the service manager
+for requests such as enabling or disabling services. They should use
+``invoke-rc.d`` as described below to invoke init scripts for requests
+such as starting and stopping service.
-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``).
+Directly managing the ``/etc/rc?.d`` links and directly invoking the
+``/etc/init.d/`` init scripts should be done only by packages providing
+the init script subsystem (such as ``init-system-helpers``).
.. _s9.3.3.1:
@@ -480,8 +488,7 @@ Managing the links
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.
+It is intended for use in package maintainer scripts.
You must not include any ``/etc/rcn.d`` symbolic links in the actual
archive or manually create or remove the symbolic links in maintainer
@@ -540,17 +547,17 @@ calls automatically. See ``dh_installinit``, ``dh_installsystemd``, etc.
.. _s9.3.3.2:
-Running initscripts
-^^^^^^^^^^^^^^^^^^^
+Running init scripts
+^^^^^^^^^^^^^^^^^^^^
The program ``invoke-rc.d`` is provided to make it easier for package
-maintainers to properly invoke an initscript, obeying runlevel and other
+maintainers to properly invoke an init script, 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 package maintainer scripts must use ``invoke-rc.d`` to invoke the
-``/etc/init.d/*`` initscripts or equivalent, instead of calling them
+``/etc/init.d/*`` init scripts or equivalent instead of calling them
directly.
By default, ``invoke-rc.d`` will pass any action requests (start, stop,
@@ -565,7 +572,7 @@ Most packages will simply use:
in their ``postinst`` and ``prerm`` scripts.
-A package should register its initscript services using ``update-rc.d``
+A package should register its init script services using ``update-rc.d``
before it tries to invoke them using ``invoke-rc.d``. Invocation of
unregistered services may fail.
@@ -588,9 +595,9 @@ This section has been deleted.
Example
~~~~~~~
-Examples on which you can base your systemd integration on is available in
-the man page :manpage:`systemd.unit(8)`. An example on which you can base
-your ``/etc/init.d`` scripts is available in the man page
+Examples on which you can base your ``systemd`` service units are
+available in the man page :manpage:`systemd.unit(8)`. An example on which
+you can base your init scripts is available in the man page
:manpage:`init-d-script(5)`.
.. _s9.4:
@@ -953,23 +960,7 @@ for information and details.
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
-:ref:`s-sysvinit` 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.
+This section has been deleted.
.. _s-upstart:
-- System Information:
Debian Release: bullseye/sid
APT prefers unstable
APT policy: (990, 'unstable'), (500, 'unstable-debug'), (1, 'experimental')
Architecture: amd64 (x86_64)
Kernel: Linux 5.4.0-1-amd64 (SMP w/8 CPU cores)
Kernel taint flags: TAINT_PROPRIETARY_MODULE, TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
debian-policy depends on no packages.
Versions of packages debian-policy recommends:
ii libjs-sphinxdoc 1.8.5-4
Versions of packages debian-policy suggests:
pn doc-base <none>
-- no debconf information
Reply to: