Bug#985616: Document change to unbound ".d" config file fragment behavior
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
The text from /usr/share/doc/unbound/NEWS.Debian.gz about this change is
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
If needed, the previous behavior can be restored by changing the following
line in /etc/unbound/unbound.conf:
to its previous setting:
-- Robert Edmonds <firstname.lastname@example.org> Sun, 09 Aug 2020 19:39:01 -0400