Document the community.ansible_netbird collection for managing NetBird
resources (users, groups, setup keys, policies, networks, DNS, posture
checks) declaratively via the REST API. Adds a new Infrastructure as
Code subsection under Self-Host NetBird with room for future entries.
Cross-links from the Automated Setup PAT bootstrap page since the
collection is the natural next step after obtaining the first token.
* Restructure Troubleshooting into a hub with per-area pages
- Add a Troubleshooting hub (/help/troubleshooting) with icon/chip cards and a "Still stuck?" CTA
- Split NetBird Client troubleshooting into an overview + per-OS pages (Linux, Windows, macOS, Android, iOS)
- Split Self-hosted troubleshooting into an overview + per-area pages (installation, IdP, dashboard, certificates, connectivity, database)
- Split "Report bugs and issues" into Community Support and NetBird Support pages
- Add Troubleshooting resource connectivity and a NetBird Cloud pending-approval page
- Add DNS troubleshooting Issue 8 (Windows NRPT rule blocked by a lingering GPO)
- Cross-reference the new pages from networks, DNS, and reverse-proxy docs; update nav
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Address review: client terminology, dead props, labels, cross-links
- Use "client" instead of "agent" across the client troubleshooting pages (headings, prose, anchors)
- Remove unused source: props from the Troubleshooting hub tiles
- Relabel the "NetBird Cloud" grouping to "Cloud & identity" (SSO/provisioning also apply to self-hosted)
- Add a Tiles title on the report-bug landing; add reverse-proxy -> resource-connectivity cross-link
- Fix comma splices introduced by the em-dash cleanup in relayed-connections
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Add client-side hash redirect for moved self-hosted anchors
Old deep links like /selfhosted/troubleshooting#debugging-turn-connections now
forward to the per-area page, since next.config redirects can't act on the URL fragment.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Apply docs-skill review: conventions + reshape area pages
- "open source" (no hyphen), expand NRPT on first use, descriptive alt text + captions on TURN images
- Fix inherited "Netbird" casing in the client glossary
- Reshape the six self-hosted area pages to Symptom -> likely causes (ordered) -> Fix -> Confirm, preserving anchored headings
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Fix two typos in client glossary (CodeRabbit)
- "nunning" -> "running" in the glossary
- possessive "it's" -> "its" in the routing-table sentence
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: fix two broken links in troubleshooting pages
- database: point the "upgrade path" link at /selfhosted/maintenance/upgrade;
selfhosted-quickstart has no #upgrade anchor so the old link landed at page top
- client: add HashRedirect so old #net-bird-agent-status deep links forward to
the renamed #net-bird-client-status section on the same page
* docs: address review follow-ups (deep-link redirects + client casing)
- self-hosted troubleshooting: extend the HashRedirect map with the per-issue
(###-level) anchors from the old single page, so old deep links land on the
exact sub-section of the new area page rather than just the page top
- client glossary: lowercase "NetBird client" in the peer-a/peer-b entries
(house convention) and fix "linux" -> "Linux"
* docs: review polish — fix image class + first-use acronym glosses
- connectivity: fix bad CSS class imagewrapper-nig -> imagewrapper on the
TURN-test screenshot (the typo'd class matched no style and broke zoom)
- gloss acronyms on first use: GPO (DNS Issue 8), IdP/SSO (identity-provider),
ACME (certificates), CORS (dashboard)
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
* docs: add unlisted Enterprise Commercial License getting-started page
Self-hosted NetBird stack guide with embedded IdP, served at /selfhosted/enterprise/getting-started. Reachable by direct link only; intentionally not added to the sidebar nav.
* docs: add custom TLS certificate appendix to Enterprise getting-started
* docs: rewrite Enterprise Commercial getting-started from script-based deployment guide
Replace the topology-choice page with the current script-based flow:
getting-started.sh for fresh installs and migrate-to-commercial.sh for
community-to-enterprise migrations. Add the migration path, numbered
sections, and a troubleshooting section; standardize on enterprise
terminology and <your-domain> placeholders. Keep the IdP-connection
links and the custom-TLS appendix.
* docs: clarify traffic-flow note in Enterprise getting-started
* docs: link Docker install in Enterprise getting-started prerequisites
Replace the two-stage memberOf+RegExReplace group rule with a single
tokenGroups-based rule, and add a callout in Step 1.6 covering the most
common filter variations (different prefix, suffix, alternation, no
filter). Update troubleshooting refs to the new rule names.
* 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
The Azure AD Graph app manifest format was deprecated in January 2025.
The attribute accessTokenAcceptedVersion has been renamed to
requestedAccessTokenVersion in the Microsoft Graph manifest format.
Co-authored-by: Ashley Mensah <ashleyamo982@gmail.com>
* 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
* Update reverse proxy documentation for domain and DNS record changes
* Clarify reverse proxy domain description in migration guide
* Update domain requirement clarification in migration guide
Clarified the domain requirement for the proxy + added missing charactr afer example domain
---------
Co-authored-by: shuuri-labs <61762328+shuuri-labs@users.noreply.github.com>
* Fix reverse proxy docs: add ProxyService gRPC route, fix container commands, support both setups
- add missing /management.ProxyService/ gRPC route to all reverse proxy config templates (traefik, nginx, caddy, NPM) in reverse-proxy.mdx
- change default proxy -> management connection to use direct docker network instead of routing through traefik, avoiding hairpin NAT and missing gRPC route issues
- add "Connecting through Traefik" section for separatevhost deployments
- fix token CLI commands: use /go/bin/ prefix (not on container PATH), add --config flag for combined container
- ratify instructions for enabling reverse proxy both combined (netbird-server) and multi-container (management) setups
* remove unecessary proxy endpoints from reverse proxy templates other than traefik in reverse-proxy.mdx
* - standardize usage of 'docker exec' as opposed to 'docker compose exec + service name' in instructions
- added AuthClientID config instructions
- added traefik grpc rule to configuration file explanation page
- idletimeout for reverse proxy migration is now 0, matching getting-started.sh
* add clarification on grpc ProxyService path for traffic - only required if the proxy service is on a different docker network to traefik
* fix: correct step count in Traefik connection section from two to three
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* Change header from H2 to H1 in backup.mdx
With H2 header, the browser tab name was "undefined" instead of the proper name
* Change H2 header to H1 in remove.mdx
With H2 header, the browser tab name was "undefined" instead of the proper name
* Change H2 header to H1 in upgrade.mdx
With H2 header, the browser tab name was "undefined" instead of the proper name
* Promote h3 sub-headings to h2 in upgrade.mdx to fix TOC error
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Jack Carter <128555021+SunsetDrifter@users.noreply.github.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>
Jack Carter