How to Configure Network Online Detection in Ubuntu Using systemd-networkd-wait-online

In modern Ubuntu installations utilizing systemd-networkd or Netplan, system services that require outbound network connectivity—such as database clusters, cloud synchronization agents, time synchronisation daemons, and configuration management runners—order themselves after network-online.target. To determine when the network stack has transitioned from an unconfigured state to an active, routable state, systemd relies on the helper binary systemd-networkd-wait-online. However, on multi-NIC workstations, virtual machines with unplugged secondary adapters, or servers awaiting dynamic DHCP responses, the default configuration waits indefinitely for all managed interfaces to reach fully routable status, causing notorious 120-second boot stalls. Understanding how to configure, tune, and constrain systemd-networkd-wait-online ensures fast server boot cycles while maintaining reliable network dependencies.

How systemd-networkd-wait-online Evaluates Link Operational States

The systemd-networkd-wait-online.service unit executes a dedicated binary that polls the operational state of local network interfaces via the kernel Netlink interface and systemd-networkd internal DBus states. Interfaces transition through a sequence of operational levels (operstates):

  • missing / off: The network device is absent or administratively shut down.
  • no-carrier: Physical Ethernet cable is disconnected or Wi-Fi radio is disassociated.
  • carrier: Physical Layer 1 signal detected, but no Layer 2/3 negotiation has occurred.
  • degraded: The interface has obtained an IPv4 link-local address (169.254.x.x) or IPv6 link-local address (fe80::) but lacks a routable global IP.
  • routable: The interface has negotiated a valid IPv4 or IPv6 address and holds an active default gateway route in the kernel routing table.

By default, systemd-networkd-wait-online enforces two problematic defaults: it requires every managed network device to reach the degraded or routable state, and it enforces a generous default timeout of 120 seconds before giving up.

Auditing Current Interface Operational States with networkctl

Before adjusting wait-online parameters, inspect the real-time operational states and setup statuses of all network adapters on your Ubuntu system:

# Check the operational state of all network links
networkctl list

# Inspect detailed status and online requirements for a specific link
networkctl status eth0

In the output, review the OPERATIONAL and REQUIRED FOR ONLINE fields. If a disconnected secondary interface (e.g. eth1) displays no-carrier while marked as required for online, that interface is causing boot delays.

Tuning systemd-networkd-wait-online via Service Drop-In Overrides

The recommended approach to alter wait-online behaviour is creating a declarative systemd drop-in file rather than modifying distribution unit files directly:

# Create a systemd drop-in override for the wait-online service
sudo systemctl edit systemd-networkd-wait-online.service

Inside the editor, add the [Service] section. First, clear the default ExecStart= directive by declaring an empty assignment, then specify custom operational criteria:

[Service]
ExecStart=
ExecStart=/lib/systemd/systemd-networkd-wait-online --interface=eth0 --operational-state=routable --timeout=15

Evaluate the flags utilized in this tuning configuration:

  • --interface=eth0 (or -i): Explicitly restricts the wait condition to the primary uplink interface, ignoring secondary disconnected interfaces or virtualization bridges.
  • --any: Instructs the binary to unblock the boot sequence as soon as at least one interface reaches online status, rather than waiting for all interfaces.
  • --operational-state=routable (or -o): Ensures the interface holds a valid default gateway route before downstream services spawn.
  • --timeout=15: Caps the maximum wait duration to 15 seconds, preventing a 2-minute server boot delay if DHCP is temporarily unreachable.

Configuring RequiredForOnline Declaratively in Netplan

On modern Ubuntu releases, Netplan allows administrators to declare whether an interface is required for system boot directly within YAML network configurations (/etc/netplan/*.yaml):

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: true
      # Primary interface is strictly required before network-online.target
      optional: false
    eth1:
      dhcp4: true
      # Secondary interface will not hold up boot if unplugged
      optional: true

Setting optional: true instructs Netplan to configure RequiredForOnline=no within the generated systemd-networkd configuration under /run/systemd/network/, automatically excluding that interface from systemd-networkd-wait-online checks.

Testing Configuration and Measuring Boot Impact

After applying drop-ins or Netplan configurations, reload the systemd daemon and test the wait-online command interactively in the terminal:

# Reload systemd unit definitions
sudo systemctl daemon-reload

# Apply Netplan changes if modified
sudo netplan apply

# Test the wait-online binary interactively
/lib/systemd/systemd-networkd-wait-online --interface=eth0 --timeout=5

If the command exits immediately with return code 0, your network online detection is configured properly. Verify system boot performance using systemd-analyze blame to confirm that systemd-networkd-wait-online.service no longer introduces multi-minute boot latency.

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.