* docs: add 'Choosing a pattern' overview to K8s getting started
Add a decision table and rules of thumb covering routing peer vs client
sidecar vs API server proxy vs Gateway API, so readers can pick the right
operator pattern. Clarifies that a sidecar (not a routing peer) is the
answer when a pod needs its own identity or to originate traffic onto the
overlay.
* docs: name the NetworkRouter CRD and clarify its DNS zone in the pattern table
* docs: add Highly Available Routing Peers use-case page (Kubernetes operator)
Add a standalone use-case page under a new Use Cases group in the Kubernetes
nav, covering how to run the operator's routing peers in HA: NetworkRouter
workloadOverride.replicas (default 3), the auto-created PodDisruptionBudget
(maxUnavailable: 1), equal-metric automatic failover, and spreading replicas
across failure domains via workloadOverride.podTemplate. Models least-privilege
(named destination group + access policy) rather than the All group.
* docs: add topology diagrams to HA routing peers page
Two SVG topology diagrams: replicas on a single node (single point of
failure) and replicas spread one-per-node via topologySpreadConstraints.
Embedded in Step 1 and the failure-domains section.
* docs: correct HA scheduling framing; drop single-node diagram
kube-scheduler spreads a Deployment's replicas across nodes by default
(best-effort, via built-in PodTopologySpread defaults). The earlier text/
diagram wrongly implied replicas co-locate by default. Reframe: multi-node
spread is the default; topologySpreadConstraints turns it into a guarantee
(or spans zones). Remove the single-node diagram (non-HA case, out of scope).
* docs: add Friendly DNS names appendix to HA routing peers page
Document exposing a service under a cleaner name via a CNAME in a custom
zone pointing at the operator's <service>.<namespace>.<zone> record (verified
end-to-end). Placed as an appendix for now; can move to a shared location later.
* docs: use ScheduleAnyway in spread example; note DoNotSchedule rollout deadlock
Multi-node verification: default scheduling already spreads replicas one-per-node;
the operator merges workloadOverride.podTemplate.topologySpreadConstraints into the
Deployment. DoNotSchedule with replicas == schedulable nodes deadlocks rolling updates
(surge pod can't place). Switch the example to ScheduleAnyway (verified clean rollout)
and document DoNotSchedule + the node-count/maxSurge caveat for a hard guarantee.
* docs: clarify custom-zone records are per-name (no whole-domain shadowing)
Verified on the lab: a NetBird custom zone serves only the records you add; other
names under the domain fall through to upstream DNS. Reusing a real internal domain
for friendly names is safe except for exact-name collisions.
* docs: expand into full 'Route to a Kubernetes service' how-to
Restructure the HA use-case page into an end-to-end guide covering the whole
journey: create the custom DNS zone, groups, and access policy (dashboard) ->
deploy HA routing peers (NetworkRouter, replicas:3) -> expose a Service
(NetworkResource) -> verify + failover. Generic, human-readable example names
(k8s.company.internal, kubernetes-clients/-services, network 'kubernetes',
nginx). Keeps the failure-domains diagram + ScheduleAnyway/DoNotSchedule note
and the friendly-DNS appendix. Adds <img> slots for 5 dashboard/terminal
screenshots (to be supplied). Renames the page + nav entry to
route-to-a-kubernetes-service; old slug removed.
* docs: add dashboard/terminal screenshots to the K8s how-to
Four screenshots (DNS zone, access policy, the kubernetes network with HA +
3 routing peers, kubectl pods-across-nodes). Drop the groups screenshot and
renumber the <img> refs to match.
* docs: swap in cleaner pods-across-nodes screenshot for Step 5
* docs: make node-spread central to the HA guide
Node-spread is the point of an HA guide, not a tail-end section. Move the
topology diagram up to 'What you'll achieve', fold the node-spread story into
Step 3 (deploy HA routing peers) - leading with the verified fact that the
scheduler spreads replicas across nodes by default (HA out of the box), with
topologySpreadConstraints as optional hardening - and drop the orphaned
'Spread across failure domains' section.
* docs: clarify the custom zone is created empty (operator fills the record)
Step 1 showed the auto-created A record without saying you don't enter it.
Note that you create only the zone (no hostname/IP/TTL by hand) and the
operator adds <service>.<namespace>.<zone> -> ClusterIP (5-min TTL) in Step 4.
* docs: replace Excalidraw topology with a custom dark-mode SVG
Hand-authored dark-background topology diagram (NetBird overlay -> routing
peers one-per-node -> Service) that matches the dark docs theme, replacing the
light Excalidraw-derived SVG. Removes the orphaned ha-routing-peers-spread-nodes.svg.
* docs: add CNAME dialog screenshot to the friendly-DNS appendix
Show the Add DNS Record dialog (CNAME 'app' -> nginx.default.k8s.company.internal)
and align the example hostname to 'app' to match.
* docs: drop maxSurge:0 workaround (not configurable via the operator)
The operator's workloadOverride only exposes annotations, labels, podTemplate,
and replicas — there is no hook for the Deployment's strategy.rollingUpdate.maxSurge.
Keep the achievable workaround (more schedulable nodes than replicas).
* docs: drop manual topology spread guidance (operator handles it by default)
* 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>
* 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: 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'
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>
* 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
* Update BYOP documentation to reflect "Clusters" terminology and add shared vs account cluster details.
* Update BYOP DNS documentation and replace modal images
* docs: add Masquerade configuration page
Documents persistent return-route setup on the destination host when
masquerade is disabled on a routing peer. Covers Netplan, systemd-networkd,
NetworkManager, ifupdown, and RHEL legacy network-scripts, plus verification
and a security note. Resolves the previously dangling "Related" tile in
how-routing-peers-work.mdx.
* docs: clarify masquerade page and trim persistent recipes
- Netplan: show as a fragment with addresses/default route context so readers
don't paste it as a standalone file
- systemd-networkd: note the drop-in needs a matching .network file and
point at networkctl status to find it
- Test section: add ping/curl reachability examples
- Verify section: call out that proto/onlink/metric fields are normal
- Remove NetworkManager, ifupdown, and RHEL legacy sections
* docs: clarify netplan section when /etc/netplan is empty
Lead with the common case (cloud-init / installer yaml already exists),
and call out the placeholders in the example. Add a fallback path for
the rare case where /etc/netplan/ is empty.
* docs: comment <IFACE> placeholder in netplan example
* docs: clarify <IFACE> is the destination's LAN interface
* docs: comment <PEER_LAN_IP> placeholder in netplan example
* docs: tighten <PEER_LAN_IP> comment to 'local IP on this subnet'
* docs: make 'pick one' explicit for the persistent-config methods
Replace the weak one-liner with a bold "pick one" callout and a
two-bullet decision criterion (ls /etc/netplan/) so readers don't
mistake the two H3 sections for sequential steps.
* docs: add 'Find your account's NetBird range' to the masquerade page
Mirror the section already on the site-to-vpn page so readers learn to
use their account's /16 block rather than pinning the whole /10. Same
prose and netbird status recipe; trailing line adapted to reference
100.64.0.0/10 (the placeholder used elsewhere on this page).
* docs: remove 'Related' Tiles block from masquerade page
* docs: align security warning with the recommended /16 range
* docs: restore cross-link from advanced-configuration to masquerade
* docs: drop ping from the test-route example
ping would fail for ACL reasons (not routing reasons) on policies
scoped to specific TCP ports, misdirecting troubleshooting. Use curl or
nc against an allowed port instead.
* docs: apply review findings to masquerade page and legacy warning
masquerade.mdx
- add "Disable masquerade on the routing peer" section (dashboard +
API path), so the page actually documents the toggle, not just
the prerequisite
- "What changes when masquerade is off": say the route lives on the
destination host (or its gateway for multi-hop)
- forward-ref "Find your account's NetBird range" from the inputs
list to remove the substitute-then-rewind loop
- ip route del: include via <PEER_LAN_IP> so the test takedown is
unambiguous
- netplan prose: spell out that you append to the existing routes:
list, not add a second routes: key (YAML rejects that)
- verify output: use 192.168.1.10 for the routing peer so it stops
colliding with the 192.168.1.50 used as the destination's own IP
in the netplan example
- add an end-to-end verification step (curl + tcpdump) so a reader
confirms source IPs are actually preserved, not just that a route
exists in the table
advanced-configuration.mdx
- rewrite the contradictory Warning so it scopes correctly to legacy
Network Routes (which match peer NetBird IPs only) and points
readers to the Networks path when they want policy-layer ACLs
with masquerade off
* docs: promote the /16 substitution reminder to a Note callout
* docs: clearer wording for the /16 substitution Note
The agent already enables ip_forward inside the container's own network
namespace when it has NET_ADMIN, so the blanket claim that a container
cannot do this on its own is misleading. The preceding paragraph
already covers the fallback case when the agent cannot modify sysctl.
* docs: rewrite Site-to-VPN SNAT requirement to always be manual
The dashboard Masquerade flag does not cover the Site-to-VPN direction on
any route — the marking rules NetBird installs are only wired up when a
policy targets the resource, and the documented flow uses a peer-to-peer
policy. The old guidance ("on Linux kernel mode, no manual SNAT needed")
was wrong, so manual SNAT is now framed as required on every routing peer
regardless of OS or WireGuard mode.
Also adds an nftables example alongside the iptables one, drops the
"(If applicable)" qualifier from the Step 3 heading, fixes the four
in-page anchor links that were already 404ing against the old heading,
and reframes the Step 4 masquerade-flag note plus the Outbound SNAT
requirement and Troubleshooting sections to match.
Verified end-to-end in a kernel-mode Linux lab: with the documented setup
(masquerade=true, peer-to-peer policy only, no manual SNAT) curl from a
clientless device to the overlay peer's NetBird IP times out; adding
either the iptables or the nftables rule from the new Step 3 makes it
return HTTP 200.
* docs: make Step 3 SNAT examples persistent
The previous version showed runtime iptables/nft commands with
persistence as a trailing comment. Replace with two equivalent
fully-persistent options: iptables-persistent (recommended) and a
dedicated systemd-unit + /etc/nftables.d/ file for nftables-native
setups.
Explicitly call out why /etc/nftables.conf is not the right persistence
target — its default starts with "flush ruleset", which wipes the
iptables-nft chains NetBird installs.
Both options verified end-to-end in a lab: rule applied, curl succeeds;
rule removed (simulating reboot), curl fails; reload via
netfilter-persistent / systemctl restart, curl succeeds again.
* docs: drop nftables-only option from Step 3
iptables-persistent works on every Linux NetBird supports — whether the
underlying backend is iptables-legacy or iptables-nft — so a separate
nftables variant with its own systemd unit was strictly more complexity
for the same outcome. Keep the iptables-persistent block as the single
Linux instruction.
* docs: drop UFW/firewalld FORWARD caveat from Step 3
The note was scoped to a minority of routing peers (those running UFW or
firewalld with default-DROP on FORWARD), and the persistence guidance
was too vague to be actionable. The symptom — packets reaching the
routing peer but not the target — is already covered by the
Troubleshooting section, which is enough of a lead for affected users.
* docs: drop standalone Outbound SNAT requirement section
The section's three takeaways — ACL ipset rejects routed-CIDR sources,
SNAT rewrites the source to a known NetBird IP, dashboard Masquerade
flag doesn't cover this direction — are already covered inline in Step
3 and the Step 4 masquerade note. Fold the one unique bit (the ipset
mechanic) into Step 3's opening sentence and drop the standalone
section plus the three "see Outbound SNAT requirement" backreferences
that pointed at it.
* docs: use ss -tan in Test Connectivity verification
The previous command (ss -tnp | grep :8080) filters by process and
misses TIME-WAIT sockets, which are kernel-owned. After a fast curl the
TCP connection closes before ss runs, so the user only ever sees the
LISTEN socket — no indication of the source IP. ss -tan lists all
states, so the TIME-WAIT entry showing the routing peer's NetBird IP as
the remote address is reliably visible for ~60 s.
Verified end-to-end in a kernel-mode Linux lab.
* docs: make Linux static route in Step 6 persistent
Replace the runtime "ip route add" + persistence-as-a-comment with two
fully-persistent options: a netplan drop-in (Ubuntu Server default) and
an nmcli equivalent (RHEL / Fedora / desktop). The netplan YAML was
validated against netplan generate. Also annotate the Windows command
to highlight that "-p" is what makes it persistent.
* docs: drop unverified pfSense/OPNsense and MikroTik examples
Neither platform ships a first-class NetBird routing-peer setup, and we
have no way to verify the SNAT commands in those sections work as
written. Replace with a single "Other platforms" paragraph that points
back to the general principle (any SNAT that rewrites the site-CIDR
source on egress from wt0 is sufficient) without claiming to give
verified instructions. Also tighten the Prerequisites line that
referenced "per-platform SNAT syntax" that no longer exists.
* docs: rewrite DNS NXDOMAIN troubleshooting entry
The previous entry referenced a "127.0.0.1-co-located NetBird resolver"
that doesn't exist — the doc's own DNS section explicitly notes that
the NetBird daemon binds its resolver on the peer's own NetBird IP,
not on 127.0.0.1. The "binding loopback causes it to refuse forwarding"
explanation was therefore exactly backwards.
Replace with a dig-based isolation flow that distinguishes the three
real failure modes (timeout = dnsmasq not reachable on the site IP;
SERVFAIL = forward to NetBird resolver failed; NXDOMAIN = wrong FQDN).
Diagnostic flow verified end-to-end in a lab — valid hostnames return
NOERROR with an answer record, unknown ones return status: NXDOMAIN as
described.
Matches the dashboard rename. The setting moves DNS resolution for
routed domains from the client to the routing peer; wildcard routing
is one consequence rather than the primary purpose, so the canonical
section now leads with that framing.
Heading anchor changes from #enable-dns-wildcard-routing to
#enable-routing-peer-dns-resolution. Keeps an invisible legacy anchor
on both pages so external bookmarks still scroll to the section.
The Networks and Network Routes "By Scenario" / "By Resource Type" /
"By Configuration" subgroups had grown into reskinned walkthroughs of
flows already on the concept pages. Collapse to what's actually
distinct, flatten the survivors up one level, fold unique nuggets
into the concept pages.
Networks:
- Delete the "By Resource Type" trio (Multiple IP Resources, Domain
Resources, Wildcard Domains) and Remote Worker Access — all rehashes
of /manage/networks. Fold the wildcard-vs-base-domain gotcha and the
shared-policy pattern into the concept page.
- Delete the Use Cases overview; fold the VPN-to-Site framing into the
concept page.
- Flatten access-home-devices and cloud-to-on-premise up out of
/by-scenario/.
Network Routes:
- Consolidate site-to-site-{home,office,cloud} into one
/manage/network-routes/use-cases/site-to-site page covering the
shared walkthrough plus AWS/GCP/Azure routing-peer requirements.
- Move exit-nodes, access-control, overlapping-routes, and
advanced-configuration up out of /by-{scenario,configuration}/.
- Trim advanced-configuration (301 → 144 lines), dropping masquerade
basics, ACL setup, site-to-site flow, and HA repetition duplicated
elsewhere. Keep the masquerade trade-off matrix, Networks-vs-Routes
comparison, troubleshooting, and debug commands.
- Delete the Use Cases overview.
Permanent redirects added for every removed URL. Inbound references
updated across introduction, ipv6, homelab, cloud, security,
site-to-site overview, android-tv/tvOS install pages, and the concept
pages.
* docs: add Site-to-VPN scenario guide
New dedicated guide for letting clientless devices on a local network
initiate connections to NetBird peers (the reverse of VPN-to-Site).
Covers static-route and DNAT options, DNS resolution via dnsmasq, and
explains why the target peer always observes the routing peer's NetBird
IP as the source.
- Add src/pages/manage/network-routes/use-cases/by-scenario/site-to-vpn.mdx
- Wire it into NavigationDocs.jsx
- Update the site-to-site overview table row to point at the new page
- Replace the stub Site-to-VPN subsection in site-to-site-office.mdx
with a pointer to the new guide
* docs(site-to-vpn): correct source-IP section, add firewall and interface notes
- Source IP Behavior: remove the option that suggested emptying the
destination peer's policies. That doesn't preserve source IP; it just
tears down the wireguard pairing. Replace with an honest "not possible
with legacy Network Routes."
- Step 3: call out that hosts with FORWARD-DROP firewalls (UFW, firewalld)
need an explicit ACCEPT rule between the site interface and wt0.
- Option B: prefix the DNAT step with `ip -br addr` so customers find the
right site-facing interface instead of assuming eth0.
- Step 1: use "Name" for the setup key field instead of the route-only
"Network Identifier".
* docs(site-to-vpn): tighten prereqs, firewall step, and source-IP wording
- Drop generic prereqs (account, routing peer hardware, target peer)
- Reduce Step 3 to the host-firewall FORWARD rule
- Label Networks-feature Site-to-VPN as 'not possible' rather than limited
- Rename topology arrow to 'NetBird Overlay'
- Clarify masquerade lives on the routing peer in troubleshooting
* docs(site-to-vpn): switch primary path to Networks; document outbound SNAT requirement
Verified in the lab that Networks supports Site-to-VPN with the same
shape as Network Routes (Resource + Routing Peer + peer-group policy).
The differentiating factor is not the feature but the routing peer
platform: NetBird's masquerade flag does not install a working outbound
SNAT on non-Linux peers or in userspace mode, so the user must configure
it explicitly on the routing peer or upstream firewall.
Doc changes:
- Lead with Networks; Network Routes is now framed as an equivalent
alternative rather than the only option
- New Step 3 dedicated to the outbound SNAT (Linux iptables, pfSense /
OPNsense, MikroTik examples)
- New section "Outbound SNAT requirement" explaining why the destination
peer's access control rejects unrewritten site IPs and where the
dashboard masquerade flag is and isn't sufficient
- Up-front Warning calls out the platform requirement so customers don't
silently misconfigure
- Troubleshooting entry updated to point at SNAT counters and tcpdump
- Updated Source IP Behavior section to reflect that the behavior is the
same on both Networks and Network Routes
Parent page changes:
- /use-cases/site-to-site: Scenario Support table now shows Site-to-VPN
as Yes on both Networks and Network Routes; "Which Scenario Do I Need"
row points at both implementations
* docs(site-to-vpn): make static route the only Step 6 path; move DNAT to appendix
The static-route approach is the canonical setup; the per-service DNAT
option is a fallback for sites where routing changes aren't possible.
Treat it that way in the doc to keep the main flow linear.
- Step 6 now describes only the static-route approach (former Option A)
- Add a one-line pointer at the end of Step 6 to the appendix for sites
where the route can't be set
- Move the DNAT instructions to a new appendix at the bottom of the page
- Simplify Test Connectivity to a single curl
- Trim the Option-A/Option-B framing from the Troubleshooting "Connection
times out" entry
* docs(site-to-vpn): drop Source IP Behavior section
The "Outbound SNAT requirement" section already covers why the source IP
ends up as the routing peer's NetBird IP; a separate Source IP Behavior
section was repeating the same point and adding a speculative paragraph
about future Networks support. Drop both, plus the up-front Warning that
pointed at the removed section.
* docs(site-to-vpn): drop the Networks-vs-Network-Routes note
The guide is written around Networks; the side-note suggesting Network
Routes as an alternative path adds noise without value. The Step 4 inline
note keeps the Network Routes equivalent for anyone who needs it.
* docs(site-to-vpn): drop the inline Network Routes equivalent note
The guide is Networks-only now. Pointing readers at Network Routes mid-flow
just creates two paths to maintain without serving the reader who's
following the steps in front of them.
* docs(site-to-vpn): move page under Networks → Use Cases
The page describes a Networks-based setup; living under Network Routes
mis-categorised it.
- git mv to /manage/networks/use-cases/site-to-vpn.mdx (as a direct
child of Use Cases, not under By Scenario)
- Navigation: remove entry from Network Routes → By Scenario, add under
Networks → Use Cases
- Redirect old URL (/manage/network-routes/use-cases/by-scenario/site-to-vpn)
to new URL, permanent
- Update in-tree links in use-cases/site-to-site/index.mdx and
network-routes/use-cases/by-scenario/site-to-site-office.mdx
* docs(site-to-site): drop Network Routes mentions for Site-to-VPN
The Site-to-VPN guide is Networks-only; the overview page shouldn't
still be listing Network Routes alongside it.
* docs(site-to-vpn): trust NetBird's automatic SNAT on Linux kernel mode
On Linux in kernel mode, NetBird installs the SNAT itself when masquerade
is enabled on the routing peer — the user does not need a manual iptables
rule. Reframe Step 3 around this:
- Linux: enable ip_forward only; NetBird does the SNAT
- Non-Linux (pfSense / OPNsense / MikroTik / Windows / macOS / userspace):
configure manual outbound SNAT on the routing peer or upstream firewall
- Tighten the "Outbound SNAT requirement" appendix accordingly
- Move the explicit Linux iptables MASQUERADE rule into a troubleshooting
fallback for the case where NetBird's automatic SNAT doesn't fire
* docs(site-to-vpn): drop sysctl ip_forward instruction on Linux
NetBird handles IP forwarding itself on Linux; the manual sysctl was
unnecessary noise. Keep the host-firewall FORWARD-ACCEPT note since
UFW/firewalld setups still need it.
* docs(site-to-vpn): route the account's /16, not the entire /10 CGNAT range
NetBird assigns each account one /16 block out of 100.64.0.0/10 (chosen
randomly, customisable). Routing the whole /10 sends unrelated CGNAT
addresses through the routing peer; the correct target is the account's
own /16.
Step 6 now:
- Explains the /16-per-account model with the 64-block context
- Shows how to read the account's /16 from `netbird status` on any peer
- Switches the Linux / Windows / DHCP-option-121 examples to a concrete
/16 example (100.121.0.0/16) with a note to substitute your own
* docs(site-to-vpn): clarify when the target peer uses a setup key
Setup keys are for service / appliance peers; user peers (laptops,
workstations) enroll through SSO and inherit groups from existing
assignments. Reword the target-peer instruction to reflect that
distinction.
* docs(site-to-vpn): rename target peer to overlay-peer / overlay-peers
The previous backup-collector / backup-collectors naming carried
scenario-specific framing into the step examples. Use the generic
overlay-peer / overlay-peers throughout to keep the guide universal.
* chore: add trailing commas in Kubernetes nav entries
* Revert "chore: add trailing commas in Kubernetes nav entries"
This reverts commit d11b7eb7d0.
* docs(event-streaming): add Wazuh integration guide
Documents how to wire NetBird's Generic HTTP event-streaming integration
to a self-hosted Wazuh manager: NetBird-side configuration, KQL queries
for audit and traffic events in the Wazuh dashboard, and a schema
reference for both event shapes via the receiver wrapper.
Adds the page to the Stream Activity Events sidebar and the
event-streaming index.
* docs(event-streaming): replace Wazuh Generic HTTP screenshot
* ci: validate PRs with build and MDX heading linter
Adds a pull_request workflow running npm run lint:mdx, npm run build,
and npm run lint so heading-hierarchy bugs and broken builds get caught
before merge rather than after.
The new linter (scripts/lint-mdx-headings.mjs) enforces that the first
heading is h1 and that heading levels never jump by more than one. Also
fixes three existing pages that had no h1 title — two were using a
legacy export const title pattern, one was missing a title entirely.
* ci: use npm install since lockfile is gitignored
package-lock.json is in .gitignore, so npm ci and setup-node's npm
cache both fail on a fresh CI checkout. Match the Dockerfile pattern
(npm install, no cache) instead.
* ci: drop ESLint step; project config is broken
`npm run lint` fails with 'Converting circular structure to JSON'
under ESLint 9.x — the repo has no .eslintrc or eslint.config file,
so the legacy resolver hits the React plugin's circular reference.
This is pre-existing (build_n_push.yml never ran lint, so it stayed
hidden); fixing it needs flat-config migration and is out of scope.
Drop the step until that lands.
* docs: rewrite traffic events logging Limitations section
The previous matrix mixed several inaccurate claims about feature
availability across WireGuard modes. Replace it with the actual
constraint — policy IDs and blocked events are only reported when
the destination/routing peer is in userspace mode — plus the
command Linux operators use to force userspace mode.
Collapse the two duplicated inline notes in the Correlating events
section into short pointers to Limitations so the constraint and
command live in one canonical place.
* Update src/pages/manage/activity/traffic-events-logging.mdx
Co-authored-by: Viktor Liu <17948409+lixmal@users.noreply.github.com>
---------
Co-authored-by: Viktor Liu <17948409+lixmal@users.noreply.github.com>
The page jumped from h1 directly to h3, leaving no h2 heading and
breaking the docs build. Promote both NetworkRouter and NetworkResource
sections to h2 so the hierarchy is contiguous.
House style writes "Zero Trust" / "zero trust" without a hyphen
in prose. Sweep all hyphenated prose occurrences under `src/pages/`
to match.
URL slugs (e.g. `/use-cases/security/implement-zero-trust`) and
external links (CrowdStrike press release / blog URLs that include
`zero-trust` as a path segment) are intentionally preserved.
Earlier docs asserted that policies using `ALL`, `ICMP`, or portless
`TCP`/`UDP` must be bidirectional. Data-plane testing on NetBird
0.59.10 shows the engine honors the direction flag for every
protocol — peer-d's iptables only installs the destination-side
`ACCEPT` rule, so reverse-initiated traffic is dropped at the source
even when the policy uses `ALL` or `ICMP`. The greyed-out direction
toggle in the dashboard is a UX guardrail, not an enforcement gap.
- manage-network-access.mdx: rewrite the Policies overview and
Multiple Mesh Networks paragraphs; drop the outdated `Note`
callout; trim Creating Policies guidance.
- access-control/index.mdx: rewrite Protocol-Specific Behavior;
drop the "Always Bidirectional (regardless of UI setting)" list.
- implement-zero-trust.mdx: soften TCP/UDP+ports framing.
- troubleshooting-client.mdx: drop "always true for the protocol
`ALL`" clause from the bidirectional-rule bullet.
Network-resource (routing peer) policies remain genuinely
unidirectional — that statement preserved.
New page covering how to pre-populate default.json so NetBird peers
register with the right settings on first start in IaC, Docker, and
Kubernetes deployments. Documents file location across OSes, common
keys (with guidance to leave PrivateKey empty and treat PreSharedKey
as optional), runtime setup-key injection with worked Docker and
Kubernetes ConfigMap + Secret examples, backup hazards around the
embedded WireGuard private key, and how to verify registration via
netbird status --check startup, --json, and GET /api/peers.
Includes a callout that this workflow is for unattended workloads
only -- end-user devices should still enroll via the SSO flow so
Zero Trust can re-verify the user identity.
Linked from Manage NetBird -> Peers, right after Setup Keys.
* docs(routing-peers): apply outstanding review feedback
- Drop the unverified Cloud-specific settings subsection (AWS/GCP/Azure
bullets) and the related AWS source/destination pitfall bullet
- Spell out "high availability" in the Masquerade note for clarity
* docs(routing-peers): expand inbound cross-links to How Routing Peers Work
Surface the routing peer primer from 11 high-leverage pages so readers
landing in a configuration or scenario guide can find the mental model
without having to backtrack through the sidebar.
- Index pages (manage/networks, manage/network-routes): move the
cross-link from the page top into the Routing Peer(s) subsection,
where it sits adjacent to existing routing-peer guidance
- exit-nodes scenario: cross-link inside the Routing Peer subsection,
anchored at #exit-node-mode
- internal-dns-servers: cross-link under Domain Resources and Routing
Peer DNS, anchored at #routing-peer-dns-resolution
- Procedural and comparison pages (access-control, by-scenario VPN-to-Site
guides, site-to-site overview, Kubernetes operator, routing peers in
Kubernetes): cross-link near the page top with section-specific anchors
* docs(routing-peers): spell out HA across the primer and cross-link notes
- Index-page cross-link notes (manage/networks, manage/network-routes):
expand "HA" to "high availability" in the bullet list
- Primer page: spell out the three remaining HA references in the High
availability section and Common pitfalls; use "highly available peers"
as the adjective form
* docs: add How Routing Peers Work concept page
Add a feature-agnostic primer covering the routing peer mental model:
traffic flow through forward vs input chains, host requirements (IP
forwarding on Linux/Windows, container caps, cloud settings), HA modes
(primary/failover and equal-metric latency switching), masquerade,
access control, DNS routing, exit nodes, and common pitfalls. Surface
it in the sidebar under Networks and cross-link from both the Networks
and Network Routes concept pages.
* docs(routing-peers): apply review feedback
- Clarify mental-model walkthrough describes the Linux kernel-mode path
- Expand OS list to Linux/Windows/macOS/FreeBSD/Android/tvOS/Docker
- Correct container IP-forwarding guidance: set sysctl on the host
- Reframe Windows NB_ENABLE_LOCAL_FORWARDING as opt-in for exposing
services on the routing peer's local addresses, off by default
- Soften failover wording to avoid implying tunnel rebuild; scope
reset claim to established TCP connections, drop "typically"
- Add masquerade-off caveats: Linux only, breaks HA
- Drop unfounded ACL-Groups-require-masquerade Warning
- Drop misplaced internal-DNS-resolver link from DNS section intro
- Rename Wildcard domains section to Routing Peer DNS Resolution
- Drop container/host IP-forwarding pitfall (not a real-world failure)
- Rephrase exit-node ICMP pitfall: clients can't connect at all
* docs(routing-peers): add example for forward vs input chain policies
A concrete scenario (office subnet behind the peer + Grafana on
TCP/3000 + SSH on TCP/22) showing the two policies needed: a network
resource policy on the forward chain and a peer-to-peer policy on
the input chain.
Adds a new API guide covering the cross-tenant `?account=<tenant_id>`
query parameter that scopes calls to a specific tenant under an MSP
account. Includes setup steps for picking a user and generating a PAT,
how to retrieve tenant IDs via the MSP listing endpoint, read/write
examples, and auditing/security guidance.
Cross-references added from the Authentication guide, the MSP Portal
page, and the public-api token-creation page so the new guide is
discoverable from each entry point an MSP user is likely to hit.
* docs(macos): add CLI-only binary install and MDM deployment guide
Document the previously undocumented binary-only install path for macOS
using USE_BIN_INSTALL and SKIP_UI_APP flags. Add a new guide for
building custom CLI-only .pkg packages for MDM fleet deployment,
covering pkgbuild workflow, pre/postinstall scripts, setup key
enrollment, and update strategies.
* docs(macos): add warnings about unsigned binaries in tarballs
The darwin tarballs from GitHub releases contain unsigned binaries —
only the official .pkg goes through the sign pipeline. Add warnings
to both the install page and MDM guide, and document the full signing
workflow: codesign for the binary, pkgbuild --sign for the package,
and optional notarization via notarytool.
Add silent installation section to the Windows install page covering
the AUTOSTART MSI property and the fixed EXE silent install default.
Update Intune and Acronis deployment guides to mention autostart.
Jack Carter