sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-08-24 16:51:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: routing-peer self-access + Active Directory guides, and DNS/routing-peer clarifications (#796)

Browse Source 
* docs: add routing-peer self-access and Active Directory guides

New use-case guides: reaching a service on a routing peer's own LAN IP
(route + peer-to-peer policy + NB_ENABLE_LOCAL_FORWARDING) and an
end-to-end Active Directory / Windows file shares guide over NetBird.

Clarify domain-resource DNS: with Routing Peer DNS Resolution on, the
routing peer answers the client's A/AAAA lookups (a domain resource
matches the exact name; use a wildcard for hostnames under a domain),
but AD still needs a nameserver group for the SRV/DC-locator records.

Add navigation entries, overlay-vs-LAN-IP notes, and ICMP/ping
troubleshooting guidance.

* docs: fix WireGuard anchor slug and sharpen local-forwarding caution

The #why-wireguard-with-netbird anchor doesn't resolve — the heading
slugifies to #why-wire-guard-with-net-bird (decamelized). Fix it in the
networks intro and the netbird-vs-traditional-vpn self-link.

Clarify the NB_ENABLE_LOCAL_FORWARDING caution: with it on, any permitted
peer can reach services bound to the routing peer's own addresses,
including 127.0.0.1, at the peer's NetBird IP.

* docs: polish routing-peer and Active Directory guides

- Correct the DC policy note: TCP/UDP need separate policies because a
  policy carries one protocol, not because of a first-rule limitation
- Make internal-dns-servers the canonical A/AAAA-vs-SRV explanation;
  collapse the three duplicates to one-line pointers
- Trim emphatic bold to enumerated requirements, ports, and flags
- Reduce em-dash density and clarify the routing-peer SSH-management
  and HA cautions in the AD guide

* docs: make Active Directory guide clearer for junior admins

- Rewrite the Verify section to explain why (test as the signed-in
  domain user, port 445 vs ping, name vs IP) instead of assuming
  ICMP/Kerberos/NTLM knowledge
- Clarify the SSH-management and HA cautions in Step 3
- Note Get-DfsnFolderTarget needs the DFS Management tools (RSAT),
  not just any domain-joined machine
- Reduce em-dash density throughout

* docs: Routing Peer DNS Resolution applies to all domain resources, not just wildcards

* docs: refine Active Directory guide and nameserver terminology

- Step 3 DC ports as a Port/Protocol/Needed-for table; promote 123
  (time sync) and 464 (kpasswd) into the baseline
- DFS step: derive each target server's FQDN for the domain resource
- order the agent-placement and reachability shapes consistently
  (dedicated routing peer first)
- drop the niche SSH-wedge caution and the premature masquerade note
- tie the ping/ICMP caveat to the port-scoped policies
- use "Nameserver" + "match domain" (the UI term) instead of
  "nameserver group" across the AD, internal-DNS, and reach-services pages

* docs: scope the local-forwarding caution — loopback exposure is netstack-only

Reaching the routing peer's own 127.0.0.1-bound services via its NetBird IP
only happens on netstack-mode peers; on userspace-TUN (Windows/macOS) it does
not (verified), and Linux kernel mode is a no-op. The general "exposes own
addresses" caution stands; drop the over-broad 127.0.0.1/localhost specifics.

* docs: trim DC-through-routing-peer section to the DNS-only reason and reorder AD subsections

Drop the setup-flavored framing from 'Reaching a Domain Controller
through a routing peer' (it lives on the AD use-case page), keeping the
DNS reference fact: A/AAAA resolves on the routing peer but SRV/DC-locator
records don't, so AD still needs a nameserver to the DC. Heading text is
unchanged so the existing anchor still resolves. Reorder the AD & Domain
Controllers subsections to lead with the recommended case (reach the DC
through a separate routing peer), then the discouraged DC-as-routing-peer
path, then its WireGuard port-conflict troubleshooting.

* docs: drop redundant cross-link from AD Step 4 nameserver note

The note already explains why a domain resource doesn't remove the
nameserver requirement (SRV/DC-locator records). The trailing link to the
DNS page's 'Reaching a Domain Controller through a routing peer' section
just repeated that fact and linked back here, bouncing the reader. Step 4
already links to Internal DNS Servers for the general setup.

* docs: restructure AD routing-peer guidance — least-privilege tiers, DC route/policy split, de-loop cross-links

Active Directory & Windows File Shares:
- Add a TL;DR linking to a new 'The four settings' checklist at the bottom.
- Split Step 3 into Step 3 (route the DC) and Step 4 (allow the AD ports);
  DNS becomes Step 5. Keeps the route distinct from the access policies.
- Step 2: break each routing-peer case into sub-bullets of what's needed;
  point the self-access case to Reach Services on the Routing Peer.
- Step 3: present /32 or apex domain as the granular default and the
  *.corp.example.com wildcard as the least-privilege opt-in — and spell out
  the wildcard's one-policy-scope cost (uniform ports across the whole domain).

