From 628f28a68d3fdd49cd934120e3377063be3ea8e5 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 7 Jul 2026 14:49:41 +0200 Subject: [PATCH 1/5] docs: recommend Linux routing peers for file-share workloads Add performance guidance to the Active Directory use case (Step 1 placement choice) and a performance trade-off note to Reach Services on the Routing Peer: Windows/macOS peers process the data path in userspace, and self-access delivery is slowest for reads, so a dedicated Linux routing peer is the fast default for SMB/DFS. --- .../manage/networks/use-cases/active-directory.mdx | 14 +++++++++----- .../reach-services-on-the-routing-peer.mdx | 6 ++++++ 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/src/pages/manage/networks/use-cases/active-directory.mdx b/src/pages/manage/networks/use-cases/active-directory.mdx index ff57d847..5fb56c0f 100644 --- a/src/pages/manage/networks/use-cases/active-directory.mdx +++ b/src/pages/manage/networks/use-cases/active-directory.mdx @@ -33,17 +33,21 @@ The domain controller is in almost every step: DNS (steps 1 and 3), the referral You rarely install the NetBird client on every server. Pick one of two shapes: -- **A dedicated routing peer at the site.** A separate machine runs the NetBird client and routes to the DC and file servers across the LAN. Natural when shares are spread across several servers. -- **The file server is the routing peer.** The NetBird client runs on the file server itself; the DC stays clientless behind it. Natural when one file server holds the shares. +- **A dedicated routing peer at the site.** A separate machine runs the NetBird client and routes to the DC and file servers across the LAN. Natural when shares are spread across several servers, and the fastest shape for file transfers. +- **The file server is the routing peer.** The NetBird client runs on the file server itself; the DC stays clientless behind it. Tempting when one file server holds the shares, because it saves a machine, but it is the slowest shape for exactly the traffic this guide is about (see the performance note below). -Most setups use a dedicated routing peer, and the rest of this guide assumes that. If the file server itself runs the client, only Step 2 changes — reach it via [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer) instead — while Steps 3–5 (routing the DC, its ports, and DNS) apply either way. +Use a dedicated routing peer, and make it a **Linux machine**: a small VM next to the servers is enough. The rest of this guide assumes that. If the file server itself runs the client, only Step 2 changes (reach it via [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer) instead), while Steps 3–5 (routing the DC, its ports, and DNS) apply either way. + + +**Why Linux, and why not the file server itself: performance.** A Linux routing peer forwards traffic in the kernel, so moving files through it costs the machine almost nothing. On Windows and macOS the NetBird client processes every packet in userspace instead: routing file-share traffic through a Windows peer caps throughput well below LAN speed and puts sustained CPU load on that machine. Running the client directly on a Windows file server compounds it, because traffic to the server's own LAN IP takes an extra internal delivery step that is slowest in the read direction — and reading is what opening and copying documents from a share is. Every shape works; they differ in how fast the same share feels to users. If remote users report documents opening much slower over NetBird than in the office, this choice is the first thing to check. + ## Step 2: Make the file server(s) reachable - **If a separate machine is the routing peer**, each file server is an ordinary host behind it. You will need: - a Network resource — a `/32`, or a domain resource set to its FQDN (e.g. `fileserver1.corp.example.com`) - an access control policy from your remote-users group to it on **TCP 445** (or whatever the service requires) -- **If the file server is the routing peer**, clients address it at its own LAN IP (the *self-access* case) — follow [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer). +- **If the file server is the routing peer**, clients address it at its own LAN IP (the *self-access* case) — follow [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer). This works, but it is the slowest shape for serving files; see the Step 1 performance note. If your DFS folders are spread across several file servers, route each one. Find the targets from a machine with the DFS Management tools (RSAT) installed: @@ -149,7 +153,7 @@ Both come from how Windows handles Kerberos logins, not from routing. Avoid them The whole setup is these pieces — create each one and domain login, shares, and DFS all work: -- **A routing peer** — a peer at the site that routes to the DC and file servers: a dedicated machine, or the file server itself. *(Step 1)* +- **A routing peer** — a peer at the site that routes to the DC and file servers: a dedicated Linux machine for the best file-transfer performance, or the file server itself. *(Step 1)* - **A route to the file server** — a Network resource (`/32` or FQDN, e.g. `fileserver1.corp.example.com`) for each share host. *(Step 2)* - **A route to the domain controller** — a Network resource (`/32` or `corp.example.com`). *(Step 3)* - **An access control policy to the file server** — on **TCP 445** (or whatever the service needs). *(Step 2)* diff --git a/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx b/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx index ae959369..5aa2a69a 100644 --- a/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx +++ b/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx @@ -1,7 +1,13 @@ +import { Note } from '@/components/mdx' + # Reach Services on the Routing Peer Most routing-peer guides cover reaching resources behind the peer. This one covers the opposite case: reaching a service that runs *on the routing peer itself*, at the peer's own LAN IP — the shape you get when the only machine running the NetBird client *is* the service host. The classic example is a file server that runs NetBird and serves SMB/DFS shares to remote users. + +**Performance trade-off.** This shape runs the entire data path inside the NetBird client on the service host. On Windows and macOS that path is userspace, and delivery to the peer's own LAN IP is slowest in the read direction: serving file contents out to users. It is fine for occasional access. For file-transfer-heavy workloads, such as everyday document shares, a dedicated Linux routing peer in front of the file server is several times faster and takes the load off the server; see [Step 1 of the Active Directory guide](/manage/networks/use-cases/active-directory#step-1-decide-where-the-net-bird-client-runs) for that shape. + + ## The scenario Every peer has two addresses: its **NetBird IP** (its `100.x` overlay address, the one in `netbird status`) and its **LAN IP** (its address on the local network). This case is about reaching a service at the peer's **LAN IP** — the address its name resolves to on the corporate network. From 4039db7eaa0b7fbcb2d99a6a9a5385978b72f39a Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 7 Jul 2026 14:51:53 +0200 Subject: [PATCH 2/5] docs: platform-split the self-access performance note Linux kernel-mode service hosts deliver to their own LAN IP at full speed; the read-direction penalty is specific to Windows/macOS userspace hosts. --- .../networks/use-cases/reach-services-on-the-routing-peer.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx b/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx index 5aa2a69a..8476e881 100644 --- a/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx +++ b/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx @@ -5,7 +5,7 @@ import { Note } from '@/components/mdx' Most routing-peer guides cover reaching resources behind the peer. This one covers the opposite case: reaching a service that runs *on the routing peer itself*, at the peer's own LAN IP — the shape you get when the only machine running the NetBird client *is* the service host. The classic example is a file server that runs NetBird and serves SMB/DFS shares to remote users. -**Performance trade-off.** This shape runs the entire data path inside the NetBird client on the service host. On Windows and macOS that path is userspace, and delivery to the peer's own LAN IP is slowest in the read direction: serving file contents out to users. It is fine for occasional access. For file-transfer-heavy workloads, such as everyday document shares, a dedicated Linux routing peer in front of the file server is several times faster and takes the load off the server; see [Step 1 of the Active Directory guide](/manage/networks/use-cases/active-directory#step-1-decide-where-the-net-bird-client-runs) for that shape. +**Performance depends on the service host's platform.** On a **Linux** service host (with the default kernel forwarding), this shape is fast: delivery to the peer's own LAN IP goes through the kernel and performs like any peer-to-peer connection, so a Linux file server or NAS can happily be its own routing peer. On **Windows and macOS** the NetBird client processes the data path in userspace, and delivery to the peer's own LAN IP is slowest in the read direction: serving file contents out to users. That is fine for occasional access, but for file-transfer-heavy workloads, such as everyday document shares on a Windows file server, a dedicated Linux routing peer in front of the server is several times faster and takes the load off it; see [Step 1 of the Active Directory guide](/manage/networks/use-cases/active-directory#step-1-decide-where-the-net-bird-client-runs) for that shape. ## The scenario From 8746547ee8739e73637f83e1c83cfe9e952dc1bc Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 7 Jul 2026 14:52:22 +0200 Subject: [PATCH 3/5] docs: scope the AD self-access caveat to Windows file servers --- src/pages/manage/networks/use-cases/active-directory.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/manage/networks/use-cases/active-directory.mdx b/src/pages/manage/networks/use-cases/active-directory.mdx index 5fb56c0f..b830a345 100644 --- a/src/pages/manage/networks/use-cases/active-directory.mdx +++ b/src/pages/manage/networks/use-cases/active-directory.mdx @@ -47,7 +47,7 @@ Use a dedicated routing peer, and make it a **Linux machine**: a small VM next t - **If a separate machine is the routing peer**, each file server is an ordinary host behind it. You will need: - a Network resource — a `/32`, or a domain resource set to its FQDN (e.g. `fileserver1.corp.example.com`) - an access control policy from your remote-users group to it on **TCP 445** (or whatever the service requires) -- **If the file server is the routing peer**, clients address it at its own LAN IP (the *self-access* case) — follow [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer). This works, but it is the slowest shape for serving files; see the Step 1 performance note. +- **If the file server is the routing peer**, clients address it at its own LAN IP (the *self-access* case) — follow [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer). This works, but on a Windows file server it is the slowest shape for serving files; see the Step 1 performance note. If your DFS folders are spread across several file servers, route each one. Find the targets from a machine with the DFS Management tools (RSAT) installed: From 31bc84e24842df627b3052c1456cec9d9bd754d7 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 7 Jul 2026 14:54:42 +0200 Subject: [PATCH 4/5] docs: drop read-direction specifics from performance notes The directional asymmetry is a suspected client defect under engineering escalation, not durable documented behavior. Keep only the kernel-vs-userspace guidance. --- src/pages/manage/networks/use-cases/active-directory.mdx | 2 +- .../networks/use-cases/reach-services-on-the-routing-peer.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/manage/networks/use-cases/active-directory.mdx b/src/pages/manage/networks/use-cases/active-directory.mdx index b830a345..b1090c13 100644 --- a/src/pages/manage/networks/use-cases/active-directory.mdx +++ b/src/pages/manage/networks/use-cases/active-directory.mdx @@ -39,7 +39,7 @@ You rarely install the NetBird client on every server. Pick one of two shapes: Use a dedicated routing peer, and make it a **Linux machine**: a small VM next to the servers is enough. The rest of this guide assumes that. If the file server itself runs the client, only Step 2 changes (reach it via [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer) instead), while Steps 3–5 (routing the DC, its ports, and DNS) apply either way. -**Why Linux, and why not the file server itself: performance.** A Linux routing peer forwards traffic in the kernel, so moving files through it costs the machine almost nothing. On Windows and macOS the NetBird client processes every packet in userspace instead: routing file-share traffic through a Windows peer caps throughput well below LAN speed and puts sustained CPU load on that machine. Running the client directly on a Windows file server compounds it, because traffic to the server's own LAN IP takes an extra internal delivery step that is slowest in the read direction — and reading is what opening and copying documents from a share is. Every shape works; they differ in how fast the same share feels to users. If remote users report documents opening much slower over NetBird than in the office, this choice is the first thing to check. +**Why Linux, and why not the file server itself: performance.** A Linux routing peer forwards traffic in the kernel, so moving files through it costs the machine almost nothing. On Windows and macOS the NetBird client processes every packet in userspace instead: routing file-share traffic through a Windows peer caps throughput well below LAN speed and puts sustained CPU load on that machine. Running the client directly on a Windows file server compounds it, because traffic to the server's own LAN IP takes an extra internal delivery step on top. Every shape works; they differ in how fast the same share feels to users. If remote users report documents opening much slower over NetBird than in the office, this choice is the first thing to check. ## Step 2: Make the file server(s) reachable diff --git a/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx b/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx index 8476e881..f1b7d4e9 100644 --- a/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx +++ b/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx @@ -5,7 +5,7 @@ import { Note } from '@/components/mdx' Most routing-peer guides cover reaching resources behind the peer. This one covers the opposite case: reaching a service that runs *on the routing peer itself*, at the peer's own LAN IP — the shape you get when the only machine running the NetBird client *is* the service host. The classic example is a file server that runs NetBird and serves SMB/DFS shares to remote users. -**Performance depends on the service host's platform.** On a **Linux** service host (with the default kernel forwarding), this shape is fast: delivery to the peer's own LAN IP goes through the kernel and performs like any peer-to-peer connection, so a Linux file server or NAS can happily be its own routing peer. On **Windows and macOS** the NetBird client processes the data path in userspace, and delivery to the peer's own LAN IP is slowest in the read direction: serving file contents out to users. That is fine for occasional access, but for file-transfer-heavy workloads, such as everyday document shares on a Windows file server, a dedicated Linux routing peer in front of the server is several times faster and takes the load off it; see [Step 1 of the Active Directory guide](/manage/networks/use-cases/active-directory#step-1-decide-where-the-net-bird-client-runs) for that shape. +**Performance depends on the service host's platform.** On a **Linux** service host (with the default kernel forwarding), this shape is fast: delivery to the peer's own LAN IP goes through the kernel and performs like any peer-to-peer connection, so a Linux file server or NAS can happily be its own routing peer. On **Windows and macOS** the NetBird client processes the data path in userspace, which limits file-transfer throughput and puts the load on the service host itself. That is fine for occasional access, but for file-transfer-heavy workloads, such as everyday document shares on a Windows file server, a dedicated Linux routing peer in front of the server is several times faster and takes the load off it; see [Step 1 of the Active Directory guide](/manage/networks/use-cases/active-directory#step-1-decide-where-the-net-bird-client-runs) for that shape. ## The scenario From dcdeaf5c3d40304121d3fc61a0f09f13cef770a8 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 7 Jul 2026 15:29:24 +0200 Subject: [PATCH 5/5] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20dedu?= =?UTF-8?q?pe=20performance=20guidance,=20fix=20note=20placement?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AD page: performance point stated once (Step 1 note, linking how-routing-peers-work for the mechanism); bullets and recap trimmed; Step 1 bullet now carries the Windows qualifier - reach-services: note compressed to consequence + links, moved below The scenario where LAN IP and the shape are defined --- .../manage/networks/use-cases/active-directory.mdx | 10 +++++----- .../use-cases/reach-services-on-the-routing-peer.mdx | 8 ++++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/pages/manage/networks/use-cases/active-directory.mdx b/src/pages/manage/networks/use-cases/active-directory.mdx index b1090c13..df8ebf0c 100644 --- a/src/pages/manage/networks/use-cases/active-directory.mdx +++ b/src/pages/manage/networks/use-cases/active-directory.mdx @@ -33,13 +33,13 @@ The domain controller is in almost every step: DNS (steps 1 and 3), the referral You rarely install the NetBird client on every server. Pick one of two shapes: -- **A dedicated routing peer at the site.** A separate machine runs the NetBird client and routes to the DC and file servers across the LAN. Natural when shares are spread across several servers, and the fastest shape for file transfers. -- **The file server is the routing peer.** The NetBird client runs on the file server itself; the DC stays clientless behind it. Tempting when one file server holds the shares, because it saves a machine, but it is the slowest shape for exactly the traffic this guide is about (see the performance note below). +- **A dedicated routing peer at the site.** A separate machine runs the NetBird client and routes to the DC and file servers across the LAN. Natural when shares are spread across several servers. +- **The file server is the routing peer.** The NetBird client runs on the file server itself; the DC stays clientless behind it. Saves a machine, but on a Windows server it costs file-transfer performance (see the note below). Use a dedicated routing peer, and make it a **Linux machine**: a small VM next to the servers is enough. The rest of this guide assumes that. If the file server itself runs the client, only Step 2 changes (reach it via [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer) instead), while Steps 3–5 (routing the DC, its ports, and DNS) apply either way. -**Why Linux, and why not the file server itself: performance.** A Linux routing peer forwards traffic in the kernel, so moving files through it costs the machine almost nothing. On Windows and macOS the NetBird client processes every packet in userspace instead: routing file-share traffic through a Windows peer caps throughput well below LAN speed and puts sustained CPU load on that machine. Running the client directly on a Windows file server compounds it, because traffic to the server's own LAN IP takes an extra internal delivery step on top. Every shape works; they differ in how fast the same share feels to users. If remote users report documents opening much slower over NetBird than in the office, this choice is the first thing to check. +**Why Linux: performance.** A Linux routing peer forwards traffic in the kernel at almost no cost; Windows and macOS peers process every packet in userspace, which caps file-transfer throughput well below LAN speed and loads the machine (see [How Routing Peers Work](/manage/networks/how-routing-peers-work)). Running the client directly on a Windows file server adds an extra internal delivery step on top. If remote users report documents opening much slower over NetBird than in the office, this choice is the first thing to check. ## Step 2: Make the file server(s) reachable @@ -47,7 +47,7 @@ Use a dedicated routing peer, and make it a **Linux machine**: a small VM next t - **If a separate machine is the routing peer**, each file server is an ordinary host behind it. You will need: - a Network resource — a `/32`, or a domain resource set to its FQDN (e.g. `fileserver1.corp.example.com`) - an access control policy from your remote-users group to it on **TCP 445** (or whatever the service requires) -- **If the file server is the routing peer**, clients address it at its own LAN IP (the *self-access* case) — follow [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer). This works, but on a Windows file server it is the slowest shape for serving files; see the Step 1 performance note. +- **If the file server is the routing peer**, clients address it at its own LAN IP (the *self-access* case) — follow [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer). If your DFS folders are spread across several file servers, route each one. Find the targets from a machine with the DFS Management tools (RSAT) installed: @@ -153,7 +153,7 @@ Both come from how Windows handles Kerberos logins, not from routing. Avoid them The whole setup is these pieces — create each one and domain login, shares, and DFS all work: -- **A routing peer** — a peer at the site that routes to the DC and file servers: a dedicated Linux machine for the best file-transfer performance, or the file server itself. *(Step 1)* +- **A routing peer** — a peer at the site that routes to the DC and file servers: a dedicated Linux machine, or the file server itself. *(Step 1)* - **A route to the file server** — a Network resource (`/32` or FQDN, e.g. `fileserver1.corp.example.com`) for each share host. *(Step 2)* - **A route to the domain controller** — a Network resource (`/32` or `corp.example.com`). *(Step 3)* - **An access control policy to the file server** — on **TCP 445** (or whatever the service needs). *(Step 2)* diff --git a/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx b/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx index f1b7d4e9..47568f8f 100644 --- a/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx +++ b/src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx @@ -4,10 +4,6 @@ import { Note } from '@/components/mdx' Most routing-peer guides cover reaching resources behind the peer. This one covers the opposite case: reaching a service that runs *on the routing peer itself*, at the peer's own LAN IP — the shape you get when the only machine running the NetBird client *is* the service host. The classic example is a file server that runs NetBird and serves SMB/DFS shares to remote users. - -**Performance depends on the service host's platform.** On a **Linux** service host (with the default kernel forwarding), this shape is fast: delivery to the peer's own LAN IP goes through the kernel and performs like any peer-to-peer connection, so a Linux file server or NAS can happily be its own routing peer. On **Windows and macOS** the NetBird client processes the data path in userspace, which limits file-transfer throughput and puts the load on the service host itself. That is fine for occasional access, but for file-transfer-heavy workloads, such as everyday document shares on a Windows file server, a dedicated Linux routing peer in front of the server is several times faster and takes the load off it; see [Step 1 of the Active Directory guide](/manage/networks/use-cases/active-directory#step-1-decide-where-the-net-bird-client-runs) for that shape. - - ## The scenario Every peer has two addresses: its **NetBird IP** (its `100.x` overlay address, the one in `netbird status`) and its **LAN IP** (its address on the local network). This case is about reaching a service at the peer's **LAN IP** — the address its name resolves to on the corporate network. @@ -19,6 +15,10 @@ Remote user ──tunnel──► File server = routing peer (its own SMB/DFS s (NetBird) └──► Domain Controller (clientless, on the same LAN) ``` + +**Performance.** On a Linux service host this shape serves at full speed — a Linux file server or NAS can happily be its own routing peer. On Windows and macOS the client's data path runs in userspace, which limits file-transfer throughput; for busy shares on a Windows server, a dedicated Linux routing peer in front is the faster shape (see [Step 1 of the Active Directory guide](/manage/networks/use-cases/active-directory#step-1-decide-where-the-net-bird-client-runs)). + + ## The setup The target *is* the routing peer, addressed by its own LAN IP. Set up the following together: