* Restructure Troubleshooting into a hub with per-area pages
- Add a Troubleshooting hub (/help/troubleshooting) with icon/chip cards and a "Still stuck?" CTA
- Split NetBird Client troubleshooting into an overview + per-OS pages (Linux, Windows, macOS, Android, iOS)
- Split Self-hosted troubleshooting into an overview + per-area pages (installation, IdP, dashboard, certificates, connectivity, database)
- Split "Report bugs and issues" into Community Support and NetBird Support pages
- Add Troubleshooting resource connectivity and a NetBird Cloud pending-approval page
- Add DNS troubleshooting Issue 8 (Windows NRPT rule blocked by a lingering GPO)
- Cross-reference the new pages from networks, DNS, and reverse-proxy docs; update nav
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Address review: client terminology, dead props, labels, cross-links
- Use "client" instead of "agent" across the client troubleshooting pages (headings, prose, anchors)
- Remove unused source: props from the Troubleshooting hub tiles
- Relabel the "NetBird Cloud" grouping to "Cloud & identity" (SSO/provisioning also apply to self-hosted)
- Add a Tiles title on the report-bug landing; add reverse-proxy -> resource-connectivity cross-link
- Fix comma splices introduced by the em-dash cleanup in relayed-connections
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Add client-side hash redirect for moved self-hosted anchors
Old deep links like /selfhosted/troubleshooting#debugging-turn-connections now
forward to the per-area page, since next.config redirects can't act on the URL fragment.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Apply docs-skill review: conventions + reshape area pages
- "open source" (no hyphen), expand NRPT on first use, descriptive alt text + captions on TURN images
- Fix inherited "Netbird" casing in the client glossary
- Reshape the six self-hosted area pages to Symptom -> likely causes (ordered) -> Fix -> Confirm, preserving anchored headings
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Fix two typos in client glossary (CodeRabbit)
- "nunning" -> "running" in the glossary
- possessive "it's" -> "its" in the routing-table sentence
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: fix two broken links in troubleshooting pages
- database: point the "upgrade path" link at /selfhosted/maintenance/upgrade;
selfhosted-quickstart has no #upgrade anchor so the old link landed at page top
- client: add HashRedirect so old #net-bird-agent-status deep links forward to
the renamed #net-bird-client-status section on the same page
* docs: address review follow-ups (deep-link redirects + client casing)
- self-hosted troubleshooting: extend the HashRedirect map with the per-issue
(###-level) anchors from the old single page, so old deep links land on the
exact sub-section of the new area page rather than just the page top
- client glossary: lowercase "NetBird client" in the peer-a/peer-b entries
(house convention) and fix "linux" -> "Linux"
* docs: review polish — fix image class + first-use acronym glosses
- connectivity: fix bad CSS class imagewrapper-nig -> imagewrapper on the
TURN-test screenshot (the typo'd class matched no style and broke zoom)
- gloss acronyms on first use: GPO (DNS Issue 8), IdP/SSO (identity-provider),
ACME (certificates), CORS (dashboard)
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
* docs: add persistent-route guidance for clientless devices and align site-to-site on Networks
Step 5 of both site-to-site guides (and the masquerade page) now walk a
first-time admin through persisting a Linux static route end to end:
detect Netplan vs systemd-networkd with `ls /etc/netplan/`, then a clear
Option A / Option B that are framed as alternatives, with the exact
editing mechanics (open in nano, save/exit keys, or a one-paste
systemd-networkd drop-in). Standardize on the `<IFACE>` placeholder with
an `ip -br addr` hint so a literal `eth0` can't silently misconfigure
hosts using predictable interface names.
Update the site-to-site use-case hub to recommend Networks for all
non-exit-node scenarios, rename "Network Routes" to "Routes", and
reconcile the comparison section with the Routes deprecation.
* docs: promote Routes site-to-site recommendation to a deprecation warning
Move the 'use Networks instead' callout above the Architecture section
and make it a Warning, matching the Routes deprecation. Keep the legacy
no-Policy nuance and the Site-to-VPN pointer; rename Network Routes to Routes.
* docs: correct Networks scenario support and mark Routes deprecated
- advanced-configuration: Networks supports all scenarios (VPN-to-Site,
Site-to-VPN, Site-to-Site), not VPN-to-Site only
- how-routing-peers-work: Routes labeled deprecated, not 'still supported'
* docs: import Note explicitly in site-to-site use-case page
Addresses CodeRabbit: <Note> was used without an explicit import from
@/components/mdx, relying on the global MDX provider.
* docs: repoint site-to-site cross-links to Networks
Site-to-site moved to Networks; update the homelab and cloud use-case
tiles/table and the access-home-devices and cloud-to-on-premise Next
Steps links to /manage/networks/use-cases/site-to-site.
* docs: rename Network Routes to Routes in prose and repoint advanced-config links
Bucket A rename (display text only): rename the 'Network Routes' feature
name to 'Routes' across prose, link labels, table cells, alt text, Tiles
names, and code comments. Headings are deliberately left unchanged to
avoid breaking anchors and inbound links; URL paths (/manage/network-routes)
are unchanged. Generic routing-table mentions and the desktop system-tray
UI label are left as-is.
Also repoint the access-home-devices and cloud-to-on-premise 'Advanced
configuration' Next Steps links from the Routes advanced-config page to
/manage/networks/masquerade.
* Update site-to-site documentation for clarity
Removed outdated information about using Routes for site-to-site connections.
* Update src/pages/manage/networks/use-cases/site-to-site.mdx
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
* Update section title from 'Networks vs Network Routes' to 'Networks vs Routes'
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
The /selfhosted/environment-variables reference page had no inbound
links and was only reachable by direct URL or search. Add it under
Maintenance, after Configuration Files.
* 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.
* docs: add unlisted Enterprise Commercial License getting-started page
Self-hosted NetBird stack guide with embedded IdP, served at /selfhosted/enterprise/getting-started. Reachable by direct link only; intentionally not added to the sidebar nav.
* docs: add custom TLS certificate appendix to Enterprise getting-started
* docs: rewrite Enterprise Commercial getting-started from script-based deployment guide
Replace the topology-choice page with the current script-based flow:
getting-started.sh for fresh installs and migrate-to-commercial.sh for
community-to-enterprise migrations. Add the migration path, numbered
sections, and a troubleshooting section; standardize on enterprise
terminology and <your-domain> placeholders. Keep the IdP-connection
links and the custom-TLS appendix.
* docs: clarify traffic-flow note in Enterprise getting-started
* docs: link Docker install in Enterprise getting-started prerequisites
* docs: rename Network Routes to Routes, deprecate, and relocate Browser Client Architecture
- Rename the docs sidebar entry "Network Routes" to "Routes" and the page H1
- Add a deprecation note to the Routes page: all use cases except exit nodes
have moved to Networks; reconcile the body framing accordingly
- Move Browser Client Architecture under Peers > Browser Client
(/manage/peers/browser-client/architecture), nest the nav, add a redirect,
and update cross-links
- Shrink the site-to-site Architecture diagram boxes to fit their content
* docs: rename Routes nav 'Concept' link to 'Overview'
* docs: add Troubleshooting relayed connections teaching page
Adds a help-section teaching doc that walks junior admins from
'Connection type: Relayed' to a fixed P2P connection (or a justified
stop): mental model, the four players (NAT/Signal/STUN/Relay), ICE
candidate reading, an elimination-based decision flow, a port-forwarding
escape hatch, a worked walkthrough, and when relay is the right answer.
Moves the troubleshooting-oriented sections (Checking Your Connection
Type, Tips for Improving P2P Success) out of Understanding NAT and
Connectivity, leaving it purely conceptual with pointers to the new
page. Adds sidebar entry and a pointer from troubleshooting-client.
* fix: correct nftables example for STUN outbound rule
The STUN service runs on UDP 80/443/3478/5555, but the example rule
allowed TCP/443. Also note that nftables resolves hostnames at
ruleset-load time only, which matters for a dynamic geo-distributed
endpoint pool.
Create a standalone User Roles reference covering all six roles (Owner,
Admin, Network Admin, Billing Admin, Auditor, User) with a permission
matrix aligned to the current dashboard, per-role sections, API/token
notes, and role-assignment steps.
Reduce the role section on the Add Users page to a pointer (keeping the
existing anchor), repoint inbound links from delete-account,
control-center, and msp-portal, add the page to the Team sidebar, and
refresh the role screenshots.
* bulk text edit to fit new flows
* Updated screenshots, some minor docs fix. (#782)
* Update Settings on site-to-site.mdx
* fix image names and embedded links
* Update high level dia
* general dashboard images and auto-update stucture fix
* remove temp audit file
---------
Co-authored-by: PizzaLovingNerd <cameron@stillhq.io>
* docs: rewrite Networks page as a teaching guide
Rework /manage/networks from a reference-style concept page into a
structured teaching guide: mental model, the four building blocks
(Network, Resource, Access policy, Routing peer), how a packet reaches
a resource, and an end-to-end walkthrough for reaching two internal
apps with Zero Trust access by default.
- Add a production checklist (HA, monitoring, masquerade, internal DNS,
routing-peer access) and a clear "Networks or Network Routes?" split:
Networks now covers every remote-access scenario except exit nodes.
- Add worked-example and resource-list screenshots.
- how-routing-peers-work: point site-to-site at Networks, describe
Routing Peer DNS Resolution as on by default, and restore the
0.59.x domain-resolution compatibility note.
- Rename the sidebar entry from "Concept" to "Overview".
* image organization into /networks dir
* fix embedded images in networks/index.mdx
* docs: note no inbound ports and Linux-only masquerade on Networks page
---------
Co-authored-by: TechHutTV <brandon@techhut.tv>
Adds docs for env variables for logging (including the new NB_LOG_DISABLE_ROTATION) and troubleshooting using external logging rotation (describing also new detection behavior).
* docs: add Networks site-to-site use-case guide
Add a canonical site-to-site guide built on Networks/Resources/Policies,
which is the recommended and actively developed approach. Reposition the
legacy Network Routes site-to-site Note to point at the new page and scope
Network Routes to the wide-open, no-policy case only. Add the new page to
the docs sidebar under Networks > Use Cases.
* docs: fix Resource fields, policy heading, and prerequisites in Networks site-to-site
- Remove non-existent 'Type: Subnet' field; describe Resource Groups under
Additional Options to match the actual UI
- Rename Step 4 to 'Create access control policies'
- Trim prerequisites (drop account line and device examples)
* docs: clarify Masquerade requirement and Linux-only SNAT for site-to-site
Add a 'When Posture Checks Are Evaluated' section to the posture checks
page covering connect/login evaluation, immediate distribution of changes,
and the connection-time evaluation caveat for mid-session state changes.
Add a 'How Policy Changes Are Distributed' section to the access control
overview covering event-driven push, no redistribution interval, and
change coalescing. The two sections cross-link.
Answers common customer questions about the Entra ID API to SCIM
migration that the public docs did not cover:
- One-integration-at-a-time limit and tenant-separation workaround
- Reusing an existing Enterprise Application for SCIM vs. the legacy
API App Registration
- Why the group externalId mapping is removed (displayName matching)
- Why unused user attribute mappings are trimmed
- Why externalId source changes from mailNickname to objectId
- New Sync Behavior section contrasting 5-min API polling with
event-driven SCIM provisioning
* fix: replace invalid <p> wrapping Button with <div>
The Button component renders a <div> in its primary variant. HTML
disallows block elements inside <p>, so browsers auto-close the <p>
during parsing and React 19 reports a hydration mismatch. The
float="center" attribute was non-functional, so rendering is unchanged.
* chore: gitignore .playwright-mcp run artifacts
* OPNsense checkbox "Show community plugins"
OPNsense requires a new checkbox "Show community plugins" to be checked, before you can find the netbird plugin.
Tested on OPNsense 26.1.8_5
* docs: tighten OPNsense community plugins instruction
---------
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
* Add Support Matrix section under Get More Help
Adds /help/support-matrix with an overview, NetBird client (split into
per-OS pages following the get-started/install layout), Kubernetes
operator, Terraform provider, and self-hosted sub-sections.
Linux/Windows/macOS pages pre-fill OS version cutoffs derived from the
Go toolchain's minimum OS requirements at each NetBird release's Go
version (sourced from go.mod at release tags). Each derived page carries
a Warning callout marking the values as inferences pending team
confirmation. Mobile/TV pages and the other component pages remain TBD
placeholders.
* Rework Linux support page around client modes
Drops the per-distro TBD table and consolidates the description with the
Warning callout. Splits Linux support by client mode: userspace follows
the Go toolchain's minimum OS requirements; kernel mode depends on the
host's iptables/nftables features. Notes Ubuntu 20.04 as the
end-to-end test floor.
* Add full Linux e2e test matrix to support page
Replaces the single Ubuntu 20.04 floor reference with the full set of
distributions covered by the NetBird team's end-to-end tests: Ubuntu
20.04/22.04/24.04, Debian 12, Rocky Linux 9, and Fedora 41. Ubuntu
20.04 remains called out as the oldest tested release.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
* Update BYOP documentation to reflect "Clusters" terminology and add shared vs account cluster details.
* Update BYOP DNS documentation and replace modal images
