On Sun, 25 Jun 2023 at 16:52, Ansgar <ans...@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 <bl...@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