Fix systemd-networkd-wait-online Service Timing Out During Boot

https://www.baeldung.com/linux/systemd-networkd-wait-online-service-timeout-solution

1. Overview

The boot process is a critical phase for initializing system services, but it shouldn’t take an excessively long time to complete. Yet, the systemd-networkd-wait-online service can sometimes cause this process to hang, timing out while it waits for the network to be fully configured.

In this tutorial, we’ll explore the common issue of the systemd-networkd-wait-online service timing out during boot, its causes, and most importantly, its solutions.

2. What Does systemd-networkd-wait-online Do?

*systemd-networkd-wait-online* operates as a *oneshot* service, meaning it runs once during boot and then exits. Specifically, it delays reaching the network-online.target, a synchronization point for other services that need the network.

Simply put *systemd-networkd-wait-online* acts as a gatekeeper, ensuring that the network is fully operational before other network-dependent services can start. Once the network is ready, this service signals the all-clear to other services that rely on network connectivity. It does this by waiting for a signal from systemd-networkd via DBus, indicating that all network profiles have either been activated or are in a disconnected state. This is helpful as it prevents premature service startup, avoiding potential issues.

systemd-networkd-wait-online can be important, particularly for systems that rely on network connectivity for mounting remote files or connecting to network-dependent applications upon startup.

3. Understand the Reasons Behind Timeouts

Let’s take a quick look at why this problem can happen. Understanding why *systemd-networkd-wait-online* times out helps us pinpoint the root cause, enabling a more targeted fix instead of attempting solutions ad-hoc.

To begin with, we can list some usual suspects:

network configuration issues: since the service waits for all network interfaces to be online, a misconfigured or slow interface can lead to a timeout (common in environments with multiple network devices)
service dependencies: certain services, such as the configuration of /etc/fstab (CIFS or NFS shares), depend on the network being fully up before they can proceed
conflicts with other networking stacks: if two network-managing services try to control the same interface without proper coordination, it can prevent the interface from getting configured in time

Common to all these scenarios is the fact that if the network is not ready, systemd-networkd-wait-online holds up the boot process and causes timeouts.

Let’s look at how to work around this issue.

4. Use One Network Management Service

Most contemporary Linux systems typically use either systemd-networkd or NetworkManager. Having both enabled can lead to timeouts, as both *NetworkManager-wait-online.service* and *systemd-networkd-wait-online.service* wait for the network to be up.
We can check which one is active using the systemctl command:

systemctl is-enabled systemd-networkd-wait-online.service NetworkManager-wait-online.service
## enabled
## enabled

In this case, it looks like the system has both services enabled. So, the next step is to disable one network service. Which one we choose depends on the one that’s actually managing the existing network interfaces.

If NetworkManager is the default network stack (common on desktop systems), we can safely disable *systemd-networkd* along with its wait service:

systemctl disable systemd-networkd.service

By now, running the systemctl is-enabled command should show that systemd-networkd-wait-online.service is disabled, resolving the boot hang issue.

5. Modify the Wait Service Behavior

By default, the systemd-networkd-wait-online service waits up to two minutes for all network interfaces to connect. However, we can adjust its behavior in multiple ways to suit different needs.

5.1. Wait for Any Interface

Let’s start by configuring the service to wait for the first network interface to connect, instead of all interfaces. To do this, we can just modify its unit file with systemctl edit:

sudo systemctl edit systemd-networkd-wait-online.service

After opening the configuration, let’s add an extra non-specified ExecStart= directive, and then update the specified ExecStart= to include the –any option:

[Service]
ExecStart=
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --any

After closing, the system reloads the configuration automatically, so there’s no need to execute *systemctl daemon-reload*. Ultimately, this should enable the service to proceed once any interface is configured.

Why use *ExecStart=* twice? We add ExecStart= with no value to clear any existing entry in the main service file configuration. To clarify, systemctl edit creates an override file meant to extend the main service configuration (located in /etc/systemd/system). Without clearing the existing ExecStart= directive (or any other directive), systemd appends the new configuration to the original, rather than replacing it. Inevitably, this can lead to multiple ExecStart= values, which can cause conflicts or errors.

