mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-23 02:46:35 +00:00
aa11529511
* update slack url and twitter use a dedicated url for slack, allowing update in a single place rename Twitter references to X * rollback Install NetBird title in navigation menu
86 lines
4.2 KiB
Plaintext
86 lines
4.2 KiB
Plaintext
import {Note} from "@/components/mdx";
|
||
|
||
# Lazy Connections
|
||
NetBird now includes an experimental 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.
|
||
|
||
<Note>
|
||
Minimum supported agent version: <strong>v0.45.0</strong>.
|
||
This or higher version must also be installed on the peers you are trying to access for lazy connections to function.
|
||
</Note>
|
||
|
||
<Note>
|
||
This feature also requires an upgraded NetBird Management server.
|
||
If you're self-hosting NetBird, ensure your server is updated to version <strong>v0.45.0</strong>, which adds support for lazy connections.
|
||
</Note>
|
||
|
||
<Note>
|
||
This feature is currently under active development and will continue to evolve. Future releases will enhance disconnection logic and add support for accessing resources through routing peers, which is not yet available.
|
||
</Note>
|
||
|
||
## What Are Lazy Connections?
|
||
|
||
When enabled, lazy connections allow the NetBird agent to:
|
||
|
||
- 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 routers or excluded peers) **always connected** to ensure uninterrupted communication.
|
||
|
||
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.
|
||
|
||
<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>
|
||
|
||
|
||
### How Automatic Disconnection Works
|
||
|
||
Once a connection between two peers is established, it will remain open **as long as the remote peer is reachable**. The connection is **not** closed just because there is no data transfer.
|
||
|
||
In other words, the inactivity timer only triggers a disconnect if the peer is both <em>inactive</em> and <em>unreachable</em> for the full duration of the threshold.
|
||
|
||
<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.
|
||
</Note>
|
||
|
||
Additionally, the disconnection logic is being improved and will be enhanced in future releases to better support mobile devices—providing more intelligent reconnection behavior and improved handling of intermittent connectivity.
|
||
|
||
## Enabling Lazy Connections on agent
|
||
|
||
Lazy connections are disabled by default. You can enable Lazy Connections using the following environment variable:
|
||
|
||
```bash
|
||
export NB_ENABLE_EXPERIMENTAL_LAZY_CONN=true
|
||
```
|
||
|
||
Or pass the flag directly via the CLI when running the agent:
|
||
|
||
```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).
|
||
</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
|
||
<p float="center" >
|
||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
|
||
</p>
|
||
|
||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||
- Follow us [on X](https://x.com/netbird)
|
||
- Join our [Slack Channel](/slack-url)
|
||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|