* fix: correct ICE candidate field semantics in troubleshooting docs
The ICE candidate (Local/Remote) field shows the selected pair only, so
every relayed connection reads -/- on both peers, even when STUN worked
and srflx candidates were gathered (symmetric NAT case). Lab-verified on
client 0.76.3 against NetBird Cloud.
- relayed-connections: fix the relay/relay sample to -/-; reword the
candidate table (the '-' row named one cause for a symptom with two);
replace the 'weaker side' heuristic, which cannot work when both sides
show '-', with a client-log method that splits the two causes; mark
'relay' as the legacy TURN fallback path
- troubleshooting-client: replace the 0.27.4 status sample with 0.76.3
output (Direct/Routes fields are gone; Relay server address and
Networks exist now) and update the field explanations to match
* docs: show Networks line with routed subnet and exit node in status sample
Verified output: a client's status -d lists the routes a routing peer
serves it under that peer's block (Networks: 0.0.0.0/0, 10.0.0.0/24),
while the trailing summary Networks line stays '-' unless this device
routes something itself. Adds a Networks field explanation.
* docs: accuracy and readability pass on status field docs
- status sample: kernel WireGuard interface implies Linux, so the sample
host is linux/amd64 now
- clearer table cells (candidate pair, not connection; per-row P2P
implications) and untangled the log-reading sentence
- consistent phrasing in the Relay server address and Networks field
explanations
* docs: expand srflx and prflx abbreviations in the candidate table
srflx (server-reflexive) and prflx (peer-reflexive) were used without
ever being expanded anywhere in the help pages.
* docs: mark turn.netbird.io as fallback-only on Ports & Firewalls
Since v0.29.0 (relay integration, #2244) clients relay through
*.relay.netbird.io and contact TURN only when that relay is unreachable
or the remote peer runs an older client. The rule stays recommended as
the last relay path.
* docs: include bare relay.netbird.io in the fallback-only note
Clients bootstrap against relay.netbird.io before being assigned a
regional *.relay.netbird.io host, so both belong in the reference.
* docs: trim the keep-this-rule advice from the fallback note
* docs: call the TURN relay legacy in the fallback note
Matches the 'Legacy fallback' wording in the relayed-connections
candidate table.
* docs: srflx plus failed checks does not skip the firewall steps
A gathered srflx candidate proves STUN discovery only; the failed
connectivity checks can still be a host firewall or a destination-scoped
egress policy, so clear Steps 4-5 on both peers before concluding
symmetric NAT.
* docs: fix self-hosted SCIM Tenant URL and explain duplicate users
The embedded Entra SCIM page showed the NetBird Cloud Tenant URL
(api.netbird.io) on a self-hosted page; a reader who copies it points
Entra at Cloud and provisioning silently fails. Use the reader's own
management domain instead.
Add a section explaining why externalId must map to objectId: NetBird
matches users by stable ID, not email, so a mailNickname externalId
creates a same-email duplicate of an existing sign-in user. Includes
remediation for accounts that already have duplicates.
* docs: safer duplicate-user remediation via integration reset
Address review feedback: don't tell operators a SCIM-created account is safe
to delete based on origin alone. Recommend deleting the integration to clear
the synced accounts (sign-in accounts are untouched), then reconfiguring with
externalId=objectId and re-provisioning. If removing a single account, verify
ownership and migrate peers/access first.
Add a decision-flow guide for "NetBird feels slow" that helps a reader
find whether the tunnel, their own connection, a routing peer, or the app
is the real cause, instead of assuming NetBird is at fault.
The page leads with the path traffic takes, a one-minute Quick test that
resolves the two most common causes (a relayed peer, or the local
network), then a Start here checklist that links down to detail sections:
checking the connection with netbird status -d, setting a baseline with
iperf3 in both directions, isolating the slow hop, ruling out packet size
and inspecting firewalls, and separating startup delays from throughput.
Add a reusable PathFlow component that draws the hop-by-hop path as a
labelled icon flow, used for the overview, the routing-peer example, and
the recap. Wire the page into the docs sidebar and the troubleshooting
hub.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add clientless RDP for third parties use case guide
Covers publishing an internal RDP host as a TCP reverse proxy service
as an RDP gateway replacement for third parties that cannot install
the NetBird client: single-host resource, TCP service with auto-assigned
listen port, mandatory IP allowlist/CrowdSec restrictions, .rdp file
handover, and the L4 security boundaries (no SSO/PIN on TCP, port
re-rolls on service re-create, service publishing bypasses access
policies).
* docs: make CrowdSec conditional on broad allow rules, add UDP transport note
Review feedback: CrowdSec Enforce is redundant behind a strict single-IP
allowlist, so it is now recommended only when allow rules are broader.
Adds a note that RDP's optional UDP transport cannot be used through the
shared proxy cluster (independent auto-assigned listen ports) and that
clients fall back to TCP-only automatically.
* docs: update access control screenshot to match single-IP recommendation
* docs: scope the UDP transport limitation to the shared proxy cluster
Auto-assigned listen ports apply to the NetBird-hosted cluster only; a
BYOP cluster can bind a TCP and a UDP service to the same custom port.
* docs: UDP transport through a BYOP same-port service pair is verified working
Tested with mstsc against a BYOP cluster binding TCP and UDP services on
one custom port: the client negotiates the UDP transport through the
proxy, and removing the UDP service degrades cleanly to TCP-only. Also
notes the macOS client does not support the RDP UDP transport.
* docs: scope the macOS UDP claim to what was observed
* docs: macOS UDP claim holds with the app's UDP setting enabled
* docs: split into shared-proxy and BYOP use cases, drop client-specific UDP note
Adds a comparison of the two proxy deployments (auto-assigned port and
TCP-only vs custom ports and RDP UDP transport), a BYOP walkthrough with
the same-port TCP+UDP service pair, and keeps resource setup, access
restrictions, and verification shared between both paths.
* docs: clarify BYOP TLS requirement and service-domain resolution, grammar fixes
* docs: add Quantum Resistance check to client status and make its fields navigable
Two related updates to the NetBird client status troubleshooting section,
prompted by an incident where a peer stayed invisible until Quantum Resistance
was turned off:
- Document the `Quantum resistance` status field as a cause and fix. A peer with
Quantum Resistance enabled only connects to peers that also have it enabled, so
a mismatch can keep a peer from connecting. Cross-link the Quantum-Resistance
doc and its permissive mode.
- Convert the flat peer-field list into per-field h3 subsections (Connection
type, Direct, ICE candidate, Last WireGuard handshake, Quantum resistance,
Transfer status) so each appears in the On this page nav.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: tighten status field descriptions per review
- ICE candidate: describe relay/host as the local and remote ICE candidate
types, and point to Connection type for whether the path is P2P or relayed,
since a host candidate does not by itself mean the remote path is direct.
- Last WireGuard handshake: distinguish an empty value (no handshake yet) from
an old timestamp (a previous connection that is now stale).
- Quantum resistance: call Rosenpass post-quantum key exchange rather than
encryption.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: promote Agent Network in the sidebar and make sections collapsible
Rework the docs sidebar navigation:
- Render any nav group flagged `featured: true` as a highlighted card at the
top of the sidebar, with an optional `badge` label (currently Agent Network,
"New"). The flag is data-driven, so a future feature can take the spot by
moving two lines.
- Add a dropdown chevron to every collapsible menu, including the top-level
sections and the featured card, so it is obvious they expand.
- Collapse the top-level sections by default and expand the active one, so the
sidebar reads as a clean menu.
- Only render the active-page marker while its section is open, fixing the
orange highlight bar that lingered after collapsing an active section.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: make sidebar section toggles keyboard-accessible
The collapse toggle was a click-only span, so after sections collapse by
default keyboard and screen-reader users could not expand a section or reach
its links. Make each toggle a semantic button with aria-expanded and an
aria-label, which restores keyboard operation and announces the open state.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: keep sidebar sections expanded by default, collapse only Agent Network
Restore the original behavior where top-level sections start expanded and only
the nested sub-groups start collapsed, instead of collapsing everything. The
featured Agent Network card keeps its own isOpen: false so it starts collapsed.
The dropdown chevrons, featured card, and keyboard-accessible toggles are
unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* Include Alpine Linux installation steps
Add installation instructions for Alpine Linux, including CLI and desktop app setup.
* Revise Alpine instructions
I omitted the fact that the community repo had to be enabled in my original commit
* Apply suggestion from @braginini
* Changes requested by @TechHutTV
Updated installation instructions for Alpine Linux and added commands for starting the NetBird service.
---------
Co-authored-by: Misha Bragin <bangvalo@gmail.com>
A property marked x-omit-from-example: true in the openapi spec is left
out of the composed request/response examples while staying fully
documented in the parameter list and schema blocks. Needed for mutually
exclusive field pairs (policy rule ports vs port_ranges), where
composing an example from every optional field shows a payload the API
rejects. Companion spec change: netbirdio/netbird#7158
* docs: unmanaged DNS mode also ignores Custom Zone records
A peer whose group is under DNS Settings -> Disable DNS Management (or
started with --disable-dns) never gets NetBird's resolver wired into the
OS, so Custom Zone records silently stop resolving along with
nameservers. The unmanaged-mode description, the Custom Zones
limitations list, and the DNS troubleshooting flow now say so, and the
troubleshooting page gains a confirm-managed-mode first check (the
existing --disable-dns isolation test reproduces this exact cause and
misreads as 'not NetBird DNS').
Also fixes the API Reference links to the canonical /api path (/ipa
redirects).
* docs: fix DNS API Reference link on the DNS landing page
* docs: explain macOS two-resolver-stack DNS behavior and the match-only vs primary nameserver split
Lab-validated against client 0.76.3 (macOS 26, NetBird Cloud):
- DNS troubleshooting: new Issue 5 'dig and host fail, but browsers and
curl work (macOS)' with the scoped-resolver vs resolv.conf explanation,
the language-runtime split table (pure-Go/dnspython/c-ares vs
getaddrinfo), and the Windows nslookup-vs-NRPT analog; renumbered
Issues 5-8 to 6-9; checklist step 6 now says why it prescribes
dscacheutil/Resolve-DnsName
- Internal DNS Servers: primary-vs-match now explains that match-only
leaves resolv.conf untouched on macOS; new warning that emptying a
match group's domains silently drops the search suffix (masked on
domain-joined Windows); split-horizon example gains the
route-everything-internal variant (the OpenVPN migration shape)
- DNS overview: macOS line now distinguishes scoped resolvers from the
primary case, where configd regenerates resolv.conf with NetBird's
resolver
* docs: add dashboard screenshot for the route-all-internal nameserver example
* docs: polish wording in the macOS DNS additions
* docs: promote the route-all-internal example to its own section
* docs: drop the Example prefix from the nameserver scenario headings
* docs: state the public-resolution prerequisite for an internal primary nameserver
* docs: make the direct-resolver check precise
* docs: anchor the scoped-resolver term to scutil output and split the dense solution paragraph
* docs: add corporate firewalls table to Ports & Firewalls
Add a "Corporate firewalls" section covering common enterprise firewall and
SASE products (Palo Alto, Fortinet, Cisco, Check Point, Zscaler, Netskope,
Cloudflare Gateway, Sophos, SonicWall, Barracuda). It explains how NetBird
behaves through a corporate firewall, that it falls back to the TCP/443 relay
when direct peer-to-peer is blocked so peers stay connected, and what to allow
per product, including which TLS inspection feature to exclude the NetBird
domains from.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: refine corporate firewalls section and cross-link from troubleshooting
Address review feedback on the new Corporate firewalls section:
- Distinguish the two firewall failure modes. Blocking outbound UDP falls back
to the TCP/443 relay, but TLS/DPI inspection of the control plane can prevent
connecting at all.
- Correct the STUN vs TURN roles. STUN enables direct connections, while TURN
and the relay service are the fallback, not a way to keep connections direct.
- Make the relay domains explicit in the inspection-bypass guidance, since a
*.netbird.io wildcard does not match the deeper *.relay.netbird.io hosts.
Cross-link the section from the relayed-connections guide (Step 3) and the
troubleshooting hub, since a corporate firewall blocking UDP is a common cause
of relayed connections.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add Palo Alto source-NAT guidance and surface firewalls at relay escalation
Corporate firewalls: note that some enterprise firewalls apply per-destination
(symmetric) source NAT, which defeats hole punching and forces the relay. Add
the port-preserving fix, with Palo Alto's Persistent Dynamic IP And Port mode in
its row and a general note covering the pattern and UDP session timeouts.
Relayed connections: the symmetric-NAT cause is often a corporate firewall the
operator controls, so reference the Corporate firewalls section at the final
escalation step, and scope the earlier "no firewall tuning will change that"
claim to mobile and cloud NAT where it actually holds.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: address second review pass on corporate firewalls guidance
- Broaden the firewall failure modes beyond UDP blocking and TLS inspection to
include blocked or proxied outbound TCP/443 and strict destination egress,
which break the control plane before any inspection.
- Note that reaching the NetBird service endpoints does not by itself prove a
direct peer path, since a firewall can allow STUN/TURN yet block UDP to peer
addresses. Qualify the relayed-connections conclusion accordingly.
- Match the STUN/TURN fix to the transport that netbird status reports: STUN is
UDP 80/443/3478/5555, TURN is UDP 80/443 plus TCP 443-65535, rather than
applying STUN's UDP ports to TURN.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: drop TURN wording from corporate firewalls guidance
Refer to the outbound relay endpoints as "relay" rather than "STUN/TURN" and
"Relay (TURN)" in the Corporate firewalls section, in line with NetBird's relay
terminology. Endpoint hostnames are unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: replace TURN wording with relay in user-facing docs
TURN is legacy in NetBird, so the user-facing docs now call it the relay
service:
- Ports & Firewalls: rename the "Relay (TURN) service" endpoint and split the
two relay endpoints by transport (UDP/TCP and TCP) to keep them distinct,
and drop TURN from the notes and the JSON-download line.
- Relayed-connections and troubleshooting hub: drop TURN from the status and
rollout wording and the connectivity chip label.
- Zero Trust use case: describe STUN and relay instead of STUN/TURN.
Endpoint hostnames (turn.netbird.io) and the netbird status output are
unchanged. Self-hosted coturn documentation is intentionally left as-is, since
there TURN refers to the actual legacy software.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: scope TURN wording changes to Ports & Firewalls and relayed connections
Revert the TURN wording in the troubleshooting hub chip and the Zero Trust use
case, keeping the TURN-to-relay rename limited to the Ports & Firewalls and
relayed-connections docs for now. The corporate-firewalls cross-link chip in
the hub stays.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: sort the corporate firewalls table alphabetically
Order the firewall and SASE rows alphabetically by product (Barracuda through
Zscaler) so readers can scan for their vendor.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add pfSense and OPNsense to the corporate firewalls table
Add pfSense and OPNsense rows, each linking to its existing NetBird setup
section for keeping connections direct (Static Port outbound NAT, or
Endpoint-Independent NAT / EIM-NAT beta on pfSense). Broaden the table intro
from "enterprise" firewalls since these are open-source firewalls.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* fix: update self-hosted docs for the Traefik reverse proxy
`getting-started-enterprise.sh` deploys Traefik instead of Caddy, but the
enterprise getting-started page still described the Caddy stack. The worst of it
was the custom-TLS appendix, which edits a `Caddyfile` the installer no longer
generates, so it could not be followed at all.
- Rewrite the custom TLS certificate appendix for Traefik: supply the
certificate through the file provider, then remove both the ACME resolver
flags and the four router `certresolver` labels. Removing the labels alone is
not enough, because the certificate already stored in `acme.json` continues to
be served in preference to the supplied one.
- Document renewal correctly. Traefik watches the dynamic configuration file
rather than the certificate files it references, so replacing the certificates
has no effect until that file is touched. No container restart is needed.
- Correct the certificate issuance guidance on the enterprise page and in
certificate troubleshooting. The generated stack uses the TLS-ALPN-01
challenge only, so TCP/443 is what must be reachable; port 80 serves the
HTTP→HTTPS redirect and is never used for validation. The community installer
sets the same flag, so this applies to both.
- Drop the `Caddyfile` row from the generated-files table. The installer writes
`.env`, `docker-compose.yml` and `config.yaml` only, and configures routing
and TLS through Traefik labels and command flags.
- Replace `caddy` with `traefik` in the stack components table, the log
commands, and the cleanup instructions, and fix `selfhosted-guide` still
calling the bundled proxy Caddy where the same page elsewhere says Traefik.
- Add the consequences that were previously unstated: a peer that does not trust
a private issuing CA fails to connect, `config.yaml`'s empty `server.tls`
block is intentional, and dropping the `80:80` mapping costs the HTTP→HTTPS
redirect.
* fix: mount the Traefik dynamic config as a directory, not a single file
A bind-mounted single file is pinned to one inode, so any tool that replaces the
file rather than editing it in place — most editors, `sed -i`, many
configuration-management tools — leaves the container reading the old content
indefinitely, with no error and no way to recover by touching the new file.
Traefik's own documentation recommends `directory` over `filename` for this
reason.
Switch to `--providers.file.directory=/etc/traefik/dynamic` with `./traefik`
bind-mounted, and move the dynamic configuration to `traefik/dynamic.yaml`. The
renewal instruction is otherwise unchanged: the certificates are referenced
rather than watched, so they are picked up by touching the dynamic configuration,
without restarting any container.
Also drop the `tls.certificates` list from the example. It is redundant next to
`stores.default.defaultCertificate`, which already covers every connection
including clients that send no SNI.
* docs: scope the custom TLS appendix to the fresh enterprise install
The appendix sits on a page that also documents `migrate-to-enterprise.sh`, and
the two paths differ. A migrated deployment is built on the community
`getting-started.sh` render, which already configures a file provider when the
reverse proxy is enabled. `providers.file.filename` and
`providers.file.directory` are mutually exclusive, so following these steps
verbatim there would declare a conflicting second provider.
Note that deployments which already have a file provider should extend its
dynamic configuration instead, and adjust router names to match their own
Compose file.
* docs: apply NetBird house style to the custom TLS appendix
Replace the em dashes added by the previous commits with commas, colons and
parentheses. House convention is to reach for an em dash deliberately or not at
all, and the appendix had accumulated eleven of them.
Also state when not to follow the appendix at all: the default Let's Encrypt
path renews itself, and everything in the appendix makes renewal the operator's
responsibility. Expand SNI on first use.
* docs: correct the migrate-path guidance in the custom TLS appendix
Running the appendix against a real migrated deployment (community install with
the built-in Traefik, then migrate-to-enterprise.sh with Postgres and traffic
flow) showed the previous note pointed at the wrong difference. The four router
names are identical to the fresh install, so there is nothing to adjust there.
What actually differs is which file holds each label. `netbird-dashboard`,
`netbird-grpc` and `netbird-backend` are in `docker-compose.yml`, while
`netbird-flow` is on the `flow-receiver` service in
`docker-compose.override.yml`, so the deletions span two files. The `traefik`
service and the ACME flags stay in `docker-compose.yml`.
Also state why a deployment that already has a file provider must extend it
rather than add a second one: `providers.file.directory` and
`providers.file.filename` are mutually exclusive.
* docs: tighten the custom TLS appendix
The appendix had grown to four stacked callouts, two of them before the reader
reaches the first step. Cut it from 690 to 554 words and from four callouts to
two, without dropping anything load-bearing.
Move the migrate-path and existing-file-provider caveats out of a 106 word
preamble block and into the two steps they actually affect. Drop a decorative
sentence about all routes passing through Traefik, shorten the inode note, and
trim the SNI gloss to expanding the acronym.
* docs: find the resolver labels by grep instead of enumerating them
The appendix is the supported way to serve a custom certificate, not a stopgap,
so it should not hard-code "four labels, one on dashboard, two on
netbird-server, one on receiver". That count goes stale the moment a router is
added, and silently.
Replace the enumeration with a grep over `docker-compose*.yml`. It is shorter,
survives new routers, and spans `docker-compose.override.yml` on a migrated
deployment, which removes the need for a separate note about where the
`netbird-flow` label lives.
Also reword the intro so the file provider reads as the mechanism you enable
rather than something the installer failed to configure.
* docs: fix three gaps in the custom TLS appendix
- The `traefik` directory was never created. "Create `traefik/dynamic.yaml`"
fails in any editor that will not create a missing parent, so add the
`mkdir -p traefik` the steps assumed.
- `/certs` appeared in the dynamic configuration one step before the mount that
defines it. Say that it is a container path and where it comes from.
- Point the file-provider caveat at the named edit it refers to instead of "the
next step's first edit", and reword the grep sentence.
* docs: move MDM deployment guides under Manage > Peers
The five fleet-deployment guides (GPO, macOS .pkg, Jamf Pro, Kandji,
Intune) lived under Integrations, but nothing in them integrates with
NetBird's platform — they are peer onboarding at scale, which lives
under Peers. The label also collided with Access Control's
'Integrate MDM & EDR', which uses MDM in the opposite sense.
- Move pages from /manage/integrations/mdm-deployment/ to
/manage/peers/mdm-deployment/ with a permanent wildcard redirect
- Re-point legacy /how-to redirects directly at the new paths
- Move the nav group under Peers as 'MDM Deployment'; remove the
now-empty Integrations group
- Update internal links
* docs: link full GPO deployment guide from MDM integration page
* docs: show setup-key secret wiring and replica naming for k8s routing peers
Fold the two verified-novel bits from the Access Infrastructure
autoscaling tutorial before purging it:
- Replace the 'use a secret' Note with the actual kubectl create
secret + secretKeyRef wiring (matches what the NetBird operator
injects for routing peers)
- In the HA section, note that removing the static NB_HOSTNAME lets
each replica register under its pod name (client falls back to
os.Hostname(), which is the pod name in Kubernetes)
* docs: purge redundant Access Infrastructure tutorials
The four pages under Manage > Peers > Access Infrastructure were
2024-era SEO tutorials that duplicated canonical feature docs and
carried outdated claims (pre-rewrite SSH model without the built-in
SSH server, a Docker section that never actually enrolls the
container with a setup key, CrowdStrike presented as the only EDR
integration, stale v0.29 output and vintage-UI screenshots).
Cross-checked each page against its canonical counterpart; nothing
novel remained (the two useful Kubernetes snippets were folded into
the routing-peers use case in the previous commit).
- Delete the four pages and their screenshot directory
- Remove the Access Infrastructure nav group
- Redirect each URL to its canonical replacement:
secure-remote-webserver-access -> /manage/peers/ssh
setup-keys-add-servers-to-network -> /manage/peers/register-machines-using-setup-keys
access-internal-resources-from-autoscaled-environments -> /use-cases/kubernetes
peer-approval-for-remote-worker-access -> /manage/peers/approve-peers
- Re-point the legacy /how-to redirects at the same targets to avoid
redirect chains
* docs: reorder Peers nav into enrollment, approval, day-2 flow
Group the five enrollment methods first (Add Peers, Setup Keys,
Bootstrap via Config File, MDM Deployment, Browser Client), then the
Approve Peers admission gate, then running-peer features (SSH, Lazy
Connections, Remote Jobs) and Auto Update last. Approve Peers
previously sat between two enrollment pages.
* docs: cross-link DNS aliases and internal DNS pages, fix tutorial inaccuracies
The two pages solve adjacent problems (NetBird-hosted records vs
forwarding to existing internal DNS) but never pointed at each other.
Add a which-page-do-I-need Note to each.
Also fix defects in the DNS Aliases tutorial found while cross-checking
it against the Custom Zones reference and dashboard source:
- 'Keep this enabled' implied search domain is on by default; it is
off by default (DNSZoneModal.tsx: enable_search_domain ?? false)
- Step 3 said 'wildcard resource' but the steps add exact-name domain
resources
- Wrong alt text ('Delete DNS Zone') on the zone-config screenshot
- Add missing meta description and a link to the Custom Zones
reference
* docs: align MSP portal page with 2026 partner program, rename For Partners nav
Cross-checked the MSP portal page against the 2026 MSP/MSSP Partner
Program document:
- Point the application link at netbird.io/use-cases/msp (the program's
canonical page) instead of a demo-form URL displayed as netbird.io/msp
- State tenant plan options (Team or Business) and the post-trial
minimum (Team plan with one user)
- Mention CSV/PDF usage export alongside the API
- Clarify the 3-day trial for existing accounts brought in as tenants:
it is a window to subscribe the tenant under the MSP account
- Add a subtle msp@netbird.io contact line at the bottom
Also rename the For Partners nav entries by deliverable instead of
audience (the section header already says who it's for): MSP Portal,
Distributor Portal, Deploy with Acronis.
* docs: update CLAUDE.md for agent-network, proxy.js, and tooling gaps
Audited every claim against the current repo. Stack, routing, security,
and convention claims all still hold; four gaps had accumulated:
- Add agent-network/ to the content structure list
- Document src/proxy.js in URL Routing: /api data requests must be
rewritten there because the config rewrite loses data-request context
on client-side navigation (Next.js #39669) and strips pageProps
- Add npm run lint:mdx; note npm run gen requires a Go toolchain
- Note fenced mermaid code blocks render as diagrams
* docs: address review findings on PR #906
- Move the MDM deployment screenshot directories to match the new page
paths; the URL rewrite had updated MDX image references without
moving the assets, breaking all Intune/Jamf/Kandji images
- Normalize pre-existing double slashes in Jamf and Kandji image URLs
- Align the routing-peers secret example with bootstrap-via-config-file
(same secret name, so both now use the NB_SETUP_KEY data key)
- DNS aliases: include the routing peer's group in the zone's
distribution groups. Verified in client source: the DNS route
interceptor (priority 100) outranks local zone records (priority 75)
and never falls through, so clients forward routed-domain queries to
the routing peer, which must receive the zone to answer
* Update docs for reverse-proxy migration.
Fixes https://github.com/netbirdio/netbird/issues/6059.
However, make sure to have someone from NetBird review before the pull
request.
* typo fixes for reverse proxy change
* Improved documentation for crowdsec.
* harden: non-root container with tini, healthcheck, and a robust entrypoint
entrypoint.sh: escape sed metacharacters (\, &, #) so any future DocSearch value substitutes literally instead of crashing the pass or corrupting the bundle; rewrite only files that still contain the placeholder, making restarts no-ops; on substitution failure, log a warning and start the server anyway rather than crash-looping under restart: unless-stopped.
Dockerfile: run as the built-in non-root node user (artifacts chowned so the runtime sed keeps write access); add tini as PID 1 so SIGTERM actually reaches node and docker stop takes ~1s instead of the 10s kill grace; add a HEALTHCHECK so a dead server shows as unhealthy instead of silently Up.
Container-tested: boots 202ms, all routes/assets/redirects OK, metacharacter-laden values injected literally, uid 1000, health reaches healthy, restart idempotent (no rewrites, value intact), docker stop 0s.
* harden: substitute DocSearch placeholders independently; strip CR/LF from values
Review findings: the three substitutions were &&-chained, so one failing value skipped the remaining valid ones; and a raw newline in a value breaks the single-line sed command. Run each substitution independently, accumulating failures into one warning, and strip CR/LF in escape() (no legitimate DocSearch token contains them).
Container-tested: newline-laden appId is sanitized and all three placeholders still apply with no warning; forced full failure logs all three sed errors plus one warning and the server still starts healthy.
---------
Co-authored-by: Brandon Hopkins <brandon@techhut.tv>
* fix: serve props JSON for /api data requests via middleware rewrite
The /api/:path* -> /ipa/:path* rewrite in next.config.mjs is applied by
Vercel's routing to client-side props fetches
(/_next/data/<buildId>/api/....json), but the data-request context is
lost and the prerendered page HTML is returned instead of JSON
(vercel/next.js#39669). The router then never receives pageProps, so the
API sidebar stays collapsed and the tab title shows undefined until a
full reload. This half of the bug only occurs on Vercel infrastructure;
the dev server and next start resolve rewrites for data requests
correctly, and #900 fixed only the /ipa redirect half.
Middleware rewrites preserve data-request semantics, so rewrite /api/*
to /ipa/* in middleware for data requests only (x-nextjs-data header).
Regular page requests fall through to the existing config rewrites, and
the /ipa -> /api canonical redirect is unchanged.
* fix: move /api data-request rewrite into existing proxy.js
Next 16 uses proxy.js and rejects builds where both middleware.js and
proxy.js exist; this repo already had src/proxy.js for the
/docs-static/_next asset rewrite. Fold the /api -> /ipa data-request
rewrite into it and drop middleware.js. Verified the proxy intercepts:
data responses now carry x-middleware-rewrite: /ipa/... and JSON bodies.
* fix: map bare api.json data requests to ipa/introduction.json
The raw data-path fallback rewrote /_next/data/<build>/api.json to
/_next/data/<build>/ipa.json, but there is no /ipa index page; mirror
the /api -> /ipa/introduction rewrite instead.
The /ipa/:path* -> /api/:path* redirect also matched Next.js data
requests (/_next/data/.../ipa/...), returning a 308 instead of page
props. Client-side navigations to API pages therefore lost pageProps,
leaving the sidebar method list collapsed and the tab title undefined
until a full reload. Skip the redirect when the x-nextjs-data header is
present so props fetches go through; browser visits to /ipa/* still get
the canonical redirect to /api/*.
The supported identity providers were a bullet list of links, so none of
them appeared in the "On this page" navigation. Make each one a
subsection heading with its setup link, and promote Generic SCIM to a
top-level section so it is a peer rather than a sub-item. Also fix a
typo (identify -> identity).
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The collection now warns instead of silently ignoring immutable
setup-key parameters, refuses to un-revoke a key, and can rotate a
key that cannot enrol peers. Name lookups fail on duplicates instead
of picking one, group deletion can resolve auto_groups pins, a zone
name defaults to its domain, and a network router masquerades by
default. Update the troubleshooting entries that described the old
behavior and add symptom-shaped entries for the new failure modes.
* docs: masquerade-off HA is achievable, not impossible
Both the routing-peers page and the masquerade page stated that high
availability "stops working" with masquerade off. That reads as a flat
impossibility and loses a legitimate use case (source IP preservation for
audit, per-user database rules, or firewall policy keyed on the real source).
What is actually true is narrower: NetBird's half of the failover still
works, clients move to the standby peer on their own. What is missing is the
return route inside the destination network following that move. State the
condition instead of the impossibility, and add a short section on what
meeting it takes: distinct metrics so the active peer is the same for every
client, plus a virtual IP or a router-moved route so the next hop follows.
Both live outside NetBird, so the section names the pattern rather than
shipping a third-party config we would then own.
Also:
- Soften "failover is automatic and immediate". Clients re-select within
seconds, which is fast but not instant, and "immediate" invites a support
ticket from anyone who measures it. Phrased so it does not assert whether
the client or the management side detects the loss, which this change did
not verify.
- Warn against pointing the return route at both peers, as two static routes
or an equal-cost pair. It is the intuitive fix and it fails silently.
- Note that the second interruption on recovery cannot be avoided by pinning
the virtual IP to the standby, since the client's switch back is automatic.
Pinning the route while the client moves back strands the return path.
- The return route can live on the destination subnet's default gateway even
when the gateway and the routing peer share that subnet, which is the only
option when the destination host is not the customer's to configure. The
page previously offered the gateway only for a different-subnet
destination, and its persistent-config steps assume host access throughout.
* docs: health check must cross the path, not test the peer
A routing peer can stay enrolled and report healthy, with its WireGuard
interface present, while being unable to forward from the tunnel to the
destination subnet: a failed LAN interface, or a firewall change. Nothing
fails over in that state. NetBird sees a reachable peer, and a health check
that only looks for the interface sees a healthy one, so the return route
stays pointed at a peer that forwards nothing until someone intervenes.
Say that the check has to reach a destination through the tunnel.
* docs: held connections stall across a failover, they do not reset
Measured on a routing-peer pair with masquerade off: a held TCP connection
survives the switch. Four failovers, graceful shutdown and hard kill, all
showed the same signature — one round trip with multi-second latency, then the
same connection continuing with monotonic sequence numbers. No resets, and no
RST on the wire in any of them.
The reason is a property of masquerade being off: the addresses on the
connection do not change when another peer takes over, so the flow is portable
between peers, and the routed ACL accepts on addresses rather than on
connection state, so the standby forwards mid-stream packets it never saw a
handshake for.
Note this is specific to masquerade being off. The general high-availability
section still says established connections reset, which is the masquerade-on
default, where the standby would translate to a different source address.
Also trims the mechanism guidance to name the pattern rather than lean on any
one implementation, since which mechanism is right may change.
* docs: scope the reset claim to masquerade on, fix leftover contradiction
Review of the branch turned up three problems.
The Networks overview still said disabling masquerade 'breaks high
availability', one click from the page arguing it does not. Reworded to say it
makes high availability something you arrange rather than something you get.
Neither reset/stall sentence named its masquerade scope, so a reader with
masquerade off met both and they flatly disagreed. The general failover section
now scopes its reset claim to masquerade on, names the reason (the standby
translates to a different source address), and links onward.
'Stalls for the length of the failover' understated it. Measured stalls were 6
to 13 seconds against a 6 second failover, because the sender waits for its
next retransmit after the path returns. Says so, with the range, and keeps the
claim hedged to what was observed rather than asserting connections are never
broken.
Turn "Commercial License" into a plain nav group and add an "Overview"
child pointing at /selfhosted/enterprise, above "Getting Started". This
matches the pattern already used by Networks, Cloud Marketplaces,
Observability, and Troubleshooting, where the section index page is
reachable as its own "Overview" link rather than only via the group
label.
The Wails 3 desktop app links GTK 4.10+ (GtkFileDialog) and WebKitGTK 6.0,
verified against the shipped v0.75.0 netbird-ui binary. The previously
documented floor of Debian 12 / Ubuntu 22.04 is below that: both ship
WebKitGTK 6.0 but only GTK 4.8 and 4.6, where the app starts and then
crashes on the first file dialog.
- Document the real floor per distribution and mark RHEL 9, Amazon Linux 2
and Amazon Linux 2023 as CLI only.
- Name the GTK 4 and WebKitGTK 6.0 packages in the install commands, since
netbird-ui does not declare them as dependencies.
- Note that EPEL provides webkitgtk6.0 on RHEL/AlmaLinux/Rocky 10.
- Remove libappindicator from the RPM install lines. The tray is a D-Bus
StatusNotifierItem and does not link libappindicator; keep the GNOME
extension step, which is still required for the tray to appear.
- Note that Linux netbird-ui packages are x86_64 only.
