New page covering how to pre-populate default.json so NetBird peers
register with the right settings on first start in IaC, Docker, and
Kubernetes deployments. Documents file location across OSes, common
keys (with guidance to leave PrivateKey empty and treat PreSharedKey
as optional), runtime setup-key injection with worked Docker and
Kubernetes ConfigMap + Secret examples, backup hazards around the
embedded WireGuard private key, and how to verify registration via
netbird status --check startup, --json, and GET /api/peers.
Includes a callout that this workflow is for unattended workloads
only -- end-user devices should still enroll via the SSO flow so
Zero Trust can re-verify the user identity.
Linked from Manage NetBird -> Peers, right after Setup Keys.
* docs: add How Routing Peers Work concept page
Add a feature-agnostic primer covering the routing peer mental model:
traffic flow through forward vs input chains, host requirements (IP
forwarding on Linux/Windows, container caps, cloud settings), HA modes
(primary/failover and equal-metric latency switching), masquerade,
access control, DNS routing, exit nodes, and common pitfalls. Surface
it in the sidebar under Networks and cross-link from both the Networks
and Network Routes concept pages.
* docs(routing-peers): apply review feedback
- Clarify mental-model walkthrough describes the Linux kernel-mode path
- Expand OS list to Linux/Windows/macOS/FreeBSD/Android/tvOS/Docker
- Correct container IP-forwarding guidance: set sysctl on the host
- Reframe Windows NB_ENABLE_LOCAL_FORWARDING as opt-in for exposing
services on the routing peer's local addresses, off by default
- Soften failover wording to avoid implying tunnel rebuild; scope
reset claim to established TCP connections, drop "typically"
- Add masquerade-off caveats: Linux only, breaks HA
- Drop unfounded ACL-Groups-require-masquerade Warning
- Drop misplaced internal-DNS-resolver link from DNS section intro
- Rename Wildcard domains section to Routing Peer DNS Resolution
- Drop container/host IP-forwarding pitfall (not a real-world failure)
- Rephrase exit-node ICMP pitfall: clients can't connect at all
* docs(routing-peers): add example for forward vs input chain policies
A concrete scenario (office subnet behind the peer + Grafana on
TCP/3000 + SSH on TCP/22) showing the two policies needed: a network
resource policy on the forward chain and a peer-to-peer policy on
the input chain.
Add the embedded IdP sync pages (Microsoft Entra ID API/SCIM, Google
Workspace, JumpCloud, Keycloak) under SELF-HOST NETBIRD so users can
discover them from the navigation instead of relying on direct links.
Regroup the Authentication subsection by purpose: Local Users, Identity
Provider Connectors (wraps Self-hosted and Managed IdPs), and Provision
Users & Groups.
* docs(macos): add CLI-only binary install and MDM deployment guide
Document the previously undocumented binary-only install path for macOS
using USE_BIN_INSTALL and SKIP_UI_APP flags. Add a new guide for
building custom CLI-only .pkg packages for MDM fleet deployment,
covering pkgbuild workflow, pre/postinstall scripts, setup key
enrollment, and update strategies.
* docs(macos): add warnings about unsigned binaries in tarballs
The darwin tarballs from GitHub releases contain unsigned binaries —
only the official .pkg goes through the sign pipeline. Add warnings
to both the install page and MDM guide, and document the full signing
workflow: codesign for the binary, pkgbuild --sign for the package,
and optional notarization via notarytool.
* docs: add ADFS with Web Application Proxy self-hosted guide
New guide for integrating on-prem Active Directory with ADFS as an OIDC
identity provider for self-hosted NetBird. Covers ADFS on a dedicated
member server, Web Application Proxy in a DMZ, Duo ADFS MFA Adapter,
claim transform rules, and the required NetBird configuration
(NETBIRD_TOKEN_SOURCE=idToken, NETBIRD_AUTH_USER_ID_CLAIM=upn).
* docs: rewrite ADFS guide for Community Edition Dashboard flow
Switch from standalone/setup.env style to the CE-native Dashboard-based
external IdP flow:
- Use a confidential Server Application (Add-AdfsServerApplication with
generated client secret) instead of a Native Application with PKCE.
- Redirect URI now comes from NetBird's Settings > Identity Providers
flow, not hard-coded /peers paths.
- Drop the NETBIRD_TOKEN_SOURCE and NETBIRD_AUTH_USER_ID_CLAIM env vars
(those are standalone/commercial-license settings).
- Fix the base64 sub claim issue upstream in ADFS via a new claim rule
(Rule 5) that emits sub from UPN, with a fallback note about
PairwiseIdentifierEnabled for ADFS builds that need it.
- Update Troubleshooting and Configuration Summary to match.
* docs: expand ADFS Step 1 and Step 5 with deeper setup prose
Pull in the richer explanations from the updated source guide:
- Step 1 gets server-provisioning prerequisites, Get-WindowsFeature
verification after role install, expanded TLS cert rationale with
Test-Certificate, a three-option service-account discussion with the
Get-KdsRootKey check and lab-mode EffectiveTime trick, a full
troubleshooting block for Install-ADServiceAccount, per-parameter
explanations for Install-AdfsFarm, and a Start-Service + event-log
fallback plus detailed OIDC-endpoint troubleshooting in 1.5.
- Step 5 gets a full Provision the WAP Server section covering server
specs, the domain-join decision (with SCADA framing generalized),
pre-install firewall rules, hosts-file name resolution with Test-
NetConnection, and exact Export-PfxCertificate/Import-PfxCertificate
flow for the WAP cert. Step 5.3 is reframed as Establish the Proxy
Trust with what-it-does and what-you-need callouts; 5.4 expands
Get-WebApplicationProxyHealth troubleshooting.
CE-specific rewrites (Server Application flow, Dashboard IdP config,
Rule 5 sub override, Duo-optional framing) are preserved.
* docs: fix ADFS intra-page anchor links
@sindresorhus/slugify (the project's heading slug generator) splits
CamelCase words (NetBird -> net-bird) and inserts hyphens between
period-separated digits (2.3 -> 2-3). Update every in-page anchor to
match the generated slugs so step links resolve correctly.
Also redirect the UPN row in the AD attributes table to Step 3, since
the 'Required NetBird Configuration Settings' subsection it used to
reference was removed in the CE rewrite.
* docs: note that ADFS group-membership claim rules are optional
Rules 3a and 3b in Step 3 produce the 'groups' claim consumed by
JWT Group Sync. Add a Note explaining they can be skipped if group
sync isn't needed, and clarify that 3a and 3b must be kept together
(3a emits into a temp claim, 3b filters and renames it to 'groups').
* docs: expand ADFS Step 3 intro with context and per-rule overview
The prior one-sentence intro ('NetBird requires specific claims in the
OIDC tokens') didn't explain what issuance transform rules are or what
each of the six rules does. Add a paragraph on why ADFS needs them and
a short bullet list describing each rule's purpose and dependencies
(e.g., Rule 5 depends on Rule 4). The optional-rules Note and code
block follow unchanged.
* docs: fix ADFS guide inaccuracies flagged in review
- Replace Get-EventLog with Get-WinEvent in Step 1.5 — Get-EventLog
only reads classic logs and cannot open 'AD FS/Admin', which lives
under Applications and Services Logs.
- Remove references to Set-AdfsServerApplication -PairwiseIdentifierEnabled
$false; that parameter does not exist on the cmdlet. Replace the
fallback guidance with NETBIRD_AUTH_USER_ID_CLAIM="upn" in setup.env,
which was the actual POC fix alongside the Rule 5 claim override.
- Restructure the 404 troubleshooting entry as a two-step fix
(claim rule + NetBird env var) with a decode-token sanity check.
- Drop the 'Domain Users' example from the JWT group sync paragraph
since Rule 3b's default '^NetBird-' filter would exclude it;
clarify that visible groups are governed by the filter regex.
- Relabel the LDAP/LDAPS firewall row as 'directory and attribute
lookups (claim data)' rather than 'authentication'; ADFS
authenticates users via Kerberos and uses LDAP for attribute lookup.
- Add a clarifying Note to Step 2.5 explaining that the guide reuses
the client_id as the Web API identifier for simplicity, and larger
environments may prefer a distinct resource URI.
* docs: rewrite ADFS guide to focus on NetBird-specific configuration
* docs: nest ADFS/DC and WAP/NetBird in topology as separate boxes
* docs: refer to NetBird's Microsoft AD FS connector instead of Generic OIDC
* docs: rework ADFS topology diagram and convert callouts to Note components
* docs: rename Restricted/OT to Restricted Network in ADFS guide
* docs: drop Generic OIDC link from ADFS related resources
* docs: drop single-group limitation from ADFS guide
* Add force approval docs
* add force approval
* add filter and batch operation
* Rename force approval docs to bypass compliance
- Rename force-approval.mdx to bypass-compliance.mdx
- Update navigation title from "Force Approval" to "Bypass Compliance"
- Update all internal links to use new path
- Update image paths to /bypass-compliance/
- Update terminology in EDR integration docs
* add images
---------
Co-authored-by: Ashley Mensah <ashleyamo982@gmail.com>
Add all 5 system tray settings under Client > Settings: Allow SSH,
Block Inbound Connections, Connect on Startup, Enable Lazy Connections,
and Enable Quantum-Resistance. Allow SSH and Enable Lazy Connections
redirect to existing docs. Connect on Startup is a new page. Renames
Post-Quantum Cryptography heading to Enable Quantum-Resistance to match
the GUI label.
* added migration guide from external to embedded idp
* updated guide
* clarify issuer domain used
* improved docs structure and added clarifying notes
* updated guide to match latest binary
* link fixes and added extra psql instructions
* update versions properly
Add documentation for enabling the NetBird enterprise application in
Microsoft Entra ID, including finding the app by Application ID and
granting admin consent for the directory.
* Add backend service configuration guide for reverse proxy trusted proxies
Many self-hosted services (Jellyfin, Home Assistant, Nextcloud, Plex)
require a "trusted proxies" or "known hosts" setting when behind a
reverse proxy. With NetBird, the proxy's IP is a dynamic NetBird IP
from 100.64.0.0/10 that can change on restart, so hardcoding it breaks.
This adds a new doc page with the recommended solution (trust the full
CGNAT range), per-service config examples, Docker bridge network
guidance, and a warning on the reverse proxy overview page.
* Update service-configuration.mdx and move/add images
* Fixing typos
---------
Co-authored-by: Brandon Hopkins <brandon@techhut.tv>
- Create Internal DNS Servers page consolidating nameserver configuration,
private DNS routing, and Active Directory guidance
- Trim DNS Overview, DNS Settings removing duplicated and filler content
- Merge Configuring Nameservers page into Internal DNS Servers
- Replace Quickstart and Configuring Nameservers pages with redirects
- Update navigation sidebar and all internal links
* Add Block Inbound Connections documentation to Client settings
Document the previously undocumented "Block Inbound Connections" client
setting (introduced in v0.46.0). Adds a dedicated feature page under
Client > Settings, updates the sidebar navigation, and adds the
--block-inbound flag to the CLI reference.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Move Post-Quantum Cryptography to Client settings and add systray notes
Move the Rosenpass/post-quantum cryptography page from manage/integrations/
to client/ under the new Settings section. Add redirects for the old URL.
Also add systray toggle instructions to both the Quantum-Resistance and
Lazy Connections pages.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Rename post-quantum cryptography page and fix hydration error
Drop the "Enable" prefix from the page title and filename for a cleaner
topic name. Update redirects and navigation. Fix hydration mismatch
caused by a <div> (Button component) nested inside a <p> tag.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* Reverse Proxy Doc Amendments
- update custom domains page to more closely reflect wording in the UI, added screenshots
- add warning to index page that reverse proxy feature does not currently work with pre-shared keys/rosenpass
* Update navigation order (move reverse proxy below network routes)
* update migration guide to mention the need for TWO cname records (proxy and proxy wildcard)
* Streamlined site-to-site docs in new dedicated section. Removed old use-case guide and added redirects
* restructure use-cases, move network use cases to network sections
* Reorganize network routes and networks documentation structure
- Restructure use cases into by-scenario and by-configuration folders
- Reorganize images to match new doc structure (concepts, by-scenario, by-resource-type)
- Add screenshots for site-to-site guides (home, office, cloud)
- Add policy screenshots for networks use cases
- Update site-to-site docs to use two separate policies instead of bidirectional
- Fix Access Control Groups to use correct destination groups
- Move "Self-Hosted vs Cloud" page to about section
- Update navigation and add redirects for moved pages
- Add CLAUDE.md for Claude Code guidance
* cleaned up network docs/image folder structure
* Align site-to-site use case links and redirects
Co-authored-by: Cursor <cursoragent@cursor.com>
* Update CLAUDE.md with accurate project details
Fix Next.js version (14 → 16), add React 19/Tailwind/Pages Router
details, document MDX page conventions, image paths, and note
absence of test suite.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix broken images and hydration error on networks page
- Restore 6 network index images accidentally deleted in 4116092
- Fix keycloak image filename typo (keycloack -> keycloak)
- Fix hydration mismatch by replacing invalid <p><div> nesting with <div>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* Fix 4 broken internal links found in PR review
- Fix missing by-scenario/ segment in site-to-site-home and
site-to-site-office Tile hrefs (network-routes use-cases index)
- Fix lazy-connections typo to lazy-connection (implement-zero-trust)
- Update stale redirect link to direct path for access-control
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add Zero Trust implementation guide
* minor text and formatting fixes
* various improvements to the zero trust guide
* Added links to other relevant docs pages
* docs: improve Zero Trust implementation guide
- Add guide to navigation menu
- Rewrite section 5.2 on routing peer traffic direction for clarity
- Add documentation links throughout (Networks, Access Control, DNS,
Control Center, Setup Keys, IdP sync, Traffic Events, Event Streaming)
- Add internal section and appendix cross-references
- Remove "Subject" terminology, replace with "source groups" and
clearer user/peer terminology
- Expand acronyms on first use (IdP, SSO, MFA, SIEM, CIDR, VPC, etc.)
- Add explanations for technical concepts (masquerading, overlay networks,
NAT traversal, protocols, ports)
- Enhance firewall rules section with service explanations and FAQ link
- Improve worked examples with port and protocol context
- Add command-line tool explanations for troubleshooting
- Make guide more accessible for junior network admins and students
* Minor changes and adjustments.
* Add various diagrams
* Add dashboard settings best practices section
* Improve zero trust guide with MDX components, examples, and clarity
- Add Note/Warning MDX components replacing markdown blockquotes
- Add TURN service rules to firewall configuration section
- Add JSON API example for policy creation
- Improve three-tier app diagram with box-drawing characters
- Add Networks vs legacy Network Routes warning for Zero Trust
- Add CIDR posture check limitation note (iOS/Android unsupported)
- Add DNS forwarder port change note (v0.59.0+)
- Add lazy connections feature limitations and version requirements
- Add Users view to Control Center documentation
- Convert verification checklists to Note components
- Fix grammar throughout (serial commas, hyphenation consistency)
- Improve term definitions and service descriptions
* Update zero trust guide to enhance clarity and provide outbound port references
- Replace detailed outbound allowlist rules with links to FAQ and self-hosted guide for port requirements
- Minor adjustments to lazy connections feature description for consistency
---------
Co-authored-by: Brandon Hopkins <76761586+TechHutTV@users.noreply.github.com>
Co-authored-by: Ashley Mensah <ashleyamo982@gmail.com>
Adds a comprehensive reference page for all environment variables used
when self-hosting NetBird, covering Management Server, Signal Server,
Relay Server, Dashboard, and Coturn services. Focuses on the new
embedded identity provider approach, removing deprecated external IDP
configuration variables.
* Add Automatic Updates Documentation
* Add more information and version notes
* Update
* Set version
---------
Co-authored-by: Zoltán Papp <zoltan.pmail@gmail.com>
* docs: Restructure and improve DNS documentation
Reorganizes DNS docs into overview, configuration, settings, and troubleshooting
guides with clearer explanations and UI-aligned terminology
* amendments from Vik's feedback
* clarified IP assignment range
* remove incorrect common mistake note
* - added diagrams
- renamed dns overview.mdx to index.mdx
- updated references/redirects
- created new spacer div class
---------
Co-authored-by: Ashley Mensah <ashley@netbird.io>
