Luca Boccassi <bl...@debian.org> writes:
> Moved as suggested. Also incorporated your suggestion on the versioned
> virtual package dependency verbatim.
Okay, I felt like doing editing this evening, apparently, so even though
only you, Sam, and Simon had a chance to respond, I went ahead and did the
editing. I'm guessing we still have some discussion to get through, but
attached is a revised diff that I think captures the content of your diff
but adds some additional explanation and justification that I was kind of
craving. Please let me know if I messed up any of the meaning here.
Note that this adds a must (held over from Luca's "required") for init
systems. I don't want to introduce that into Policy until the sysvinit
maintainers have had a chance to weigh in or someone can confirm that
sysvinit already handles running systemd-tmpfiles appropriately when it is
installed.
I should note that I dropped the admonition in the maintainer scripts
section to use upstream's tmpfiles.d files because admonitions of this
type (from Lintian and elsewhere) annoy me. The maintainer is in the best
possible position to balance the advantages of using upstream
configuration that is shared across distributions, bugs in the upstream
version that aren't fixed, upstream's ability to maintain those files
directly, whether upstream accepts contributions promptly, and whether
there are Debian-specific integration concerns that need to be addressed.
Less personally and more specific to Policy, making appropriate decisions
about when to use upstream files and when to use Debian-specific files is
a maintainer experience and expertise issue, not a Policy issue. Policy
defines how the packages should work and is agnostic about where the
pieces of it come from. If we want to give maintainers advice on how to
integrate upstream packages, I think that should go into Developers
Reference instead.
There was some earlier discussion in this bug about the possibility of
using tmpfiles.d to manage things like /run directories that, under
sysvinit, are currently managed in a somewhat ad hoc and untrackable way,
such as via mkdir in the init script. I still think there's something
there, but I don't see a good way to describe it without creating possible
problems, so I left it out.
> We don't have to handle it with this change/bug and as mentioned I've
> already reworded it as suggested, but to clarify my thinking there, the
> place I was coming from was the factory reset and first boot angle. When
> doing a first boot with only the OS vendor tree under /usr and nothing
> else, you want to get to a working system, and if there are complex
> files created under /var by maintainer scripts, that's kinda of a
> problem.
Should Debian decide to adopt the OS vendor tree concept, I certainly
understand how what gnubg does would interfere with that. This seemed
like the best of a set of bad options at the time. I may adopt Simon's
idea of just putting the generated file in /usr, which would also allow me
to drop a Debian-specific patch; I didn't do that because putting files in
/usr that dpkg doesn't know about felt icky, but Simon is correct that
there are a lot of other precedents.
> Perhaps those complex binaries should be created by oneshot services
> that run at boot with a ConditionPathExists=!/var/some/complex/binary
> other than maintainer scripts? That way if /var is blown away, you still
> get a working system on next boot.
Yes, I could also do something like that. Of course, the point may be
moot if upstream never ports GNU Backgammon to anything newer than Gtk+ 2,
and the chances of that port currently aren't looking great.
> But again, happy to shelve this for now, as it's a more complex topic.
Agreed, we don't have to cross this bridge today.
--
Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>
diff --git a/policy/ch-files.rst b/policy/ch-files.rst
index b34c183..cc685fe 100644
--- a/policy/ch-files.rst
+++ b/policy/ch-files.rst
@@ -722,6 +722,65 @@ 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, files with trivial content (such
+as short fixed strings), or symlinks in ``/var`` or ``/etc`` 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 files and 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 recent enough to
+require a version constraint, that version constraint should be added to
+both dependencies.
+
+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 207b3c0..8a6b53b 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -586,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:
+.. _s-services-dirs:
-Boot-time initialization
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-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
+``/var/cache`` or ``/var/log`` to free space).
+
+The relevant settings 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
~~~~~~~
