Luca Boccassi <bl...@debian.org> writes: > diff --git a/policy/ch-files.rst b/policy/ch-files.rst > index b34c183..30ce013 100644 > --- a/policy/ch-files.rst > +++ b/policy/ch-files.rst > @@ -722,6 +722,43 @@ 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: > + > +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/``, must 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.
This is an oddly specific list of directories and not at all the directories that I would have expected to be handled by tmpfiles.d. My naive expectation would be that the most common path handled by tmpfiles.d would be /run, /tmp, and /var/tmp. I read through the other messages in this bug but I didn't see the explanation for why those directories in particular. Given that neither /var (apart from /var/tmp) nor /etc are transient, I would have expected packages to simply ship the directories under those paths that they need in the package. Why is that not the right approach? Could you explain when tmpfiles.d should be used instead of shipping the directory in the package? > +The ``tmpfiles.d`` file format is defined by the ``systemd`` project, and is > +guaranteed to be stable. Ideally, such definitions should be defined upstream > +where applicable, and shipped as they are by Debian packages. > + > +Details about the syntax and installation paths for ``tmpfiles.d`` are > defined > +by its `reference implementation's documentation, > +<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html>`_ and will > +not be redefined here. I'm clearly missing something, but I was naively expecting this section to start with something more like this: Packages that need to create files or directories in file systems that may be deleted on each reboot (for example, ``/run``, ``/tmp``, and ``/var/tmp``) should do so via configuration files in the ``/usr/lib/tmpfiles.d`` directory. The syntax of those files is defined by the `systemd tmpfiles.d documentation <https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html>`__. However, reading that documentation, it sounds like most of the cases for other directories are handled by other systemd unit configuration directives. We should say that explicitly here and reproduce the list of other directories that should be handled directly by the unit file if that's what we want people to do. What's the plan for creating directories in /run on non-systemd systems? I had assumed that tmpfiles.d would be used for those directories so that we can use the same mechanism for both systemd and non-systemd systems, but it looks like that's not ideal for systemd systems. Is it safe to use *both* (e.g.) RuntimeDirectory= *and* tmpfiles.d for the same directory so that tmpfiles.d is used for non-systemd systems? > +``tmpfiles.d`` snippets should be detected at package build time by > +tools such as ``debhelper``, packaged, and the appropriate snippet to > +call them on installation, upgrade, removal, purge and other steps as > +required, should be automatically added by helpers such as > +``dh_installtmpfiles``. Policy should not say things like this. It's the job of Policy to define what those snippets are and be specific. It's Policy-compliant to not use debhelper at all (we've had some discussions of changing that, but we haven't yet). debhelper is one implementation of Policy (and additional non-Policy stuff), so we should be defining (at a high level) what it needs to do and what any non-debhelper parallel implementation should do. Also, isn't the most obvious way to implement this to use triggers? That runs into the problem that Policy still doesn't have any documentation of triggers, but (unlike debhelper) we can just require that implementations of the tmpfiles.d mechanism pick up new files via triggers and do the right thing, which feels appealing. > Packages shipping ``tmpfiles.d`` snippets should depend on the > +appropriate virtual packages in the following order: > +``default-systemd-tmpfiles | systemd-tmpfiles``. I read the discussion of this and agree this is the best approach. > +Init systems are required to integrate with ``tmpfiles.d`` and run the > +service that applies them on boot, and regularly for cleanup > +purposes. 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. I don't really like being this nonspecific. Can't we just say specifically what init systems need to do? I assume it's something like "call systemd-tmpfiles --create --boot on boot and systemd-tmpfiles --clean periodically on some schedule" (what schedule?). Also, based on the previous discussion, it sounds like we should also say something about how non-systemd init systems must depend on an implementation of the tmpfiles.d mechanism. That's arguably a consequence of the requirement they integrate with it, but given that the exact dependencies matter a lot for ensuring nothing weird happens during system package installation, I think we should spell it out. > +Instead, :ref:`s-tmpfiles.d` snippets should be shipped, being ideally > +provided by the upstream sources, if any. For more details about the > +``tmpfiles.d`` interface, see :ref:`s-tmpfiles.d`. I personally lean against commenting on what upstream should do. I think any maintainer already knows that ideally as much is upstreamed as possible, it's not Policy's role to say stuff like that (that's more of a Maintainer's Guide thing), and it tends to prompt people to file weird bugs or create weird Lintian checks that are unactionable for maintainers of packages whose upstreams have no intention of providing these files for whatever reason. Policy is only about Debian packages. We're not writing policy for upstream; there's a wiki page that tries to collect that sort of advice. -- Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>