mirror of
https://github.com/netbirdio/docs.git
synced 2026-08-24 16:51:26 +02:00
Updates for the NetBird 0.75 update (#881)
This commit is contained in:
PizzaLovingNerd
Binary file not shown.
|
Before Width: | Height: | Size: 81 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 116 KiB After Width: | Height: | Size: 80 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 378 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 290 KiB After Width: | Height: | Size: 95 KiB |
@@ -77,6 +77,14 @@ That makes agent access a natural responsibility for IT.
|
||||
Because NetBird connects seamlessly with existing identity providers, IT teams can integrate NetBird Agent Network into
|
||||
their enterprise stack with minimal changes.
|
||||
|
||||
## Focused Dashboard View
|
||||
|
||||
Some accounts open directly into Agent Network, with the rest of the NetBird Dashboard—such as Peers, Networks, and DNS—hidden to keep the experience focused on agents. This is the default for accounts onboarded specifically for Agent Network.
|
||||
|
||||
To use the full NetBird platform, open **Settings** and turn off **Agent Network focused view**. You can re-enable it from the same setting at any time.
|
||||
|
||||
For API-managed accounts, `agent_network_only` requires `dashboard_features.agent_network` to be enabled. See the [Accounts API reference](/ipa/resources/accounts) for the account settings schema.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Quickstart](/agent-network/quickstart). Deploy NetBird Agent Network and make your first routed LLM call.
|
||||
|
||||
@@ -28,13 +28,11 @@ When Block Inbound Connections is enabled, the client will not add any inbound f
|
||||
This setting overrides all policies from the management service. Even if an access control policy explicitly allows traffic to this peer, inbound connections will still be blocked.
|
||||
</Note>
|
||||
|
||||
## Enabling via the system tray
|
||||
## Changing the setting in the desktop app
|
||||
|
||||
1. Click the NetBird icon in the system tray.
|
||||
2. Go to **Settings**.
|
||||
3. Click **Block Inbound Connections** to toggle the setting.
|
||||
|
||||
When enabled, a checkmark will appear next to the menu item.
|
||||
1. Open the NetBird desktop app.
|
||||
2. Go to **Settings → Security**.
|
||||
3. Toggle **Block Inbound Traffic**.
|
||||
|
||||
## Enabling via the CLI
|
||||
|
||||
@@ -49,7 +47,3 @@ To disable it, run:
|
||||
```bash
|
||||
netbird up --block-inbound=false
|
||||
```
|
||||
|
||||
<Note>
|
||||
When toggling this setting via the CLI, the system tray UI may not reflect the change until the NetBird GUI is restarted.
|
||||
</Note>
|
||||
|
||||
@@ -18,20 +18,20 @@ When Connect on Startup is **enabled** (default behavior):
|
||||
|
||||
When Connect on Startup is **disabled**:
|
||||
- The NetBird service starts but does not connect automatically.
|
||||
- You must manually run `netbird up` or use the system tray to connect.
|
||||
- You must manually run `netbird up` or click **Connect** in the desktop app or tray menu.
|
||||
- The peer remains offline until an explicit connection is initiated.
|
||||
|
||||
<Note>
|
||||
Whether the device successfully connects also depends on the <a href="/manage/settings/enforce-periodic-user-authentication">Peer Session Expiration</a> setting under Settings > Authentication. If the peer's session has expired, the user must reauthenticate before the peer can connect.
|
||||
</Note>
|
||||
|
||||
## Enabling via the system tray
|
||||
## Changing the setting in the desktop app
|
||||
|
||||
1. Click the NetBird icon in the system tray.
|
||||
2. Go to **Settings**.
|
||||
3. Click **Connect on Startup** to toggle the setting.
|
||||
1. Open the NetBird desktop app.
|
||||
2. Go to **Settings → General**.
|
||||
3. Toggle **Connect on Startup**.
|
||||
|
||||
When enabled, a checkmark will appear next to the menu item.
|
||||
This setting controls the background network connection. It is separate from **Launch NetBird UI at Login**, which controls only whether the graphical interface opens when you sign in to the operating system.
|
||||
|
||||
## Enabling via the CLI
|
||||
|
||||
@@ -46,7 +46,3 @@ To re-enable it:
|
||||
```bash
|
||||
netbird up --disable-auto-connect=false
|
||||
```
|
||||
|
||||
<Note>
|
||||
When toggling this setting via the CLI, the system tray UI may not reflect the change until the NetBird GUI is restarted.
|
||||
</Note>
|
||||
|
||||
@@ -4,11 +4,13 @@ export const description = "Overview of the redesigned NetBird desktop app: Defa
|
||||
|
||||
# NetBird Desktop App
|
||||
|
||||
<Note>
|
||||
The redesigned desktop app described on this page is currently available as a **release candidate**. Behavior and screenshots may change before the stable release. To try it, download the latest release candidate from [pkgs.netbird.io](https://pkgs.netbird.io/releases/rc).
|
||||
</Note>
|
||||
Starting with NetBird v0.75.0, the desktop app uses a [Wails](https://wails.io/) webview with a React frontend. The management server and wire protocol are unchanged, but the UI and agent need to be updated together. If their versions do not match, the app displays an update notification.
|
||||
|
||||
The NetBird desktop app has been rebuilt from the ground up. It runs on a [Wails](https://wails.io/) webview with a React frontend, while the Go backend that talks to the daemon stays the same. The management server and wire protocol are unchanged. The redesigned app is not backward compatible with older agents, though, so the app and the agent need to be updated together. If their versions do not match, the app shows a notification prompting you to update.
|
||||
## First Launch
|
||||
|
||||
On first launch, the welcome dialog points you to the NetBird icon in the Windows or Linux system tray, or the macOS menu bar. Choose whether to connect to **NetBird Cloud** or a **Self-hosted** deployment. For a self-hosted deployment, enter its management URL before connecting.
|
||||
|
||||
Click **Connect** in the main window or tray menu. NetBird opens your browser to authenticate the device. Once authorization completes, the desktop app connects and displays the device's NetBird IP address.
|
||||
|
||||
## Default and Advanced Views
|
||||
|
||||
@@ -24,7 +26,7 @@ Switch to the **Advanced** view and the window expands with a peers and resource
|
||||
<img src="/docs-static/img/client/desktop-app/peers-view.png" alt="Advanced view showing the Peers tab" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
The **Resources** tab lists the network resources available to you.
|
||||
The **Resources** tab lists the network resources available to you. You can search resources, show only active or overlapping entries, toggle individual resources, or enable and disable all resources at once.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/client/desktop-app/resources-view.png" alt="Advanced view showing the Resources tab" className="imagewrapper"/>
|
||||
@@ -50,16 +52,22 @@ A colored status dot sits next to the tray icon so you can read the state of you
|
||||
<img src="/docs-static/img/client/desktop-app/tray-status.png" alt="NetBird system tray status indicator" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
The app also includes per-platform refinements: improved behavior on Linux X11 desktops, a macOS Dock icon that only appears when an app window is open, and improved status rendering on Windows.
|
||||
The tray menu also provides profile switching, session-renewal access, exit-node selection, Settings, Help & Support, and **Quit NetBird**. Closing the main window only hides it while the daemon and network connection continue running. Choosing **Quit NetBird** disconnects the daemon before the desktop app exits.
|
||||
|
||||
## Exit Nodes
|
||||
|
||||
The compact view shows the active exit node. Open the exit-node selector in the main window or tray menu to select another available exit node or return to a direct connection by deselecting it.
|
||||
|
||||
## Settings
|
||||
|
||||
The settings page uses a tabbed layout that groups options by what they control. The tabs you see depend on your role and on any [MDM policy](#mdm-driven-ui) in effect. The full set is:
|
||||
|
||||
* **General** for everyday toggles: auto-start, notifications, and display language.
|
||||
* **Network** and **Security** for connection-side options such as PSK, custom DNS port, lazy connections, and server SSH.
|
||||
* **General** for everyday toggles: Connect on Startup, Launch NetBird UI at Login, notifications, and display language.
|
||||
* **Network** for connectivity, DNS, routes, and IPv6 settings.
|
||||
* **Security** for inbound traffic, LAN access, and quantum-resistant encryption settings.
|
||||
* **Profiles** for managing the accounts the app knows about. See [Profiles](/client/profiles).
|
||||
* **SSH** and **Advanced** for options such as log level, network monitor, and native SSH.
|
||||
* **SSH** for the native SSH server and its optional features.
|
||||
* **Advanced** for log-level and custom configuration options.
|
||||
* **Troubleshoot** for [capturing a debug bundle](#capturing-a-debug-bundle).
|
||||
* **About** for version information, useful links, and updating the app.
|
||||
|
||||
@@ -67,12 +75,14 @@ The settings page uses a tabbed layout that groups options by what they control.
|
||||
<img src="/docs-static/img/client/desktop-app/settings-language.png" alt="Settings page with the General tab and Display Language picker" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
**Connect on Startup** controls whether the background service reconnects when it starts. **Launch NetBird UI at Login** controls only whether the graphical interface opens when you sign in to the operating system. On a fresh desktop installation, launch at login is enabled once by default. Upgrades preserve the user's existing preference. Administrators can manage this behavior with [`disableAutostart`](/client/mdm-integration#disableAutostart).
|
||||
|
||||
## MDM-Driven UI
|
||||
|
||||
If you roll out NetBird through MDM, the app reads the policy in effect on the device and adjusts itself to match, so users only see the options they are allowed to use. For deploying NetBird through an MDM provider, see the [MDM deployment guides](/manage/integrations/mdm-deployment/intune-netbird-integration).
|
||||
|
||||
* **Hide whole views.** `DisableAdvancedView` hides the Advanced view of the main window, so managed users only see the compact one.
|
||||
* **Gate specific capabilities.** Flags such as `AllowServerSSH` control whether the corresponding toggle is available in the app.
|
||||
* **Hide whole views.** `disableAdvancedView` hides the Advanced view of the main window, so managed users only see the compact one.
|
||||
* **Gate specific capabilities.** Keys such as `allowServerSSH` control whether the corresponding toggle is available in the app.
|
||||
* **Refresh in the background.** Restrictions are re-read when the window becomes visible or the connection status changes, so MDM-pushed policy updates apply without a restart.
|
||||
|
||||
<Note>
|
||||
@@ -81,7 +91,7 @@ If you roll out NetBird through MDM, the app reads the policy in effect on the d
|
||||
|
||||
## Session Expiration and Renewal
|
||||
|
||||
When a session is about to expire, the app shows a dialog with a countdown and two clear actions: renew or log out. An operating system notification fires ahead of time, so the dialog is not the first signal you get.
|
||||
When a session is about to expire, the app shows a dialog with a countdown and two clear actions: renew or log out. An operating system notification fires ahead of time, and the session deadline remains visible across reconnects.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/client/desktop-app/session-expiration.png" alt="Session expiry dialog with a countdown and renew or logout actions" className="imagewrapper"/>
|
||||
@@ -91,10 +101,14 @@ The renewal flow follows one rule: re-authenticating never closes an active conn
|
||||
|
||||
## Localization
|
||||
|
||||
You can switch languages from the **Display Language** picker in **Settings → General**, and the change applies instantly. The release candidate ships with initial translations for English, French, German, Hungarian, Italian, Portuguese, Russian, Simplified Chinese, and Spanish.
|
||||
You can switch languages from the **Display Language** picker in **Settings → General**, and the change applies instantly. NetBird v0.75 ships with English, French, German, Hungarian, Italian, Japanese, Portuguese, Russian, Simplified Chinese, and Spanish.
|
||||
|
||||
These initial translations are still a work in progress. If your language is missing or a phrase reads incorrectly, please [open a pull request](https://github.com/netbirdio/netbird). Feedback from native speakers is exactly what helps here.
|
||||
Translations are a continuing community effort. If your language is missing or a phrase reads incorrectly, please [open a pull request](https://github.com/netbirdio/netbird).
|
||||
|
||||
## Capturing a Debug Bundle
|
||||
|
||||
The **Troubleshoot** tab can capture a debug bundle that collects both the daemon logs and the UI logs at the current log level in one step. Attach the bundle when you report an issue so the team has the full picture.
|
||||
The **Troubleshoot** tab can capture a debug bundle that collects daemon and UI logs in one step. You can collect new trace logs for 1–30 minutes, cycle the connection, include a packet capture and system information, anonymize sensitive data, and either upload the result to NetBird or keep it locally. See [Troubleshooting the client](/help/troubleshooting-client#debug-bundle-uploads-with-gui) for the complete flow.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/help/troubleshooting-client/ui-bundle-local-success.png" alt="Completed debug bundle saved locally in the NetBird desktop app" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
@@ -72,7 +72,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 lazy-connection override. `on` forces lazy connections enabled, `off` forces them disabled, and leaving it unset defers to the Management or MDM setting. Overrides MDM when both are configured. Replaces the removed `NB_ENABLE_EXPERIMENTAL_LAZY_CONN`; the deprecated `--enable-lazy-connection` CLI flag is inert. |
|
||||
| `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
|
||||
@@ -81,6 +81,7 @@ To clear all saved service parameters (including env vars), run `sudo netbird se
|
||||
|---|---|---|
|
||||
| `NB_DNS_FORWARDER_PORT` | All | Override the port the internal DNS forwarder binds to for handling DNS routes received from clients (default: `22054`). The forwarder is separate from the local resolver. |
|
||||
| `NB_SKIP_DNS_PROBE` | All | Skip the startup check that sends a test query to the local resolver to verify it is reachable. Set this if the probe causes delays (e.g. in air-gapped networks). |
|
||||
| `NB_DNS_LAZY_WARMUP_TIMEOUT` | All | Per-query budget for waking an idle peer when the local resolver returns one of its A or AAAA records (Go duration, default: `2s`). The value must be positive; invalid, zero, or negative values use the default. |
|
||||
| `NB_UNCLEAN_SHUTDOWN_RESOLV_FILE` | Linux, FreeBSD | Custom file path to store a backup of `/etc/resolv.conf` before the client modifies it. Used to restore the original on next startup if the client crashed without cleaning up (default: `<state-dir>/resolv.conf`, i.e. `/var/lib/netbird/resolv.conf` on Linux, `/var/db/netbird/resolv.conf` on FreeBSD). |
|
||||
|
||||
## Connection retry
|
||||
|
||||
@@ -71,7 +71,8 @@ PascalCase variant in the Group Policy Editor — both are recognized.
|
||||
| `wireguardPort` | integer | UDP port the local WireGuard interface binds to. Range `1–65535`. |
|
||||
| `allowServerSSH` | boolean | Allow the embedded NetBird SSH server on this peer. |
|
||||
| `disableAutoConnect` | boolean | Skip auto-connecting on startup; require an explicit `netbird up`. |
|
||||
| `disableAutostart` | boolean | Prevent the GUI from registering itself as an OS autostart entry on fresh installs, and — when enabled at any later point — remove an existing registration on the next GUI launch (Windows Registry `Run` key, macOS Login Item, Linux `.desktop`). Desktop GUIs only; no-op on iOS/Android. Once the admin lifts the policy, the setting stays off until the user re-enables it in Settings. |
|
||||
| <span id="disableAutostart"></span>`disableAutostart` | boolean | Prevent the GUI from registering itself as an OS autostart entry on fresh installs, and — when enabled at any later point — remove an existing registration on the next GUI launch (Windows Registry `Run` key, macOS Login Item, Linux `.desktop`). Desktop GUIs only; no-op on iOS/Android. Once the admin lifts the policy, the setting stays off until the user re-enables it in Settings. |
|
||||
| `lazyConnection` | boolean | Local override for lazy connections. `true` forces lazy connections on, `false` forces them off, and an absent key defers to the Management setting. `NB_LAZY_CONN` takes precedence when both are configured. |
|
||||
| `rosenpassEnabled` | boolean | Turn on the post-quantum Rosenpass key exchange. |
|
||||
| `rosenpassPermissive` | boolean | Permissive mode for Rosenpass (interop with non-Rosenpass peers). |
|
||||
| `blockInbound` | boolean | Drop all inbound traffic except established/related — kill-switch style. |
|
||||
|
||||
@@ -25,11 +25,11 @@ that automatically rotates and applies WireGuard pre-shared keys to every point-
|
||||
This is still an experimental feature, may contain bugs, and is not supported on mobile devices.
|
||||
</Note>
|
||||
|
||||
### Enabling via the system tray
|
||||
### Enabling via the desktop app
|
||||
|
||||
1. Click the NetBird icon in the system tray.
|
||||
2. Go to **Settings**.
|
||||
3. Click **Enable Quantum-Resistance** to toggle the setting.
|
||||
1. Open the NetBird desktop app.
|
||||
2. Go to **Settings → Security**.
|
||||
3. Toggle **Enable Quantum-Resistance**.
|
||||
|
||||
### Enabling via the CLI
|
||||
|
||||
|
||||
@@ -7,47 +7,29 @@ This feature also allows you to switch between self-hosted and cloud-hosted NetB
|
||||
to juggle multiple config files.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/client/profiles/profiles.png" alt="profiles" className="imagewrapper"/>
|
||||
<img src="/docs-static/img/client/profiles/profiles.png" alt="Profile selector in the NetBird desktop app" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Watch a short demo GIF demonstrating how profile switching works [here](/docs-static/img/client/profiles/profiles.gif).
|
||||
|
||||
## NetBird Profiles GUI Quickstart
|
||||
|
||||
To get started with NetBird profiles:
|
||||
1. Open the desktop app. NetBird creates a `default` profile automatically.
|
||||
2. Open **Settings → Profiles** and select **Add profile**.
|
||||
3. Give the profile a recognizable name and configure whether it connects to NetBird Cloud or a self-hosted management URL.
|
||||
4. Select the profile from the selector in the main window or tray menu.
|
||||
|
||||
- Upgrade your client application to the latest NetBird version.
|
||||
- Run the GUI app
|
||||
|
||||
You will see a `default` profile created automatically.
|
||||
|
||||
Add more profiles by hovering over the default profile and clicking "Manage Profiles".
|
||||
After adding a new profile, select it to make it active.
|
||||
|
||||
You can now change the NetBird settings, e.g., providing a self-hosted
|
||||
instance URL or allowing SSH. The new settings will be saved in the new profile. Click "Connect" to bring up the new profile.
|
||||
|
||||
The consequent selection of your profiles from the menu will automatically trigger the NetBird client to connect to the network and authentication
|
||||
if needed.
|
||||
Selecting a profile makes it active and connects automatically. The first time you use a profile, NetBird opens the browser authentication flow if needed. Later switches reuse that profile's saved login state. While the Profiles settings page is open for management, selecting a profile does not interrupt the profile you are editing.
|
||||
|
||||
## Manage Profiles in the GUI
|
||||
|
||||
* **Add** a new profile with a friendly name input. Names need not be unique, each profile is tracked by its own generated ID.
|
||||
* **Delete** any inactive profile (trash icon).
|
||||
* **Active and default** profiles cannot be removed.
|
||||
Open **Settings → Profiles** to:
|
||||
|
||||
* **Add** a profile with a friendly name. Names need not be unique because each profile has a generated ID.
|
||||
* **Edit or rename** an existing profile, including its management URL.
|
||||
* **Delete** any inactive profile. Active and default profiles cannot be removed.
|
||||
* Recognize profiles by their assigned Work, Home, Default, or other type icon.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/client/profiles/manage-profiles.png" alt="profiles" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
The redesigned desktop app, currently available as a **release candidate**, expands profile management. You can now **rename and edit** existing profiles, not just add and delete them. Profile names accept uppercase letters and spaces, so names like `Work Prod` or `Home Lab` are valid. Each profile is assigned an **icon based on its type** (Work, Home, Default, and others) so the active profile is easy to recognize in the tray and switcher.
|
||||
|
||||
In the new app, profiles are managed from the dedicated **Profiles** tab in Settings.
|
||||
</Note>
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/client/profiles/profiles-edit.png" alt="Editing and renaming profiles in the new desktop app" className="imagewrapper"/>
|
||||
<img src="/docs-static/img/client/profiles/profiles-edit.png" alt="Profiles settings in the NetBird desktop app" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
## What Is a Profile?
|
||||
@@ -74,13 +56,15 @@ Each profile has two parts:
|
||||
The `default` profile is special: its ID is always `default`. You can rename its display label,
|
||||
but it keeps that reserved ID and cannot be removed.
|
||||
|
||||
Profiles live in your system or user config folders, stored as `<id>.json`:
|
||||
The default profile is stored as `default.json` in NetBird's state directory. Additional service profiles are stored under a per-user subdirectory as `<id>.json`:
|
||||
|
||||
| OS | Config path |
|
||||
| ------ | --------------------------------- |
|
||||
| Linux | `/var/lib/netbird/...` |
|
||||
| macOS | `/var/lib/netbird...`|
|
||||
| Windows| `%ProgramData%\Netbird\profiles\` |
|
||||
| OS | Default state directory | Additional profile example |
|
||||
| --- | --- | --- |
|
||||
| Linux and macOS | `/var/lib/netbird/` | `/var/lib/netbird/<username>/<id>.json` |
|
||||
| FreeBSD | `/var/db/netbird/` | `/var/db/netbird/<username>/<id>.json` |
|
||||
| Windows | `%ProgramData%\Netbird\` | `%ProgramData%\Netbird\<username>\<id>.json` |
|
||||
|
||||
`NB_STATE_DIR` overrides the default state directory. Treat profile files as credentials: stop the service before manual maintenance, restrict access, and prefer the GUI or CLI for normal profile management.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -102,7 +102,7 @@ The command will check if the peer is logged in and connect to the management se
|
||||
--disable-ssh-auth Disable SSH JWT authentication. If enabled, any peer with network access can connect without user authentication.
|
||||
--dns-resolver-address string Sets a custom address for NetBird's local DNS resolver. If set, the agent won't attempt to discover the best IP and port to listen on. An empty string "" clears the previous configuration. E.g. --dns-resolver-address 127.0.0.1:5053 or --dns-resolver-address ""
|
||||
--dns-router-interval duration DNS route update interval (default 1m0s)
|
||||
--enable-lazy-connection Enable the lazy connection feature. If enabled, the client will establish connections on-demand. Note: this setting may be overridden by management configuration.
|
||||
--enable-lazy-connection Deprecated and no longer used. Lazy connections are controlled by Management and the NB_LAZY_CONN environment variable.
|
||||
--enable-rosenpass [Experimental] Enable Rosenpass feature. If enabled, the connection will be post-quantum secured via Rosenpass.
|
||||
--enable-ssh-local-port-forwarding Enable local port forwarding for SSH server
|
||||
--enable-ssh-remote-port-forwarding Enable remote port forwarding for SSH server
|
||||
@@ -799,8 +799,15 @@ netbird debug [command]
|
||||
|
||||
### debug bundle
|
||||
Generates a compressed archive containing diagnostic information, which can be used for troubleshooting.
|
||||
The file will be generated in a temporary directory and the path will be printed to the console.
|
||||
The file is only accessible as root/Administrator.
|
||||
The file will be generated in the daemon's temporary directory and the path will be printed to the console. With a
|
||||
standard service installation, the location is `/tmp/netbird.debug.<number>.zip` on Linux and macOS, and
|
||||
`C:\Windows\Temp\netbird.debug.<number>.zip` on Windows. A custom operating-system temporary directory can change this
|
||||
path.
|
||||
|
||||
The local ZIP is created whether or not `--upload-bundle` is used. With `--upload-bundle`, the command also prints an
|
||||
upload key that you can share with the NetBird team.
|
||||
The file belongs to the daemon service account (`root` on standard Linux and macOS installations and `LocalSystem` on
|
||||
Windows), so elevated permissions may be required to access it directly.
|
||||
|
||||
#### Usage
|
||||
To create a debug bundle:
|
||||
|
||||
@@ -41,10 +41,10 @@ With the client installed, you now need to connect it to your network.
|
||||
|
||||
|
||||
|
||||
1. After installation, find the NetBird icon in your system tray or menu bar.
|
||||
2. Click the icon and select **Connect**.
|
||||
3. This will open a new browser tab, prompting you to authorize the new device. Authenticate using the same IdP you used to sign up.
|
||||
4. Once authorized, you will see a "Login successful" message. The onboarding UI will update to show that your first peer is connected, displaying its name and assigned NetBird IP address.
|
||||
1. Launch the NetBird desktop app. On first launch, the welcome screen points you to the system tray on Windows and Linux or the menu bar on macOS, then asks whether you use NetBird Cloud or a self-hosted deployment.
|
||||
2. Click **Connect** in the main window or tray/menu-bar menu.
|
||||
3. NetBird opens a browser tab so you can authorize the device with the same identity provider you used to sign up.
|
||||
4. Once authorized, the app displays the connected state and assigned NetBird IP address. The onboarding UI also updates to show that your first peer is connected.
|
||||
|
||||
### Add a Second Peer (Headless Linux Server)
|
||||
Next, let's add a second, headless peer, like a Linux server or a Raspberry Pi. For devices without a graphical interface, we use a [Setup Key](https://docs.netbird.io/manage/peers/register-machines-using-setup-keys).
|
||||
@@ -150,7 +150,7 @@ After running the second command, the terminal will confirm Connected. Your head
|
||||
Now, set up the device you will use to connect to your private network.
|
||||
1. Back in the web UI, the wizard will prompt you to "Time to add your client device." Click Install NetBird.
|
||||
2. Download and run the installer for your client machine's OS (e.g., macOS).
|
||||
3. Once installed, find the NetBird icon in your system tray or menu bar, click it, and select Connect.
|
||||
3. Once installed, launch the desktop app and click **Connect** in the main window or tray/menu-bar menu.
|
||||
4. Authorize this new device in the browser tab that opens.
|
||||
|
||||
### Test the Connection
|
||||
|
||||
@@ -27,12 +27,7 @@ The NetBird client (agent) allows a peer to join a pre-existing NetBird deployme
|
||||
|
||||
## Running NetBird with SSO Login
|
||||
### Desktop UI Application
|
||||
If you installed the Desktop UI client, you can launch it and click on Connect.
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
Launch the desktop app and click **Connect** in the main window or tray/menu-bar menu. On first launch, choose NetBird Cloud or enter the URL of your self-hosted deployment. NetBird opens your browser to authenticate the device. See the [desktop app guide](/client/desktop-app) for the complete interface.
|
||||
|
||||
### CLI
|
||||
Alternatively, you could use command line. Simply run
|
||||
|
||||
@@ -6,19 +6,25 @@ The NetBird client (agent) allows a peer to join a pre-existing NetBird deployme
|
||||
|
||||
## Desktop App Dependencies
|
||||
|
||||
<Note>
|
||||
This applies to the redesigned NetBird desktop app, currently available as a **release candidate** (download the latest from [pkgs.netbird.io](https://pkgs.netbird.io/releases/rc)). The current stable GUI does not require these packages.
|
||||
</Note>
|
||||
The desktop app introduced in NetBird v0.75.0 renders its interface in a GTK 4 WebKit webview. Supported packages normally install these dependencies automatically. For manual or unsupported deployments, install the corresponding packages before launching the GUI.
|
||||
|
||||
The redesigned desktop app renders its interface in a GTK 4 WebKit webview. Linux distributions package these libraries under inconsistent names, so install them manually before launching the GUI.
|
||||
|
||||
**Debian / Ubuntu**
|
||||
**Debian 12+ / Ubuntu 22.04+**
|
||||
|
||||
```bash
|
||||
sudo apt-get install libgtk-4-1 libwebkitgtk-6.0-4 xdg-utils
|
||||
```
|
||||
|
||||
On other distributions, install the equivalent **GTK 4**, **WebKitGTK 6.0**, and **xdg-utils** packages from your package manager.
|
||||
**Fedora / RHEL 10+**
|
||||
|
||||
```bash
|
||||
sudo dnf install gtk4 webkitgtk6.0 xdg-utils
|
||||
```
|
||||
|
||||
<Note>
|
||||
RHEL 9 includes GTK 4 but does not provide WebKitGTK 6.0, which the desktop app requires. RHEL 10 is supported after enabling [EPEL](https://docs.fedoraproject.org/en-US/epel/getting-started/), which provides the `webkitgtk6.0` package.
|
||||
</Note>
|
||||
|
||||
On other distributions, install the equivalent **GTK 4**, **WebKitGTK 6.0**, and **xdg-utils** packages from your package manager, many systems may already include some of all of these packages.
|
||||
|
||||
## Linux Install Script
|
||||
|
||||
@@ -302,12 +308,7 @@ netbird up
|
||||
|
||||
## Running NetBird with SSO Login
|
||||
### Desktop UI Application
|
||||
If you installed the Desktop UI client, you can launch it and click on Connect.
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
Launch the desktop app and click **Connect** in the main window or system-tray menu. On first launch, choose NetBird Cloud or enter the URL of your self-hosted deployment. NetBird opens your browser to authenticate the device. See the [desktop app guide](/client/desktop-app) for the complete interface.
|
||||
|
||||
### CLI
|
||||
Alternatively, you could use command line. Simply run
|
||||
|
||||
@@ -111,12 +111,7 @@ This creates a launchd daemon at `/Library/LaunchDaemons/netbird.plist` that run
|
||||
|
||||
## Running NetBird with SSO Login
|
||||
### Desktop UI Application
|
||||
If you installed the Desktop UI client, you can launch it and click on Connect.
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
Launch the desktop app and click **Connect** in the main window or menu-bar menu. On first launch, choose NetBird Cloud or enter the URL of your self-hosted deployment. NetBird opens your browser to authenticate the device. See the [desktop app guide](/client/desktop-app) for the complete interface.
|
||||
|
||||
### CLI
|
||||
Alternatively, you could use command line. Simply run
|
||||
|
||||
@@ -16,7 +16,7 @@ The NetBird client (agent) allows a peer to join a pre-existing NetBird deployme
|
||||
|
||||
## Silent and Automated Installation
|
||||
|
||||
Both installers support silent (unattended) installation for use with RMM tools, MDM platforms, and scripted deployments. By default, silent installations automatically configure the NetBird UI to start at user login, so the system tray icon is available without manual intervention.
|
||||
Both installers support silent (unattended) installation for use with RMM tools, MDM platforms, and scripted deployments.
|
||||
|
||||
### EXE Installer (NSIS)
|
||||
|
||||
@@ -26,7 +26,7 @@ Run the EXE installer with the `/S` flag for a silent installation:
|
||||
netbird_installer_<VERSION>_windows_amd64.exe /S
|
||||
```
|
||||
|
||||
The UI tray autostart is enabled by default for both interactive and silent installs. The installer writes the autostart entry to `HKLM\Software\Microsoft\Windows\CurrentVersion\Run`, which applies to all users on the machine.
|
||||
The installer no longer writes a machine-wide `HKLM\Software\Microsoft\Windows\CurrentVersion\Run` entry. Starting with v0.75.0, the desktop app manages launch at login as a per-user preference.
|
||||
|
||||
### MSI Installer
|
||||
|
||||
@@ -36,16 +36,10 @@ Run the MSI installer with `msiexec` for a silent installation:
|
||||
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi /quiet
|
||||
```
|
||||
|
||||
The MSI installer includes an `AUTOSTART` property that defaults to `1` (enabled). When enabled, it registers `netbird-ui.exe` in `HKLM\Software\Microsoft\Windows\CurrentVersion\Run` so the UI tray starts automatically at login for all users.
|
||||
|
||||
To disable the UI tray autostart during installation:
|
||||
|
||||
```bash
|
||||
msiexec /i netbird_installer_<VERSION>_windows_amd64.msi AUTOSTART=0 /quiet
|
||||
```
|
||||
The MSI does not expose an `AUTOSTART` property. On a fresh desktop installation, the app enables **Launch NetBird UI at Login** for the current user the first time the UI runs. Upgrades preserve the user's existing preference. Users can change it under **Settings → General**, and administrators can suppress or remove the per-user registration with the [`disableAutostart` MDM setting](/client/mdm-integration#disableAutostart).
|
||||
|
||||
<Note>
|
||||
Disabling `AUTOSTART` only prevents the UI tray from launching at login. The NetBird background service still runs and maintains connectivity regardless of this setting.
|
||||
**Launch NetBird UI at Login** affects only the graphical interface. The NetBird background service starts independently and can maintain connectivity even when the UI does not launch.
|
||||
</Note>
|
||||
|
||||
### Combining with a Setup Key
|
||||
@@ -70,12 +64,7 @@ netbird up --setup-key <SETUP KEY>
|
||||
|
||||
## Running NetBird with SSO Login
|
||||
### Desktop UI Application
|
||||
If you installed the Desktop UI client, you can launch it and click on Connect.
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/get-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
Launch the desktop app and click **Connect** in the main window or system-tray menu. On first launch, choose NetBird Cloud or enter the URL of your self-hosted deployment. NetBird opens your browser to authenticate the device. See the [desktop app guide](/client/desktop-app) for the complete interface.
|
||||
|
||||
### CLI
|
||||
Alternatively, you could use command line. Simply run
|
||||
|
||||
@@ -222,9 +222,19 @@ Adding the `--system-info (-S)` flag will add system information like network ro
|
||||
netbird debug bundle --anonymize --system-info
|
||||
```
|
||||
|
||||
This will output the path of the generated file. The output file is owned by and can only be accessed by the user
|
||||
NetBird is running as, by default it is: `Administrator` on Windows, `root` on MacOS/Linux or the operating system\'s
|
||||
equivalent.
|
||||
NetBird always creates a local ZIP in the daemon's temporary directory, including when you choose to upload the bundle.
|
||||
With a standard service installation, bundles are stored in:
|
||||
|
||||
| Platform | Default location |
|
||||
|---|---|
|
||||
| Linux | `/tmp/netbird.debug.<number>.zip` |
|
||||
| macOS | `/tmp/netbird.debug.<number>.zip` |
|
||||
| Windows | `C:\Windows\Temp\netbird.debug.<number>.zip` |
|
||||
|
||||
The CLI always prints the generated path. The desktop app displays the ZIP path and an **Open Folder** action when upload is disabled or fails; after a successful upload, it displays the upload key instead. If the operating system's temporary directory has been
|
||||
overridden, use the path shown by the client. The ZIP is owned by the account running the NetBird daemon: `root` on
|
||||
standard Linux and macOS installations and `LocalSystem` on Windows. Elevated permissions may be required to access it
|
||||
directly.
|
||||
|
||||
On iOS, the `netbird` CLI is not available. Collect the bundle from the app instead, under **Settings → Troubleshoot**. See [NetBird client on iOS](/help/troubleshooting-client/ios).
|
||||
|
||||
@@ -241,6 +251,8 @@ The archive collects the most useful diagnostics into one file, and every bundle
|
||||
| `resolv.conf`, `scutil_dns.txt`, `resolved_domains.txt` | DNS resolver configuration and the domains NetBird resolved |
|
||||
| `network_map.json` | Sync response: peers, routes, DNS settings, and firewall rules |
|
||||
| `config.txt`, `state.json` | Client configuration and internal client state |
|
||||
| `service_params.json` | Service-install parameters when available; sensitive environment values are masked |
|
||||
| `metrics.txt` | Buffered client metrics when available; peer identifiers are anonymized |
|
||||
|
||||
With `--anonymize`, IP addresses, domains, and interface names are replaced consistently across every file, so the bundle stays readable while sensitive values are masked. Private keys and SSH keys are never included, and the packet capture (`capture.pcap`) is left out of anonymized bundles because it holds raw decrypted packets.
|
||||
|
||||
@@ -283,6 +295,7 @@ netbird debug bundle --system-info --upload-bundle
|
||||
|
||||
This will output an `Upload file key`, which is effectively a random filename in our internal storage system
|
||||
and can be safely shared with us through public channels such as GitHub Issues or Slack.
|
||||
Uploading the bundle does not remove the local ZIP from the temporary directory.
|
||||
|
||||
```shell
|
||||
netbird debug bundle --system-info --upload-bundle
|
||||
@@ -296,28 +309,38 @@ Upload file key:
|
||||
The flag `--anonymize` can be used to anonymize IP addresses and non-netbird.io domains in logs and status output when needed.
|
||||
</Note>
|
||||
### Debug bundle uploads with GUI
|
||||
Since version `0.43.2` users can upload their debug bundle via the GUI client.
|
||||
|
||||
To generate a bundle via GUI, you can access the application then go to `Settings` > `Create Debug Bundle` and follow
|
||||
the wizard to upload the bundle:
|
||||
The desktop app can create and optionally upload a debug bundle without using the CLI. Open **Settings → Troubleshoot**.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/help/troubleshooting-client/ui-settings.png" alt="service-user-overview" className="imagewrapper-big"/>
|
||||
<img src="/docs-static/img/help/troubleshooting-client/ui-settings.png" alt="Troubleshoot settings in the NetBird desktop app" className="imagewrapper-big"/>
|
||||
</p>
|
||||
<Note>
|
||||
If needed, you can update the upload URL and select to anonymize sensitive information like IP addresses and non-netbird.io domains in logs and status output.
|
||||
</Note>
|
||||
<p>
|
||||
<img src="/docs-static/img/help/troubleshooting-client/ui-bundle-wizard.png" alt="service-user-overview" className="imagewrapper-big"/>
|
||||
</p>
|
||||
By default running with trace log enable before generating the bundle is selected. This will restart the client connections and provide a `disconnect to connected` information for our engineers.
|
||||
|
||||
If you uncheck this option, a bundle will be generated without running this step. Which is very useful when you have an
|
||||
issue that recovers when restarting the client.
|
||||
Choose the data and capture behavior that fits the issue:
|
||||
|
||||
* **Anonymize sensitive data** masks IP addresses, domains, interface names, and peer identifiers where supported.
|
||||
* **Include system information** adds routes, interfaces, resolver state, and firewall information.
|
||||
* **Upload Bundle to NetBird Servers** uploads the completed archive to NetBird's fixed debug-bundle service. Disable it to keep the bundle local.
|
||||
* **Enable trace logging** temporarily raises the client log level while the bundle is collected.
|
||||
* **Restart connection** cycles the NetBird connection during collection. Disable it when reconnecting makes the issue disappear.
|
||||
* **Capture packets** adds a packet capture while collecting new logs. Packet captures are excluded from anonymized bundles because they contain raw packets.
|
||||
* **Capture duration** accepts 1–30 minutes.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/help/troubleshooting-client/ui-bundle-success.png" alt="service-user-overview" className="imagewrapper-big"/>
|
||||
<img src="/docs-static/img/help/troubleshooting-client/ui-bundle-wizard.png" alt="Debug bundle capture options in the NetBird desktop app" className="imagewrapper-big"/>
|
||||
</p>
|
||||
Once the bundle generation is complete, you can click on `Copy Key` to get the uploaded key and share with NetBird\'s team.
|
||||
|
||||
Click **Create debug bundle**. You can cancel while logs are being collected. When the operation finishes:
|
||||
|
||||
* If **Upload Bundle to NetBird Servers** is enabled, the app displays an upload key. Copy the key and share it with the NetBird team.
|
||||
* If upload is disabled, the app displays the ZIP location and an **Open Folder** button.
|
||||
|
||||
In both cases, the ZIP is stored locally in the platform's temporary directory listed above.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/help/troubleshooting-client/ui-bundle-success.png" alt="Completed debug bundle uploaded with a key in the NetBird desktop app" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
If you kept the bundle local, attach the ZIP through the support channel you are using.
|
||||
|
||||
### Remote debug bundle generation
|
||||
|
||||
@@ -758,5 +781,3 @@ For `net-tools` (`ifconfig`, `route`, `netstat` tools):
|
||||
|
||||
- `route -n` to find built-in `100.*.0.0/16` route,
|
||||
- neither `route` nor `netstat` support viewing content of custom routing tables,
|
||||
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Traffic Events Logging
|
||||
|
||||
<Note>
|
||||
This feature is available only in the NetBird cloud under the [Business plan](https://www.netbird.io/pricing?utm_source=docs&utm_content=traffic-events).
|
||||
This is feature is in Beta and may change over time — including how data is collected and reported.
|
||||
This feature is available in NetBird Cloud under the [Business plan](https://www.netbird.io/pricing?utm_source=docs&utm_content=traffic-events) and in licensed self-hosted Enterprise deployments with traffic flow enabled.
|
||||
This feature is in Beta and may change over time — including how data is collected and reported.
|
||||
To use this feature, make sure you're running NetBird client version 0.39 or higher.
|
||||
</Note>
|
||||
|
||||
@@ -37,7 +37,7 @@ NetBird would log the blocked event on the peer that refused the connection.
|
||||
|
||||
#### Successful P2P Connection Events
|
||||
|
||||
NetBird helps you better understand connection flows by correlating related events and presenting them in a clear, organized manner.
|
||||
NetBird helps you better understand connection flows by aggregating related events and presenting them in a clear, organized manner.
|
||||
|
||||
For example, in a successful peer-to-peer connection scenario, a user initiates a connection from the peer `Alice` to the peer `server`.
|
||||
This is illustrated in the screenshot below.
|
||||
@@ -46,12 +46,9 @@ This is illustrated in the screenshot below.
|
||||
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-successful-connection.png" alt="traffic-events-p2p-successful-connection" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
You'll see two grouped sets of events, one from each peer (source and destination). The source peer `Alice` initiates the
|
||||
connection and then terminates it after a few seconds.
|
||||
You'll see two aggregated flow records, one reported by each peer (source and destination). The record from `Alice` counts the connection start and end from the initiator's perspective.
|
||||
|
||||
On the other side, the destination peer `server` receives the connection request and also terminates it shortly afterward,
|
||||
following the disconnection from `Alice`. Since `server` allows the connection, the log includes the policy `IT Admins to Servers`
|
||||
that authorized the connection over the `ICMP` protocol.
|
||||
The record from `server` represents the receiver's perspective. Because `server` allows the connection, it includes the policy `IT Admins to Servers` that authorized the flow over `TCP` on port `443`.
|
||||
|
||||
<Note>
|
||||
Use the `P2P` filter in the table to view only peer-to-peer connection events.
|
||||
@@ -103,8 +100,7 @@ Note the `ROUTER` column in the table, which identifies the routing peer respons
|
||||
In the event of a blocked connection, the initiating peer logs the connection attempt, while the routing peer records the blocked event.
|
||||
The screenshot below demonstrates this behavior: the routing peer blocks a connection to the network resource `CRM` because
|
||||
the policy `IT Admins to AWS Servers` does not permit connections over the `HTTP` protocol on port `6432`.
|
||||
You can see multiple blocked events reported by the routing peer, which indicates that the initiating peer `Alice` attempted to connect multiple times
|
||||
in one TCP session, but the routing peer blocked all attempts.
|
||||
The routing peer's aggregate shows the number of dropped attempts, so repeated application retries increase the drop count instead of creating one top-level row for every attempt.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/activity/traffic-events-logging/network-resource-blocked-connection.png" alt="network-resource-succesful-connection" className="imagewrapper-big"/>
|
||||
@@ -115,6 +111,17 @@ in one TCP session, but the routing peer blocked all attempts.
|
||||
E.g., `nc -v crm.netbird.cloud 443`.
|
||||
</Note>
|
||||
|
||||
## Event Aggregation
|
||||
|
||||
Starting with v0.75, clients aggregate related traffic events before reporting them. For a given source address and direction, a group is identified by protocol, destination address, destination port for TCP or UDP, and ICMP type for ICMP traffic. Source port and ICMP code do not split aggregates. During each reporting window, NetBird accumulates:
|
||||
|
||||
* connection start, end, and drop counts;
|
||||
* transmitted and received packet totals;
|
||||
* transmitted and received byte totals;
|
||||
* the start and end of the aggregation window.
|
||||
|
||||
The Dashboard and API therefore present one flow record with counters for activity in that window instead of a separate top-level record for every start, end, or blocked event. The `events` array can retain individual event timestamps where they are available.
|
||||
|
||||
## Enabling Traffic Events Logging
|
||||
|
||||
Traffic events logging feature is disabled by default. To enable it on the NetBird dashboard, navigate to `Settings > Networks`.
|
||||
@@ -149,11 +156,11 @@ choose the groups you want to include, and click `Save Groups`.
|
||||
## Log Retention
|
||||
|
||||
While in experimental mode, logs are retained for **seven days**.
|
||||
Additionally, please note that the current API returns a maximum of **50,000 events**.
|
||||
We are actively working on expanding this limit in the coming days to support larger datasets and increased usage.
|
||||
Additionally, the current API returns a maximum of **50,000 flow records**.
|
||||
This limit may change.
|
||||
|
||||
## Report rate
|
||||
The events might take up to **ten minutes** to become available via API and Dashboard. For some TCP connections, the full event cycle might take longer, depending on OS settings and connection termination.
|
||||
Aggregated flows might take up to **ten minutes** to become available through the API and Dashboard. An end count for some TCP connections can appear in a later window, depending on OS settings and connection termination.
|
||||
|
||||
## Enable Traffic Events Streaming to SIEM Systems
|
||||
|
||||
@@ -167,16 +174,16 @@ For detailed instructions on supported integrations and how to set them up, refe
|
||||
|
||||
When enabled, a NetBird peer will record metadata for each network flow that it participates in. The data collected by peers includes:
|
||||
|
||||
* **Timestamp**: When the flow started and ended.
|
||||
* **Flow ID**: A unique identifier for the traffic event flow.
|
||||
* **Type**: The type of traffic event, such as Start, End, or Blocked.
|
||||
* **Window start and end**: The bounds of the aggregation window.
|
||||
* **Flow ID**: A unique identifier for the aggregated traffic flow.
|
||||
* **Event counts**: `num_of_starts`, `num_of_ends`, and `num_of_drops` for the group.
|
||||
* **Source and Destination IP Addresses**: The IP of the peer (source) and the IP of the remote endpoint (destination). For peer-to-peer traffic,
|
||||
these will be the NetBird network IPs (e.g. 100.x.x.x addresses of each peer). For traffic to an external resource (like a private server or subnet), the destination might be an IP in that remote network.
|
||||
* **Source and Destination Ports**: The network ports used by the connection (for TCP/UDP flows).
|
||||
* **ICMP Code and Type**: For ICMP traffic, the ICMP code and type.
|
||||
* **Source and Destination Ports**: The network ports recorded for TCP/UDP flows. Destination port is part of the aggregation key; source port does not split aggregates.
|
||||
* **ICMP Type**: For ICMP traffic, the ICMP type used to group the flow. ICMP code does not split aggregates.
|
||||
* **Protocol**: The protocol of the traffic, such as TCP, UDP, or ICMP.
|
||||
* **Direction**: Whether the flow was inbound or outbound. This takes into consideration the perspective of the **peer reporting the traffic** and the NetBird interface.
|
||||
* **Volume of Data**: The amount of data transferred, measured in number of packets and bytes sent/received for the duration of the flow.
|
||||
* **Volume of Data**: Packet and byte totals sent and received during the aggregation window.
|
||||
* **Resource ID**: Network route or Networks resource ID that the flow is associated with. This is useful for identifying the routing configuration that allowed the flow. DNS route information is **available only** on the routing client.
|
||||
* **Rule ID**: The ID of the policy that allowed the flow. This is useful for identifying the access control policy that allowed the flow. This information is **available only** on the receiving side of the traffic.
|
||||
|
||||
@@ -229,10 +236,23 @@ In addition to the data collected by the peers, the NetBird API provides additio
|
||||
"os": "Darwin",
|
||||
"type": "PEER"
|
||||
},
|
||||
"timestamp": "2025-03-22T20:26:16.937522Z",
|
||||
"window_start": "2025-03-22T20:26:16.937522Z",
|
||||
"window_end": "2025-03-22T20:30:17.257891Z",
|
||||
"num_of_starts": 1,
|
||||
"num_of_ends": 1,
|
||||
"num_of_drops": 0,
|
||||
"tx_bytes": 64,
|
||||
"tx_packets": 1,
|
||||
"type": "TYPE_START",
|
||||
"events": [
|
||||
{
|
||||
"type": "TYPE_START",
|
||||
"timestamp": "2025-03-22T20:26:16.937522Z"
|
||||
},
|
||||
{
|
||||
"type": "TYPE_END",
|
||||
"timestamp": "2025-03-22T20:30:17.257891Z"
|
||||
}
|
||||
],
|
||||
"user_email": "john@example.com",
|
||||
"user_id": "google-oauth2|xyz0123",
|
||||
"user_name": "John Doe"
|
||||
@@ -247,42 +267,28 @@ There are two places where you can see the traffic events on the NetBird dashboa
|
||||
|
||||
### Filters
|
||||
You can use various filters to search and filter received events. The filters include:
|
||||
- **Peer name**: Name of the peer that is the source or destination of the traffic event
|
||||
- **Resource name**: Name of the resource or network route
|
||||
- **Source**: Select a source peer, network resource, route, or user. The API equivalent is `source_id`.
|
||||
- **Destination**: Select a destination peer or network resource. The API equivalent is `destination_id`.
|
||||
- **IP address**: Source or destination IP addresses
|
||||
- **Ports**: Source or destination ports
|
||||
- **User**: User from the peer that initiated the connection
|
||||
- **Timestamp**: Time range of the event
|
||||
- **Protocol**: ICMP, TCP, UDP
|
||||
- **Type of event**:
|
||||
- **P2P connection started (inbound/outbound)**: Events with started status and initiated by peers to other peers
|
||||
- **P2P connection stopped (inbound/outbound)**: Events with stopped status and initiated by peers to other peers
|
||||
- **P2P connection blocked (inbound/outbound)**: Events with blocked status and initiated by peers to other peers
|
||||
- **Routed connection started (inbound/outbound)**: Events with started status and with a remote resource destination
|
||||
- **Routed connection stopped (inbound/outbound)**: Events with stopped status and with a remote resource destination
|
||||
- **Routed connection blocked (inbound/outbound)**: Events with blocked status and with a remote resource destination
|
||||
- **Timestamp**: Aggregation-window time range
|
||||
- **Protocol**: ICMP, TCP, or UDP
|
||||
- **Flow type and direction**: P2P or routed traffic, inbound or outbound, including groups with start, end, or drop counts
|
||||
|
||||
## Correlating events
|
||||
Events can be correlated by observing the traffic from both peers involved in a traffic session. Let's say you have two peers, Peer A and Peer B, and Peer A initiates a connection to Peer B. In the traffic events,
|
||||
you will see up to 4 events from these peers. If the connection was successful, you will see a started and a stopped event from Peer A and Peer B. But, if one peer blocks the connection, then you will see a started and stopped events from the initiator and
|
||||
a blocked event from the responder.
|
||||
Correlate a session by comparing the aggregated flow records reported by both sides. If Peer A connects to Peer B, each reporter can contribute a record for the same source and destination tuple. A successful flow normally increases the start and end counters. If Peer B rejects it, the receiver's record increases the drop counter while the initiator may only know that it attempted the connection.
|
||||
<Note>
|
||||
Blocked events are only reported when the destination peer is in userspace mode. See [Limitations](#limitations).
|
||||
</Note>
|
||||
|
||||
### Viewing TCP and UDP connections
|
||||
You can use source ports to correlate TCP and UDP. Below we will analyze a few examples for a connection between a user computer and a Web and FTP servers.
|
||||
You can use endpoint addresses, destination ports, and the other flow fields to correlate TCP and UDP records. Below we will analyze a few examples for a connection between a user computer and Web and FTP servers.
|
||||
|
||||
The peer Maycons-MacBook-Pro.local initiates a connection to the Web server. The source port is `51997` and the destination port is TCP/80. The connection is successful, and the event is marked as started and stopped. See screenshot below:
|
||||
The peer Maycons-MacBook-Pro.local initiates a connection to the Web server on destination port TCP/80. A successful aggregate has non-zero start and end counters and totals the packets and bytes transferred in the reporting window:
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-tcp-allow.png" alt="P2P TCP Allowed" className="imagewrapper-big"/>
|
||||
</p>
|
||||
Besides the ports and protocol information, we can review the event description in the screenshot above to understand what happened. For all four events we have the following:
|
||||
- **Peer `Maycons-MacBook-Pro-2.local` requested P2P connection to Peer `webserver`**: This is the event from the perspective of the peer that initiated the connection. The sources and destination provide the IPs and ports used in the connection.
|
||||
- **Peer `webserver` received P2P connection from Peer `Maycons-MacBook-Pro-2.local`**: This is the event from the perspective of the peer that received the connection.
|
||||
- **Peer `Maycons-MacBook-Pro-2.local` stopped P2P connection to Peer `webserver`**: This is the event from the perspective of the peer that initiated the connection when the connection ended on its side.
|
||||
- **Peer `webserver` stopped P2P connection from Peer `Maycons-MacBook-Pro-2.local`**: This is the event from the perspective of the peer that received the connection when the connection has ended on its side.
|
||||
In case of the peer receiving the connection, the stopped status might arrive several minutes later, due to TCP sessions.
|
||||
Use the reporter, source, destination, direction, protocol, and destination port to align the two perspectives. An end can be reported in a later window when the operating system keeps the TCP session open.
|
||||
|
||||
|
||||
The UDP connection is very similar:
|
||||
@@ -290,7 +296,7 @@ The UDP connection is very similar:
|
||||
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-udp-allow.png" alt="P2P UDP Allowed" className="imagewrapper-big"/>
|
||||
</p>
|
||||
<Note>
|
||||
The UDP connection is stateless, so the stopped event will be generated right after a certain period of inactivity.
|
||||
UDP is stateless, so its end counter is updated after the client observes the configured inactivity period.
|
||||
</Note>
|
||||
|
||||
When a connection is blocked, you may see similar entries to the following events but with a few differences:
|
||||
@@ -304,9 +310,7 @@ When a connection is blocked, you may see similar entries to the following event
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-udp-blocked.png" alt="P2P UDP Blocked" className="imagewrapper-big"/>
|
||||
</p>
|
||||
Key differences:
|
||||
- There are no events that have started or stopped on the refusing side. The connection is blocked right after the request.
|
||||
- Depending on the application making a request in the initiator, you may see multiple blocked events from the receiving side of the connection due to retries:
|
||||
On the refusing side, retries increase `num_of_drops`; the client does not record a successful start or end for traffic it rejected.
|
||||
<Note>
|
||||
Blocked events are only reported when the destination peer is in userspace mode. See [Limitations](#limitations).
|
||||
</Note>
|
||||
@@ -317,7 +321,7 @@ ICMP events are similar to TCP and UDP events. The main difference is that ICMP
|
||||
<img src="/docs-static/img/manage/activity/traffic-events-logging/p2p-icmp-allowed.png" alt="P2P ICMP Allowed" className="imagewrapper-big"/>
|
||||
</p>
|
||||
<Note>
|
||||
The ICMP connection is stateless, so the stopped event will be generated right after a certain period of inactivity.
|
||||
ICMP is grouped by ICMP type and does not use ports. Its end counter is updated after inactivity.
|
||||
</Note>
|
||||
### Routed events
|
||||
Routed events follow the same pattern as P2P events. The main difference is that the destination or source can be a resource or network route. Below, we have a few examples of a connection from a peer to a resource:
|
||||
@@ -330,10 +334,7 @@ Routed events follow the same pattern as P2P events. The main difference is that
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/activity/traffic-events-logging/routed-tcp-allowed.png" alt="Routed TCP Allowed" className="imagewrapper-big"/>
|
||||
</p>
|
||||
Key differences:
|
||||
- The source or destination is a resource or network route.
|
||||
- On the receiver side, we will have an indication of which routing peer reported the event.
|
||||
- The source or destination identifier will be unknown on the routing peer side if the route or resource is of a DNS type.
|
||||
For routed aggregates, the source or destination can be a resource or network route. The record identifies the routing peer that reported it. The source or destination identifier can be unknown on the routing-peer side for DNS resources.
|
||||
|
||||
For site-2-site connections, the events will be similar to the above examples, but you will see a routing peer for each event:
|
||||
<p>
|
||||
|
||||
@@ -81,7 +81,7 @@ In the `Install / Uninstall commands` tab, configure the silent installation par
|
||||
|
||||
The `/S` parameter ensures silent installation without user prompts for NetBird's EXE installer, while `{{full_path}}` and `{{uninstall_cmd}}` are Acronis variables that automatically resolve to the correct paths during deployment. Click `Next` when ready.
|
||||
|
||||
> **Note**: Both the EXE and MSI installers automatically enable the NetBird UI tray autostart when installed silently, so users will see the system tray icon after login. If you're using NetBird's MSI installer instead of the EXE installer, use `/qn` in the **Installation options** field instead of `"{{full_path}}" /S`. The **Uninstallation options** field remains the same (`{{uninstall_cmd}} /S`) for both installer types. The `/qn` parameter provides quiet installation with no user interface for MSI packages. To disable UI autostart with the MSI installer, add `AUTOSTART=0` to the installation options (e.g., `/qn AUTOSTART=0`).
|
||||
> **Note**: If you're using NetBird's MSI installer instead of the EXE installer, use `/qn` in the **Installation options** field instead of `"{{full_path}}" /S`. The **Uninstallation options** field remains the same (`{{uninstall_cmd}} /S`) for both installer types. Starting with v0.75.0, neither installer creates a machine-wide UI autostart entry and the MSI has no `AUTOSTART` property. The desktop app manages **Launch NetBird UI at Login** per user. Use the [`disableAutostart` MDM setting](/client/mdm-integration#disableAutostart) to suppress it on managed endpoints.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -104,7 +104,7 @@ You can leave the rest of the fields empty.
|
||||
- **Install command:** `netbird_installer_0.43.0_windows_amd64.exe /S`
|
||||
- **Uninstall command:** `"%ProgramFiles%\Netbird\netbird_uninstall.exe" /S`
|
||||
|
||||
>**Note:** The commands above assume a standard installation using the `/S` flag to specify "silent mode". Change them accordingly if you require NetBird installed on a different path. The `/S` flag automatically enables the UI tray autostart, so users will see the NetBird system tray icon after login without any additional configuration.
|
||||
>**Note:** The commands above assume a standard installation using the `/S` flag to specify silent mode. Change them accordingly if you require NetBird installed on a different path. Starting with v0.75.0, the installer does not create a machine-wide UI autostart entry. The desktop app manages **Launch NetBird UI at Login** per user; use the [`disableAutostart` MDM setting](/client/mdm-integration#disableAutostart) when administrators need to suppress it.
|
||||
|
||||
For this example, leave the rest of the configuration unchanged. Note that you can change the install behavior and users' ability to uninstall NetBird if required.
|
||||
|
||||
@@ -182,7 +182,7 @@ Click `Next` to configure NetBird with the following details:
|
||||
- **Publisher**: NetBird
|
||||
- **App install context**: Device
|
||||
- **Ignore app version**: No (This ensures updates will be applied when available)
|
||||
- **Command-line arguments**: Leave empty (the default MSI installation enables UI tray autostart; to disable it, enter `AUTOSTART=0`)
|
||||
- **Command-line arguments**: Leave empty. The v0.75 MSI has no `AUTOSTART` property; manage launch at login with the `disableAutostart` MDM setting instead.
|
||||
- **Category**: Select any category that fits your needs (optional)
|
||||
- **Show this as a featured app in the Company Portal**: Yes
|
||||
- **Information URL**: https://docs.netbird.io/
|
||||
|
||||
@@ -98,11 +98,9 @@ The script deliberately never touches an existing installation, so machines that
|
||||
|
||||
Create a second GPO named `NetBird Install` (or reuse the first), and add the script under **Computer Configuration > Policies > Windows Settings > Scripts (Startup/Shutdown) > Startup**, on the **PowerShell Scripts** tab. Link it to the same OU.
|
||||
|
||||
By default, the installer makes the NetBird tray application start every time a user signs in, by writing a `Run` entry under `HKLM\Software\Microsoft\Windows\CurrentVersion\Run`. If you do not want the tray application to appear at sign-in, add `AUTOSTART=0` to the `msiexec` argument list in the script above.
|
||||
Starting with v0.75.0, the Windows installer does not create a machine-wide `Run` entry and the MSI does not expose an `AUTOSTART` property. The desktop app manages **Launch NetBird UI at Login** per user. It enables the preference on the first UI launch of a genuinely fresh installation and preserves the existing preference during upgrades.
|
||||
|
||||
<Note>
|
||||
The **Disable Autostart** policy in the ADMX does not do this, and it is easy to reach for by mistake. That policy controls a different mechanism: the launch-on-login setting inside the NetBird client itself. The installer's `Run` entry is created before any policy is read and is removed by neither. `AUTOSTART=0` at install time is the only switch that keeps the tray application from launching at sign-in.
|
||||
</Note>
|
||||
To keep the UI from launching at sign-in, enable **Disable Autostart** in the NetBird ADMX policy. The app suppresses the fresh-install default and removes an existing per-user registration the next time the UI runs. Removing the policy later does not automatically re-enable launch at login; the user must turn it on under **Settings → General**.
|
||||
|
||||
## 4. Scope the GPOs
|
||||
|
||||
@@ -114,7 +112,7 @@ The **Disable Autostart** policy in the ADMX does not do this, and it is easy to
|
||||
|
||||
After the next reboot, the machine has NetBird installed and every managed value enforced, but no tunnel yet:
|
||||
|
||||
1. The user clicks **Connect** in the NetBird tray application.
|
||||
1. The user opens the NetBird desktop app and clicks **Connect** in the main window or tray menu.
|
||||
2. The daemon loads its configuration with the managed values on top and connects to `https://api.example.com:443`.
|
||||
3. A browser window opens for single sign-on; the user signs in with their identity provider account and the device becomes a peer.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ NetBird [Routes](/manage/network-routes) enable peers to access external network
|
||||
|
||||
## Using Route Selection
|
||||
|
||||
You can select routes through the CLI or the system tray GUI.
|
||||
You can select routes through the CLI or the desktop app.
|
||||
|
||||
### CLI
|
||||
|
||||
@@ -57,10 +57,10 @@ netbird routes select -a route3
|
||||
|
||||
### GUI
|
||||
|
||||
Open the NetBird system tray application and navigate to **Network Routes**. Click the checkbox next to each route to select or deselect it.
|
||||
Open the desktop app, switch to **Advanced** view, and select **Resources**. Use the **Overlapping** filter to narrow the list, then toggle each resource you want to use. You can also search by name and use **Enable all** or **Disable all** for bulk changes.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/network-routes/overlapping-routes/select-network-routes.png" alt="Route selection in system tray" className="imagewrapper"/>
|
||||
<img src="/docs-static/img/manage/network-routes/overlapping-routes/select-network-routes.png" alt="Overlapping resource selection in the NetBird desktop app" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Enabling All Routes
|
||||
|
||||
@@ -1,79 +1,60 @@
|
||||
import {Note} from "@/components/mdx";
|
||||
|
||||
# Lazy Connections
|
||||
NetBird includes a lazy connection feature designed to improve performance and reduce resource usage by connecting to peers only when needed. Instead of maintaining always-on connections, NetBird activates them on-demand based on activity or signaling.
|
||||
|
||||
This guide walks you through enabling and configuring this feature in your NetBird client.
|
||||
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.
|
||||
|
||||
<Note>
|
||||
Minimum supported agent version: <strong>v0.50.1</strong>.
|
||||
This or higher version must also be installed on the peers you are trying to access for lazy connections to function.
|
||||
Lazy connections require NetBird v0.50.1 or later on the client, the peers it communicates with, and self-hosted Management and Signal servers.
|
||||
</Note>
|
||||
|
||||
## How Lazy Connections Work
|
||||
|
||||
When lazy connections are enabled, the client:
|
||||
|
||||
- Starts a connection to a peer when traffic is sent to it.
|
||||
- Tears down an established peer connection after it has been idle for the configured inactivity threshold.
|
||||
- Keeps peers used for ingress forwarding connected so forwarding targets remain reachable.
|
||||
- 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](https://pkg.go.dev/time#ParseDuration) such as `30m` or `1h`.
|
||||
|
||||
<Note>
|
||||
This feature also requires an upgraded NetBird Management and Signal server.
|
||||
If you're self-hosting NetBird, ensure your server is updated to version <strong>v0.50.1</strong>, which adds support for lazy connections.
|
||||
The first request to an idle peer can take slightly longer while NetBird establishes the connection.
|
||||
</Note>
|
||||
|
||||
## What Are Lazy Connections?
|
||||
### DNS warm-up
|
||||
|
||||
When enabled, lazy connections allow the NetBird agent to:
|
||||
When the local NetBird resolver returns an A or AAAA record for an idle peer, it starts waking that peer before the application sends its first packet. The resolver waits for up to two seconds by default for one matching peer to connect, reducing the chance that the application's first request races the lazy connection.
|
||||
|
||||
- Establish peer-to-peer connections **only when needed** (e.g., when pinging a remote peer).
|
||||
- Monitor peer activity and **automatically disconnect peers** that remain inactive **and unreachable** for a specified time.
|
||||
- Keep critical peers (such as excluded peers) **always connected** to ensure uninterrupted communication.
|
||||
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.
|
||||
|
||||
This feature is especially useful in **large-scale deployments** or **resource-constrained environments**, where maintaining full-mesh, permanent connections to all peers is unnecessary and inefficient.
|
||||
## Enable Lazy Connections in Management
|
||||
|
||||
<Note>
|
||||
When using lazy connections, there may be a **slight delay** when initiating a connection to a peer that is not yet connected. This is expected behavior, as the connection is established on-demand.
|
||||
</Note>
|
||||
The account setting in the NetBird Dashboard is the normal source of truth. 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.
|
||||
|
||||
Existing active connections are not interrupted merely because lazy mode is enabled. They become eligible for teardown after the inactivity threshold.
|
||||
|
||||
### How Automatic Disconnection Works
|
||||
## Override the Management Setting on a Client
|
||||
|
||||
Once a connection between two peers is established, it will remain open only if there is ongoing traffic from the remote peer. If no traffic is received for 15 minutes, the connection will be closed — even if the remote peer is still reachable.
|
||||
|
||||
<Note>
|
||||
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>
|
||||
|
||||
## Enabling via the system tray
|
||||
|
||||
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:
|
||||
Set `NB_LAZY_CONN` on the NetBird daemon when one client must override the account setting:
|
||||
|
||||
```bash
|
||||
export NB_ENABLE_EXPERIMENTAL_LAZY_CONN=true
|
||||
# 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
|
||||
```
|
||||
|
||||
Or pass the flag directly via the CLI when running the agent:
|
||||
`on` and `off` override Management in both directions. Leave the variable unset to follow the Management setting. See [Client Environment Variables](/client/environment-variables#ice-and-connectivity) 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.
|
||||
|
||||
```bash
|
||||
netbird up --enable-lazy-connection
|
||||
```
|
||||
<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 deprecated `NB_ENABLE_EXPERIMENTAL_LAZY_CONN` variable is no longer used. The deprecated `netbird up --enable-lazy-connection` flag is also inert in v0.75. Use the Management setting, `NB_LAZY_CONN`, or the MDM policy instead.
|
||||
</Note>
|
||||
|
||||
## Enabling Lazy Connections in the NetBird Dashboard
|
||||
|
||||
The lazy connection feature can also be configured through the NetBird Dashboard. Here’s how it works once the setting is updated:
|
||||
|
||||
Setting enabled:
|
||||
* The client’s lazy connection manager is now active. Existing peer connections and ongoing connection attempts will remain unchanged for one hour.
|
||||
After that, any connection that couldn't be established due to unavailable remote peers will transition to an idle state.
|
||||
|
||||
Setting disabled:
|
||||
* The lazy connection manager is now disabled. The client will immediately attempt to establish connections with all remote peers.
|
||||
|
||||
## Get started
|
||||
<div>
|
||||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
|
||||
|
||||
@@ -63,12 +63,12 @@ On the machine you want to access via SSH, enable the NetBird SSH server.
|
||||
|
||||
**Using the GUI:**
|
||||
|
||||
1. Click on the NetBird tray icon
|
||||
2. Navigate to Settings
|
||||
3. Click on **Allow SSH** to enable the SSH server
|
||||
1. Open the NetBird desktop app.
|
||||
2. Go to **Settings → SSH**.
|
||||
3. Toggle **Enable SSH Server**. Configure local forwarding, remote forwarding, SFTP, or root access only when required.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/manage/peers/ssh/ssh-client.png" alt="netbird ssh client"
|
||||
<img src="/docs-static/img/manage/peers/ssh/ssh-client.png" alt="SSH server settings in the NetBird desktop app"
|
||||
className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
@@ -130,7 +130,7 @@ These variables can override CLI flags at runtime. The naming convention is `NB_
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `NB_PPROF_ADDR` | Enable pprof on a given address |
|
||||
| `NB_PPROF_ADDR` | Start the unauthenticated Go pprof HTTP listener at a `host:port` address, for example `127.0.0.1:6060`. Unset disables it. Bind to loopback or another trusted interface and restart the server after changing it; never expose pprof directly to the public internet. |
|
||||
| `NB_EVENT_ACTIVITY_LOG_ENABLED` | Enable activity log events |
|
||||
| `NB_GET_ACCOUNT_BUFFER_INTERVAL` | Account buffer interval duration |
|
||||
| `NB_SQL_MAX_OPEN_CONNS` | Maximum SQL database connections |
|
||||
@@ -182,6 +182,7 @@ These variables can override CLI flags at runtime. The naming convention is `NB_
|
||||
| `NB_LETSENCRYPT_DOMAINS` | - | Let's Encrypt domains |
|
||||
| `NB_LETSENCRYPT_EMAIL` | - | Let's Encrypt email |
|
||||
| `NB_HEALTH_LISTEN_ADDRESS` | - | Health check listen address |
|
||||
| `NB_TRUSTED_PROXIES` | - | Comma-separated IP addresses or CIDRs for immediate upstream proxies whose `X-Real-Ip` and `X-Real-Port` headers the relay may trust. Empty trusts no forwarding headers. |
|
||||
| `NB_ENABLE_STUN` | `false` | Enable embedded STUN server |
|
||||
| `NB_STUN_PORTS` | `3478` | STUN server UDP ports (comma-separated) |
|
||||
| `NB_STUN_LOG_LEVEL` | `info` | STUN server log level |
|
||||
|
||||
@@ -376,7 +376,7 @@ Default password requirements for local users:
|
||||
|
||||
- JWT tokens are issued upon successful authentication
|
||||
- Token expiration follows OIDC best practices
|
||||
- Device authorization flow available for CLI clients
|
||||
- Device authorization flow available for compatible clients by default. Administrators can disable it with [`server.auth.grantTypes`](/selfhosted/maintenance/configuration-files#authentication-settings).
|
||||
|
||||
### Audit Logging
|
||||
|
||||
|
||||
@@ -277,6 +277,9 @@ Configures the built-in identity provider (embedded IdP) that handles user authe
|
||||
<Property name="server.auth.cliRedirectURIs" type="array">
|
||||
Redirect URIs for CLI-based authentication. Default: `["http://localhost:53000/"]`. Used when authenticating via the `netbird` CLI tool.
|
||||
</Property>
|
||||
<Property name="server.auth.grantTypes" type="array">
|
||||
Restricts the OAuth2 grant types exposed by the embedded IdP. Leaving it unset preserves the Dex defaults. Common values are `authorization_code`, `refresh_token`, and `device_code`. Omit `device_code` to disable the device authorization flow while retaining browser-based authorization and refresh tokens.
|
||||
</Property>
|
||||
<Property name="server.auth.owner.email" type="string">
|
||||
Email address for the initial admin user. Optional. When set together with `owner.password`, the server creates this user on first startup with admin privileges.
|
||||
</Property>
|
||||
@@ -292,12 +295,33 @@ Configures the built-in identity provider (embedded IdP) that handles user authe
|
||||
|
||||
</Properties>
|
||||
|
||||
For example, disable the OAuth device flow while retaining dashboard/browser login and refresh tokens:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
auth:
|
||||
grantTypes:
|
||||
- authorization_code
|
||||
- refresh_token
|
||||
```
|
||||
|
||||
Restart `netbird-server` after changing the grant list. Verify that OIDC discovery still loads and that the device endpoint returns `404`:
|
||||
|
||||
```bash
|
||||
curl -fsS https://your-domain/oauth2/.well-known/openid-configuration
|
||||
curl -i -X POST https://your-domain/oauth2/device/code
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Disabling `device_code` prevents NetBird clients and other applications that depend on OAuth device authorization from completing that login flow. Confirm that your deployed clients can use the remaining authorization flow before disabling it.
|
||||
</Warning>
|
||||
|
||||
When the embedded IdP is active, the server automatically hosts these OIDC endpoints:
|
||||
|
||||
- **Discovery**: `https://your-domain/oauth2/.well-known/openid-configuration`
|
||||
- **JWKS (signing keys)**: `https://your-domain/oauth2/keys`
|
||||
- **Token issuance**: `https://your-domain/oauth2/token`
|
||||
- **Device authorization**: `https://your-domain/oauth2/device/authorize`
|
||||
- **Device authorization**: `https://your-domain/oauth2/device/code` when `device_code` is allowed
|
||||
|
||||
<Note>
|
||||
NetBird also supports integration with external OIDC-compatible identity providers for Single Sign-On (SSO), Multi-Factor Authentication (MFA), and centralized user management. See the [Authentication & IdPs page](/selfhosted/identity-providers) for configuration details.
|
||||
|
||||
@@ -363,6 +363,8 @@ Common requirements for every pool:
|
||||
| **Connection draining on rolling upgrade** | When you remove a backend, the LB should let in-flight gRPC streams and WebSocket connections finish before tearing them down. |
|
||||
| **Generous idle timeout** | Management gRPC streams and Relay WebSocket connections can be long-lived. Set the idle timeout above your peer-sync interval. Ten to 30 minutes is a comfortable range for both. |
|
||||
|
||||
For the Relay frontend, configure the load balancer to strip any client-supplied `X-Real-Ip` and `X-Real-Port`, then overwrite both headers from the validated client connection. Each Relay instance must trust only the load balancer addresses that connect directly to it, using `NB_TRUSTED_PROXIES`. Without that trust, forwarded client addresses are intentionally ignored.
|
||||
|
||||
For the full set of paths and protocols NetBird exposes to each load balancer, see [Configuration Files Reference](/selfhosted/maintenance/configuration-files).
|
||||
|
||||
If you're using a managed cloud load balancer, configure the equivalent of each row above using your provider's UI or infrastructure as code. If you're using a self-hosted reverse proxy, create one backend pool per service, attach health checks, and enable HTTP/2 or WebSocket support as appropriate for each pool.
|
||||
@@ -390,6 +392,7 @@ services:
|
||||
- NB_LISTEN_ADDRESS=:443
|
||||
- NB_EXPOSED_ADDRESS=rels://relay.example.com:443
|
||||
- NB_AUTH_SECRET=<shared secret, identical on every Relay instance and on the Management pool>
|
||||
- NB_TRUSTED_PROXIES=<Relay LB IP or CIDR; comma-separated if needed>
|
||||
- NB_ENABLE_STUN=true
|
||||
- NB_STUN_PORTS=3478
|
||||
```
|
||||
@@ -400,6 +403,7 @@ services:
|
||||
| `NB_AUTH_SECRET` | Yes | Shared with `server.relays.secret` in every Management replica's `config.yaml`. Must be byte-identical on every Relay instance and on every Management replica. |
|
||||
| `NB_LISTEN_ADDRESS` | Yes | The address the relay binds inside the container. |
|
||||
| `NB_LOG_LEVEL` | No | `debug`, `info` (default), `warn`, `error`. |
|
||||
| `NB_TRUSTED_PROXIES` | When preserving client addresses behind the LB | Comma-separated immediate load-balancer IPs or CIDRs allowed to supply `X-Real-Ip` and `X-Real-Port`. Both headers are required. The load balancer must strip client-supplied values and overwrite them from the validated connection. Never use broad, uncontrolled ranges. |
|
||||
| `NB_ENABLE_STUN` | No | Enables the embedded STUN server on UDP. |
|
||||
| `NB_STUN_PORTS` | No | STUN port (default `3478`). |
|
||||
|
||||
|
||||
@@ -42,6 +42,9 @@ NB_LISTEN_ADDRESS=:443
|
||||
NB_EXPOSED_ADDRESS=rels://relay-us.example.com:443
|
||||
NB_AUTH_SECRET=your-shared-secret-here
|
||||
|
||||
# Only when a reverse proxy or load balancer is directly in front of the relay
|
||||
# NB_TRUSTED_PROXIES=10.20.0.10,10.20.1.0/24
|
||||
|
||||
# TLS via Let's Encrypt (automatic certificate provisioning)
|
||||
NB_LETSENCRYPT_DOMAINS=relay-us.example.com
|
||||
NB_LETSENCRYPT_EMAIL=admin@example.com
|
||||
@@ -82,6 +85,22 @@ volumes:
|
||||
relay_data:
|
||||
```
|
||||
|
||||
## Running the Relay Behind a Proxy or Load Balancer
|
||||
|
||||
When a reverse proxy or load balancer terminates the Relay WebSocket connection, set `NB_TRUSTED_PROXIES` to the IP addresses or CIDRs of the proxies that connect **directly** to the relay:
|
||||
|
||||
```bash
|
||||
NB_TRUSTED_PROXIES=10.20.0.10,10.20.1.0/24
|
||||
```
|
||||
|
||||
The proxy must strip any client-supplied `X-Real-Ip` and `X-Real-Port`, then overwrite both headers with the address and source port from the validated client connection. The relay accepts those headers only when the immediate connection source matches the trusted list. If either header is missing, the list is empty, or the immediate source is not trusted, the relay ignores the headers and uses the direct connection address.
|
||||
|
||||
<Warning>
|
||||
Trust only the smallest proxy IP ranges you control. Do not trust `0.0.0.0/0`, `::/0`, or a shared network where untrusted systems can connect directly to the relay and forge forwarding headers. Invalid IP or CIDR entries prevent the relay from starting.
|
||||
</Warning>
|
||||
|
||||
The CLI equivalent is `--trusted-proxies`. Restart the relay after changing the list and check its startup logs for parsing errors.
|
||||
|
||||
## Alternative: TLS with Existing Certificates
|
||||
|
||||
If you have existing TLS certificates (e.g., from your own CA or a wildcard cert), replace the Let's Encrypt variables in `relay.env` with:
|
||||
|
||||
Reference in New Issue
Block a user