Bug#985616: Document change to unbound ".d" config file fragment behavior

[Robert Edmonds]

Package: release-notes
Severity: normal

Hi,

During the bullseye release cycle the default /etc/unbound/unbound.conf
file was changed to use the newly introduced "include-toplevel:"
directive rather than the "include:" directive. This should probably be
mentioned in the bullseye release notes because it will break
configurations where the user added a clauseless config file fragment to
/etc/unbound/unbound.conf.d/.

The text from /usr/share/doc/unbound/NEWS.Debian.gz about this change is
quoted below.

Thanks!


unbound (1.11.0-1) unstable; urgency=medium

The default Debian config file shipped in the unbound package has changed
from using the "include:" directive to using the "include-toplevel:"
directive in order to include the config file fragments in
/etc/unbound/unbound.conf.d/*.conf into the unbound configuration.

The "include-toplevel:" directive has been newly introduced in unbound
1.11.0 and it requires that any included config file fragment begin its own
clause (e.g., "server:").

The existing "include:" directive that was used in previous Debian releases
of the unbound package only performed textual inclusion, and it was possible
to construct a set of config file fragments that depended on the presence or
ordering of specific config file fragments in order to parse correctly. For
instance, a config file fragment could have specified an option that can
only appear in the "server:" clause, and rely on a previously included
config file fragment to begin that clause. This behavior is no longer
allowed by the use of the "include-toplevel:" directive because it is not
robust against config file fragments being added, removed, or reordered.

If you are upgrading the unbound package and you have installed any config
file fragments into /etc/unbound/unbound.conf.d/ you should check that each
config file fragment begins its own clause (e.g., "server:") and update each
config file fragment as necessary to be compatible with the behavior of the
"include-toplevel:" directive.

If needed, the previous behavior can be restored by changing the following
line in /etc/unbound/unbound.conf:

include-toplevel: "/etc/unbound/unbound.conf.d/*.conf"

to its previous setting:

include: "/etc/unbound/unbound.conf.d/*.conf"

-- Robert Edmonds <***@debian.org> Sun, 09 Aug 2020 19:39:01 -0400

[Justin B Rye]

Post by Robert Edmonds
During the bullseye release cycle the default /etc/unbound/unbound.conf
file was changed to use the newly introduced "include-toplevel:"
directive rather than the "include:" directive. This should probably be
mentioned in the bullseye release notes because it will break
configurations where the user added a clauseless config file fragment to
/etc/unbound/unbound.conf.d/.
The text from /usr/share/doc/unbound/NEWS.Debian.gz about this change is
quoted below.

For the Release Notes we ought to add some material: people reading
the NEWS file can be assumed to have chosen to install unbound, but
this version needs to start by making it clear what unbound is (and
that if you haven't heard of it you don't need to read the technical
details). Then after that we could squeeze things a bit:

<section id="unbound-config-file-handling">
<title>Config file fragment handling in unbound</title>
<para>
The DNS resolver <systemitem role="package">unbound</systemitem>
has changed the way it includes configuration file fragments.
Instead of using an <literal>include:</literal> directive to read
in files in <filename>/etc/unbound/unbound.conf.d/*.conf</filename>,
the default configuration file for Debian bullseye uses
<literal>include-toplevel:</literal>, which has extra requirements.
</para>
<para>
Instead of allowing fragments that need to be concatenated to form
valid configuration clauses, <literal>include-toplevel:</literal>
requires each one to begin its own clause (e.g.,
<literal>server:</literal>). If your system uses included fragments
you should ensure they will still be valid; if this is not possible
the previous behavior can be restored by editing
<filename>/etc/unbound/unbound.conf</filename> and switching the
<literal>include-toplevel:</literal> directive back to
<literal>include:</literal>.
</para>
</section>

Is that compressed too far? I was hoping to fit the word "robustness"
somewhere. Maybe a mention of unbound-checkconf?

[Andrei POPESCU]

Post by Justin B Rye

Post by Robert Edmonds
During the bullseye release cycle the default /etc/unbound/unbound.conf
file was changed to use the newly introduced "include-toplevel:"
directive rather than the "include:" directive. This should probably be
mentioned in the bullseye release notes because it will break
configurations where the user added a clauseless config file fragment to
/etc/unbound/unbound.conf.d/.
The text from /usr/share/doc/unbound/NEWS.Debian.gz about this change is
quoted below.

For the Release Notes we ought to add some material: people reading
the NEWS file can be assumed to have chosen to install unbound, but
this version needs to start by making it clear what unbound is (and
that if you haven't heard of it you don't need to read the technical

[snip two paragraphs]

Post by Justin B Rye
Is that compressed too far? I was hoping to fit the word "robustness"
somewhere. Maybe a mention of unbound-checkconf?

How about squeezing even further and pointing to the NEWS file instead
(for those that have unbound installed, but not apt-listchanges).

Kind regards,
Andrei

[Justin B Rye]

Post by Andrei POPESCU

Post by Justin B Rye

Post by Robert Edmonds
During the bullseye release cycle the default /etc/unbound/unbound.conf
file was changed to use the newly introduced "include-toplevel:"
directive rather than the "include:" directive. This should probably be
mentioned in the bullseye release notes because it will break
configurations where the user added a clauseless config file fragment to
/etc/unbound/unbound.conf.d/.
The text from /usr/share/doc/unbound/NEWS.Debian.gz about this change is
quoted below.

For the Release Notes we ought to add some material: people reading
the NEWS file can be assumed to have chosen to install unbound, but
this version needs to start by making it clear what unbound is (and
that if you haven't heard of it you don't need to read the technical

[snip two paragraphs]

Post by Justin B Rye
Is that compressed too far? I was hoping to fit the word "robustness"
somewhere. Maybe a mention of unbound-checkconf?

How about squeezing even further and pointing to the NEWS file instead
(for those that have unbound installed, but not apt-listchanges).

The problem is, that way the information they need to implement a fix
only arrives on their system as part of the process that breaks their
resolver. That's less of a disaster than if the solution was only
available online, but it still sounds annoying.

(Putting it on a Wiki page that they can read before the upgrade would
work, though.)

[Andrei POPESCU]

Post by Justin B Rye

Post by Andrei POPESCU
How about squeezing even further and pointing to the NEWS file instead
(for those that have unbound installed, but not apt-listchanges).

The problem is, that way the information they need to implement a fix
only arrives on their system as part of the process that breaks their
resolver. That's less of a disaster than if the solution was only
available online, but it still sounds annoying.

The NEWS file is also available online:

https://sources.debian.org/src/unbound/1.13.1-1/debian/NEWS/

Kind regards,
Andrei

[Justin B Rye]

Post by Andrei POPESCU
https://sources.debian.org/src/unbound/1.13.1-1/debian/NEWS/

That's a better idea than the alternative I was considering, which was
to point at this bug report. So we could cut it all the way down to
something like:

<section id="unbound-config-file-handling">
<title>Config file fragment handling in unbound</title>
<para>
The DNS resolver <systemitem role="package">unbound</systemitem>
has changed the way it handles configuration file fragments. If
you are relying on an <literal>include:</literal> directive to
merge several fragments into a valid configuration, you should
read <ulink
url="https://sources.debian.org/src/unbound/1.13.1-1/debian/NEWS/">the
NEWS file</ulink>.
</para>
</section>

[Andrei POPESCU]

Post by Justin B Rye

Post by Andrei POPESCU
https://sources.debian.org/src/unbound/1.13.1-1/debian/NEWS/

That's a better idea than the alternative I was considering, which was
to point at this bug report. So we could cut it all the way down to
<section id="unbound-config-file-handling">
<title>Config file fragment handling in unbound</title>
<para>
The DNS resolver <systemitem role="package">unbound</systemitem>
has changed the way it handles configuration file fragments. If
you are relying on an <literal>include:</literal> directive to
merge several fragments into a valid configuration, you should
read <ulink
url="https://sources.debian.org/src/unbound/1.13.1-1/debian/NEWS/">the
NEWS file</ulink>.
</para>
</section>

LGTM FWIW.

Kind regards,
Andrei

[Paul Gevers]

Hi,

Post by Justin B Rye

Post by Andrei POPESCU
https://sources.debian.org/src/unbound/1.13.1-1/debian/NEWS/

That's a better idea than the alternative I was considering, which was
to point at this bug report. So we could cut it all the way down to
<section id="unbound-config-file-handling">
<title>Config file fragment handling in unbound</title>
<para>
The DNS resolver <systemitem role="package">unbound</systemitem>
has changed the way it handles configuration file fragments. If
you are relying on an <literal>include:</literal> directive to
merge several fragments into a valid configuration, you should
read <ulink
url="https://sources.debian.org/src/unbound/1.13.1-1/debian/NEWS/">the

To be slightly more robust, should we replace 1.13.1-1 with bullseye?
https://sources.debian.org/src/unbound/bullseye/debian/NEWS/ seems to
work as intended.

Post by Justin B Rye
NEWS file</ulink>.
</para>
</section>

Paul

[Justin B Rye]

Post by Paul Gevers

Post by Justin B Rye
<section id="unbound-config-file-handling">
<title>Config file fragment handling in unbound</title>
<para>
The DNS resolver <systemitem role="package">unbound</systemitem>
has changed the way it handles configuration file fragments. If
you are relying on an <literal>include:</literal> directive to
merge several fragments into a valid configuration, you should
read <ulink
url="https://sources.debian.org/src/unbound/1.13.1-1/debian/NEWS/">the

To be slightly more robust, should we replace 1.13.1-1 with bullseye?
https://sources.debian.org/src/unbound/bullseye/debian/NEWS/ seems to
work as intended.

Good idea!

[Debian Bug Tracking System]

Your message dated Wed, 24 Mar 2021 19:51:39 +0100
with message-id <68cd497b-3b16-97ea-ac88-***@debian.org>
and subject line Re: Bug#985616: Document change to unbound ".d" config file fragment behavior
has caused the Debian Bug report #985616,
regarding Document change to unbound ".d" config file fragment behavior
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact ***@bugs.debian.org
immediately.)