Skip to content

Update lazy connection docs for NB_LAZY_CONN #821

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lixmal wants to merge 1 commit into
base: main
Choose a base branch
from
+7 −18
Open

Update lazy connection docs for NB_LAZY_CONN #821

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/pages/client/environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ To clear all saved service parameters (including env vars), run `sudo netbird se
| `NB_ICE_FAILED_TIMEOUT_SEC` | All | Seconds of silence before ICE gives up on the connection entirely and falls back to relay (default: `6`). |
| `NB_ICE_RELAY_ACCEPTANCE_MIN_WAIT_SEC` | All | Minimum seconds ICE waits for a direct (P2P) candidate before accepting a relay candidate. Higher values give direct connections more time to succeed at the cost of slower initial connection (default: `2`). |
| `NB_ICE_MONITOR_PERIOD` | All | Interval between ICE connection health checks that verify handshake freshness and trigger reconnection if needed (Go duration, default: `5m`). |
| `NB_ENABLE_EXPERIMENTAL_LAZY_CONN` | All | Open WireGuard tunnels to peers only when traffic is detected, instead of connecting to all peers at startup. Same effect as the `--enable-lazy-connection` CLI flag. |
| `NB_LAZY_CONN` | All | Local override for the lazy connection feature, which opens WireGuard tunnels to peers only when traffic is detected. `on` forces it enabled, `off` forces it disabled, unset defers to the management setting. Overrides the management configuration in both directions. Replaces the removed `NB_ENABLE_EXPERIMENTAL_LAZY_CONN`. |
| `NB_LAZY_CONN_INACTIVITY_THRESHOLD` | All | How long a lazy connection can be idle before it is torn down (Go duration, default: `15m`). Only applies when lazy connections are enabled. |

## DNS
Expand Down
23 changes: 6 additions & 17 deletions src/pages/manage/peers/lazy-connection.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,29 +42,18 @@ Once a connection between two peers is established, it will remain open only if
The default inactivity threshold is <strong>60 minutes</strong>, and can be configured via the <code>NB_LAZY_CONN_INACTIVITY_THRESHOLD</code> environment variable (`60`).
</Note>
Comment on lines 42 to 43

@coderabbitai coderabbitai Bot Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify the correct default for lazy connection inactivity threshold.

# Search for the default value in source code or other docs
rg -n 'LAZY_CONN_INACTIVITY_THRESHOLD' --type=go --type=md --type=mdx -C 2

Repository: netbirdio/docs

Length of output: 180

Align the inactivity threshold with the rest of the docs.
This note says the default is 60 minutes / 60, but src/pages/client/environment-variables.mdx uses 15m for NB_LAZY_CONN_INACTIVITY_THRESHOLD. Update this to match the actual default.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/pages/manage/peers/lazy-connection.mdx` around lines 42 - 43, The lazy
connection inactivity threshold documentation is inconsistent with the
environment variable reference, so update the copy in the lazy-connection page
to match the actual default used for NB_LAZY_CONN_INACTIVITY_THRESHOLD. Adjust
the note around the inactivity threshold text in that MDX file so it aligns with
the value documented in the environment variables page, keeping the same symbols
and wording style already used there.


## Enabling via the system tray
## Overriding Lazy Connections on the agent

You can toggle Lazy Connections directly from the NetBird system tray:

1. Click the NetBird icon in the system tray.
2. Go to **Settings**.
3. Click **Enable Lazy Connections** to toggle the setting.

## Enabling Lazy Connections on agent

Lazy connections are disabled by default. You can enable Lazy Connections using the following environment variable:
Whether lazy connections are enabled is controlled by your management settings (see the Dashboard section below). You can override that decision locally on an agent with the `NB_LAZY_CONN` environment variable:

```bash
export NB_ENABLE_EXPERIMENTAL_LAZY_CONN=true
export NB_LAZY_CONN=on # force enabled
export NB_LAZY_CONN=off # force disabled
```

Or pass the flag directly via the CLI when running the agent:

```bash
netbird up --enable-lazy-connection
```
Both `on` and `off` override the management setting; leave the variable unset to defer to management. On managed devices, the same override can be applied through an MDM policy using the `lazyConnection` key (`on` / `off`).
<Note>
This configuration is <strong>not persistent</strong>. You must reapply the flag or environment variable after each restart unless it is built into your service definition (e.g., systemd or Docker).
The environment variable is <strong>not persistent</strong>. You must reapply it after each restart unless it is built into your service definition (e.g., systemd or Docker).
</Note>

## Enabling Lazy Connections in the NetBird Dashboard
Expand Down
Loading