From ce4151c551e751746e06201c8185f902dc6ee6c2 Mon Sep 17 00:00:00 2001
From: Zoltan Papp <zoltan.pmail@gmail.com>
Date: Wed, 21 May 2025 11:18:15 +0200
Subject: [PATCH] Add lazy connection page (#317)

* Add lazy connection page

* Update based on feedback

* Add note about future developments

* Fix URL

* Add to the navigation
---
 src/components/NavigationDocs.jsx    |  1 +
 src/pages/how-to/lazy-connection.mdx | 80 ++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 src/pages/how-to/lazy-connection.mdx

diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx
index 7e3514b2..09efdc0a 100644
--- a/src/components/NavigationDocs.jsx
+++ b/src/components/NavigationDocs.jsx
@@ -48,6 +48,7 @@ export const docsNavigation = [
                  { title: 'Add Peers', href: '/how-to/add-machines-to-your-network' },
                  { title: 'Approve Peers', href: '/how-to/approve-peers' },
                  { title: 'Setup Keys', href: '/how-to/register-machines-using-setup-keys' },
+                 { title: 'Lazy connections concept', href: '/how-to/lazy-connection'},
                  {
                      title: 'Access Infrastructure',
                      isOpen: true,
diff --git a/src/pages/how-to/lazy-connection.mdx b/src/pages/how-to/lazy-connection.mdx
new file mode 100644
index 00000000..c703dbd7
--- /dev/null
+++ b/src/pages/how-to/lazy-connection.mdx
@@ -0,0 +1,80 @@
+import {Note} from "@/components/mdx";
+
+# Overview
+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>
+</Note>
+
+<Note>
+    <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.
+</Note>
+
+
+## What Are Lazy Connections?
+
+When enabled, Lazy Connections allow the NetBird agent to:
+
+- Establish peer-to-peer connections **only when required** (e.g., when ping the 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
+
+Lazy connections are disabled by default. To enable them:
+
+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>
+
+### Platform-Specific Examples
+For platform-specific examples of how to configure this:
+
+- [See Windows example](/how-to/troubleshooting-client#windows)
+- [See Linux with systemd example](/how-to/troubleshooting-client#on-linux-with-systemd)
+
+
+
+
+## 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 Twitter](https://twitter.com/netbird)
+- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-31rofwmxc-27akKd0Le0vyRpBcwXkP0g)
+- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub