--- Begin Message ---
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
--- End Message ---
--- Begin Message ---
Source: debian-policy
Source-Version: 4.5.0.0
We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive.
A summary of the changes between this version and the previous one is
attached.
Thank you for reporting the bug, which will now be closed. If you
have further comments please address them to 948115@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.
Debian distribution maintenance software
pp.
Sean Whitton <spwhitton@spwhitton.name> (supplier of updated debian-policy package)
(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
Format: 1.8
Date: Mon, 20 Jan 2020 12:37:09 -0700
Source: debian-policy
Architecture: source
Version: 4.5.0.0
Distribution: unstable
Urgency: medium
Maintainer: Debian Policy Editors <debian-policy@lists.debian.org>
Changed-By: Sean Whitton <spwhitton@spwhitton.name>
Closes: 941198 948115 949007 949390
Changes:
debian-policy (4.5.0.0) unstable; urgency=medium
.
[ Russ Allbery ]
* Clarify the footnote explaining why packages should not depend on X
fonts. Thanks, Stephen Kitt.
.
[ Sean Whitton ]
* Policy: Packages including daemons should ship systemd units
Wording: Russ Allbery <rra@debian.org>
Seconded: Sean Whitton <spwhitton@spwhitton.name>
Seconded: Ansgar <ansgar@debian.org>
Closes: #941198
* Policy: New package usernames should begin with an underscore
Wording: Philipp Kern <pkern@debian.org>
Seconded: Sean Whitton <spwhitton@spwhitton.name>
Seconded: Russ Allbery <rra@debian.org>
Closes: #949390
* Policy: Revise init script policy in light of GR result
Wording: Russ Allbery <rra@debian.org>
Seconded: Sam Hartman <hartmans@debian.org>
Seconded: Sean Whitton <spwhitton@spwhitton.name>
Closes: #948115
- This change involved changing a number of Sphinx anchor names. This
may break some external links into Policy.
.
debian-policy (4.4.1.3) UNRELEASED; urgency=medium
.
[ Sean Whitton ]
* Fix 'day-of week'.
Thanks to Jakub Wilk.
.
[ Russ Allbery ]
* Fix error in Perl example for the gain root command. Thanks, Niels
Thykier. (Closes: #949007)
Checksums-Sha1:
097221d4cd4981ac92d1410800eb91ef17e92705 2023 debian-policy_4.5.0.0.dsc
351dcd44e0ae9bd65be167bb504073ea87edc255 540968 debian-policy_4.5.0.0.tar.xz
Checksums-Sha256:
52d3de968c60fc66dc40d5c195d39718a20eb619c0e373c4e0ce30a94729dc44 2023 debian-policy_4.5.0.0.dsc
523b1847ed4448564150ac860e6b7a3df93837e7ccb6b0530ba7d071f5d457a7 540968 debian-policy_4.5.0.0.tar.xz
Files:
fd2e9e5ff66c7f06c7353700557c5f78 2023 doc optional debian-policy_4.5.0.0.dsc
5f8da84e127fc6266b4450cb3a8cd670 540968 doc optional debian-policy_4.5.0.0.tar.xz
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAl4mAlMACgkQaVt65L8G
YkADjg//SkyBizCLSqdCi9dcnvfREzopVNVen2mgKpO5tCu487XD34LyRgIZe2J/
5/IhQqIzYwSci1j3xfPM/FUFw7O4mIOQEdU73UTgjVJKrnhBJ+VqhTBcko3JrIdZ
TGwXEUT9SmLRQemNEnesenEhlwbNOF+MvPR5P7RmU4TEonj9sefvh3VudTDk458S
Z6mMYFl07j/lhjRI2xDHt4+eTfJ5HjfdgrkymZ5fXd70en4or3iIbEvvsZB1Kn1T
K1mnWSsNv3cMKjSumPH4tryxabMWOo/hgKf0MZJtemoL1X9veIEMHkc0CzB/ESES
U+IwJx6jNfsl8Fri41S3ESvbjTGicX29MGJonH9k113P5FJKIt0bhNGXfnuqAY0H
QMsOHCjZwGWrxGI/aWWUj+s4FZ8R74B9F5ib+DCdcKkpGSOQRJm0Qb5MDyh9C9zp
KWDc5HwiBze1VI8xSqRk6Hsf8rvNjh0e5pBQHYuetGT+1xDtYHvm3WSmiXe5z3oJ
BE0GSOiaYJPevLM8cwQm62c+7SE7oa6e+FSDtmIM3qw4eAz43NxOK0yw/mPnbDiX
KphcjAsq2e7Kyb3KeUJ/A44YI32JRIvtngWbPpv57zUrkntisuXnjRpwobFaejXa
kTcQCayZZTuhnafvJkZnydT2AHs3ipkmPp8koF8Xye5FO3BL++s=
=duDb
-----END PGP SIGNATURE-----
--- End Message ---