some file

Lazy Connections

Updated

Lazy connections reduce resource use in large NetBird networks by opening peer connections only when traffic needs them, rather than maintaining every possible full-mesh connection continuously.

Lazy connections require NetBird v0.50.1 or later on the client, the peers it communicates with, and self-hosted Management and Signal servers.

How Lazy Connections Work

When lazy connections are enabled, the client:

  • Starts a connection to a peer when traffic is sent to it, or when the remote peer signals a connection attempt.
  • Tears down an established peer connection after it has been idle for the configured inactivity threshold. Idle detection runs on clients using userspace WireGuard; a client running kernel WireGuard relies on the remote peer to detect inactivity and close the connection.
  • Keeps routing peers in the same high-availability group awake together while any one of them is active, so failover targets stay usable.
  • Keeps peers used for ingress forwarding connected so forwarding targets remain reachable.
  • Opens permanent connections to peers whose client version does not support lazy connections.
  • Reopens all applicable peer connections when lazy connections are disabled.

The default inactivity threshold is 15m. Change it with NB_LAZY_CONN_INACTIVITY_THRESHOLD, using a Go duration such as 30m or 1h. The minimum is 1m; shorter or invalid values fall back to the default.

The first request to an idle peer can take slightly longer while NetBird establishes the connection. Since NetBird v0.74.0, the packet that triggers the connection is delivered once the connection is up instead of being dropped.

DNS warm-up

When the local NetBird resolver answers with two or more A or AAAA records that point at idle peers, it wakes those peers before the application sends its first packet. The answer waits up to two seconds by default for one of them to connect, so the first request does not race the connection.

Warm-up only applies to names in custom DNS zones and in the zones NetBird creates for private services. A name with a single record does not trigger it, and neither does a peer's own name, such as peer-a.netbird.cloud. Peer names are excluded on purpose: otherwise every lookup would wake idle connections across the network.

Set NB_DNS_LAZY_WARMUP_TIMEOUT on the daemon to change this per-query wait. The value must be a positive Go duration, for example 5s. Invalid, zero, or negative values fall back to the 2s default.

Enable Lazy Connections in Management

The account setting in the NetBird Dashboard is the normal source of truth: go to Settings > Clients and turn on the Enable Lazy Connections toggle. When it is enabled, compatible clients activate their lazy connection manager. When it is disabled, clients stop lazy mode and immediately attempt to connect to all applicable peers.

Accounts created on NetBird v0.74.0 or later have lazy connections enabled by default. Accounts created before that keep the setting disabled until an administrator turns it on.

Existing active connections are not interrupted merely because lazy mode is enabled. They become eligible for teardown after the inactivity threshold.

Clients with Rosenpass post-quantum cryptography enabled do not start the lazy connection manager and keep permanent connections regardless of this setting.

Override the Management Setting on a Client

Set NB_LAZY_CONN on the NetBird daemon when one client must override the account setting:

# Force lazy connections on
sudo netbird service reconfigure --service-env NB_LAZY_CONN=on

# Force lazy connections off
sudo netbird service reconfigure --service-env NB_LAZY_CONN=off

on and off override Management in both directions; boolean values such as true/false or 1/0 are also accepted. Leave the variable unset to follow the Management setting. Any other value logs a warning and is treated as unset. See Client Environment Variables for service configuration details.

On MDM-managed clients, the boolean lazyConnection policy key provides the same local override: true forces lazy connections on, false forces them off, and an absent key defers to Management. If both are configured, NB_LAZY_CONN takes precedence over MDM.

To check a peer, run netbird status on it. The Lazy connection line shows whether lazy connections are on for that peer, with any override applied.

NetBird v0.74.1 removed the Enable Lazy Connections checkbox from the desktop client's Settings menu and made the netbird up --enable-lazy-connection flag inert; the flag now only prints a deprecation warning. Both could turn lazy connections on, but neither could turn them off once Management had enabled them. NB_LAZY_CONN replaces both. The deprecated NB_ENABLE_EXPERIMENTAL_LAZY_CONN variable is no longer used.

Each peer decides for its own connections

Whether it comes from Management or from NB_LAZY_CONN, the setting only controls the peer it applies to. A peer with lazy connections off connects to every peer your policies let it reach, and a lazy peer accepts that connection when asked. So turning lazy connections on for a routing peer does not make the devices that use it lazy.

An unused connection only stays closed when both of its ends are lazy. If only one end is lazy, that end closes the connection after the inactivity threshold, the other end reopens it shortly afterwards, and the cycle repeats. This is also what happens between every lazy peer and a peer you opt out with NB_LAZY_CONN=off while the account has lazy connections on. Keep two limits in mind:

  • For a few seconds after each close, the non-lazy end still treats the connection as up, and traffic it sends in that window is dropped.
  • A lazy peer running kernel WireGuard does not detect idle connections itself, so its connection to a non-lazy peer stays up instead of cycling.

Try lazy connections on a few peers

To try lazy connections before turning them on for the whole account, leave the Management setting off and set NB_LAZY_CONN=on on every peer in the test, for example two peers that talk to each other:

# On both peers
sudo netbird service reconfigure --service-env NB_LAZY_CONN=on

The connection between the two then opens on demand and closes after the inactivity threshold. Their connections to other peers keep closing and reopening, as described above, because the other end is not lazy. When the test is over, turn the Management setting on or remove NB_LAZY_CONN from the test peers.

Get started