mirror of
https://github.com/netbirdio/docs.git
synced 2026-10-18 03:29:03 +02:00
Updates for the NetBird 0.75 update (#881)
This commit is contained in:
PizzaLovingNerd
@@ -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>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user