Skip to content

Commit 09b3a37

Browse files
pappzbraginini
andauthored
Explain lazy connection enable-disable logic (#321)
* Explain lazy connection enable-disable logic * Change text * Add line break * Improve lazy connections doc * Improve lazy connections doc * Clarify lazy connections versioning --------- Co-authored-by: braginini <[email protected]>
1 parent ce4151c commit 09b3a37

File tree

2 files changed

+21
-16
lines changed

2 files changed

+21
-16
lines changed

src/components/NavigationDocs.jsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ export const docsNavigation = [
4848
{ title: 'Add Peers', href: '/how-to/add-machines-to-your-network' },
4949
{ title: 'Approve Peers', href: '/how-to/approve-peers' },
5050
{ title: 'Setup Keys', href: '/how-to/register-machines-using-setup-keys' },
51-
{ title: 'Lazy connections concept', href: '/how-to/lazy-connection'},
51+
{ title: 'Lazy Connections', href: '/how-to/lazy-connection'},
5252
{
5353
title: 'Access Infrastructure',
5454
isOpen: true,

src/pages/how-to/lazy-connection.mdx

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,29 @@
11
import {Note} from "@/components/mdx";
22

3-
# Overview
3+
# Lazy Connections
44
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.
55

66
This guide walks you through enabling and configuring this feature in your NetBird client.
77

88
<Note>
9-
Minimum supported agent version: <strong>v0.45.0</strong>
9+
Minimum supported agent version: <strong>v0.45.0</strong>.
10+
This or higher version must also be installed on the peers you are trying to access for lazy connections to function.
1011
</Note>
1112

1213
<Note>
13-
<strong>Self-hosted only:</strong> This feature also requires an upgraded NetBird management server. Make sure your server is updated to the <strong>v0.45.0</strong> version that supports lazy connections.
14+
This feature also requires an upgraded NetBird Management server.
15+
If you're self-hosting NetBird, ensure your server is updated to version <strong>v0.45.0</strong>, which adds support for lazy connections.
1416
</Note>
1517

18+
<Note>
19+
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.
20+
</Note>
1621

1722
## What Are Lazy Connections?
1823

19-
When enabled, Lazy Connections allow the NetBird agent to:
24+
When enabled, lazy connections allow the NetBird agent to:
2025

21-
- Establish peer-to-peer connections **only when required** (e.g., when ping the remote peer).
26+
- Establish peer-to-peer connections **only when needed** (e.g., when pinging a remote peer).
2227
- Monitor peer activity and **automatically disconnect peers** that remain inactive **and unreachable** for a specified time.
2328
- Keep critical peers (such as routers or excluded peers) **always connected** to ensure uninterrupted communication.
2429

@@ -41,11 +46,9 @@ In other words, the inactivity timer only triggers a disconnect if the peer is b
4146

4247
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.
4348

44-
## Enabling Lazy Connections
45-
46-
Lazy connections are disabled by default. To enable them:
49+
## Enabling Lazy Connections on agent
4750

48-
You can enable Lazy Connections using the following environment variable:
51+
Lazy connections are disabled by default. You can enable Lazy Connections using the following environment variable:
4952

5053
```bash
5154
export NB_ENABLE_EXPERIMENTAL_LAZY_CONN=true
@@ -56,18 +59,20 @@ Or pass the flag directly via the CLI when running the agent:
5659
```bash
5760
netbird up --enable-lazy-connection
5861
```
59-
<Note>
62+
<Note>
6063
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).
6164
</Note>
6265

63-
### Platform-Specific Examples
64-
For platform-specific examples of how to configure this:
65-
66-
- [See Windows example](/how-to/troubleshooting-client#windows)
67-
- [See Linux with systemd example](/how-to/troubleshooting-client#on-linux-with-systemd)
66+
## Enabling Lazy Connections in the NetBird Dashboard
6867

68+
The lazy connection feature can also be configured through the NetBird Dashboard. Here’s how it works once the setting is updated:
6969

70+
Setting enabled:
71+
* The client’s lazy connection manager is now active. Existing peer connections and ongoing connection attempts will remain unchanged for one hour.
72+
After that, any connection that couldn't be established due to unavailable remote peers will transition to an idle state.
7073

74+
Setting disabled:
75+
* The lazy connection manager is now disabled. The client will immediately attempt to establish connections with all remote peers.
7176

7277
## Get started
7378
<p float="center" >

0 commit comments

Comments
 (0)