The proxy's embedded NetBird client connects to Signal and the relay at the
NetBird domain's public address, even when the proxy reaches Management over the
Docker network. Without hairpin NAT every proxied service times out; split DNS
works but forces relayed connections.
Step 7's config.yaml had no auth block, and the combined server exits without one
(issuer is required). The guide also enabled trafficFlow without deploying the
services that receive and store traffic events. Add both, the receiver's subject
under the traffic-events stream, its secret (the relay secret), and the
/flow.FlowService/ route on the Management load balancer.
With a private-CA certificate the proxy container registers as online but cannot reach Signal until it trusts the CA. Document giving it a CA bundle through docker-compose.override.yml, which getting-started-enterprise.sh does not regenerate.
* docs: clarify Signal message encryption and Windows PATH after install
- how-netbird-works: the Signal candidate message uses NaCl box
(Curve25519, XSalsa20, Poly1305): a shared key derived from the
local private key and the remote public key, no separate signature.
Spell that out so readers with an RSA sign-then-encrypt model do not
read the sentence as a mistake.
- windows install: both installers add C:\Program Files\NetBird to the
system PATH, but terminals opened before the install keep the old
PATH. Add a note to open a new terminal, and use the full exe path in
the scripted install + setup-key snippets, where the same shell runs
both commands.
* docs: state that Signal sees the peers' public keys, not the body
* docs: keep bare netbird up in the setup-key snippets, note a new terminal instead
* docs: drop the repeated new-terminal note from the setup-key section
* Add Sign-in Domains page
Documents how an email domain is matched to an account: adding a domain,
proving ownership with a DNS TXT record, and what changes for users once it is
verified.
Two points the page is careful about, because both are easy to assume wrongly:
- Verifying a domain decides where *new* users land. It does not move users who
already have an account of their own, so domains want adding before a team is
onboarded rather than after.
- A verified sign-in domain is not an SSO domain. Routing a domain to an
identity provider is a separate step on the integration, which is what lets
one domain sign in through SSO while another uses Google or a social login.
The four screenshots it references are not in this commit and need to be added
before merge:
public/docs-static/img/manage/team/sign-in-domains/
sign-in-domains-settings.png the Sign-in Domains tab in Settings
sign-in-domains-pending.png a newly added domain, Pending
sign-in-domains-dns-verification.png the TXT record dialog
sign-in-domains-login.png the login page
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Tighten the Sign-in Domains page
Switches the examples to company.com / company.net, drops the step-by-step
walkthrough of how matching works, and trims the instructions down to what a
reader actually needs to do. The prose and the callouts carry the page now.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Trim the Sign-in Domains page further
Parallel section titles (Add / Verify / Remove Domain), drops the
"What Changes for Your Users" and "Things Worth Knowing" sections, and cuts
the availability note and the SSO note back to one line each.
The warning now says to add domains before onboarding a team from another
domain, which is the case it actually matters for.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Move Sign-in Domains under Settings, and lead with the two domains
Sign-in Domains is a Settings tab in the dashboard, not part of Team, so the
page moves to /manage/settings/sign-in-domains and sits in the Settings nav
after Authentication, mirroring the dashboard's own tab order. Screenshots move
with it to img/manage/settings/sign-in-domains/.
The intro also led with jane@company.com, which would already have matched the
primary domain and so did not show the problem at all. It now establishes
company.com as the account's own domain and company.net as the second one, and
the colleague who needs it is jane@company.net.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Lead with what sign-in domains are for
Retitles the page "Allow Users from Other Domains to Join Your Account", which
is the job it does, and opens with the behaviour rather than with the account's
own domain: users on one business email domain are already joined into one
account, and most businesses have more than one domain -- another location, a
country domain, a second brand -- whose users are not.
Also documents the email route the verification dialog offers for anyone
without DNS access, and matches the dialog's own wording (Verify on the row,
then Start Verification).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Sharpen the intro and drop the primary-domain aside
- The colleague on another domain is not recognized unless invited by hand, so
the intro says so and links to the invite page.
- "With sign-in domains you prove ownership of those domains, and everyone
across your organization joins the same account."
- Drops the paragraph about company.com staying the primary domain. Remove
Domain named that term without defining it afterwards, so it now says "the
domain your account signed up with" instead.
- Drops the detail about the retry interval widening; that it keeps checking is
the part a reader needs.
- US spelling, matching the rest of the docs.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Shorten the one-account-per-domain note
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Drop the SSO section, and nest the page under Authentication
The "Sign-in Domains and SSO" section read as confusing rather than
clarifying, so it goes along with its recap bullet. The constraint a reader
actually meets survives in Remove Domain: a domain an SSO integration uses
cannot be deleted until it is detached there.
The page also moves under the Authentication group in the sidebar, next to
Peer Session Expiration and Multi-Factor Authentication.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Follow the dashboard: Sign-in Domains lives under Authentication
The dashboard no longer gives sign-in domains a tab of their own, so the
instruction now sends the reader to Settings > Authentication and the section
within it. The screenshot is renamed to authentication-tab.png to match what
it has to show.
Also spells out that joining happens automatically without direct invites,
and drops the same point from the opening paragraph where it was now said
twice.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Move the page under Single Sign-On
/manage/team/single-sign-on/sign-in-domains, nested under Single Sign-On in
the Team section rather than sitting under Settings. Screenshots move with it
to img/manage/team/single-sign-on/sign-in-domains/.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Put the page at manage/team/sign-in-domains
A sibling of Single Sign-On in the Team section, listed after it, rather than
nested inside it or under Settings. Screenshots follow to
img/manage/team/sign-in-domains/.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Fix wording and a stale example domain
The DNS instruction still named www.company.net after the example moved to
company.co.uk, which is the one that actually misleads: that sentence is
telling people where to put the record.
Also a "usees" typo, a link with no object ("unless you invite manually"), a
missing comma after "By default", "as you" where the comparison is to your
domain, "E.g." opening a sentence, and "another one" where it means another
account.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Drop the authentication clause from the recap
It summarised the SSO section, which is gone.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Add the Sign-in Domains screenshots
- authentication-tab.png: the section under Authentication, with two domains
pending and two verified, which is what the page describes
- dns-verification.png: the Verify Domain Ownership dialog
- login.png: the login page
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Point domain verification help at NetBird Support
Replace the support@netbird.io mailto links with links to the support
page, and tell users with an account they were not aware of to reach out
so the team can verify their identity and point them to its admin.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: add Reverse Proxy on OpenShift guide
Add a guide for running the NetBird reverse proxy on OpenShift with the
rootless UBI image under the restricted-v2 SCC. It covers the proxy
Deployment with self-managed ACME certificates on a PVC, exposure via a
TCP LoadBalancer or TLS-passthrough Routes, wiring a backend through a
routing peer, verification, and troubleshooting.
Adds the page to the Reverse Proxy sidebar and cross-links it from the
overview and Bring Your Own Proxy pages.
* docs: simplify OpenShift proxy guide
Drop the version availability note and the amd64 node restriction since
the rootless UBI proxy image is published for both AMD64 and ARM64, and
replace the interactive token prompt with plain export statements.
* docs: restructure OpenShift proxy guide and add http-01 variation
Make the guide easier to follow for reverse proxy operators:
- Put the LoadBalancer vs passthrough Route decision and the resource
footprint up front.
- Source the management address from the Secret and drop hardcoded
namespaces so the manifests apply without edits.
- Add checkpoints after each step and move alternatives (cert-manager,
replicas, upgrades, removal) into an "Operating the proxy" section.
- Document http-01 with the UBI image's :8081 challenge listener and why
it requires the LoadBalancer exposure.
Fixes from a test deployment on OpenShift 4.17 with the PR build of the
UBI proxy image:
- Add pkgs.netbird.io (geolocation database) to the egress requirements.
- Show how to switch a pending LoadBalancer Service back to ClusterIP.
- Describe the periodic PROTOCOL_ERROR reconnect symptom of a management
idle timeout separately from gRPC routing failures.
- Note that autocert handshake warnings during first issuance are expected.
* docs: give each relay instance its own address in the HA guide
The guide put every relay instance behind one load balancer with an
identical NB_EXPOSED_ADDRESS. Relay instances share no state, and the
address an instance announces becomes each peer's relay identity. With one
shared address, two peers whose connections land on different instances
each wait for the other on their own instance, and the relayed connection
never forms (`peer not available: ..., context deadline exceeded`), while
every peer still reports the relay as Available.
Replace the relay load balancer with two options:
1. List every instance in server.relays.addresses. Clients connect to all
of them, keep the fastest, and fail over by themselves.
2. A geo-DNS name in server.relays.addresses, with a unique, reachable
NB_EXPOSED_ADDRESS kept on every instance. Each instance then needs one
certificate valid for the shared name and its own name, supplied rather
than issued by the relay's built-in Let's Encrypt, and the DNS record
needs health checks.
Also:
- Correct the relay health check (404 page not found, not 200) and the
secret-mismatch error (invalid signature, not auth: invalid token).
- Add troubleshooting entries for both relay failure modes.
- Apply a rotated NB_AUTH_SECRET with `docker compose up -d`.
- Move the relay secret into a relay.env file with chmod 600.
- Update prerequisites, Step 4, Step 7, the Step 8 failure scenarios and the
operations section for two load balancers instead of three.
* docs: name the Management image and fix its health check and Redis errors in the HA guide
The Management replicas run the combined netbird-server-cloud image. /api/health
does not exist on it, so the load balancer check and the bring-up step now use
the OIDC discovery document, which answers while the replica serves. The Redis
troubleshooting entry now quotes the two errors the image actually prints.
* docs: use netbird.example.com for the Management domain, as the rest of the self-hosted docs do
* docs: add a tested self-hosted NATS cluster example to the HA guide
* docs: encrypt the NATS example with TLS from a private CA, and trust it in Management and Signal
* Revert "docs: encrypt the NATS example with TLS from a private CA, and trust it in Management and Signal"
This reverts commit f85a128ef3.
* docs: state that the NATS example does not configure TLS
* docs: add an external relays guide for commercial-license deployments
On NetBird Enterprise the relay's shared secret is also the traffic-flow
receiver's secret. The community guide tells readers to generate a new
secret, which on Enterprise leaves peers connected while traffic event
logging stops. Add a standalone Enterprise page that reuses the existing
secret, reads it from config.yaml, and ends with a check that the receiver
is still accepting events.
Correct the community guide:
- Relay hosts need 443/tcp, 443/udp and 3478/udp, not port 80: the relay
obtains its certificate with the TLS-ALPN-01 challenge on 443. Publish
443/udp in the compose file too, for QUIC.
- Apply a config.yaml change with `docker compose restart netbird-server`,
and a docker-compose.yml port change with `docker compose up -d`.
- Treat the config.yaml example as an addition to the server block, which
also holds auth, reverseProxy and store.
- Keep server.authSecret. Setting relays.addresses turns off the embedded
relay and STUN server, with no way to keep the embedded relay alongside.
- Relay choice is a latency race, a client can hold more than one relay
connection, and either transport can win.
- STUN status is not a failover signal, and a secret mismatch is best seen
in the relay host's log.
- Describe the startup log, the /relay response, and a certificate request
that hangs rather than errors.
- Make the proxy and supplied-certificate sections complete: the relay's
own configuration behind a proxy, what the proxy must do, what the
trusted-proxy headers affect, how to apply changes, and the pitfalls of
supplied certificates, including private CAs.
- chmod 600 relay.env, and apply later relay.env changes with
`docker compose up -d`.
List the new page under Commercial License as "External Relays (Licensed)"
and link it from the scaling guide.
* docs: clarify the receiver's log level, the firewall that restricts a published relay port, and the leftover Let's Encrypt sign
* docs: qualify the Step 1 traffic events check by the receiver's log level
* docs: cover migrated and no-traffic-flow deployments on the external relays page, and separate the two secret mismatches
* docs: name the QUIC form of the relay's secret-mismatch reason
* docs: read the active server configuration in Step 2, cover a stale receiver secret in Step 8, and separate what each receiver check proves
* Trim Google Workspace IdP sync screenshots
* docs: render the GCP permissions callout as a Note
* docs: scope the GCP key-creation exception to the NetBird project
Replace the org-wide deletion of iam.disableServiceAccountKeyCreation
with a project-level override, and restore enforcement after the key
is uploaded.
---------
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
GitHub Actions runners no longer ship Node 20 for JavaScript actions, and the
ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION opt-out is gone, so any action whose
own action.yml declares `runs.using: node20` (or older) now fails to start.
Each target tag below was verified by reading its action.yml runtime directly,
not inferred from the version number.
actions/checkout v3, v4, v6 -> v7
actions/setup-node v4 -> v7
actions/cache v4 -> v6
actions/setup-go v5, v6 -> v7
docker/metadata-action v5 -> v6
docker/login-action v3 -> v4
docker/build-push-action v6 -> v7
booxmedialtd/ws-action-parse-semver is knowingly left alone. It declares node12
at v1, its newest tag v1.4.7 and master are node16, and the repo has not been
touched since 2023, so there is no version to move to. Replacing it is a real
change, not a version bump: it validates through node-semver and fails the job
on a non-semver tag, and the obvious substitutes are weaker. A plain shell
capture accepts the dispatch input's own placeholder default of refs/tags/vX.Y.Z,
and netbirdio/shared-actions/actions/parse-semver falls back to 0.0.0 rather
than failing. Either would let the job run on past the bad version, 404 the
openapi.yml download, and push a commit deleting all 36 generated API pages,
because the curl has no --fail and the Go expander ignores read and parse
errors. That swap needs those guards and its own PR.
Breaking changes across every major crossed were checked against the actual
workflow lines and none apply: setup-node v5/v6 auto-caching needs a
packageManager field package.json does not have (and every call site already
passes cache: 'npm'); setup-node v7 drops a NODE_AUTH_TOKEN export nothing
here uses, as no step sets registry-url; cache v5/v6 and checkout v5 raise the
runner floor, and every job runs on ubuntu-latest or macos-latest; checkout v6
relocates persisted credentials, which generate_api_pages already proves
harmless by pushing over HTTPS on v6 today; checkout v7 blocks fork PR heads
under pull_request_target and workflow_run, neither of which is a trigger in
this repo; metadata-action v6 changes '#' handling in list inputs, and the one
input is a bare image name; build-push-action v7 removes DOCKER_BUILD_NO_SUMMARY
and DOCKER_BUILD_EXPORT_RETENTION_DAYS, neither set anywhere; setup-go v6
reworks toolchain selection, and the only Go dependency here declares go 1.18
against an installed 1.21.
The two pull_request-triggered checkouts that run PR-authored code and never
touch a remote — pr-build and codespell — also stop persisting a token into
the workspace. build_n_push keeps its credentials: the same checkout feeds the
promote step's `git ls-remote origin`, so hardening it needs a job split.
setup-node's node-version stays at 20. That is a real concern separately, since
Node 20 is EOL, but docker/Dockerfile is FROM node:20-slim and build_n_push
builds the Next standalone bundle on the runner and copies it into that image,
so build-time and runtime Node have to move together and be proven by a real
build. It belongs in its own PR.
Remote jobs are now an explicit opt-in on the peer (default off), enabled
with --allow-remote-jobs or the allowRemoteJobs MDM policy, and a new
debugBundleUploadURL MDM policy overrides the debug-bundle upload service.
Document both MDM keys in the MDM integration reference, and note the
opt-in requirement plus the new anonymization-level and upload-URL bundle
parameters on the Remote Jobs page.
Every `default.json` example on the bootstrap page had at least one value
the client cannot parse, and a bad value there is fatal: the daemon exits
rather than falling back to defaults.
- `ManagementURL` and `AdminURL` were shown as strings. `Config.ManagementURL`
is a `*url.URL`, so the daemon dies with `cannot unmarshal string into Go
struct field Config.ManagementURL of type url.URL`. Reproduced on 0.69.0,
0.73.0, 0.78.2 and 0.79.0-rc.1.
- The Docker example bind-mounted the single file. The client rewrites
`default.json` on first start via temp-file-plus-rename, and a rename cannot
replace a bind-mounted file, so the daemon dies with `device or resource
busy`. This happens with and without `:ro`. Mount the directory instead.
- The Kubernetes example mounted the ConfigMap at the file path with
`subPath`, which is the same read-only single-file mount. Seed a writable
`emptyDir` from the ConfigMap with an init container instead.
Verified in a systemd container against the real client: the corrected
`default.json` starts cleanly, keeps the templated values, and regenerates
`PrivateKey`. The fields left untouched (`IFaceBlackList` as an array, the
empty `PrivateKey`, the platform path table, `status --check` values) were
checked and are correct.
The Kubernetes manifest is the one change not run end to end: no cluster was
available. Both failure modes it avoids were reproduced directly with
equivalent mounts, and the pattern it uses is the verified-working one.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
The management server has reported agent_network_* counters (accounts,
providers, policies, budget rules, log collection enabled, input/output
tokens, cost) since Agent Network shipped, but the FAQ list was not
updated. Counters only, no identifying data.
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
The geo section told readers to build a 0.0.0.0/0 Network resource
because a posture check on a Route exit node "does not work". That is
only true when the check sits on the route's access control groups.
Placed on the policy between the users group and the exit node group,
the check withdraws the default route entirely, because routes are only
distributed from peers the device is allowed to connect to. Rewrite the
section around the exit node's native Routes setup, name the wrong
placement, and add the office-subnet variant with a Peer Network Range
check.
If you want a body line with it:
docs: add OpenShift client installation guide
Covers the certified rootless UBI image on restricted-v2, with both
ephemeral (no volume) and PVC-backed peer identity modes.
Domains that already have CAA records refuse certificate issuance unless
the certificate authority is authorized, leaving reverse proxy services
unreachable over HTTPS after the domain verifies successfully.
Document the sectigo.com value used by ZeroSSL on NetBird Cloud's managed
proxy clusters, the issue/issuewild records to add, CAA inheritance from
parent domains, and how to check existing records. Add a troubleshooting
entry for certificates that are not issued after verification.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* [doc] Explain custom domain verification expiry
Describe the 48-hour verification deadline, hourly cleanup, and activity event
so administrators know why a pending domain disappears and how to register it
again. Include the upgrade window and the exception for legacy service use.
* [doc] Explain custom domain name normalization
Describe how new custom domain registrations normalize case, internationalized
names, and a trailing dot, and reject malformed or wildcard names.
* docs: add NetBird client compatibility to the operator support matrix
Add a "NetBird client compatibility" section to the Kubernetes operator
support matrix. Each operator release is built and tested against a
specific NetBird release and deploys that exact, digest-pinned client by
default, so a default install runs the supported combination. Document the
current pairing (operator v0.8.0 with NetBird v0.72.4), a table of tested
clients for recent releases, and that overriding routingClientImage is
neither supported nor tested.
Also replace an em dash in the Kubernetes compatibility section with two
plain sentences.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: ask for NetBird client version in operator issue reports
Address CodeRabbit review: the compatibility section makes the client
version part of the supported combination, so the reporting checklist now
asks for the NetBird client version and any routingClientImage override.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add Control Center Draft Mode guide
Add a how-to page for the new Draft Mode in Control Center: build a
change on a working copy of the canvas, review the exact API requests,
and deploy everything as one batch. A single running example (giving
DevOps HTTPS access to a not-yet-installed staging server) carries
through entering a draft, the canvas toolbar, node interactions,
placeholder-peer installs, and Review & Deploy.
Along the way:
- Nest Control Center in the sidebar (Overview + Draft Mode) and update
the overview page: Users view in the intro and quick start, an Edit
Nodes section covering live edits vs Draft Mode, permissions notes
including the Network Admin setup-key limitation, and a HashRedirect
for the renamed #editing-policies-from-the-graph anchor.
- Add a shared <Video> component for screen recordings: lazy playback
via IntersectionObserver, visible controls, preload="metadata", and
no autoplay under prefers-reduced-motion.
- Optimize media: re-encode recordings (H.264 CRF 26, 30 fps,
faststart, audio stripped) and losslessly recompress screenshots,
cutting the page's media payload from 6.3 MB to 1.2 MB.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: image zoom overlay flickering on close
The closing fade-out ran without animation-fill-mode: forwards, so when
the 200ms animation finished the overlay snapped back to full opacity
until React's unmount timeout fired, flashing for a frame or two.
Holding the animation end state covers that gap.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: tighten Draft Mode intro
Give the running example its own paragraph and drop the header-chrome
description; the video right below it shows the same thing.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: add Focus Mode section and group-from-selection video
Document Focus Mode on the Control Center overview (right-click a node
and choose Focus, or select it and press F) with two screenshots, and
move the F shortcut prose there from the Draft Mode page. Add a
recording of creating a group from a multi-peer selection to the
Draft Mode page. New media compressed like the rest.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: correct Focus Mode shortcut order
F is pressed first, then the node is selected.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: drop setup-key caveat from Draft Mode permissions note
The Network Admin limitation is already covered where it bites, in the
placeholder install section.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: drop Agent Network disambiguation from Add Nodes
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: reorder Assign Peers to Groups videos
Show the drag-to-group recording right after the text it illustrates,
then the group-from-selection flow.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: remove change-type badge list from review section
The review rows do not carry Add/Modify/Delete/Install badges.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: trim group-membership parenthetical from review example
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix: react to prefers-reduced-motion changes in Video
The reduced-motion check ran once on mount, so toggling the OS setting
while the page was open either kept videos auto-playing or left them
permanently inert. Listen for MediaQueryList changes: pause and drop
the observer when reduced motion turns on, re-observe when it turns
off.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* docs: document the fallback when the client cannot manage firewall rules
Add a troubleshooting section for hosts that are missing the netfilter
modules the client's firewall rules depend on, such as the mark match used
for policy routing or ipset. Include the client log excerpt so the error is
findable by search, with timestamps, hostname and peer identifiers removed.
Document what actually happens. The client logs the failure and proceeds
with the userspace packet filter, so NetBird keeps working and keeps
filtering, and on a routing peer the forwarding path moves to userspace as
well. Remedies are ordered from narrowest to broadest, starting with
loading the missing module and the related environment variables before
reaching for --disable-firewall.
Warn that --disable-firewall is not the same as that automatic fallback.
The userspace filter does not take over, so NetBird enforces no access
control on the peer, and the operator has to recreate the restrictions with
the host's own firewall.
Reference the new section from the Synology install page, where these
netfilter match modules can be missing alongside the tun module already
covered there.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: reword the NB_USE_LEGACY_ROUTING line
Address CodeRabbit review: 'ip-rule based routing' was an incorrectly
hyphenated compound modifier. Reword so the sentence describes the fallback
directly and drops the compound modifier.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: document that a primary nameserver is exclusive on Windows
A peer with a primary nameserver now gets a Name Resolution Policy Table rule
covering every namespace, so all resolution goes through NetBird and nowhere
else. Without it Windows queries every adapter's resolvers in parallel and keeps
whichever answer arrives first, which leaks queries to the local network and lets
another resolver answer for a name NetBird is authoritative for.
Two consequences worth knowing before it surprises someone:
- Zones only the local network resolves stop working while connected, unless
they are declared as match domains. A more specific rule takes precedence, so
declaring the zone is the fix. `.local` is exempt, so multicast DNS is
unaffected.
- Short names depend on which adapter's suffix Windows tries first, and it stops
at the first "no such name" rather than continuing down the list. On
domain-joined machines the machine's own domain wins that first attempt, so a
short name can fail while its fully qualified form resolves.
Placed next to the existing macOS note in the same section, since both are about
what a primary nameserver does beyond catching unmatched queries, and next to the
existing warning about emptying match domains, which the suffix caveat explains
the other half of.
Also documents NB_USE_LEGACY_DNS_RESOLUTION, which restores the old behaviour on
a peer.
* docs: correct how Windows expands short names, and say from which version
Two fixes to the notes added in the previous commit.
The short-name mechanism was described wrongly. Windows does not stop at the
first suffix that misses: it walks the whole suffix list of the preferred
interface, and what it will not do is fall through to another interface's
suffixes. Measured on a Windows 11 machine — with NetBird's adapter preferred, a
list of {fritz.box, netbird.cloud} resolves a name that only exists under the
second entry; with the metric raised so the physical adapter wins, the same name
fails because only that adapter's single suffix is ever tried. The practical
advice changes with it: declaring the local zone with search domains enabled puts
both suffixes in one list, which is what makes short names work either way.
Both notes now say the exclusive behaviour arrives in client v0.78.0 and what
earlier clients did instead, so the page reads correctly for someone still on
0.77, and the environment variable is marked with the version that introduces it.
* docs: say that exclusive resolution is what breaks short names on Windows
The suffix-search behaviour is not Windows' own: without the catch-all NRPT
rule Windows keeps searching the other adapters' suffix lists, and the short
name resolves. Gate the note to v0.78.0 and point at it from the exclusivity
note, so both texts agree on what the change costs.
On the Add Users page, the indirect-user-invites note told users to email
hello@netbird.io or ping Slack to fix a domain that was not classified as
private. Point it to the NetBird Support page instead, so support requests
go through the same channel as the rest of the docs.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebuild connecting-from-the-office on Networks
The page walked the legacy Network Routes flow: create a route, assign
distribution groups, and gate the routing-peer policy. Networks is the
current model, and there was no Networks version of this use case
anywhere in the docs.
Rewritten around the Networks building blocks: the posture check hangs
off the access policy whose destination is the office resource, so the
route is not distributed while the device is on site. Adds a limits
section (re-evaluation delay after a network change, ranges carry no
identity, platform coverage) and a summary. Drops the three legacy
route-UI screenshots.
* docs: Android reports local network addresses from 0.77.1
PR #7235 landed the Android side of PeerNetworkRange: the client now
parses local interface addresses from the host app's interface
discovery, so NetworkAddresses is no longer empty. First release
containing it is v0.77.1.
Scopes the known limitation to Android clients older than 0.77.1 and
leads with the fix, mirroring how the iOS 0.69.0 note reads. Also
matches the posture check name in the office guide to the screenshot.
* docs: correct client command, alt text and wording in the office guide
netbird routes is a deprecated alias; the command is netbird networks
list. Alt text now describes what each screenshot actually shows, and
the check name, Wi-Fi spelling and description line are consistent.
* docs: use documentation-only public ranges, scope the Android note in the Zero Trust guide
1.0.0.0/24 and 3.0.0.0/23 are allocated space and a reader can copy
them into a Block check, so the public-block examples now use RFC 5737
documentation ranges.
The Zero Trust guide still stated the Android limitation
unconditionally, which contradicted the posture check reference after
0.77.1.
* docs: tighten the office guide and the Android limitation
Scopes the intro claim to what the page's own screenshots show, stops
overstating what netbird networks list reports, restores the
platform-targeting bullet with Android 0.77.1 included, and leads the
Android section with the version scope so it reads correctly under
Known Limitations.
* docs: do not present macOS interface names as cross-platform
utun100 is the macOS default (client/iface/configurer/name_darwin.go);
wt0 is the default everywhere else. The verify section now names both
once, and the summary talks about the local link and the NetBird
interface instead of en0 and utun100.
* docs: add selective internal access behind an exit node use case
Documents the two-routing-peer architecture for combining an exit node
with access to specific internal resources only: a resource peer inside
the data center scoped by policies, and an exit node placed on a segment
with internet-only egress. Names the two shortcuts that do not achieve
this (Block LAN access only covers directly attached subnets; host
forward-chain firewall rules are superseded by NetBird's own allow
rules) and adds verification steps, including the netbird down
requirement when enabling Block LAN access over the CLI on a connected
peer. Cross-links from the routing peer concepts and from How Routing
Peers Work.
* docs: make the single-host example clearly outside the subnet resource
* docs: accept all blocked-connection results and scope the exit-node guarantee
* docs: vendor-neutral egress wording and verify bullet polish
* docs: state what actually happens with multiple separate exit nodes
Replaces the 'does not work: ... no coordinated selection' claim in
Regional Exit Nodes with the verified behavior: separate exit nodes
appear as independent choices in the device's exit node selector, the
client auto-selects the alphabetically first name (metrics and latency
play no part), and there is no failover between exit nodes - a device
whose selected exit node loses its routing peer keeps it selected and
loses internet entirely, even across reconnects. Adds the matching
non-overlapping-distribution-groups caveat to the per-group placement
advice, and aligns 'exit node entry' wording to plain 'exit node'.
* docs: scope multi-exit-node selection behavior to Auto Apply
* docs: deduplicate multi-exit-node caveats
* docs: state the one-auto-applied-exit-node-per-device rule
* docs: clarify Windows client updates need no user admin on the service path
The 'update needs admin' confusion comes from mixing two paths. Clarify both:
- auto-update: accepting a prompted update is installed by the NetBird
service (system privileges), not the logged-in user, so no admin rights
are needed. Only the manual download-link path is a per-machine install
that requires elevation.
- Windows install: silent install/upgrade needs an elevated (SYSTEM)
context, which RMM/MDM tools provide; a standard user gets 1625. Add an
Updating section: the same installer upgrades in place (no separate
update package), pushed via the same RMM/MDM tool; downgrades are blocked.
All claims lab-verified 2026-08-20 (WS2022, v0.76.0 -> v0.77.0).
* docs: qualify elevation context and warn install-only deploy jobs skip upgrades
- Not every deployment configuration runs as SYSTEM; a user-context job
fails with 1625. Say the job must run elevated.
- The GPO deployment script exits when NetBird is already installed, so it
is install-only. Warn that upgrades need an upgrade-capable job.
* docs: correct downgrade behavior per installer and address review on update section
The MSI (WiX MajorUpgrade) blocks downgrades; the NSIS EXE has no version
check and will downgrade. Stop teaching 1603 as a downgrade signature,
add same-installer-type guidance, service-restart warning, rollback path,
Automatic Updates version floors and Latest Version pinning conflict.
Match the page's EXE-first order and <VERSION> placeholder.
* docs: state Force Automatic Updates version scope (server and clients)
* docs: promote update section to top level and fix Automatic Updates note placement
Branch offices with strict egress policies need stable outbound rules
toward main locations. Documents pinning --wireguard-port per peer plus
a static DNAT at the main site, with the no-inbound trade-off stated
and scoped, and cross-links from Incoming ports and the relayed-
connections troubleshooting note.
Exit nodes previously lived only under Use Cases. Add them to the Routes
sidebar group and mention them on the Routes overview. Document that a
default route grants access to everything the routing peer can reach,
with Block LAN access and network isolation as mitigations, and link
How Routing Peers Work back to the exit nodes guide.
* docs: standardize on "NetBird client" over "agent" for the client software
* docs: address review feedback
- fix "a software" grammar and use lowercase "NetBird client"
- define routing peer as a peer whose client bridges, keeping peer and client distinct
- correct kernel-space claim: the kernel WireGuard data path is what runs in the kernel
- clarify which address the application uses to reach the SOCKS5 proxy from a separate container
* docs: add exit node enforcement section (Auto Apply + disableNetworks)
Adds 'Enforcing the Exit Node on Managed Devices' to the exit nodes
use-case page: the Auto Apply + disableNetworks recipe, the
deploy-before-users-touch-it ordering caveat, the disableUpdateSettings
mix-up, and the honest boundary (netbird down is not gated). Adds a
reciprocal note under the MDM page's key notes. Lab-verified on Linux
(service flag) and macOS (managed preferences + GUI) with client
v0.77.0.
* docs: use American English variant (afterwards -> afterward)
* docs: tighten enforcement wording (selection-scoped claim, page idiom)
* Improve CrowdSec setup, recovery, monitoring, and access-log documentation
* Refine CrowdSec dashboard recovery and access-log field documentation
* Image and API ref update
* Api ref fix
* Probe both api/.env
Jack Carter