Bug#945269: debian-policy: packages should use tmpfiles.d(5) to create directories below /var
On Sun, 25 Jun 2023 at 16:52, Ansgar <ansgar@43-1.org> wrote:
>
> Hi Luca,
>
> On Tue, 2023-06-20 at 22:53 +0100, Luca Boccassi wrote:
> > Russ, anything I've missed that you want me to change from the most
> > recent revision at
> > https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=945269#160 ?
>
> I suggest a minor change:
>
> In the paragraph
>
> +---
> | Init systems other than ``systemd`` should allow providing the same
> | functionality as appropriate for each system, for example managing the
> | directories from the init script shipped by the package.
> +---
>
> change "init script shipped by the package" to "appropriate service
> startup configuration".
>
> This should address concerns raise on d-devel@ that some packages might
> not ship an init script. It also better covers alternative init systems
> that do something more interesting than just starting the same sysvinit
> scripts of old (not sure if any do).
Sure, updated as suggested.
Kind regards,
Luca Boccassi
From 8538f41dc235e9d9be4101595d469d389db693ef Mon Sep 17 00:00:00 2001
From: Luca Boccassi <bluca@debian.org>
Date: Tue, 9 May 2023 01:38:13 +0100
Subject: [PATCH] Define service directories and tmpfiles.d interfaces and
usage
---
policy/ch-files.rst | 64 +++++++++++++++++++++++++++++++++
policy/ch-maintainerscripts.rst | 7 ++++
2 files changed, 71 insertions(+)
diff --git a/policy/ch-files.rst b/policy/ch-files.rst
index b34c183..830f69c 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-service-directories:
+
+Service Directories
+-------------------
+
+Services might need auxiliary directories under ``/var/``, ``/run/`` or
+``/etc``. Instead of shipping empty directories in packages, or creating them
+with custom code in maintainer scripts, services should use ``systemd``'s native
+settings to ensure the required directories are created regardless of the
+privilege level under which the services are running. The relevant settings are
+`RuntimeDirectory=, StateDirectory=, CacheDirectory=, LogsDirectory= and
+ConfigurationDirectory=
+<https://freedesktop.org/software/systemd/man/systemd.exec.html#RuntimeDirectory=>`_,
+covering respectively ``/run/``, ``/var/lib/``, ``/var/cache/``, ``/var/log/``
+and ``/etc/`` for system services, and the equivalent XDG-defined location for
+user services.
+
+Init systems other than ``systemd`` should allow providing the same
+functionality as appropriate for each system, for example managing the
+directories from the appropriate service startup configuration.
+
+.. _s-tmpfiles.d:
+
+tmpfiles.d
+----------
+
+Packages might need additional files or directories to implement their
+functionality. Directories that are located under ``/var/`` or ``/etc/``, and
+files that are located under ``/var/``, should not be created manually via
+maintainer scripts, but instead be declaratively defined via the `tmpfiles.d
+<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html>`_ interface.
+Files and directories under ephemeral filesystems such as ``/tmp/`` may also be
+created and managed via ``tmpfiles.d`` snippets.
+
+When ownership of a directory can be clearly tied to a specific service,
+``Service Directories`` should be preferred to ``tmpfiles.d`` snippets.
+
+The ``tmpfiles.d`` file format is defined by the ``systemd`` project, and is
+guaranteed to be stable. Details about the syntax and installation paths are
+defined by its `reference implementation's documentation,
+<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html>`_ and will
+not be redefined here.
+
+``tmpfiles.d`` snippets should be usable on systems that do not boot (such as a
+very minimal chroot image), and also on systems booting with init systems other
+than ``systemd``.
+
+``tmpfiles.d`` snippets should be integrated in packages using automated shared
+tooling rather than by manually writing package-specific code in maintainers
+scripts. For example, packages built using ``debhelper`` should make use of the
+``dh_installtmpfiles`` addon. Packages shipping ``tmpfiles.d`` snippets should
+depend on the appropriate virtual packages in the following order:
+``default-systemd-tmpfiles | systemd-tmpfiles``.
+
+Init systems are required to integrate with ``tmpfiles.d`` and run the service
+that applies them on boot, and regularly for cleanup purposes, depending on the
+appropriate package providing the appropriate implementation that best
+integrates with each system. For example, ``systemd`` will make the reference
+implementation available when its main package is installed. The documentation
+for the reference implementation, `systemd-tmpfiles,
+<https://www.freedesktop.org/software/systemd/man/systemd-tmpfiles.html>`_
+explains how to call the program so that the appropriate ``tmpfiles.d`` snippets
+are applied at the appropriate time.
+
.. [#]
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..3734deb 100644
--- a/policy/ch-maintainerscripts.rst
+++ b/policy/ch-maintainerscripts.rst
@@ -50,6 +50,13 @@ 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 or remove auxiliary files and/or
+directories that packages may need, such as those in ``/var/`` or ``/etc/``.
+Instead, :ref:`s-tmpfiles.d` snippets should be shipped, with the ones provided
+by the upstream sources, if any, to be preferred over Debian-specific ones when
+possible. For more details about the ``tmpfiles.d`` interface, see
+:ref:`s-tmpfiles.d`.
+
.. _s-idempotency:
Maintainer scripts idempotency
--
2.39.2
Reply to: