Use nm-online to Gate Work on NetworkManager Connectivity

You will finish with a small, testable way to wait for NetworkManager to report an active connection, use the result in a shell script, and choose deliberately between connectivity and NetworkManager startup. The examples use NetworkManager 1.46.0, installed here as Debian package network-manager 1.46.0-1ubuntu2.8.

Allow about ten minutes. You need a shell, NetworkManager and the nm-online command. This guide only observes connection state. It does not bring an interface up, change connection profiles or restart NetworkManager, so no elevated privileges are normally needed.

1. Check the installed command

Confirm which executable and package version you are using. These are ordinary read-only commands:

$ command -v nm-online
/usr/bin/nm-online
$ dpkg-query -W -f='${Package} ${Version}\n' network-manager
network-manager 1.46.0-1ubuntu2.8
$ nm-online --help
Usage:
  nm-online [OPTION...]

Waits for NetworkManager to finish activating startup network connections.

The installed help also reports a maximum timeout of 2,073,600 seconds. The guide uses much shorter values. The local manual page identifies the source as NetworkManager 1.46.0, so check the installed help if you are applying these examples to another release.

2. Wait for an active connection

Run nm-online with its default behaviour when the next command genuinely needs NetworkManager to report an active connection:

$ nm-online
Connecting... [offline]

The progress line is rewritten while the command waits, so the exact display varies with the terminal and connection state. On success, the command returns status 0. It waits for a connection for 30 seconds by default. The printed text is not the interface your script should parse.

Use a shorter timeout for an interactive check or a bounded pre-flight step:

$ nm-online --quiet --timeout=5
$ printf 'nm-online status: %s\n' "$?"
nm-online status: 0

The result above means NetworkManager reported a connection within five seconds. If the host is offline or the timeout expires, the status is 1. A status of 2 means an unknown or unspecified error. Keep those cases visible instead of allowing later commands to fail with a less useful message.

3. Put the status check in a script

Capture the status immediately, then branch on it. --quiet keeps normal operation free of diagnostic output:

if nm-online --quiet --timeout=15; then
    printf '%s\n' 'NetworkManager reports an active connection'
    /path/to/network-dependent-command
else
    status=$?
    case "$status" in
        1) printf '%s\n' 'No active connection within 15 seconds' >&2 ;;
        2) printf '%s\n' 'nm-online reported an unspecified error' >&2 ;;
        *) printf 'nm-online failed with status %s\n' "$status" >&2 ;;
    esac
    exit "$status"
fi

Replace /path/to/network-dependent-command with the real command. The example returns the check's non-zero status, which makes a calling service or job notice the failure. It does not retry indefinitely and it does not claim that a connected host can reach a particular server.

$ nm-online --quiet --timeout=1
$ printf 'nm-online status: %s\n' "$?"
nm-online status: 1

Your result will be 0 if a connection is already active. That is still a valid test of the command, but it does not exercise the timeout branch.

4. Understand the timeout setting

The --timeout option takes seconds. If you omit it, nm-online honours the NM_ONLINE_TIMEOUT environment variable, then falls back to 30 seconds. A command-line value is clearer in a script because it is visible beside the check:

$ NM_ONLINE_TIMEOUT=2 nm-online --quiet
$ printf 'status: %s\n' "$?"
status: 1

This environment assignment affects only that invocation. It does not change NetworkManager's configuration and it does not persist after the shell command finishes. Do not set a large timeout merely to hide a disconnected host: a job that needs a usable network should also handle DNS, routing and the remote service failing after this check succeeds.

5. Choose startup mode only for boot ordering

--wait-for-startup, or -s, answers a different question. It waits for NetworkManager startup to complete after it has activated, or attempted to activate, available auto-activate connections. It does not specifically prove that the network is currently connected. Once startup has completed, nm-online -s can return immediately even if the network is later unavailable.

$ nm-online --wait-for-startup --quiet --timeout=30
$ printf 'startup status: %s\n' "$?"
startup status: 0

Use this mode when coordinating boot-time ordering. Use the default mode for a command that needs NetworkManager to report an active connection now. Mixing these meanings is a common trap: a successful startup check is not a connectivity guarantee.

The command is used by NetworkManager-wait-online.service with --wait-for-startup. If a boot target is taking too long, investigate that service and the connection profiles rather than adding an unbounded nm-online call to an unrelated script.

6. Know what online means here

nm-online asks NetworkManager about its status. It does not make an HTTP request, resolve a chosen hostname or verify that an application endpoint is reachable. Treat status 0 as "NetworkManager has an active connection", not as proof that an external service will accept the next request.

By default, NetworkManager can consider a connection activated when either IPv4 or IPv6 completes, because both ipv4.may-fail and ipv6.may-fail normally allow the other family to fail. If a boot workflow specifically requires one address family, configure that connection's corresponding may-fail property deliberately. That is a persistent network configuration change, so do not make it as part of a diagnostic check and do not use sudo unless you have decided exactly which profile should change.

7. Diagnose a failed check safely

1. Run the check again with --quiet and record the exit status immediately.
2. Ask NetworkManager for its view with nmcli general status and inspect the active connections with nmcli connection show --active. These are read-only diagnostics.
3. Check whether the timeout is simply too short for the host's normal activation time. Increase it only when the delay is expected and bounded.
4. Test the actual dependency separately, such as DNS or the remote endpoint. A successful nm-online result does not replace that test.

If NetworkManager itself is not running or is still connecting, --exit returns immediately rather than waiting. Use it when a caller needs a fast status check and has its own retry or recovery policy:

$ nm-online --exit --quiet
$ printf 'immediate status: %s\n' "$?"
immediate status: 1

There is no undo operation for any command in this guide. The commands only read state or set an environment variable for one process. Leave connection-profile edits and service restarts to a separate, reviewed change.