What gateway-ping-timeout really waits for in NetworkManager

You find connection.gateway-ping-timeout in a thread about a laptop that comes up before the network is usable, you raise it, and something changes. Whether the change helped for the reason you think is a separate question. The answer starts with what the activation is actually doing while that timer runs, and with the fact that the wait has two possible endings.

Follow one connection from the command line and the semantics become concrete.

Follow one activation

Start by looking at the saved connection rather than at a global default, because this is a per-connection property. Add --show-secrets only if you actually need it; the setting itself is not a secret.

nmcli -f connection.id,connection.gateway-ping-timeout connection show
nmcli connection show "Wired connection 1" | grep gateway-ping

With the property at zero, which is the documented default, activation moves on as soon as addressing completes. Set it to a positive value and the activation of IP configuration waits until either a reply arrives from the gateway or the timeout expires.

Then bring the connection down and up while watching the event stream. The ordering you see is the setting doing its work: device state, addressing, the wait, and finally the activated state that dependent services are usually ordered against.

The wait has two endings

Both endings matter, and most people remember only one. A reply from the gateway finishes the wait early, and the timeout finishes it too, whether or not anything answered. The property does not require a successful ping before activation can complete.

That single sentence clears up a lot of confusion about laptops at hotels and conference venues, where a captive portal often refuses ICMP until you log in. The connection still activates after the timeout expires; it simply does so later than it needed to, and every service ordered after the connection waits with it.

It is also not a liveness check. Nothing in the description starts pinging a gateway after the connection is up, and nothing disconnects an active profile because a later ping fails. If you need loss detection, that belongs to the protocol or tunnel owner, not to a property that ran once during activation.

Two objects, one setting

The wired base profile and a VPN profile are separate configuration objects, and setting the property on one does not affect the other. A VPN profile that names a base connection inherits none of its activation settings, which is why the value you changed can appear to have no effect on the thing you were watching.

nmcli -f NAME,UUID,TYPE connection show
nmcli connection show "Office VPN" | grep gateway-ping

Read the UUIDs rather than the names. Names get duplicated after a reinstall or a restored profile, and two connections with the same visible name will send you editing the wrong file while the real one stays unchanged.

The installed NetworkManager release matters too. Plugin behaviour and how a connection type maps this property onto its own activation steps vary, so test on the version you deploy instead of assuming a post you found applies unchanged.

What the wait cannot certify

Here is the part that costs the most time. A reply from the local router proves that one host answered one ICMP echo during activation. It does not prove that a VPN endpoint resolves, that the client's identity is accepted, that private routes were installed, that the office resolver answers, or that the application you care about will work.

Those are separate dependencies with separate evidence. A gateway can answer while DNS is failing, and a gateway can silently drop ICMP by policy while every application path works. Gating on this property is therefore a guess about which layer is late, not a measurement of it.

If you are waiting on a dependent service, name what it needs. An assigned address is answered by addressing. A tunnel is answered by the tunnel's own state. A private name is answered by a query. An application is answered by the application, and none of those answers come from a timer that was named after the gateway.

If you change it, write down why

Record the previous value and the reason before an approved change, then set it on the specific connection rather than everywhere. A longer wait shifts activation timing for everything ordered after that connection, which can make a slow system look fine and a fast one look broken.

One historical trap is worth naming: a value like this sometimes gets changed to make an older editor accept a profile. If that is the real story, you have two events, not one. The editor saved, and a live network policy changed. Fix the editor or the plugin and put the timer back.

The NetworkManager source defines the property as a delay of IP-addressing success until a gateway reply or the timeout, with a default of zero, and the connection setting definition is the reference to read before relying on any behaviour described second-hand.