Bug#1035733: debian -policy: packages must not use dpkg-divert to override default systemd configuraton files

[Russ Allbery]

Luca Boccassi <bluca at 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.

> 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.

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.

-- 
Russ Allbery (rra at debian.org)              <https://www.eyrie.org/~eagle/>