As an aside, we can still edit the main service file directly with the –full option, but this method is generally avoided.

5.2. Wait for Specific Interfaces

Instead of waiting for the first random interface to come online, we can specify which one to wait for. To do so, we can use the *–interface* option in the unit configuration:

[Service]
ExecStart=
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --interface=eth0

Here, the service focuses solely on eth0, disregarding the status of other network interfaces. This can be useful in scenarios where a specific network connection is critical to the system’s functionality.

5.3. Ignore a Specific Interface

Conversely, we may want to ignore a specific interface during the network-wait process.

So, let’s add –ignore coupled with the interface name to the ExecStart= entry:

...
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --ignore=enp33s0f0
...

During the next boot, the service should bypass waiting for enp33s0f0 to be configured. This can speed up boot times if the ignored interface is causing the issue or doesn’t connect immediately.

5.4. Adjust Timeout

Rather than waiting for two minutes to time out, we can simply reduce the waiting period.

Same as before, let’s first access the service file and add the TimeoutSec= directive, setting it to, say, 10 seconds:

[Service] 
ExecStart= 
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online
TimeoutSec=10

Another way is to add the –timeout option to the main command:

...
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --timeout=10
...

Both methods ensure the service waits only *10* seconds rather than the default *120* seconds.

6. Configure Network Profiles for systemd-networkd

The systemd-networkd service stores network configuration files in /etc/systemd/network/. Naturally, this enables tweaking these files to control how *systemd-networkd-wait-online* behaves through individual interface settings. So, instead of changing the service file directly, we can set directives like RequiredForOnline to exclude specific interfaces from the waiting process.

For instance, let’s look at an interface named enp0s31f6:

nano /etc/systemd/network/enp33s0f0.network
...
[Link]
RequiredForOnline=no
...

By setting RequiredForOnline to no, we instruct the wait service that enp33s0f0 doesn’t need to be online for the system to continue booting.

7. Configure Netplan

Netplan provides a convenient way to exclude interfaces during the systemd-networkd-wait-online process. We can mark non-essential interfaces as optional in the working configuration file.

Let’s modify the working Netplan configuration profile, for example /etc/netplan/33-netcfg.yaml, and then add the optional: true setting to the relevant interfaces:

network:
  version: 2
  renderer: networkd
  ethernets:
    enp11s0f0:
      dhcp4: no
    enp22s0f0:
      dhcp4: no
      optional: true
    enp33s0f0:
      dhcp4: no
      optional: true

In this snippet, we mark enp22s0f0 and enp33s0f0 as optional.

After saving the file, let’s apply the changes:

sudo netplan apply

During the next boot, the system shouldn’t wait for enp22s0f0 and enp33s0f0 to configure.

Same as before, this method is useful for interfaces that take a long time to initialize or may not always be connected

8. Disable systemd-networkd-wait-online

If none of the previous solutions work, we can simply disable the systemd-networkd-wait-online service entirely. While this service ensures that network-dependent processes start correctly, there are cases when bypassing it may be necessary.

Let’s use the systemctl disable command to stop the wait service from starting during boot.

sudo systemctl disable systemd-networkd-wait-online.service

Notably, disabling the service may sometimes not be effective as other services could trigger it to start. So, to fully prevent it from working, we can use the systemctl mask command:

sudo systemctl mask systemd-networkd-wait-online.service

This command creates a symbolic link from the service unit file to /dev/null, which makes it impossible to start, even manually. Conversely, we can reverse this effect with systemctl unmask.

9. Conclusion

In this article, we explored the common causes behind the systemd-networkd-wait-online service timing out during boot and detailed various methods to resolve or work around such issues. Specifically, we covered solutions ranging from modifying the wait service behavior to configuring interface settings and disabling the service entirely if necessary.

In conclusion, what causes systemd-networkd-wait-online to timeout can be complex and dependent on different factors. However, there are multiple workarounds to prevent it from delaying the boot process. So, in most cases, users should be able to find an effective fix without much difficulty.