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
* docs: add QUIC UDP/443 relay transport to Ports & Firewalls
Add UDP/443 (QUIC) alongside TCP/443 (WebSocket) on the relay service
entry, list the current relay above the legacy TURN one, relabel the
TURN entry as legacy, and tighten its fallback note to lead with the
older-client case.
* docs: fix punctuation in relay IPv4 note
* Added needed account settings to the migration column and added more
dependencies.
* Export libpq when installing with homebrew.
* Update migrate-sqlite-to-postgresql.mdx
Add a "Updating Billing Information and Payment Method" section to the
Plans & Billing page covering the path from Settings > Plans & Billing >
Manage Plan into the Stripe billing portal, where users can change their
payment method and use "Update information" to edit company name, billing
address, billing email, and tax information.
Note that this is NetBird Cloud specific functionality — self-hosted
deployments are not billed through the Stripe billing portal.
* fix: correct ICE candidate field semantics in troubleshooting docs
The ICE candidate (Local/Remote) field shows the selected pair only, so
every relayed connection reads -/- on both peers, even when STUN worked
and srflx candidates were gathered (symmetric NAT case). Lab-verified on
client 0.76.3 against NetBird Cloud.
- relayed-connections: fix the relay/relay sample to -/-; reword the
candidate table (the '-' row named one cause for a symptom with two);
replace the 'weaker side' heuristic, which cannot work when both sides
show '-', with a client-log method that splits the two causes; mark
'relay' as the legacy TURN fallback path
- troubleshooting-client: replace the 0.27.4 status sample with 0.76.3
output (Direct/Routes fields are gone; Relay server address and
Networks exist now) and update the field explanations to match
* docs: show Networks line with routed subnet and exit node in status sample
Verified output: a client's status -d lists the routes a routing peer
serves it under that peer's block (Networks: 0.0.0.0/0, 10.0.0.0/24),
while the trailing summary Networks line stays '-' unless this device
routes something itself. Adds a Networks field explanation.
* docs: accuracy and readability pass on status field docs
- status sample: kernel WireGuard interface implies Linux, so the sample
host is linux/amd64 now
- clearer table cells (candidate pair, not connection; per-row P2P
implications) and untangled the log-reading sentence
- consistent phrasing in the Relay server address and Networks field
explanations
* docs: expand srflx and prflx abbreviations in the candidate table
srflx (server-reflexive) and prflx (peer-reflexive) were used without
ever being expanded anywhere in the help pages.
* docs: mark turn.netbird.io as fallback-only on Ports & Firewalls
Since v0.29.0 (relay integration, #2244) clients relay through
*.relay.netbird.io and contact TURN only when that relay is unreachable
or the remote peer runs an older client. The rule stays recommended as
the last relay path.
* docs: include bare relay.netbird.io in the fallback-only note
Clients bootstrap against relay.netbird.io before being assigned a
regional *.relay.netbird.io host, so both belong in the reference.
* docs: trim the keep-this-rule advice from the fallback note
* docs: call the TURN relay legacy in the fallback note
Matches the 'Legacy fallback' wording in the relayed-connections
candidate table.
* docs: srflx plus failed checks does not skip the firewall steps
A gathered srflx candidate proves STUN discovery only; the failed
connectivity checks can still be a host firewall or a destination-scoped
egress policy, so clear Steps 4-5 on both peers before concluding
symmetric NAT.
* docs: fix self-hosted SCIM Tenant URL and explain duplicate users
The embedded Entra SCIM page showed the NetBird Cloud Tenant URL
(api.netbird.io) on a self-hosted page; a reader who copies it points
Entra at Cloud and provisioning silently fails. Use the reader's own
management domain instead.
Add a section explaining why externalId must map to objectId: NetBird
matches users by stable ID, not email, so a mailNickname externalId
creates a same-email duplicate of an existing sign-in user. Includes
remediation for accounts that already have duplicates.
* docs: safer duplicate-user remediation via integration reset
Address review feedback: don't tell operators a SCIM-created account is safe
to delete based on origin alone. Recommend deleting the integration to clear
the synced accounts (sign-in accounts are untouched), then reconfiguring with
externalId=objectId and re-provisioning. If removing a single account, verify
ownership and migrate peers/access first.
Add a decision-flow guide for "NetBird feels slow" that helps a reader
find whether the tunnel, their own connection, a routing peer, or the app
is the real cause, instead of assuming NetBird is at fault.
The page leads with the path traffic takes, a one-minute Quick test that
resolves the two most common causes (a relayed peer, or the local
network), then a Start here checklist that links down to detail sections:
checking the connection with netbird status -d, setting a baseline with
iperf3 in both directions, isolating the slow hop, ruling out packet size
and inspecting firewalls, and separating startup delays from throughput.
Add a reusable PathFlow component that draws the hop-by-hop path as a
labelled icon flow, used for the overview, the routing-peer example, and
the recap. Wire the page into the docs sidebar and the troubleshooting
hub.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add clientless RDP for third parties use case guide
Covers publishing an internal RDP host as a TCP reverse proxy service
as an RDP gateway replacement for third parties that cannot install
the NetBird client: single-host resource, TCP service with auto-assigned
listen port, mandatory IP allowlist/CrowdSec restrictions, .rdp file
handover, and the L4 security boundaries (no SSO/PIN on TCP, port
re-rolls on service re-create, service publishing bypasses access
policies).
* docs: make CrowdSec conditional on broad allow rules, add UDP transport note
Review feedback: CrowdSec Enforce is redundant behind a strict single-IP
allowlist, so it is now recommended only when allow rules are broader.
Adds a note that RDP's optional UDP transport cannot be used through the
shared proxy cluster (independent auto-assigned listen ports) and that
clients fall back to TCP-only automatically.
* docs: update access control screenshot to match single-IP recommendation
* docs: scope the UDP transport limitation to the shared proxy cluster
Auto-assigned listen ports apply to the NetBird-hosted cluster only; a
BYOP cluster can bind a TCP and a UDP service to the same custom port.
* docs: UDP transport through a BYOP same-port service pair is verified working
Tested with mstsc against a BYOP cluster binding TCP and UDP services on
one custom port: the client negotiates the UDP transport through the
proxy, and removing the UDP service degrades cleanly to TCP-only. Also
notes the macOS client does not support the RDP UDP transport.
* docs: scope the macOS UDP claim to what was observed
* docs: macOS UDP claim holds with the app's UDP setting enabled
* docs: split into shared-proxy and BYOP use cases, drop client-specific UDP note
Adds a comparison of the two proxy deployments (auto-assigned port and
TCP-only vs custom ports and RDP UDP transport), a BYOP walkthrough with
the same-port TCP+UDP service pair, and keeps resource setup, access
restrictions, and verification shared between both paths.
* docs: clarify BYOP TLS requirement and service-domain resolution, grammar fixes
* docs: add Quantum Resistance check to client status and make its fields navigable
Two related updates to the NetBird client status troubleshooting section,
prompted by an incident where a peer stayed invisible until Quantum Resistance
was turned off:
- Document the `Quantum resistance` status field as a cause and fix. A peer with
Quantum Resistance enabled only connects to peers that also have it enabled, so
a mismatch can keep a peer from connecting. Cross-link the Quantum-Resistance
doc and its permissive mode.
- Convert the flat peer-field list into per-field h3 subsections (Connection
type, Direct, ICE candidate, Last WireGuard handshake, Quantum resistance,
Transfer status) so each appears in the On this page nav.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: tighten status field descriptions per review
- ICE candidate: describe relay/host as the local and remote ICE candidate
types, and point to Connection type for whether the path is P2P or relayed,
since a host candidate does not by itself mean the remote path is direct.
- Last WireGuard handshake: distinguish an empty value (no handshake yet) from
an old timestamp (a previous connection that is now stale).
- Quantum resistance: call Rosenpass post-quantum key exchange rather than
encryption.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: promote Agent Network in the sidebar and make sections collapsible
Rework the docs sidebar navigation:
- Render any nav group flagged `featured: true` as a highlighted card at the
top of the sidebar, with an optional `badge` label (currently Agent Network,
"New"). The flag is data-driven, so a future feature can take the spot by
moving two lines.
- Add a dropdown chevron to every collapsible menu, including the top-level
sections and the featured card, so it is obvious they expand.
- Collapse the top-level sections by default and expand the active one, so the
sidebar reads as a clean menu.
- Only render the active-page marker while its section is open, fixing the
orange highlight bar that lingered after collapsing an active section.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: make sidebar section toggles keyboard-accessible
The collapse toggle was a click-only span, so after sections collapse by
default keyboard and screen-reader users could not expand a section or reach
its links. Make each toggle a semantic button with aria-expanded and an
aria-label, which restores keyboard operation and announces the open state.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: keep sidebar sections expanded by default, collapse only Agent Network
Restore the original behavior where top-level sections start expanded and only
the nested sub-groups start collapsed, instead of collapsing everything. The
featured Agent Network card keeps its own isOpen: false so it starts collapsed.
The dropdown chevrons, featured card, and keyboard-accessible toggles are
unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* Include Alpine Linux installation steps
Add installation instructions for Alpine Linux, including CLI and desktop app setup.
* Revise Alpine instructions
I omitted the fact that the community repo had to be enabled in my original commit
* Apply suggestion from @braginini
* Changes requested by @TechHutTV
Updated installation instructions for Alpine Linux and added commands for starting the NetBird service.
---------
Co-authored-by: Misha Bragin <bangvalo@gmail.com>
A property marked x-omit-from-example: true in the openapi spec is left
out of the composed request/response examples while staying fully
documented in the parameter list and schema blocks. Needed for mutually
exclusive field pairs (policy rule ports vs port_ranges), where
composing an example from every optional field shows a payload the API
rejects. Companion spec change: netbirdio/netbird#7158
* docs: unmanaged DNS mode also ignores Custom Zone records
A peer whose group is under DNS Settings -> Disable DNS Management (or
started with --disable-dns) never gets NetBird's resolver wired into the
OS, so Custom Zone records silently stop resolving along with
nameservers. The unmanaged-mode description, the Custom Zones
limitations list, and the DNS troubleshooting flow now say so, and the
troubleshooting page gains a confirm-managed-mode first check (the
existing --disable-dns isolation test reproduces this exact cause and
misreads as 'not NetBird DNS').
Also fixes the API Reference links to the canonical /api path (/ipa
redirects).
* docs: fix DNS API Reference link on the DNS landing page
* docs: explain macOS two-resolver-stack DNS behavior and the match-only vs primary nameserver split
Lab-validated against client 0.76.3 (macOS 26, NetBird Cloud):
- DNS troubleshooting: new Issue 5 'dig and host fail, but browsers and
curl work (macOS)' with the scoped-resolver vs resolv.conf explanation,
the language-runtime split table (pure-Go/dnspython/c-ares vs
getaddrinfo), and the Windows nslookup-vs-NRPT analog; renumbered
Issues 5-8 to 6-9; checklist step 6 now says why it prescribes
dscacheutil/Resolve-DnsName
- Internal DNS Servers: primary-vs-match now explains that match-only
leaves resolv.conf untouched on macOS; new warning that emptying a
match group's domains silently drops the search suffix (masked on
domain-joined Windows); split-horizon example gains the
route-everything-internal variant (the OpenVPN migration shape)
- DNS overview: macOS line now distinguishes scoped resolvers from the
primary case, where configd regenerates resolv.conf with NetBird's
resolver
* docs: add dashboard screenshot for the route-all-internal nameserver example
* docs: polish wording in the macOS DNS additions
* docs: promote the route-all-internal example to its own section
* docs: drop the Example prefix from the nameserver scenario headings
* docs: state the public-resolution prerequisite for an internal primary nameserver
* docs: make the direct-resolver check precise
* docs: anchor the scoped-resolver term to scutil output and split the dense solution paragraph
* docs: add corporate firewalls table to Ports & Firewalls
Add a "Corporate firewalls" section covering common enterprise firewall and
SASE products (Palo Alto, Fortinet, Cisco, Check Point, Zscaler, Netskope,
Cloudflare Gateway, Sophos, SonicWall, Barracuda). It explains how NetBird
behaves through a corporate firewall, that it falls back to the TCP/443 relay
when direct peer-to-peer is blocked so peers stay connected, and what to allow
per product, including which TLS inspection feature to exclude the NetBird
domains from.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: refine corporate firewalls section and cross-link from troubleshooting
Address review feedback on the new Corporate firewalls section:
- Distinguish the two firewall failure modes. Blocking outbound UDP falls back
to the TCP/443 relay, but TLS/DPI inspection of the control plane can prevent
connecting at all.
- Correct the STUN vs TURN roles. STUN enables direct connections, while TURN
and the relay service are the fallback, not a way to keep connections direct.
- Make the relay domains explicit in the inspection-bypass guidance, since a
*.netbird.io wildcard does not match the deeper *.relay.netbird.io hosts.
Cross-link the section from the relayed-connections guide (Step 3) and the
troubleshooting hub, since a corporate firewall blocking UDP is a common cause
of relayed connections.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add Palo Alto source-NAT guidance and surface firewalls at relay escalation
Corporate firewalls: note that some enterprise firewalls apply per-destination
(symmetric) source NAT, which defeats hole punching and forces the relay. Add
the port-preserving fix, with Palo Alto's Persistent Dynamic IP And Port mode in
its row and a general note covering the pattern and UDP session timeouts.
Relayed connections: the symmetric-NAT cause is often a corporate firewall the
operator controls, so reference the Corporate firewalls section at the final
escalation step, and scope the earlier "no firewall tuning will change that"
claim to mobile and cloud NAT where it actually holds.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: address second review pass on corporate firewalls guidance
- Broaden the firewall failure modes beyond UDP blocking and TLS inspection to
include blocked or proxied outbound TCP/443 and strict destination egress,
which break the control plane before any inspection.
- Note that reaching the NetBird service endpoints does not by itself prove a
direct peer path, since a firewall can allow STUN/TURN yet block UDP to peer
addresses. Qualify the relayed-connections conclusion accordingly.
- Match the STUN/TURN fix to the transport that netbird status reports: STUN is
UDP 80/443/3478/5555, TURN is UDP 80/443 plus TCP 443-65535, rather than
applying STUN's UDP ports to TURN.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: drop TURN wording from corporate firewalls guidance
Refer to the outbound relay endpoints as "relay" rather than "STUN/TURN" and
"Relay (TURN)" in the Corporate firewalls section, in line with NetBird's relay
terminology. Endpoint hostnames are unchanged.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: replace TURN wording with relay in user-facing docs
TURN is legacy in NetBird, so the user-facing docs now call it the relay
service:
- Ports & Firewalls: rename the "Relay (TURN) service" endpoint and split the
two relay endpoints by transport (UDP/TCP and TCP) to keep them distinct,
and drop TURN from the notes and the JSON-download line.
- Relayed-connections and troubleshooting hub: drop TURN from the status and
rollout wording and the connectivity chip label.
- Zero Trust use case: describe STUN and relay instead of STUN/TURN.
Endpoint hostnames (turn.netbird.io) and the netbird status output are
unchanged. Self-hosted coturn documentation is intentionally left as-is, since
there TURN refers to the actual legacy software.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: scope TURN wording changes to Ports & Firewalls and relayed connections
Revert the TURN wording in the troubleshooting hub chip and the Zero Trust use
case, keeping the TURN-to-relay rename limited to the Ports & Firewalls and
relayed-connections docs for now. The corporate-firewalls cross-link chip in
the hub stays.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: sort the corporate firewalls table alphabetically
Order the firewall and SASE rows alphabetically by product (Barracuda through
Zscaler) so readers can scan for their vendor.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add pfSense and OPNsense to the corporate firewalls table
Add pfSense and OPNsense rows, each linking to its existing NetBird setup
section for keeping connections direct (Static Port outbound NAT, or
Endpoint-Independent NAT / EIM-NAT beta on pfSense). Broaden the table intro
from "enterprise" firewalls since these are open-source firewalls.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
netbirddev