Russ Allbery <r...@debian.org> writes:
> Maybe the right way to do this is just have two examples, one as the
> default and another if you're using tmpfiles.d functionality added in a
> specific version of systemd that's newer than the version shipped with
> the stable version of Debian prior to the one you're targeting.
Here's an updated version with that change plus some other minor fixes.
--
Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>
diff --git a/debian/changelog b/debian/changelog
index 4cead28..44a3710 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -24,17 +24,6 @@ debian-policy (4.6.3.0) UNRELEASED; urgency=medium
Seconded: Helmut Grohne <hel...@subdivi.de>
Seconded: Guillem Jover <guil...@debian.org>
Closes: #970234
- * Policy: Binary and Description fields may be absent in .changes
- Wording: Russ Allbery <r...@debian.org>
- Seconded: Sam Hartman <hartm...@debian.org>
- Seconded: Guillem Jover <guil...@debian.org>
- Closes: #963524
- * Policy: systemd units are required to start and stop system services
- Wording: Luca Boccassi <bl...@debian.org>
- Wording: Russ Allbery <r...@debian.org>
- Seconded: Luca Boccassi <bl...@debian.org>
- Seconded: Sam Hartman <hartm...@debian.org>
- Closes: #1039102
-- Sean Whitton <spwhit...@spwhitton.name> Wed, 14 Jun 2023 16:58:40 +0100
diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
index d5c9d68..4bab7df 100644
--- a/policy/ch-controlfields.rst
+++ b/policy/ch-controlfields.rst
@@ -278,7 +278,7 @@ The fields in this file are:
- :ref:`Source <s-f-Source>` (mandatory)
-- :ref:`Binary <s-f-Binary>` (mandatory in some cases)
+- :ref:`Binary <s-f-Binary>` (mandatory)
- :ref:`Architecture <s-f-Architecture>` (mandatory)
@@ -292,7 +292,7 @@ The fields in this file are:
- :ref:`Changed-By <s-f-Changed-By>`
-- :ref:`Description <s-f-Description>` (mandatory in some cases)
+- :ref:`Description <s-f-Description>` (mandatory)
- :ref:`Closes <s-f-Closes>`
@@ -812,16 +812,12 @@ See :ref:`s-descriptions` for further information on
this.
In a ``.changes`` file, the ``Description`` field contains a summary of
-the descriptions of the binary packages being uploaded. If no binary
-packages are being uploaded, this field will not be present.
-
-When used inside a ``.changes`` file, the ``Description`` field has a
-different format than in source or binary control files. It is a multiline
-field with one line per binary package. The first line of the field value
-(the part on the same line as ``Description:``) is always empty. Each
-subsequent line is indented by one space and contains the name of a binary
-package, a space, a hyphen (``-``), a space, and the short description
-line from that package.
+the descriptions for the packages being uploaded. For this case, the
+first line of the field value (the part on the same line as
+``Description:``) is always empty. It is a multiline field, with one
+line per package. Each line is indented by one space and contains the
+name of a binary package, a space, a hyphen (``-``), a space, and the
+short description line from that package.
.. _s-f-Distribution:
@@ -931,8 +927,7 @@ every architecture. The source control file doesn't contain details of
which architectures are appropriate for which of the binary packages.
When it appears in a ``.changes`` file, it lists the names of the binary
-packages being uploaded, separated by whitespace (not commas). If no
-binary packages are being uploaded, this field will not be present.
+packages being uploaded, separated by whitespace (not commas).
.. _s-f-Installed-Size:
diff --git a/policy/ch-files.rst b/policy/ch-files.rst
index b34c183..fa3e5be 100644
--- a/policy/ch-files.rst
+++ b/policy/ch-files.rst
@@ -722,6 +722,70 @@ The name of the files and directories installed by binary packages
outside the system PATH must be encoded in UTF-8 and should be
restricted to ASCII when it is possible to do so.
+.. _s-tmpfiles.d:
+
+Volatile and temporary files (``tmpfiles.d``)
+---------------------------------------------
+
+Some packages require empty directories in ``/var`` or ``/etc``, or
+symlinks or files with trivial content in ``/var``, to implement their
+functionality. Examples include directories under ``/var/cache`` that are
+writable by the package as cache areas, an initially-empty directory in
+``/etc`` intended for local overrides added by the local system
+administrator, or a file in ``/var`` that should default to a symlink
+elsewhere on the system but may be changed later.
+
+Rather than include these symlinks, files, or directories in the binary
+package or create them in package maintainer scripts, packages should use
+the ``tmpfiles.d`` mechanism to specify the files and directories that
+should be created. This allows associating these files and directories
+with specific packages (not currently possible when creating them in
+maintainer scripts), and allows local administrators to delete the
+contents of directories such as ``/var/cache`` with the assurance that
+``tmpfiles.d`` can recreate the necessary file structure without
+reinstalling packages or re-running maintainer scripts.
+
+For information on how to specify files and directories that should be
+managed by the ``tmpfiles.d`` mechanism, see :manpage:`tmpfiles.d(5)`.
+
+If the files or directories are only needed by a system service or
+otherwise should only be created when that service is running, packages
+should define those files and directories in the ``systemd`` unit for the
+service (and, for alternative init systems, in the configuration for that
+init system) instead of using the ``tmpfiles.d`` mechanism. See
+:ref:`s-services-dirs` for more details.
+
+The ``tmpfiles.d`` mechanism may also be used to create and manage files
+and directories under ephemeral file systems such as ``/tmp`` and
+``/run``, although these are more likely to be associated with a running
+service and in those cases should be defined in the ``systemd`` unit for
+the service.
+
+All packages that ship ``tmpfiles.d`` configuration should declare a
+dependency on::
+
+ default-systemd-tmpfiles | systemd-tmpfiles
+
+If the package uses ``tmpfiles.d`` features that are not supported by all
+implementations of the ``systemd-tmpfiles`` virtual package in the stable
+release prior to the release being targeted, instead use::
+
+ default-systemd-tmpfiles (>= v) | systemd-tmpfiles (>= v)
+
+where ``v`` is the version of ``systemd`` in which the features were
+introduced.
+
+All packages that ship ``tmpfiles.d`` configuration should arrange for
+that configuration to be processed during package installation. This
+should be handled by the packaging helper framework; for example, packages
+using ``debhelper`` should use ``dh_installtmpfiles``, which will add the
+appropriate commands to the package maintainer scripts.
+
+The init system must ensure that ``tmpfiles.d`` configuration is applied
+during boot and that ``tmpfiles.d`` cleanup rules are invoked
+periodically. See :manpage:`systemd-tmpfiles(8)` for more information on
+how to do this.
+
.. [#]
If you are using GCC, ``-fPIC`` produces code with relocatable
position independent code, which is required for most architectures
diff --git a/policy/ch-maintainerscripts.rst b/policy/ch-maintainerscripts.rst
index 724074c..e43340f 100644
--- a/policy/ch-maintainerscripts.rst
+++ b/policy/ch-maintainerscripts.rst
@@ -50,6 +50,11 @@ absolute pathname. Maintainer scripts should also not reset the
appending package-specific directories. These considerations really
apply to all shell scripts.
+Maintainer scripts should not be used to create empty directories in
+``/var`` or ``/etc``, or symlinks or files with trivial content in
+``/var``. Instead, use the ``tmpfiles.d`` mechanism to manage those
+directories and files. See :ref:`s-tmpfiles.d` for more information.
+
.. _s-idempotency:
Maintainer scripts idempotency
diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 64c0ff6..3998f44 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -323,25 +323,20 @@ which try to write to a home directory will fail to build.
Starting system services
------------------------
-Debian packages that provide system services should arrange for those
-services to be automatically started and stopped by the init system or
-service manager. This section describes how that is done.
-
.. _s-services-intro:
Introduction
~~~~~~~~~~~~
-The default init system and service manager in Debian is ``systemd``.
-Packages that wish to automatically start and stop system services must
-include ``systemd`` service units to do so, unless the service is only
-intended for use on systems running alternate init systems. See
-:manpage:`systemd.service(5)` for details on the syntax of a service unit
-file.
+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.
-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
@@ -350,13 +345,13 @@ 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.
-``systemd`` uses dependency and ordering information contained within the
-+enabled unit files to decide which services to run and in which order.
-The ``sysv-rc`` runlevel system for ``sysvinit`` uses 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.
+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.
@@ -591,14 +586,44 @@ It is easiest for packages not to call ``invoke-rc.d`` directly, but
instead use debhelper programs that add the required ``invoke-rc.d``
calls automatically. See ``dh_installinit``, ``dh_installsystemd``, etc.
-.. _s9.3.4:
-
-Boot-time initialization
-~~~~~~~~~~~~~~~~~~~~~~~~
+.. _s-services-dirs:
-This section has been deleted.
+Service Directories
+~~~~~~~~~~~~~~~~~~~
-.. _s9.3.5:
+Many services need auxillary directories with appropriate permissions in
+``/run``, ``/var``, or ``/etc``. Rather than including empty directories
+in the binary package, creating empty directories in maintainer scripts,
+or using the ``tmpfiles.d`` mechanism (see :ref:`s-tmpfiles.d`), services
+should configure such directories in their ``systemd`` unit. This
+associates the directories with a service, ensures that permissions and
+access control will be managed correctly, and ensures the directories will
+be created when necessary (such as after the local administrator deleted
+directories under ``/var/cache`` or ``/var/log`` to free space).
+
+The relevant ``systemd`` unit settings are:
+
+=========================== ==============
+Setting Parent path
+=========================== ==============
+``RuntimeDirectory=`` ``/run``
+``StateDirectory=`` ``/var/lib``
+``CacheDirectory=`` ``/var/cache``
+``LogsDirectory=`` ``/var/log``
+``ConfigurationDirectory=`` ``/etc``
+=========================== ==============
+
+There are other settings for directory permissions and related
+configuration that may be necessary for some services. For full
+documentation, see :manpage:`systemd.exec(5)`.
+
+Packages that support alternative init systems will need to arrange for
+the same directories to be created when ``systemd`` is not used. This may
+be done by, for example, adding equivalent configuration for another init
+system, or creating such directories and setting appropriate permissions
+before starting the service in an init script.
+
+.. _s9.3.6:
Example
~~~~~~~
diff --git a/policy/upgrading-checklist.rst b/policy/upgrading-checklist.rst
index 6b5264d..162086d 100644
--- a/policy/upgrading-checklist.rst
+++ b/policy/upgrading-checklist.rst
@@ -65,20 +65,6 @@ Unreleased.
4.8
Hard links are permitted in source packages.
-5.6.13
- The ``Description`` field is not present in ``.changes`` files if no
- binary packages are being uploaded.
-
-5.6.19
- The ``Binary`` field is not present in ``.changes`` files if no binary
- packages are being uploaded.
-
-6.3
- Packages that automatically start or stop system services must include
- ``systemd`` units unless the service is only intended for use on
- systems running alternative init systems. Previously, ``systemd``
- also supported init scripts, but that support is being removed.
-
Version 4.6.2
-------------