Reach Services on the Routing Peer:
- Tighten the setup steps; concrete DNS-nameserver instruction for AD/DFS;
  state the Linux kernel-mode default for NB_ENABLE_LOCAL_FORWARDING.
- 'recipe' -> 'setup' throughout.

Internal DNS Servers:
- Clarify nameserver vs plain share: A/AAAA via the routing peer needs no
  nameserver; AD needs one for SRV records and because the resolver won't
  fall back. Distribute the nameserver to the routing peer's group *and*
  client groups that resolve directly; only when the peer can't resolve on
  its own. Reorder AD subsections; fix the overbroad distribution note.

How Routing Peers Work / cross-links:
- Remove redundant/circular cross-links across the four pages (the
  HRPW -> Internal DNS -> Active Directory -> HRPW loop).

* docs: use "NetBird client"/"clientless" wording in AD and self-access guides

Replace 'the agent'/'agentless' with the preferred 'NetBird client'/'clientless' terms, and add the missing blank line before the Step 2 heading.

* docs: lower altitude of routing-peer/AD guides for junior admins

- Unify the overlay address as 'NetBird IP' and the local one as 'LAN IP' across the routing-peer/DNS pages; add a 2-line two-address primer to the two crux pages.
- Replace the dense userspace/netstack/kernel forwarding sentence with a platform table framed to the self-access case, plus a netstack-override footnote.
- Demote the wildcard policy-scope trade-off in the AD guide to a Note, keeping the granular-first nudge in the main flow.
- Split the 'Reaching a DC through a routing peer' paragraph into what-it-needs / why-a-domain-resource-isn't-enough bullets.
- De-duplicate the self-access section: it now owns the mental model and points to the use-case page for the concrete setup.

* docs: clarify the forwarding section for junior admins

- Disambiguate NB_ENABLE_LOCAL_FORWARDING from the IP-forwarding sysctl by naming the setting explicitly before the table.
- Split local forwarding into its own '### Local forwarding' subheading, distinct from '### IP forwarding'; repoint the #local-forwarding cross-link.
- Drop the netstack-specific override footnote — edge-case reference material that doesn't help the target reader (the row already names the correct flag).

* docs: apply review feedback to routing-peer/AD guides

- AD Step 4: list the AD ports per TCP/UDP access control policy instead of a dense one-rule-per-policy sentence; add 123 to the four-settings recap.
- De-duplicate the route+policy+local-forwarding triad within how-routing-peers-work (Local forwarding now points to the canonical statement); render the LAN-IP requirements as a sub-list.
- Plain-language rewrite of why a domain resource isn't enough for AD DNS.
- Qualify Global Catalog 3268/3269 to multi-domain forests; state the default branch in AD Step 1.
- Fix the Networks Tiles description to say 'NetBird client', not 'agent'.
- Add DNS troubleshooting Issue 7 for the AD symptom (login/DFS fails but file-by-IP works), cross-linked to the AD guide and the DC section.

* docs: recast AD "four settings" as an explicit NetBird config checklist

Rename the summary to 'What you configure in NetBird' and list the discrete NetBird objects: routing peer, a route (resource) to the file server and to the DC, separate access control policies for each, and a DNS nameserver. Keep the full AD port set in Step 4 only; update the TL;DR link to the new (decamelized) anchor.

* docs: clarify the self-access setup steps

- Identify NB_ENABLE_LOCAL_FORWARDING as an environment variable and link the Client Environment Variables reference.
- Front-load the platform on step 3 (Windows/macOS need the flag; Linux kernel forwarding doesn't, only netstack) and soften the 'all three required' framing accordingly.
- Explain that steps 1 and 3 exist only because clients reach the file server at its LAN IP; reaching a peer at its NetBird IP needs only the policy.
This commit is contained in:
Jack Carter
2026-06-19 16:23:49 +02:00
committed by GitHub
parent fb4c110df3
commit 0653cacbbd
8 changed files with 308 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
src/components/NavigationDocs.jsx
View File

@@ -222,6 +222,14 @@ export const docsNavigation = [
title: 'Site-to-Site',
href: '/manage/networks/use-cases/site-to-site',
},
{
title: 'Reach Services on the Routing Peer',
href: '/manage/networks/use-cases/reach-services-on-the-routing-peer',
},
{
title: 'Active Directory & Windows File Shares',
href: '/manage/networks/use-cases/active-directory',
},
],
},
],

2
src/pages/about-netbird/netbird-vs-traditional-vpn.mdx
View File

@@ -25,7 +25,7 @@ To achieve this, NetBird client applications employ signalling servers to find o
These are similar to the signaling servers used in [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling#the_signaling_server)
Thanks to [NAT traversal techniques](https://en.wikipedia.org/wiki/NAT_traversal),
outlined in the [Why WireGuard with NetBird](#why-wireguard-with-netbird) section below,
outlined in the [Why WireGuard with NetBird](#why-wire-guard-with-net-bird) section below,
NetBird installation doesn't require complex network and firewall configuration.
It just works, minimising the maintenance effort.

36
src/pages/manage/dns/internal-dns-servers.mdx
View File

@@ -9,30 +9,33 @@ When your network has on-premise DNS infrastructure — Active Directory, BIND,
If you just need access to a few internal resources by domain name, you don't need to configure a nameserver. Create a [Network resource](/manage/networks) with the internal domain name (e.g., `fileserver.corp.local`) and an [access control policy](/manage/access-control/manage-network-access) allowing your peers to reach it. The routing peer will resolve the DNS and route traffic to that resource. This works as long as the routing peer itself can resolve the domain.
You can also use wildcard domains as resources (e.g., `*.corp.local`), but this will route all traffic to those domains through the routing peer. For more granular access to resources, we recommend using single domain names.
A domain resource matches the **exact name** you enter: `fileserver.corp.local` covers that one host, **not** other names under `corp.local`. To reach many hostnames under a domain — several servers, or names you can't list in advance — use a **wildcard** resource such as `*.corp.local`, which matches every subdomain. A wildcard routes all of those names through the routing peer, so when you only need a handful of hosts, prefer listing them as specific resources.
## Domain Resources and Routing Peer DNS
<Note>
For the mental model — see [How Routing Peers Work — Routing Peer DNS Resolution](/manage/networks/how-routing-peers-work#routing-peer-dns-resolution).
</Note>
When you define a [Network resource](/manage/networks) using a domain name (e.g., `crm.corp.local`), the **routing peer** resolves that domain using its own local DNS configuration. The client sends DNS queries to the routing peer, which looks up the domain and returns the result.
When you define a [Network resource](/manage/networks) using a domain name (e.g., `crm.corp.local`), the **routing peer** resolves that domain using its own local DNS configuration. With **[Routing Peer DNS Resolution](/manage/networks/how-routing-peers-work#routing-peer-dns-resolution)** enabled (the default), the client sends its DNS queries for that domain to the routing peer, which looks up the domain and returns the result — so the client needs no nameserver of its own to resolve that name.
This means the routing peer must be able to resolve the domain. If it can't — for example, a Linux routing peer that isn't configured to use your Active Directory DNS — domain resource lookups will fail.
To fix this, add the **routing peer's group** as a distribution group on the internal Nameserver:
<Note>
This covers ordinary name-to-IP lookups (**A/AAAA** records) for the resource's own domain. Two cases still need a nameserver configured on the client:
- **Routing Peer DNS Resolution is disabled.** It's on by default, but can be turned off per account. With it off, the client resolves the name itself instead of asking the routing peer — so point the client at your internal DNS with a nameserver (or its network adapter's DNS).
- **Active Directory.** A domain-joined client always needs a nameserver (`corp.example.com` → the DC), no matter how this setting is configured — see [Active Directory & Windows File Shares](/manage/networks/use-cases/active-directory).
</Note>
To fix this, add the **routing peer's group** to the internal Nameserver's distribution groups — along with any client groups that resolve these names directly (Active Directory clients always do):
1. Go to **DNS** → **Nameservers**
2. Edit your internal DNS nameserver (or create one if it doesn't exist)
3. Add the **routing peer's group** to the **Distribution Groups**
4. Under **Domains**, ensure your internal domains are listed (e.g., `corp.local`)
3. Under **Domains**, ensure your internal domains are listed (e.g., `corp.local`)
4. Add the **routing peer's group** — plus any client groups that resolve these names directly — to the **Distribution Groups**
5. Save
This ensures the routing peer receives the nameserver configuration and can resolve internal domains on behalf of clients.
<Note>
This applies to all domain-based resources, not just Active Directory domains. Any routing peer that needs to resolve internal domain names must have the corresponding nameserver distributed to its group.
This applies to any domain-based resource, not just Active Directory. And the routing peer doesn't have to get the nameserver from NetBird — if it already resolves the domain through its own DNS (a domain-joined file server usually does), no distribution is needed. Add the nameserver to the peer's group only when it can't resolve the domain on its own.
</Note>
## Configuring Nameservers for Internal Domains
@@ -157,6 +160,19 @@ Before deleting a primary nameserver, create a new primary first, or peers will
Active Directory (AD) environments have specific DNS requirements because Domain Controllers (DCs) run their own DNS services and rely on DNS for core AD functionality like domain joins, authentication, and service discovery.
<Note>
Setting up remote access to AD file shares, DFS, and domain login end to end? See the [Active Directory & Windows File Shares](/manage/networks/use-cases/active-directory) guide — it ties together the routing, DNS, and Kerberos pieces into a single setup. The sections below are the DNS reference behind it.
</Note>
### Reaching a Domain Controller through a routing peer
With [Routing Peer DNS Resolution](/manage/networks/how-routing-peers-work#routing-peer-dns-resolution) on (the default), a domain resource is enough for a plain file share — the routing peer resolves its name-to-IP (`A`/`AAAA`) lookup. **Active Directory needs more:**
- **What it needs** — a domain-joined client needs a **nameserver** (`corp.example.com` → the DC) for the `SRV` / DC-locator records that logon and DFS depend on. It only works once the DC itself is reachable through the peer.
- **Why a domain resource isn't enough** — the routing peer serves only `A`/`AAAA`, not `SRV` / DC-locator records. And once it's the client's resolver for the domain, the client stops asking anywhere else — it won't separately query the DC for the records it's missing. So a plain domain resource silently leaves out exactly the records AD login and DFS need.
This is the same on Windows and Linux clients.
### Domain Controllers as Routing Peers
We do not recommend using Domain Controllers as routing peers. If you must, you need to **disable DNS management** for the DC's group. If NetBird manages DNS on a Domain Controller, it can interfere with the AD DNS services that the DC depends on.

24
src/pages/manage/dns/troubleshooting.mdx
View File

@@ -1,9 +1,15 @@
import { Note } from '@/components/mdx'
export const description = 'Diagnose and fix common DNS issues in NetBird'
# DNS Troubleshooting
This guide helps you diagnose and resolve common DNS issues in NetBird. Follow the structured approach below to identify and fix problems quickly.
<Note>
The steps below use `ping` to check reachability. `ping` requires an **ICMP** peer-to-peer policy — when testing through or to a [routing peer](/manage/networks/how-routing-peers-work), name resolution and TCP can be healthy while ICMP is simply not allowed by policy. Prefer a TCP port test there: `Test-NetConnection <host> -Port <port>` (Windows) or `nc -z <host> <port>`.
</Note>
## Quick Diagnostics Checklist
Before diving deep, run through this quick checklist:
@@ -449,6 +455,24 @@ config domain
---
### Issue 7: Active Directory Login or DFS Fails (but a file share by IP works)
**Symptoms**:
- Domain login, mapped drives, or DFS paths fail for remote users — yet the file server is reachable by IP
- Errors like *"the specified domain is not available"*, or System error 1311 / 1312
- `nslookup -type=srv _ldap._tcp.dc._msdcs.corp.example.com` returns nothing
**Diagnosis**:
A domain resource only resolves `A`/`AAAA` records. Active Directory also depends on the `SRV` / DC-locator records that *find a domain controller* — which the routing peer does not serve. So a client can resolve a host by name but can't locate a DC, and logon and DFS referrals fail even though plain name-to-IP resolution works.
**Solutions**:
- Add a **DNS nameserver** with match domain `corp.example.com` pointing at the DC's IP, distributed to your remote-users group — see [Active Directory & Windows File Shares → Give clients corp DNS](/manage/networks/use-cases/active-directory#step-5-give-clients-corp-dns).
- Confirm the DC itself is reachable through the routing peer on the AD ports — see [Reaching a Domain Controller through a routing peer](/manage/dns/internal-dns-servers#reaching-a-domain-controller-through-a-routing-peer).
---
## Verifying Configuration
### Public nameservers

36
src/pages/manage/networks/how-routing-peers-work.mdx
View File

@@ -45,7 +45,7 @@ The walkthrough below describes the **Linux kernel-mode** path, where forwarding
1. The originating peer encrypts the packet to the routing peer's WireGuard public key. The packet enters the tunnel at the source and exits on the routing peer's NetBird interface.
2. The routing peer's kernel forwards the packet according to the host routing table. If the destination is on a directly attached network or reachable via the host's gateway, the packet is forwarded.
3. Forwarded packets traverse the host firewall's **forward chain**. NetBird applies the policies attached to the route or network resource here. Policies that target the routing peer itself live in the **input chain** and are evaluated separately.
4. If masquerade is enabled (the default), the routing peer SNATs the source IP to its own LAN-side address before the packet leaves. With masquerade disabled, the original NetBird overlay IP is preserved and the destination network must route return traffic back through the routing peer.
4. If masquerade is enabled (the default), the routing peer SNATs the source IP to its own LAN-side address before the packet leaves. With masquerade disabled, the original NetBird IP is preserved and the destination network must route return traffic back through the routing peer.
5. Replies follow the reverse path. The stateful firewall on the routing peer tracks established connections so return traffic does not need an explicit policy.
## Requirements
@@ -68,13 +68,25 @@ echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-netbird.conf
echo "net.ipv6.conf.all.forwarding=1" | sudo tee -a /etc/sysctl.d/99-netbird.conf
```
On Windows, no extra setup is needed to forward traffic to routed subnets. Only enable `NB_ENABLE_LOCAL_FORWARDING` if you also need clients to reach services bound to the routing peer's own local addresses — for example, a dashboard or service running on the routing peer host itself:
### Local forwarding
IP forwarding (above) carries traffic to machines *behind* the routing peer. Reaching a service on the routing peer's **own address** is a separate case (self-access), and it needs `NB_ENABLE_LOCAL_FORWARDING` — and only on peers that forward in software (the userspace router):
| Routing peer | Data path | Reaching a service on the peer's own address |
|---|---|---|
| Windows, macOS | userspace router (always) | needs `NB_ENABLE_LOCAL_FORWARDING` |
| Linux, netstack mode (`NB_USE_NETSTACK_MODE`) | userspace router | needs `NB_ENABLE_LOCAL_FORWARDING` |
| Linux, native backend (nftables/iptables) | kernel forwarding | not needed |
The flag is off by default on every platform (see [Client Environment Variables](/client/environment-variables)):
```powershell
netbird service reconfigure --service-env NB_ENABLE_LOCAL_FORWARDING=true
```
Leave it off otherwise. Turning it on can expose localhost-bound services on the routing peer unintentionally.
This flag is only one of three things self-access needs — the peer also needs a route and a peer-to-peer policy. See [Reaching the routing peer itself](#reaching-the-routing-peer-itself) for the full picture. This is the common shape when the service host *is* the routing peer: a file server that runs the NetBird client, whose clients resolve its name to its LAN IP.
Leave it off otherwise. With it on, any permitted peer can reach services bound to the routing peer's LAN addresses, not just the networks behind it — so don't enable it on a peer running local-only services you don't want exposed.
### Container capabilities
@@ -111,7 +123,7 @@ Masquerade is on by default. The routing peer SNATs forwarded traffic to its own
Turn masquerade off when:
- You need source IP visibility for auditing, compliance, or application logic.
- You want the destination network's existing firewalls to filter NetBird peers by their overlay IP.
- You want the destination network's existing firewalls to filter peers by their NetBird IP.
With masquerade off, you must add a return route on the destination network pointing the NetBird CIDR (default `100.64.0.0/10`) at the routing peer.
@@ -135,6 +147,18 @@ If users need to reach both the resources behind a routing peer **and** services
1. **Network resource policy** (forward chain): `Engineers` → `10.10.0.0/16` resource. Permits traffic *through* the routing peer.
2. **Peer-to-peer policy** (input chain): `Engineers` → routing peer group, on TCP/22 and TCP/3000. Permits traffic *to* the routing peer.
### Reaching the routing peer itself
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). Reaching the routing peer at each needs different things:
- **At its NetBird IP** — a single peer-to-peer policy (input chain) is enough. Every client already has an overlay route to every peer.
- **At its LAN IP** — when DNS (or a DFS path) resolves the service to its LAN address, the client has **no route** to that IP yet. Reaching it needs three things together:
- a **resource** that covers the LAN IP (the route),
- a **peer-to-peer policy** (the input-chain accept), and
- on userspace peers (Windows, macOS, Linux netstack), [`NB_ENABLE_LOCAL_FORWARDING`](#local-forwarding).
For the full setup — the file-server scenario, the commands, the Active Directory tie-in, and a fallback for when you can't set the flag — see [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer).
### Directionality is forced for routed traffic
Policies whose destination is a network resource are always unidirectional from source to destination. The resource has no agent and cannot initiate connections back through the overlay. The bidirectional toggle is disabled in the UI for these policies.
@@ -167,7 +191,7 @@ Clients running `0.59.0` and `0.59.1` may fail to resolve domain resources serve
### Routing Peer DNS Resolution
Wildcard domain resources rely on Routing Peer DNS Resolution, which is enabled by default. With it on, DNS resolution happens on the routing peer rather than on the client.
Domain resources rely on Routing Peer DNS Resolution, which is enabled by default. With it on, DNS resolution happens on the routing peer rather than on the client: the client forwards its name-to-IP lookups (`A`/`AAAA`) for a domain resource to the routing peer's resolver, and needs no nameserver of its own for that name. With it off, each client resolves the domain itself using its own DNS, so it must already be able to resolve the name — via a [nameserver](/manage/dns/internal-dns-servers) or its network adapter's DNS. Either way, this covers name-to-IP lookups only; Active Directory clients also need a nameserver for the `SRV` records Windows uses to find a domain controller.
### Pitfall: domains and IP ranges in the same network
@@ -205,6 +229,8 @@ Specifics:
- Mixing domain and IP-range resources in the same network.
- Exit node missing the ICMP policy, so clients can't connect to the routing peer in the first place.
- DNS port mismatch when an account has a mix of pre-0.59 and post-0.59 peers.
- Reaching a service on the routing peer's **own LAN IP** (not its NetBird IP) with only an input policy — it also needs a resource for the route, and on userspace peers `NB_ENABLE_LOCAL_FORWARDING`. See [Reaching the routing peer itself](#reaching-the-routing-peer-itself).
- Health-checking that path with `ping` — ICMP needs its own peer-to-peer policy; a service up while ping is down is a missing ICMP policy, not a routing failure.
<Tiles
title="Related"

11
src/pages/manage/networks/index.mdx
View File

@@ -6,7 +6,7 @@ export const description = "Learn how NetBird Networks work: the four building b
# Networks
Every device that runs the NetBird client joins a single private **overlay network**, encrypted end to end with [WireGuard](/about-netbird/netbird-vs-traditional-vpn#why-wireguard-with-netbird). Nothing is exposed to the public internet, and you never open an inbound port. Peers connect outbound and negotiate connectivity using ICE/STUN for NAT traversal. See [Ports & Firewalls](/about-netbird/ports-and-firewalls) for details.
Every device that runs the NetBird client joins a single private **overlay network**, encrypted end to end with [WireGuard](/about-netbird/netbird-vs-traditional-vpn#why-wire-guard-with-net-bird). Nothing is exposed to the public internet, and you never open an inbound port. Peers connect outbound and negotiate connectivity using ICE/STUN for NAT traversal. See [Ports & Firewalls](/about-netbird/ports-and-firewalls) for details.
But you can't run the client everywhere. Some devices can't run it at all, like printers, IoT sensors, and appliances you can't install software on. And installing it on every database and server is more overhead than most teams want. A **Network** fills that gap: a few clients become routing peers that open whole subnets, single hosts, and internal domains to your overlay network, with nothing reachable until a policy allows it.
@@ -110,6 +110,10 @@ TO the routing peer → input chain → peer-to-peer policy
For the full kernel-level traffic walkthrough, host requirements (IP forwarding, container capabilities), masquerade internals, and the forward-vs-input-chain rule in depth, see [How Routing Peers Work](/manage/networks/how-routing-peers-work).
</Note>
<Note>
"To the peer" has a further subtlety: a peer-to-peer policy reaches the routing peer at its **NetBird IP** (its `100.x` overlay address). To reach it at its **LAN IP** — e.g. clients resolve its name to that address — you also need a resource that covers that IP (the route), and on userspace peers `NB_ENABLE_LOCAL_FORWARDING`. See [Reaching the routing peer itself](/manage/networks/how-routing-peers-work#reaching-the-routing-peer-itself) and the [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer) use case.
</Note>
## Walkthrough: access two internal apps
A remote engineer in the `Development` group needs to reach two apps in the Berlin office: an internal **wiki** running on the host `10.10.0.5`, and an internal **dashboard** at `grafana.berlin.internal`. The two apps live on distinct hosts, so they're independent resources. One machine inside the office runs the NetBird client and serves as the routing peer.
@@ -208,6 +212,11 @@ Networks keep resources private to your overlay network. If you instead need to
name: 'Site-to-VPN',
description: 'Let clientless devices initiate connections to your overlay network.',
},
{
href: '/manage/networks/use-cases/reach-services-on-the-routing-peer',
name: 'Reach Services on the Routing Peer',
description: 'Reach a file server or SMB/DFS share when the file server itself runs the NetBird client.',
},
]}
/>

163
src/pages/manage/networks/use-cases/active-directory.mdx Normal file
View File

@@ -0,0 +1,163 @@
import { Note } from '@/components/mdx'
# Active Directory & Windows File Shares
Remote, domain-joined users expect their mapped drives, DFS (Distributed File System) paths, and domain login to *just work*, even when the domain controllers and file servers sit on a private LAN with nothing exposed publicly. This guide is the end-to-end journey for that over NetBird. It builds on two underlying pieces, [How Routing Peers Work](/manage/networks/how-routing-peers-work) and [Internal DNS Servers](/manage/dns/internal-dns-servers), and ties them together into a single setup.
<Note>
**TL;DR** — AD over NetBird is [a handful of NetBird objects](#what-you-configure-in-net-bird): a routing peer, a route to the file server, a route to the domain controller, access control policies for both, and a DNS nameserver pointing at the DC.
</Note>
The core idea: a domain-joined client's everyday actions quietly depend on **two kinds of server**, and both must be reachable over NetBird:
- the **domain controller (DC)**, for DNS, Kerberos authentication, and DFS namespace referrals;
- the **file server(s)**, the machines that actually hold the shares.
```
Remote user ──tunnel──► routing peer ──LAN──► Domain Controller (DNS, Kerberos, DFS referral)
(NetBird) └─────► File server(s) (the SMB/DFS share data)
```
## What one mapped drive actually depends on
When a user opens a DFS path such as `\\corp.example.com\dfs\share`, Windows:
1. resolves `corp.example.com` and finds a **domain controller** (ordinary DNS, plus special `SRV` records);
2. asks the DC which file server actually holds that folder (the DFS **referral**);
3. resolves that **file server's** name;
4. connects to the file server over SMB, authenticated by **Kerberos** (tickets from the DC).
The domain controller is in almost every step: DNS (steps 1 and 3), the referral (step 2), and Kerberos (step 4). The file server itself only enters at step 4. If any one of these is unreachable — the DC, the file server, or the DNS linking them — the drive fails, often with an error that points nowhere near the real cause. The steps below make all of it reachable.
## Step 1: Decide where the NetBird client runs
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.
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.
## 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 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:
```powershell
Get-DfsnFolderTarget '\\corp.example.com\dfs\share'
```
Each result's `TargetPath` (for example `\\fileserver1.corp.example.com\share`) names a file server — add the server portion, `fileserver1.corp.example.com`, as a domain resource in your NetBird network.
## Step 3: Route the domain controller
The DC is almost always clientless and reached *through* the routing peer. Add it as a resource in the NetBird Network:
- a `/32` of the DC's IP, or
- a domain resource for `corp.example.com`, whose A record points at the DCs (this routes them by name, and the routing peer must be able to resolve the domain).
Keep it granular — least privilege is the NetBird default, so route only what you need. A single `*.corp.example.com` wildcard covers the DC, file servers, and DFS targets in one resource, but trades away per-host control (see note).
<Note>
A wildcard is one resource with **one policy scope** — the ports you open apply to *every* host under the domain, so you can't give the DC the full AD port set while limiting file servers to `445`. When you want that per-host scoping, use separate resources.
</Note>
Routing the DC through a single routing peer works: domain logon, Kerberos, and DFS all function over it. One caution: don't make a single peer the *only* path to the DC if you can avoid it. It works, but for resilience add a second routing peer for high availability.
<Note>
Running the NetBird client *on* a DC is a different pattern with its own caveats. See [Domain Controllers as Routing Peers](/manage/dns/internal-dns-servers#domain-controllers-as-routing-peers) and the [WireGuard port conflict](/manage/dns/internal-dns-servers#wire-guard-port-conflict-on-domain-controllers) note.
</Note>
## Step 4: Allow the AD ports
Create a TCP policy and a UDP policy from your remote-users group to the DC, covering these baseline ports:
| Port | Protocol | Needed for |
|---|---|---|
| 53 | TCP/UDP | DNS — locating the DC and resolving AD `SRV` records |
| 88 | TCP/UDP | Kerberos — domain logon |
| 123 | UDP | Time sync (`w32time`) — clock skew beyond ~5 minutes breaks Kerberos, so this matters more than it looks |
| 135 | TCP | RPC endpoint mapper — netlogon secure-channel setup |
| 389 | TCP/UDP | LDAP / CLDAP — directory queries and DC location |
| 445 | TCP | SMB — SYSVOL (Group Policy), file shares, and DFS |
| 464 | TCP/UDP | Password changes and resets (kpasswd) — without it, a remote user whose password expires can't set a new one and is locked out |
NetBird renders one rule per access control policy, so a single policy can't mix protocols. Build **two** policies and sort each port into one or both:
- **TCP policy** — `53`, `88`, `135`, `389`, `445`, `464`
- **UDP policy** — `53`, `88`, `123`, `389`, `464`
The ports that are both TCP and UDP (`53`, `88`, `389`, `464`) go in **both** policies.
### Beyond the basics: extra DC ports
The ports above cover the everyday AD experience: logon, Kerberos, DNS, time sync, password changes, SMB/DFS, and Group Policy. Some environments need more. Add these to the DC policies as your deployment requires (keeping one protocol per policy, so each new TCP port joins the TCP policy and each new UDP port the UDP policy):
| Port | Protocol | Needed for |
|---|---|---|
| 3268 / 3269 | TCP | **Global Catalog** (LDAP / LDAPS). In multi-domain forests, used by UPN-style logons (`user@domain`) and many directory-aware apps. |
| 636 | TCP | **LDAPS**, for apps that bind to AD over TLS. |
| 9389 | TCP | **AD Web Services**, the transport for the RSAT Active Directory PowerShell module (`Get-ADUser`, and similar). |
| dynamic RPC | TCP | **Replication, some MMC consoles, and deep secure-channel checks.** Port 135 (the RPC endpoint mapper) is already in the baseline, but the high port range it hands out is not. Open it only if you manage AD this way. |
Each of these is independent — add only what you need; leaving one out affects only that feature.
## Step 5: Give clients corp DNS
A domain-joined client has to resolve many `corp.example.com` names: the file server, the DFS root, and the `SRV` records Windows uses to locate a DC. Add a **DNS nameserver** with `corp.example.com` as its **match domain**, pointing at the DC's IP address, and distribute it to your remote-users group. See [Internal DNS Servers](/manage/dns/internal-dns-servers).
<Note>
A domain resource does not remove this need: the routing peer answers name-to-IP lookups but not the `SRV` / DC-locator records login and DFS require, so an AD client always needs this nameserver (and it only works once the DC is reachable, Step 3).
</Note>
## Verify
Run these checks while signed in as the everyday domain user who will actually use the share. That user already holds a Kerberos login ticket from signing in, which is what makes the share connect cleanly.
**1. Check the file server answers on the file-sharing port.** File sharing (SMB) uses TCP port 445, so test that exact port:
```powershell
Test-NetConnection <fileserver> -Port 445
```
On Linux or macOS, use `nc -z <fileserver> 445` instead.
Do not use `ping` for this check. Because the policies above allow specific ports rather than all traffic, ICMP isn't included — so `ping` can fail even when file sharing works perfectly. A successful port 445 test is the reliable signal.
**2. Map a drive by name.** Run:
```
net use G: \\corp.example.com\dfs\share
```
It should connect exactly as it does in the office. Always use the server's **name** (the full `corp.example.com` address), never its IP. Windows logs you in by name using Kerberos — the ticket-based sign-in your domain controller provides. If you connect by IP (`\\<ip>\share`), Windows falls back to the older NTLM method, which usually fails here with *"the specified domain is not available."*
<Note>
Two errors here look like a NetBird routing problem but are actually Windows quirks:
- Mapping a share **by IP address** can fail with **System error 1311**.
- Connecting **with a typed-in username** (`net use ... /user:CORP\you`) can fail with **System error 1312**.
Both come from how Windows handles Kerberos logins, not from routing. Avoid them by testing the normal way: signed in as the domain user, connecting by name.
</Note>
## What you configure in NetBird
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 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)*
- **Access control policies to the domain controller** — a TCP and a UDP policy on the AD ports. *(Step 4)*
- **A DNS nameserver** — match domain `corp.example.com` pointing at the DC's IP, distributed to your remote-users group. *(Step 5)*
## Related
- [Reach Services on the Routing Peer](/manage/networks/use-cases/reach-services-on-the-routing-peer) — the self-access setup, for when the file server *is* the routing peer.
- [How Routing Peers Work](/manage/networks/how-routing-peers-work) — forwarding, the two policy chains, and masquerade.
- [Internal DNS Servers](/manage/dns/internal-dns-servers) — nameservers, Routing Peer DNS Resolution, and domain controllers.

45
src/pages/manage/networks/use-cases/reach-services-on-the-routing-peer.mdx Normal file
View File

@@ -0,0 +1,45 @@
# 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.
## 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.
The NetBird client is installed only on the file server, so the file server *is* the routing peer. Remote users resolve the file server's name (and any DFS paths) to its LAN IP — but that address belongs to the routing peer itself, so traffic to it must be *delivered locally on the peer, not forwarded* to a network behind it. The symptom: DNS resolves, yet SMB connections and pings to the file server fail.
```
Remote user ──tunnel──► File server = routing peer (its own SMB/DFS share at its LAN IP)
(NetBird) └──► Domain Controller (clientless, on the same LAN)
```
## The setup
The target *is* the routing peer, addressed by its own LAN IP. Set up the following together:
1. **A route to the address** — a resource covering the file server's LAN IP: a `/32`, or a domain resource set to its DNS name (the peer resolves its own name and keeps the route current if the IP changes).
2. **A peer-to-peer policy** from your users' group to the routing peer (or routing peer group), on the service port (SMB = **TCP 445**). Reaching the peer *itself* is a separate permission from reaching machines *behind* it — this grants it.
3. **On a Windows or macOS routing peer, set the `NB_ENABLE_LOCAL_FORWARDING` [environment variable](/client/environment-variables)** — it lets the NetBird client deliver to a service on its own LAN IP, not just forward onward:
```powershell
netbird service reconfigure --service-env NB_ENABLE_LOCAL_FORWARDING=true
```
A Linux peer doesn't need this with its default kernel forwarding — only in netstack mode.
Steps 1 and 3 exist only because clients reach the file server at its **LAN IP**. Reaching a peer at its **NetBird IP** needs only the policy in step 2 — every client already has a route to it, with no resource to add and no forwarding flag.
With these in place, a mapped drive to the share works unchanged — reached at its LAN IP over the tunnel.
**Domain-joined clients (AD/DFS)** need one more thing — a NetBird **DNS nameserver** for your AD domain. Add one with the match domain `corp.example.com` pointing at the DC's IP address (e.g. `10.0.0.10`), so clients resolve corp DNS and can log in. The DC must also be reachable over NetBird. See **[Active Directory & Windows File Shares](/manage/networks/use-cases/active-directory)** for the full setup.
## Verify
- Test reachability with `Test-NetConnection <host> -Port <port>` (or `nc -z`), not `ping`. ICMP needs its own peer-to-peer policy; a service working while `ping` fails is the signature of a missing ICMP policy, not a broken route.
- The service should now answer at the routing peer's LAN IP over the tunnel — for a file server, a mapped drive opens unchanged.
## Fallback: resolve the name to the NetBird IP
If you can't set `NB_ENABLE_LOCAL_FORWARDING` on the file server, there's an alternative that needs no resource, route, or forwarding flag: make each client resolve the file server's name to its NetBird IP (its `100.x` address) instead of its LAN IP — with a `hosts` file entry or a Windows NRPT rule (a per-name DNS override). The client then connects to it directly over the NetBird overlay. Logins still work, because Kerberos is tied to the server's *name*, not its IP address.
Treat this as a *last resort, not the main path*: it has to be set up on every client, whereas the setup above is configured once in NetBird and is invisible to clients.