Unbound starts too early. Please add `Wants=network-online.target` under `[Unit]` in `unbound.service`

[barrelrider-ops]

Describe the bug
Unbound starts before the network interface gains carrier. On my system this caused the following errors:
Aug 21 13:55:55 arch unbound[453]: [453:0] error: failed to connect to redis server: Network is unreachable
Aug 21 13:55:55 arch unbound[453]: [453:0] error: redis_init: failed to init redis (for thread 0)

To reproduce
Steps to reproduce the behavior:

1. Use unbound.service from https://github.com/NLnetLabs/unbound/blob/master/contrib/unbound.service.in.

2. I am using systemd-networkd. However, I think this behavior can be reproduced with other network managers too. In my /etc/systemd/network/*.network file, I added the following lines:
   [Link]
RequiredForOnline=routable
   This ensures that the network is actually routable before the network is flagged as online.

3. Configure Redis in unbound.conf, so it uses an external database for cachedb. The following lines in my unbound.conf are related to Redis:
   module-config: "respip validator cachedb iterator"
cachedb:
backend: "redis"
cachedb-check-when-serve-expired: yes
redis-server-host: 100.64.1.2
redis-server-port: 6458
redis-expire-records: no
redis-replica-server-port: 6621
redis-replica-server-path: "run/valkey/valkey.sock"
   100.64.1.2 is a local ip-address of another computer.

4. Make sure there are no other applications with a (weak) requirement dependency on network-online.target. In other words, make sure that systemctl list-dependencies --reverse network-online.target doesn't list any dependencies or only lists dependencies that are not triggered on boot. On my system, systemctl list-dependencies --reverse network-online.target lists archlinux-keyring-wkd-sync.service as a dependency, but archlinux-keyring-wkd-sync.service is triggered by a timer and is not triggered on boot.

5. This means that network-online.target will not get started at all because the line After=network-online.target in unbound.service only defines an ordering dependency. It will not actually try to start network-online.target. This causes unbound to start too early. The following lines in the logs back my claim:

Aug 21 13:55:55 arch unbound[453]: [453:0] error: failed to connect to redis server: Network is unreachable
Aug 21 13:55:55 arch unbound[453]: [453:0] error: redis_init: failed to init redis (for thread 0)
Aug 21 13:55:56 arch systemd-networkd[397]: enp5s0: Gained carrier

Expected behavior
Unbound should always start after the network gains carrier.

You can easily achieve this by setting a weak requirement dependency on network-online.target for Unbound. Currently, it only relies on an ordering dependency (After=network-online.target). An ordering dependency doesn't actually trigger the dependency to start. This is where a (weak) requirement dependency comes in. In other words, please add Wants=network-online.target under [Unit] in unbound.service.

System:

• Unbound version: 1.23.1
• OS: Arch Linux
• unbound -V output:
  Version 1.23.1

Configure line: --prefix=/usr --sysconfdir=/etc --localstatedir=/var --sbindir=/usr/bin --disable-rpath --enable-dnscrypt --enable-dnstap --enable-pie --enable-relro-now --enable-subnet --enable-systemd --enable-tfo-client --enable-tfo-server --enable-cachedb --with-libhiredis --with-conf-file=/etc/unbound/unbound.conf --with-pidfile=/run/unbound.pid --with-rootkey-file=/etc/trusted-key.key --with-libevent --with-libnghttp2 --with-pyunbound
Linked libs: libevent 2.1.12-stable (it uses epoll), OpenSSL 3.5.2 5 Aug 2025
Linked modules: dns64 cachedb subnetcache respip validator iterator
DNSCrypt feature available
TCP Fastopen feature available

BSD licensed, see LICENSE in source package for details.
Report bugs to unbound-bugs@nlnetlabs.nl or https://github.com/NLnetLabs/unbound/issues

Additional information
One more remark related to systemd-networkd. I also needed to add the following lines to /etc/systemd/network/*.network:

[Link]
RequiredForOnline=routable

Without these lines, the network is flagged as online before the network is routable. This will cause the same error: error: failed to connect to redis server: Network is unreachable.

[wcawijngaards]

The change makes the described edit and adds a Wants= line. The file in addition has a small comment to describe the reduction of Network is unreachable errors.

Thank you for the contrib service file fix! That should help with start up. If redis is not used, I guess that mostly unbound waits for queries, and only then uses the network to make queries, and UDP queries retry after a timeout, and then the network has come online.

[barrelrider-ops]

Thanks for the quick fix!

I made a small mistake in my issue report (I already edited it) which propagated into your comment in the commit. I said that I needed to add the following lines to /etc/systemd/system/*.network:

[Link]
RequiredForOnline=routable

However, the location of the file is wrong. It is not /etc/systemd/system/*.network. It should be /etc/systemd/network/*.network. Please, change /etc/systemd/system/*.network to /etc/systemd/network/*.network in your comment in the commit.

[wcawijngaards]

The commit fixes the path. It now refers to the fixed directory. Thanks for catching that!

[mjt0k]

Adding network-online.target as a requirement for a local (caching) nameserver seems very wrong to me. Name services is another syncronisation point during bootup, it is a requirement for other services. Imagine, for example, a notebook with wifi access, - does it mean that no login is possible if no wifi is around?

Also, network might go up and down, and its "online" status changes as well. Depending on network-online is almost always wrong.

Here, we should not depend on being online, but, - I think - we should be able to retry connecting to redis server. Again, imagine redis is run on another host: can we express order of hosts to go up and down? And currently, if redis server is down during startup of unbound, unbound will fail to start, possible making whole network of other computers without DNS. This seems wrong..

[wcawijngaards]

In 1.23.0, there is a fix, 5f3f214 . That makes it that upon startup, if the redis server does not work, it is not a problem any more. The server continues so start. The redis connection is reattempted later.

[Maryse47]

@wcawijngaards should ca36e21 be reverted then?

[gthess]

Not a systemd expert myself but I do think that Wants=network-online.target may be too radical.

For reference Debian and Fedora use Wants=nss-lookup.target instead.
systemd-resolved on my system also uses nss-lookup.target for Wants= and Before=.

So not reverting the previous commit but instead changing to Wants=nss-lookup.target seems like the better option here.

Any opinions?

[mjt0k]

nss-lookup.target is unrelated. It is not "instead", - it is something which should be used for any name serivce regardless of the status of the network. nss-lookup.target is a syncronisation point, it is described in man systemd.special. Both "Wants" and "Before" should be used.

[gthess]

Thanks for the reaction!
I meant instead as the value for "Wants" (Wants was not specified prior to this change), not instead of network-online.target.

But do you agree with replacing Wants=network-online.target with Wants=nss-lookup.target ?

[barrelrider-ops]

Adding network-online.target as a requirement for a local (caching) nameserver seems very wrong to me. Name services is another syncronisation point during bootup, it is a requirement for other services. Imagine, for example, a notebook with wifi access, - does it mean that no login is possible if no wifi is around?

Also, network might go up and down, and its "online" status changes as well. Depending on network-online is almost always wrong.

Here, we should not depend on being online, but, - I think - we should be able to retry connecting to redis server. Again, imagine redis is run on another host: can we express order of hosts to go up and down? And currently, if redis server is down during startup of unbound, unbound will fail to start, possible making whole network of other computers without DNS. This seems wrong..

Wants=network-online.target is a very weak requirement dependency. Its only action is to try to launch network-online.target when the system starts up. After booting, Wants=network-online.target does not do anything. In the event that network-online.target does fail to start, unbound will continue to start as expected. The activation of network-online.target is contingent upon the presence of a systemd unit that has a requirement dependency on it. If a systemd unit like that does not exist, systemd will completely skip starting network-online.target and will disregard the After=network-online.target directive. The inclusion of a weak requirement dependency ensures that systemd will always respect the After=network-online.target directive. To ensure that After=network-online.target functions correctly, it is necessary to include at least Wants=network-online.target.