mirror of
https://github.com/netbirdio/docs.git
synced 2026-10-09 15:19:04 +02:00
4a9435e70182f6b6ba3834df95114365418cfea6
9
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Jack Carterandriccardom
|
4a9435e701 |
docs: group MDM policy keys by job and split delivery into per-platform pages (#1020)
* 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> |
||
|
Maycon Santos
|
47b53bdb7d |
Document the remote-jobs opt-in and MDM keys (#914)
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. |
||
|
Viktor Liu
|
a2719629fc | Document the client local metrics endpoint (#952) | ||
|
Jack Carter
|
62baad95a1 |
docs: standardize on "NetBird client" over "agent" for the client software (#940)
* 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 |
||
|
Jack Carter
|
d60d579197 |
Add exit node enforcement section (Auto Apply + disableNetworks) (#943)
* 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) |
||
|
Jack Carter
|
f403129f66 |
Navigation cleanup: MDM deployment under Peers, purge stale tutorials, MSP portal refresh (#906)
* docs: move MDM deployment guides under Manage > Peers
The five fleet-deployment guides (GPO, macOS .pkg, Jamf Pro, Kandji,
Intune) lived under Integrations, but nothing in them integrates with
NetBird's platform — they are peer onboarding at scale, which lives
under Peers. The label also collided with Access Control's
'Integrate MDM & EDR', which uses MDM in the opposite sense.
- Move pages from /manage/integrations/mdm-deployment/ to
/manage/peers/mdm-deployment/ with a permanent wildcard redirect
- Re-point legacy /how-to redirects directly at the new paths
- Move the nav group under Peers as 'MDM Deployment'; remove the
now-empty Integrations group
- Update internal links
* docs: link full GPO deployment guide from MDM integration page
* docs: show setup-key secret wiring and replica naming for k8s routing peers
Fold the two verified-novel bits from the Access Infrastructure
autoscaling tutorial before purging it:
- Replace the 'use a secret' Note with the actual kubectl create
secret + secretKeyRef wiring (matches what the NetBird operator
injects for routing peers)
- In the HA section, note that removing the static NB_HOSTNAME lets
each replica register under its pod name (client falls back to
os.Hostname(), which is the pod name in Kubernetes)
* docs: purge redundant Access Infrastructure tutorials
The four pages under Manage > Peers > Access Infrastructure were
2024-era SEO tutorials that duplicated canonical feature docs and
carried outdated claims (pre-rewrite SSH model without the built-in
SSH server, a Docker section that never actually enrolls the
container with a setup key, CrowdStrike presented as the only EDR
integration, stale v0.29 output and vintage-UI screenshots).
Cross-checked each page against its canonical counterpart; nothing
novel remained (the two useful Kubernetes snippets were folded into
the routing-peers use case in the previous commit).
- Delete the four pages and their screenshot directory
- Remove the Access Infrastructure nav group
- Redirect each URL to its canonical replacement:
secure-remote-webserver-access -> /manage/peers/ssh
setup-keys-add-servers-to-network -> /manage/peers/register-machines-using-setup-keys
access-internal-resources-from-autoscaled-environments -> /use-cases/kubernetes
peer-approval-for-remote-worker-access -> /manage/peers/approve-peers
- Re-point the legacy /how-to redirects at the same targets to avoid
redirect chains
* docs: reorder Peers nav into enrollment, approval, day-2 flow
Group the five enrollment methods first (Add Peers, Setup Keys,
Bootstrap via Config File, MDM Deployment, Browser Client), then the
Approve Peers admission gate, then running-peer features (SSH, Lazy
Connections, Remote Jobs) and Auto Update last. Approve Peers
previously sat between two enrollment pages.
* docs: cross-link DNS aliases and internal DNS pages, fix tutorial inaccuracies
The two pages solve adjacent problems (NetBird-hosted records vs
forwarding to existing internal DNS) but never pointed at each other.
Add a which-page-do-I-need Note to each.
Also fix defects in the DNS Aliases tutorial found while cross-checking
it against the Custom Zones reference and dashboard source:
- 'Keep this enabled' implied search domain is on by default; it is
off by default (DNSZoneModal.tsx: enable_search_domain ?? false)
- Step 3 said 'wildcard resource' but the steps add exact-name domain
resources
- Wrong alt text ('Delete DNS Zone') on the zone-config screenshot
- Add missing meta description and a link to the Custom Zones
reference
* docs: align MSP portal page with 2026 partner program, rename For Partners nav
Cross-checked the MSP portal page against the 2026 MSP/MSSP Partner
Program document:
- Point the application link at netbird.io/use-cases/msp (the program's
canonical page) instead of a demo-form URL displayed as netbird.io/msp
- State tenant plan options (Team or Business) and the post-trial
minimum (Team plan with one user)
- Mention CSV/PDF usage export alongside the API
- Clarify the 3-day trial for existing accounts brought in as tenants:
it is a window to subscribe the tenant under the MSP account
- Add a subtle msp@netbird.io contact line at the bottom
Also rename the For Partners nav entries by deliverable instead of
audience (the section header already says who it's for): MSP Portal,
Distributor Portal, Deploy with Acronis.
* docs: update CLAUDE.md for agent-network, proxy.js, and tooling gaps
Audited every claim against the current repo. Stack, routing, security,
and convention claims all still hold; four gaps had accumulated:
- Add agent-network/ to the content structure list
- Document src/proxy.js in URL Routing: /api data requests must be
rewritten there because the config rewrite loses data-request context
on client-side navigation (Next.js #39669) and strips pageProps
- Add npm run lint:mdx; note npm run gen requires a Go toolchain
- Note fenced mermaid code blocks render as diagrams
* docs: address review findings on PR #906
- Move the MDM deployment screenshot directories to match the new page
paths; the URL rewrite had updated MDX image references without
moving the assets, breaking all Intune/Jamf/Kandji images
- Normalize pre-existing double slashes in Jamf and Kandji image URLs
- Align the routing-peers secret example with bootstrap-via-config-file
(same secret name, so both now use the NB_SETUP_KEY data key)
- DNS aliases: include the routing peer's group in the zone's
distribution groups. Verified in client source: the DNS route
interceptor (priority 100) outranks local zone records (priority 75)
and never falls through, so clients forward routed-domain queries to
the routing peer, which must receive the zone to answer
|
||
|
PizzaLovingNerd
|
b867aa85c8 | Updates for the NetBird 0.75 update (#881) | ||
|
Riccardo Manfrin
|
accc461a7e |
Add Mdm auto start flag doc (#855)
* MDM disableAutoStart flag * Added note on desktop only mode |
||
|
Riccardo Manfrinandcoderabbitai[bot]
|
59405c5e73 |
Adds doc for Windows/macOS MDM integration (#783)
* Adds doc for Windows/macOS MDM integration * Fixes coderabbit suggestions * Update public/docs-static/files/netbird-policy.reg.ps1 Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Check port and allow/disallow in admitted values for macos script --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> |