* docs: document the MDM keys added since the page was written, and iOS
The reference table listed 18 of the 23 keys the client recognises, and
claimed a count of 16. Six keys were missing from every downloadable
template as well, including lazyConnection, which the page already
documented:
- lazyConnection, disableAdvancedView, enableLocalMetrics,
localMetricsAddress, allowRemoteJobs and debugBundleUploadURL are now
in the reference table and in netbird.admx/.adml, io.netbird.client.plist,
netbird-macos.mobileconfig, netbird-macos.sh and netbird-policy.reg.
- Notes call out the two pairs that read as related but are not:
disableMetricsCollection (anonymous telemetry) versus
enableLocalMetrics (the client's own Prometheus endpoint), and
disableAdvancedView being UI-only, so unlike its neighbours it never
causes a request to be rejected.
iOS and tvOS now have a section of their own. The channel is Apple's
Managed App Configuration against bundle id io.netbird.app
(io.netbird.app.tv on tvOS), with a new netbird-ios-appconfig.plist
template and per-provider instructions. The section states what the
policy reaches today: the app locks its interface and refuses
configuration changes, while the tunnel engine runs in a Network
Extension that does not receive the app configuration, so keys the
engine applies to the connection are not enforced there yet.
Two template defects found on the way:
- netbird-macos.mobileconfig was not well-formed XML. Its header
comment contained a double hyphen, which XML forbids inside a
comment, so plutil -lint and any strict parser rejected the file an
admin downloaded.
- netbird-policy.reg had one LF-terminated line among CRLF ones;
normalised, with the UTF-16LE encoding reg import requires preserved.
Verified with npm run build and npm run lint:mdx, plus XML well-formedness
on all five XML templates, bash -n on the shell template, and a
cross-reference check that every string and presentation the ADMX
references is defined in the ADML.
* docs: iOS enforces every key; document when a change reaches the tunnel
The iOS section was written while the policy stopped at the app: the
network extension that runs the engine has its own preferences domain,
and Apple's app-configuration channel does not deliver there. The app
now mirrors the configuration into the shared App Group and tells the
extension when it changes, so the keys the engine applies to the
connection are enforced too.
What replaces the old warning is a timing caveat, which is what an admin
actually needs in order to plan a rollout. The hand-off happens only
while the app is running: in the foreground a change reaches the tunnel
within about 30 seconds or immediately on activation, but iOS suspends a
backgrounded app, so a policy pushed — or withdrawn — in that window
applies the next time the app is opened. A tunnel brought up by VPN On
Demand or the widget therefore runs on the last policy the app saw.
tvOS keeps the old behaviour and now says so: the hand-off needs a shared
app group, which does not work between the tvOS app and its extension, so
only the interface is enforced there.
Also corrected: blockInbound, wireguardPort and lazyConnection are no
longer listed as having no effect but as having no control to lock, and
debugBundleUploadURL moves out of the ignored list, since the engine
applies it when a remote job produces a bundle. The app-config template
carries the same three keys and the same timing note.
* docs: list allowRemoteJobs among the keys iOS enforces without a control
The key is enforced on iOS like the other engine-applied ones: a peer
whose policy withholds it refuses management-requested jobs. What is not
there yet is the lock on the Troubleshoot toggle, which arrives with the
iOS client PR that introduces that toggle — so promising it in the table
of what the user sees would describe a screen that does not exist.
Moved to the group of keys the engine applies with nothing on screen to
mark, next to blockInbound, wireguardPort, lazyConnection and
debugBundleUploadURL. It moves back to the table once the toggle ships.
* docs: sign macOS profiles with CMS, and scope the iOS claims properly
Three review findings, all correct.
`productsign` signs installer packages, not configuration profiles, and
an Apple Developer ID certificate cannot sign a profile at all — Apple's
own guidance is that a `.mobileconfig` is a CMS signed-data message. The
instruction predates this branch but the commit that fixed the malformed
XML comment rewrote it, so it is fixed here rather than carried forward.
It was also misleading in a second way: a profile delivered through an
MDM is signed by the MDM channel, so a managed rollout has nothing to
sign by hand. The step now says that, and gives `security cms -S` for the
case where the profile is handed out some other way.
"Every key is enforced on iOS" contradicted the list of
platform-inapplicable keys three paragraphs below it; it now reads "every
key that applies to the platform", and points at that list.
The engine-applied group — blockInbound, wireguardPort, lazyConnection,
allowRemoteJobs, debugBundleUploadURL — was stated without qualification
under a table headed "iOS / tvOS", while the warning just above says the
tvOS engine never receives the policy. Marked as iOS, with the tvOS case
pointed back at that warning.
* docs: group MDM policy keys by job and split delivery into per-platform pages
Rewrite /client/mdm-integration as the concept page and key reference:
a running example (a three-key baseline), the "pinned switches" model
(present means pinned, even as false), and the 23 keys grouped by the
job they do, each with its own anchor and the mistake it invites.
Correct claims that disagree with the client source (v0.80.0):
- disableClientRoutes stops the device using routes (resources, exit
nodes); it was described as not routing for others
- blockInbound also stops the SSH server and routing; not a kill switch
- since v0.75.0 the app hides managed settings, no "(MDM)" tag
- a policy change restarts the connection
- splitTunnel* have no effect today (Android has no MDM channel yet)
- managementURL pins the server, not the account, on NetBird Cloud
- the pre-shared key is readable by local users on Windows and macOS
Move Windows, macOS and iOS delivery into their own pages under
MDM Deployment, add them to the nav, and point inbound links at the
new per-key anchors.
* docs: fix MDM accuracy points found in review
- integer booleans are ignored on macOS (plist decodes as uint64); say so
- disableAutostart and disableAdvancedView lock nothing; qualify the lock claim
- managementURL: drop the disableProfiles advice, no key pins the account
- drop the unverifiable restart duration and a disableAdvancedView claim
- macOS page: fix 'never write the file' vs the shell-script channel
- Windows page: warn that the sample .reg pins every key
- tighten wording
* docs: say what disableAdvancedView hides (Peers and Resources tabs)
* docs: make clear disableNetworks removes the choice, not the networks
* docs: add recommended MDM policies by device role
* docs: lazyConnection follows the account setting, on by default since v0.74.0
* docs: drop the open-an-issue line from MDM troubleshooting
* docs: make remote jobs optional for every device role
* docs: make disableNetworks and disableAdvancedView optional for laptops
* docs: rename Recap to TL;DR on the MDM pages
* docs: TL;DR on the main MDM page only, drop the lead-in
* docs: list MDM Integration first under MDM Deployment in the nav
* docs: second review pass on the MDM pages
- macOS integer booleans are locked as well as unapplied; say so
- the lock-nothing keys are not desktop-only (disableAdvancedView on iOS)
- drop Linux from disableAutostart (no MDM channel there)
- blockInbound: drop the redundant routed-network clause
- encryption intro: Rosenpass permissive does not need to match
- troubleshooting: check macOS boolean types, no warning is logged
- wording fixes
* docs: correct MDM timing and CLI claims from a macOS lab run (v0.80.0)
- netbird debug config reads the policy file on each call; the daemon
applies a change at its next reload and logs 'MDM policy changed'
- netbird up --flag on a connected client ignores its flags; the
rejection examples now say login --flag or up on a disconnected client
- settings-field locks apply immediately; the disableUpdateSettings,
disableProfiles and disableNetworks gates apply at the next reload
- the restart on a policy change takes a second or two
* docs: MDM results from the Windows and macOS profile labs (v0.80.0)
- netbird logout works under every key and deregisters the peer; with
managementURL, disableProfiles and disableUpdateSettings pinned, logout
plus up --setup-key moves a device to another account on the same URL
- a profile-installed macOS policy file is a binary plist, root:wheel 644
- a REG_BINARY (or other unread type) value is not listed as managed
- the policy key inherits Authenticated Users read access
* docs: tighten four MDM statements to what the labs and source show
- no key blocks netbird logout of the active profile (source: only a
non-active profile logout is gated, by disableProfiles)
- the engine-restart log line appears only while the client is connected
- macOS: binary plist is what a configuration profile produces; the shell
script writes the same owner and mode
- Windows: the observed fact is that the NetBird key inherits Authenticated
Users read access, not a statement about the parent key
* docs: address CodeRabbit review on the MDM delivery pages
- iOS: the app must be managed by the MDM, not necessarily installed by
it (Apple supports taking over a user-installed app); same in the
iOS app-config template
- macOS: Jamf's Application & Custom Settings takes the bare plist, so
point Jamf at io.netbird.client.plist (and note the signed .mobileconfig
upload route); JumpCloud's MDM Custom Configuration Profile takes a
.mobileconfig per JumpCloud's docs, so drop the bare-plist claim and
its troubleshooting entry
- Windows: ADMXInstall only ingests the template; values are set through
Policy/Config/NetBird~Policy~NetBird/<PolicyName>; drop the
unverified Registry CSP path
* docs: address CodeRabbit's second review of the MDM templates
- netbird-macos.sh: managementURL, allowServerSSH and wireguardPort now
default to $NULL like every other key; the old defaults pinned them
(allowServerSSH=true pinned the SSH server allowed) on any run that
did not edit those lines
- drop the claim that disableMetricsCollection governs anonymous usage
telemetry from the mobileconfig, the bare plist, the script and the
ADML help text; the client recognizes the key but nothing reads it
* docs: correct the Mosyle path for the macOS MDM profile
Mosyle takes the .mobileconfig under Management > Management Profiles >
Certificates / Custom Profiles; there is no Custom Settings option with a
preference domain (per Orb and SI Prep deployment guides; Mosyle's own
docs need a login). Drop Mosyle from the bare-plist template header, and
align the mobileconfig header with the Jamf advice on the page.
* docs: drop the profiles-command install tip from the macOS template
macOS 11 and later cannot install configuration profiles with the
profiles command (man profiles, profiles tool 8.0+); point local testing
at a double-click and System Settings > General > Device Management, the
path the lab used.
* docs: make the Windows MDM page Intune-first, with a registry reference section
The page now leads with the Intune workflow: import the NetBird ADMX/ADML
once, create an Imported Administrative templates profile, assign it to a
device group, sync and verify, then the OMA-URI fallback and Intune
troubleshooting. Group Policy, .reg files, JumpCloud and the value-type
table move to a Registry reference section with its own troubleshooting.
New, from Microsoft Learn (Import custom ADMX templates): the current
portal paths, en-us ADML only, and that re-importing an updated template
fails until the profiles and the old template are deleted. netbird.admx
has no namespace dependencies and no combo boxes, so it imports alone.
The Intune install page stays separate; both pages now link to each
other. Main-page links follow the renamed anchors (#value-types,
#intune-troubleshooting).
* docs: move the enforce-settings link to the end of the Intune deploy page
* docs: group the Windows page's Intune steps under one heading
Mirrors the Registry reference section, so the page's table of contents
shows the Intune/registry split. Heading texts and anchors are unchanged.
* docs: rename the first MDM key group to Set the server and startup
The old heading named only managementURL; the group also holds
disableAutoConnect and disableAutostart.
* docs: add a use case to the Lock the client app section
What a developer on a locked Acme laptop sees (app tabs, the two CLI
errors, what still works), plus the finance team's disableNetworks and
Auto Apply exit node variant. Every behaviour is from the macOS and
Windows labs (v0.80.0).
* docs: replace the Lock the client app use case with a plain goals table
Goal, setting, and what users can still do, written for a junior admin.
disableProfiles row says plainly that signing out and into another
account still works (Windows lab W12).
* docs: OMA-URI payloads: <disabled/> pins an on/off setting off
The ADMX's on/off policies write enabledValue 1 and disabledValue 0, so
<enabled/> can only pin a setting on; document <disabled/> for off, the
String data type, and that un-pinning means Not configured (check the
device with reg query, since removing an OMA-URI may not clear it).
* docs: add What you can achieve tables to every MDM key section
Same goal / setting / what-to-know format as Lock the client app, for
server and startup, device exposure, encryption, support and monitoring,
and connection tuning; Lock's table now names values too. Every line
restates a claim already verified in the labs or source.
* docs: reorder the MDM page: goals first, key reference after
- What you can achieve (the six goal tables) comes first, then
Recommended policies, How the client applies a policy, and the Policy
keys reference; goal-table keys link down to their reference entries
- reference groups get noun names (Server and startup keys, ...) so no
two headings share an anchor
- the Acme running example is gone; its three keys become The laptop
baseline under Recommended policies, which the Windows, macOS and iOS
pages now link to as their example
- a one-line pin rule opens the goals, since the explanation now follows
* docs: laptop baseline goes to the user-devices group, not just laptops
* docs: rename the laptop baseline to the user device baseline
It applies to every user device (and the iOS page uses it), so the
Recommended policies column becomes User devices, the anchor becomes
#the-user-device-baseline, and the three platform pages follow.
---------
Co-authored-by: riccardom <riccardomanfrin@gmail.com>
* docs: mention the Enterprise Commercial License wherever a Cloud plan gates a feature
Cloud-plan and cloud-only notes now also name the self-hosted Enterprise
Commercial License for IdP sync, EDR/MDM, peer approval and MFA. The Zero
Trust guide, Plans and billing and Self-hosted vs Cloud gain self-hosted
equivalents. SSO notes state that OIDC IdPs work in both self-hosted
editions. The license page's feature table adds peer approval, audit event
streaming and notifications.
* docs: drop the MFA license claim; self-hosted MFA covers local users only
* docs: state that an Enterprise proof of concept includes every licensed feature
* docs: traffic events streaming fields, delivery, unrecorded traffic, audit events and peer IP allocation
* docs: scope traffic event retries to the save and list client-side data loss
* docs: scope traffic event retry guarantee to server-side steps
Reverts a2f549b4's client-side loss list and drops the restart sentence;
the retry and delayed-not-dropped claims now cover only events that have
reached the servers.
* docs: document unattended installation for the self-hosted quickstart
getting-started.sh reads every prompt's answer from a NETBIRD_* environment
variable since v0.77.1. Document the variables, the env-then-prompt-then-default
order, NETBIRD_NON_INTERACTIVE, the curl | bash pitfall, and how unattended runs
differ (domain validation, trusted peers warning, no pause for external proxies,
no overwrite on rerun).
* docs: an empty variable counts as unset in unattended installation
* docs: say the variables must be set for bash, not reach it
Firefox/Gecko suffers severe scrolling jank on the documentation pages because of the large decorative SVG in the page header.
The SVG uses both:
- `mix-blend-mode: overlay`
- `transform: skewY(-18deg)`
Removing only the transform (`skew-y-[-18deg]`) for firefox-base browsers makes scrolling smooth immediately.
Reproduced in:
- Firefox on Windows
- Zen on Windows
- Zen on macOS
Chromium is unaffected.
* docs: BYOP run command and exposing L4 ports, with a host-networking option
- Bring Your Own Proxy: update the docker run commands to the dashboard
wizard's current form (NB_PROXY_ADDRESS=:443, named certificate volume);
the image listens on 8443 by default and runs as uid 1000.
- Bring Your Own Proxy: new section on exposing TCP and UDP services:
publish and open each listen port, the recreate it takes, a pre-published
range, or host networking and its port-1024 limit.
- Enable Reverse Proxy: note that changing ports recreates the proxy, and
document host networking with the two settings it needs.
- Reverse Proxy overview: point BYOP users to the new section.
* docs(reverse-proxy): UFW does not filter Docker-published ports; host mode needs Traefik's ProxyService route
* docs: describe how reverse proxy services share ports
The reverse proxy page said every L4 service needs a dedicated port and
that each port can only be used by one service. That is not what the
proxy and management do: the conflict check is per cluster, protocol
and port, so a port takes any number of TLS services (told apart by
SNI), at most one TCP service (the catch-all for unmatched
connections), and, counted separately, at most one UDP service.
Also correct the main-port description: a TCP service may listen on the
main port too, and then receives the connections that match no SNI
route, instead of the HTTP reverse proxy.
Verified against checkPortConflict (management/internals/modules/
reverseproxy/service/manager/manager.go) and handleUnmatched
(proxy/internal/tcp/router.go) in v0.79.0, and on a self-hosted
cluster: TLS services on 443 are routed by SNI, unmatched and plain
TCP connections reach the TCP service on 443, a second TCP service on
443 is rejected with 409, and a UDP service on 443 is accepted
alongside them.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: TLS listen ports, custom-port fallback and one domain per service
TLS services always need an explicit listen port, including on clusters
without custom port selection, where the dashboard keeps the field
editable; auto-assignment applies to TCP and UDP. On a custom port with
no TCP service, unmatched and HTTP connections are dropped, and non-TLS
connections on the main port take the same fallback as unmatched SNI.
A domain belongs to one service, so the HTTP/TLS same-hostname warning
now says creation fails. In Docker the main port is 8443, so listen port
443 is a custom port. Drop the ECH example from the no-SNI case.
* docs: HTTP hostnames on a custom port fall back to its TCP service
A request for an HTTP service's hostname on a custom port matches no
route there, so it follows the same fallback as any unmatched
connection: the port's TCP service if it has one, otherwise dropped.
* docs: tighten the L4 port overview and the port-sharing warning
The port-sharing warning read as if a second service of any protocol
fails on a port; only TCP and UDP are limited to one per port, while
TLS services share by SNI. Say that directly, shorten the L4 overview
to a summary that links the two sections holding the rules, and name
the listen port in the TCP and UDP mode descriptions.
---------
Co-authored-by: Janek Härtter <janek@netbird.io>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
* docs: reverse proxy protocols, path prefix matching, active TCP services
Add a protocol support section: WebSocket, SSE and HTTP/2 in HTTP mode,
HTTP/1.1 toward cleartext targets (no h2c), and which mode fits gRPC
with and without TLS. Explain that path prefixes match as text, that the
matched prefix is stripped unless Preserve Full Path is on, and how a
trailing slash matches a whole segment. Add a troubleshooting entry for
an active TCP service whose backend does not answer.
* docs: split path matching from prefix stripping, tighten wording
Move the path-matching notes after the existing overview sentence they
were interrupting, and split them into matching (and the trailing-slash
form) and prefix stripping (and Preserve Full Path). Merge two
overlapping sentences on the upstream HTTP version, and shorten the
troubleshooting cause and solution.
* docs: point the active-TCP troubleshooting entry at the listener check
Step 3 of the checklist is an HTTP request, which cannot confirm a TCP
backend such as SSH or RDP; step 6 checks the listening socket and bind
address on the target host.
Rewrite the High availability section of How Routing Peers Work around the
routing peer selection order (metric, then direct over relayed, then latency),
the events that make a peer switch, and what a switch does to open
connections.
- Name a direct connection falling back to relayed as a switch trigger when
routing peers share a metric, and state that different metrics prevent it.
- State that, with masquerade on, every switch resets established TCP
connections, including the failback to a returning primary, which happens
as soon as the primary reconnects, before a direct connection is back.
- Replace the 20 ms latency threshold with the 10 ms margin the client uses,
and state that latency is measured when the connection is set up, so a
peer keeps its routing peer when latency later changes.
- Add where a switch appears in the client log.
- Production checklist: with equal metrics a peer picks by connection type,
then latency, when it connects; this is not load balancing.
- Exit nodes: retarget the link to the renamed section.
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>
netbirddev