* 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.
The NetBird iOS app can now collect a debug bundle from Settings ->
Troubleshoot. Update the iOS troubleshooting page to use it and route
reports to Community Support, or NetBird Support for paying customers.
Also reference the iOS method from the canonical Debug bundle section
and update the iOS card on the client troubleshooting hub.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* new: Windows GPO deployment guide under MDM for Deployment
* new: point GPO guide at the full policy key reference
* new: bold the example-posture disclaimer in GPO guide
* new: grammar and readability pass on GPO guide
* new: clarify AUTOSTART=0 vs Disable Autostart policy
* new: address review feedback on GPO guide install script and pinning
* docs: add geo-based exit node routing use case to exit nodes page
Full tunnel outside a country via a Country and Region posture check on a
0.0.0.0/0 Network resource's access policy; split tunnel inside. Warns
against the Peers-page exit node variant, where the posture check only
blocks traffic after the default route installs and in-country devices
lose internet. Lab-verified (lab-2026-07-22-geo-exit-node).
* docs: drop unverified route-appearance delay claim
* docs: revert unintended package-lock churn from local npm install
* docs: clarify why the Peers-page exit node cannot be posture-gated
* docs: compress the exit-node posture warning to one line
* docs: rename step 2 heading to Create the Network Resource
* docs: drop incorrect ICMP peer-policy requirement from geo use case
Verified live: with the resource access policy alone (peer policy to the
routing peer disabled), internet forwarding through the Networks exit
node keeps working. The ICMP-minimum note applies to network-routes
exit nodes, not the Networks resource path.
* docs: explain why match-ALL DNS matters in the geo use case
Without it a full-tunnel device leaks its location via DNS to the local
resolver (verified: zero port-53 packets on the tunnel until the
match-ALL nameserver is set); with it, split-tunnel devices reach the
same nameserver directly and keep resolving.
* docs: grammar and readability pass on the geo exit node section
* docs: refer to Routes instead of Peers page in the posture warning
* docs: state the example's goal explicitly before the setup groups
* docs: name the network after its location, the resource internet-egress
* docs: make the resource group optional in the geo use case
* docs: note the API marks the fields required, defaults are current behavior
* docs: name the GeoLite2 database and link self-hosted setup
* ci: serialise image builds and stop the API-pages workflow clobbering the lockfile
build_n_push: add a per-ref concurrency group so two quick merges to main can't race the :main tag (last push wins regardless of commit order, and the server auto-pulls :main); add permissions: contents: read; validate .dockerignore and package.json changes in the PR path filter.
generate_api_pages: pin Node 20 and switch npm install -> npm ci so the run can never rewrite the now-tracked package-lock.json with a divergent macOS-resolved tree; stage only src/pages/ipa/resources instead of git add -A; drop --force from the push — a force-push from this workflow would silently rewrite main and destroy any PR merged since its checkout.
* chore: warn when per-page dates are skipped; drop dead per-file git lookup
buildGitDateMap now logs a warning when it emits no dates (git missing or shallow clone) instead of silently blanking every page's Updated line and the sitemap lastmod entries; document the squash-merge assumption behind the --name-only walk. Remove the unused getGitLastModified. Note in CLAUDE.md that npm run start warns under output: 'standalone'. Gen output verified byte-identical.
* ci: self-heal the API-pages push when main moves mid-run
Rebase the single generated-files commit onto the moved branch before pushing, so a PR merged during the multi-minute run no longer rejects the push (the failure --force was presumably papering over). A genuine conflict — a concurrent edit of the generated files themselves — still fails the run loudly with main untouched. Also serialise dispatches with a concurrency group: run history shows several same-day dispatches, and overlapping runs regenerate the same files.
Sandbox-tested against a bare repo: plain push rejected on race; rebase+push lands with both commits intact; true conflict exits 1 leaving the branch tip untouched.
* ci: sync to branch tip before regenerating API pages
A run queued behind another checks out the commit pinned at its dispatch time; regenerating against that stale base means the pre-push rebase replays a snapshot diff, and a file the newer spec removed can silently survive from the prior run. Fetch + reset to the branch tip before generating so the diff is computed against reality. Also note the latest-dispatched-vs-newest-tag caveat on the concurrency comment.
Sandbox-proven: with the old order a removed-in-newer-spec file survives the rebase replay; with sync-first it is gone.
* Prevent stale workflows from overwriting newer published content
* Coderabbit Fix
---------
Co-authored-by: Brandon Hopkins <brandon@techhut.tv>
* Add an Updating section to the pfSense install guide
Document upgrading in place: re-fetch the latest netbird and
pfSense-pkg-NetBird .pkg files from the latest GitHub release and re-run
pkg add -f on both (no pkg delete first, -f upgrades in place), then
netbird service restart and netbird status -d to verify. Matches the
Installation section's step style and the <RELEASE_TAG>/<VERSION>/<ARCH>
placeholders, and the Updating-before-Uninstallation layout used on the
Linux and Synology pages.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Point the pfSense upgrade step at the downloaded filenames
Mirror the Installation step wording so the pkg add commands use the
exact filenames downloaded from the release, which have independent
NetBird and pfSense package versions.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add Enterprise Commercial License overview page
Add a public, shareable overview of the NetBird Enterprise Commercial
License for teams evaluating self-hosted NetBird. Answers the questions
prospects ask most: in-place migration from the open source Community
Edition, zero-downtime control-plane upgrades via active-active HA,
control-plane behavior at scale, single-tenant boundaries and the
options for serving multiple customers, and how evaluation works.
Clarifies that the Cloud "Business plan" and the self-hosted commercial
license are different products, and lists what the license unlocks
(HA, SCIM, EDR/MDM integrations, traffic-flow logging, standard support).
Served at /selfhosted/enterprise and linked from the Self-Host sidebar.
* docs: qualify connection continuity by deployment topology
The single-server upgrade answer claimed all established connections
survive a restart. That holds only when Relay runs externally. In the
default combined deployment, netbird-server bundles Management, Signal,
and Relay, so recreating it restarts Relay and active relayed sessions
reconnect. Clarify that direct peer-to-peer connections continue either
way, while relayed-session continuity depends on whether Relay is
external or restarted with the combined server.
* docs: describe the commercial PoC as assisted, with 30-day default
"Managed proof of concept" overstated the offer. Per the EULA the
customer installs and runs the stack, with NetBird providing the license
and guidance, and a commercial PoC runs 30 days by default. Reword to
"assisted proof of concept" and state the default duration.
* Expand Issue 8 (NRPT lingering GPO) with GPO-hunt and source-side fixes
Enrich the Windows NRPT lingering-GPO troubleshooting with the deeper
diagnosis and remediation the issue needs: the DnsPolicyConfig registry
check, finding the responsible GPO (gpresult plus a SYSVOL registry.pol
scan), and the source-side fixes (the dummy-rule trick for an empty
lingering container, and guidance when a GPO carries real NRPT rules).
Heading and anchor are unchanged, so existing links keep resolving.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Replace em dash with a period in Issue 8 (house style)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* Documentation for GRPC and JSON Sockets
* improve gRPC and HTTP/JSON socket documentation
* Update src/pages/client/grpc-socket.mdx
Co-authored-by: Nicolas Frati <nicofrati@gmail.com>
---------
Co-authored-by: Nicolas Frati <nicofrati@gmail.com>
Step 10 now asks customers to tell us which region their JumpCloud
console is in (US, EU, or India) along with the Client ID and Client
Secret, so the connector is configured against the right endpoint.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The "Policy exists but connection is still blocked" entry told readers to look
for "blocked due to posture" or "no matching policy" entries in Traffic Events.
Those entries do not exist: a failed posture check or group mismatch is resolved
on the management server and never produces a Traffic Event. Drop the bullet;
the remaining checks (policy and posture checks under Access Control, group
membership under Peers) are the accurate guidance.
* Reference the config-file bootstrap workflow from install and peer pages
Link Bootstrap peers via config file from the setup-key sections of the
Linux, Windows, macOS, and Docker install pages, from the Setup Keys
page, and from the Kubernetes routing-peers guide. The page was only
reachable from the sidebar, so this surfaces the unattended deployment
workflow where headless and at-scale enrollment is already discussed.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Clarify the Kubernetes example demonstrates setup-key enrollment
The manifest passes a setup key but does not mount a pre-populated
config, so reword the cross-link: the example enrolls with a setup key,
and the bootstrap guide covers the additional config-file step.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Clarify in "Step 3b: Configure access control" that access restrictions
of different types (IP CIDR, country, CrowdSec) are combined with a
logical AND by default: a connection must satisfy all of them.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The per-browser export steps led each bold browser label with an em
dash. Switch to a colon so each bullet reads as a clean
label-then-instruction, consistent with the other bullet lists in the
docs. Wording is otherwise unchanged.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Document the two failure modes when the NetBird CLI SSO login can't bind
its loopback callback port on Windows: bind forbidden (WSAEACCES, port
inside a Hyper-V/winnat reserved range) and address in use
(WSAEADDRINUSE, a stale process). Note that the redirect port is a
configured, IdP-registered set (default 53000, often 54000), not a
single hardcoded value, and cover cases where AV/EDR or other software
blocks the bind invisibly.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Link the existing "WireGuard port conflict on Domain Controllers"
guidance (on /manage/dns/internal-dns-servers) from two pages a
troubleshooting-hub user could not previously reach it from:
- Windows client troubleshooting: a bullet under Windows DNS scenarios
for the "NetBird won't start on a DC" symptom.
- DNS troubleshooting: a note after the AD/DC issue, disambiguating the
client-running-on-the-DC case.
No content duplicated; both are pointers to the one existing section.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
