Bug#1035733: debian -policy: packages must not use dpkg-divert to override default systemd configuraton files
On Tue, 6 Jun 2023 at 17:12, Russ Allbery <rra@debian.org> wrote:
>
> Luca Boccassi <bluca@debian.org> writes:
>
> > --- a/policy/ap-pkg-alternatives.rst
> > +++ b/policy/ap-pkg-alternatives.rst
> > @@ -24,3 +24,7 @@ See the :manpage:`update-alternatives(8)` man page for details.
> > If ``update-alternatives`` does not seem appropriate you may wish to
> > consider using diversions instead.
> >
> > +Do not attempt to use alternatives for files belonging or used by components
> > +that support native overriding mechanisms, such as ``systemd`` unit files. Read
> > +:doc:`ch-binary` for more information.
>
> "Do not attempt" in US English reads a little weirdly (I know you're
> copying an existing UK English phrasing). I instead suggest:
>
> Do not use alternatives for ``systemd`` configuration files. See
> :doc:`ch-binary` for more information.
>
> (See below for why this is systemd-specific.) This doesn't use our normal
> normative language conventions, which I think is correct since this is a
> non-normative appendix.
>
> > diff --git a/policy/ap-pkg-diversions.rst b/policy/ap-pkg-diversions.rst
> > index fe360d1..09367d7 100644
> > --- a/policy/ap-pkg-diversions.rst
> > +++ b/policy/ap-pkg-diversions.rst
> > @@ -81,3 +81,7 @@ when the file does not exist.
> > Do not attempt to divert a conffile, as ``dpkg`` does not handle it
> > well.
> >
> > +Do not attempt to divert files belonging or used by components that support
> > +native overriding mechanisms, such as ``systemd`` unit files. Read
> > +:doc:`ch-binary` for more information.
>
> Similarly here:
>
> Do not use diversions for files that have their own native override
> mechanisms, such as ``systemd`` unit files. See :doc:`ch-binary` for
> more information.
Sounds all good to me, applied, I simply had copied the previous
paragraph's style.
> > diff --git a/policy/ch-binary.rst b/policy/ch-binary.rst
> > index e517f26..e36d028 100644
> > --- a/policy/ch-binary.rst
> > +++ b/policy/ch-binary.rst
> > @@ -371,6 +371,37 @@ against earlier versions of something that previously did not use
> > ``update-alternatives``; this is an exception to the usual rule that
> > versioned conflicts should be avoided.)
> >
> > +Diversions and alternatives should be used primarily as a tool for local
> > +administrators and local packages to override the behaviour of Debian. Its use
> > +between Debian packages should be rare, should involve coordination between the
> > +packages and their maintainers, and must only be used to solve problems that
> > +cannot be handled through other facilities or native mechanisms.
>
> I think this not correct for alternatives. They are intended for use
> between Debian packages, so we need to distinguish between alternatives
> and diversions here. This might be clearer if we created a subsection for
> alternatives and diversions and added a bit of additional context from the
> appendices (and ideally removed the appendices). That's not something to
> do on this bug, just noting mostly for Sean and future work.
While I disagree on that, because alternatives make a mess of
image-based systems and are a pain to handle (requires moving parts
via maint scripts to be effective), it is also a bit off topic so I
have applied your suggestion as-is.
> I think there's also a bit more justification than we need. The
> justification is useful for discussing the Policy bug, but once we've
> decided on an approach, I think we can just point at the correct
> alternative mechanism.
>
> How about something like this:
>
> Diversions are primarily intended as a tool for local administrators
> or local packages to override the behavior of Debian. While there are
> some circumstances where one Debian package may need to divert a file
> of another Debian package, those circumstances are rare and diversions
> should only be used as a last resort when no other suitable mechanism
> exists. Diversion of a file in one Debian package by another Debian
> package should be coordinated between the maintainers of those
> packages.
>
> Diversions must not be used when a suitable override mechanism that
> accomplishes the same goal is already available.
>
> One specific case of that rule is that configuration files used by
> ``systemd`` components, such as `units,
> <https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description>`_
> `udev rules,
> <https://www.freedesktop.org/software/systemd/man/udev.html#Rules%20Files>`_
> `tmpfiles.d,
> <https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html#Configuration%20Directories%20and%20Precedence>`_
> `modules-load.d,
> <https://www.freedesktop.org/software/systemd/man/modules-load.d.html#Configuration%20Format>`_,
> `sysusers
> <https://www.freedesktop.org/software/systemd/man/sysusers.d.html#Configuration%20Directories%20and%20Precedence>`_
> and other such files, including those specific to systemd daemons
> (e.g.: `/etc/systemd/system.conf).
> <https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html>`_
> must not be diverted by any Debian package. Instead, use masking and
> drop-ins.
>
> "masking" and "drop-ins" here should ideally be links to the relevant
> documentation.
>
> We then have to figure out what to say about alternatives. I think the
> above rule is too strong for alternatives; it's often convenient to use
> slave alternatives even in places where there may be a native override
> mechanism, although it sounds like the systemd maintainers think this is
> always inappropriate for systemd. Here, I wonder if we do just want a
> systemd-specific rule. The systemd-specific rule shouldn't reference
> masking or drop-ins, though, I think, since I can't see how you would do
> what alternatives does using masking and drop-ins (one package would
> always override the other, I think, rather than allowing
> update-alternatives to choose between them).
>
> I think the correct observation here is that alternatives really don't
> make any sense for daemons. You don't want to pick between implemenations
> of a system service using alternatives for a few reasons, but one of the
> most obvious is that running update-alternatives to change the preferred
> implementation doesn't stop and restart the service (nor should it know to
> do that), so you end up putting your system in a confusing state.
>
> Therefore, I wonder if we want to just say something simpler here about
> alternatives:
>
> Alternatives must never be used for ``systemd`` configuration files.
> The alternatives system does not know how to apply changes to services
> when updating alternatives, so the resulting behavior would be
> confusing and unpredictable.
>
> I keep wanting to suggest an alternative, but I'm not sure there's an
> obvious alternative to suggest (the options are going to be very
> situation-specific), so I'm inclined to just leave it at that.
There is a native alternative: aliases. We already do that today in
the archive for the well-known 'dbus' unit. The dbus package ships the
reference implementation, and dbus-broker which is an alternative
implementation ships its own unit, which also lists 'dbus.service' as
an alias. I have listed this in addition to your suggested paragraph.
From 27ca4fabed2ae547b2406635498903de11f442d1 Mon Sep 17 00:00:00 2001
From: Luca Boccassi <bluca@debian.org>
Date: Mon, 8 May 2023 03:21:14 +0100
Subject: [PATCH] Forbid using dpkg-divert/alternatives when there are native
mechanisms
The supported mechanism for augmenting, changing, overriding and
disabling systemd configuration files is natively supported and fully
integrated in Debian, via drop-ins, hierarchical overrides, and
masking. dpkg-divert is not integrated in systemd tools so its use
is completely hidden in logs and status interfaces, and it is specific
to Debian and thus diverges from what users expect as implemented by
all other distros, going against one of the core goals of the systemd
project which is to provide a uniform interface regardless of distro
vendor or flavour.
Clarify that diversions and alternatives should only be used when
needed, with cooperation, and must not be used when there are native
mechanisms to obtain the same goals, and use systemd files as an
example.
---
policy/ap-pkg-alternatives.rst | 3 +++
policy/ap-pkg-diversions.rst | 3 +++
policy/ch-binary.rst | 35 ++++++++++++++++++++++++++++++++++
3 files changed, 41 insertions(+)
diff --git a/policy/ap-pkg-alternatives.rst b/policy/ap-pkg-alternatives.rst
index ffa2163..6f7780f 100644
--- a/policy/ap-pkg-alternatives.rst
+++ b/policy/ap-pkg-alternatives.rst
@@ -24,3 +24,6 @@ See the :manpage:`update-alternatives(8)` man page for details.
If ``update-alternatives`` does not seem appropriate you may wish to
consider using diversions instead.
+Do not use alternatives for ``systemd`` configuration files. See
+:doc:`ch-binary` for more information.
+
diff --git a/policy/ap-pkg-diversions.rst b/policy/ap-pkg-diversions.rst
index fe360d1..d299d04 100644
--- a/policy/ap-pkg-diversions.rst
+++ b/policy/ap-pkg-diversions.rst
@@ -81,3 +81,6 @@ when the file does not exist.
Do not attempt to divert a conffile, as ``dpkg`` does not handle it
well.
+Do not use diversions for files that have their own native override mechanisms,
+such as ``systemd`` unit files. See :doc:`ch-binary` for more information.
+
diff --git a/policy/ch-binary.rst b/policy/ch-binary.rst
index e517f26..4ceec3f 100644
--- a/policy/ch-binary.rst
+++ b/policy/ch-binary.rst
@@ -371,6 +371,41 @@ against earlier versions of something that previously did not use
``update-alternatives``; this is an exception to the usual rule that
versioned conflicts should be avoided.)
+Diversions are primarily intended as a tool for local administrators or local
+packages to override the behavior of Debian. While there are some circumstances
+where one Debian package may need to divert a file of another Debian package,
+those circumstances are rare and diversions should only be used as a last resort
+when no other suitable mechanism exists. Diversion of a file in one Debian
+package by another Debian package should be coordinated between the maintainers
+of those packages.
+
+Diversions must not be used when a suitable override mechanism that
+accomplishes the same goal is already available.
+
+One specific case of that rule is that configuration files used by
+``systemd`` components, such as `units,
+<https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description>`_
+`udev rules,
+<https://www.freedesktop.org/software/systemd/man/udev.html#Rules%20Files>`_
+`tmpfiles.d,
+<https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html#Configuration%20Directories%20and%20Precedence>`_
+`modules-load.d,
+<https://www.freedesktop.org/software/systemd/man/modules-load.d.html#Configuration%20Format>`_,
+`sysusers
+<https://www.freedesktop.org/software/systemd/man/sysusers.d.html#Configuration%20Directories%20and%20Precedence>`_
+and other such files, including those specific to systemd daemons
+(e.g.: `/etc/systemd/system.conf).
+<https://www.freedesktop.org/software/systemd/man/systemd-system.conf.html>`_
+must not be diverted by any Debian package. Instead, use `masking and drop-ins
+<https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description>`_.
+
+Alternatives must never be used for ``systemd`` configuration files. The
+alternatives system does not know how to apply changes to services when updating
+alternatives, so the resulting behavior would be confusing and unpredictable.
+Instead, `aliases
+<https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Description>`_
+can be used to provide alternative implementations of the same named unit.
+
.. _s-maintscriptprompt:
Prompting in maintainer scripts
--
2.39.2
Reply to: