Adds doc for Windows/macOS MDM integration#783
Conversation
📝 WalkthroughWalkthroughThe PR introduces a new MDM Integration documentation page accessible from the client documentation navigation. It provides a complete reference for enforcing NetBird client configuration via OS-native MDM on Windows and macOS, including platform-specific delivery methods, verification workflows, and troubleshooting guidance. ChangesMDM Integration Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
src/components/NavigationDocs.jsxOops! Something went wrong! :( ESLint: 9.39.4 TypeError: Converting circular structure to JSON src/pages/client/mdm-integration.mdxOops! Something went wrong! :( ESLint: 9.39.4 TypeError: Converting circular structure to JSON Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/components/NavigationDocs.jsx`:
- Line 749: ESLint is crashing when loading the next/core-web-vitals config due
to a circular structure in the exported config; open eslint.config.mjs and
remove any direct require/import that injects complex module objects into the
exported config (e.g., spreading a require(...) result or exporting non-plain
objects), and instead reference the Next config by name in a plain extends array
(use extends: ['next/core-web-vitals'] or the equivalent flat-config entry) so
the exported default is a simple serializable object; also ensure you aren’t
exporting functions or Next internals and that eslint-config-next /
eslint-plugin-next versions are compatible, then rerun npm run lint to confirm
the crash is resolved.
In `@src/pages/client/mdm-integration.mdx`:
- Around line 119-199: The MDX references to docs assets (netbird.admx,
netbird.adml, netbird-policy.reg, netbird-policy.reg.ps1) are broken in
src/pages/client/mdm-integration.mdx; either add the missing files to the docs/
directory with those exact names or update the links in mdm-integration.mdx to
point to the actual locations (e.g., repo paths that currently contain the
ADMX/ADML and .reg/.ps1 samples); specifically check and fix occurrences of
"docs/netbird.admx", "docs/netbird.adml", "docs/netbird-policy.reg", and
"docs/netbird-policy.reg.ps1" so they resolve to existing files in the repo.
- Around line 221-306: The MDX page src/pages/client/mdm-integration.mdx
references three non-existent template files (docs/netbird-macos.mobileconfig,
docs/io.netbird.client.plist, docs/netbird-macos.sh); either add the missing
template files under docs/ with the expected names and contents, or update the
references in mdm-integration.mdx to point to the actual existing
filenames/paths in the repo (and adjust the JumpCloud instructions to reference
the correct plist name if different); ensure the chosen fix is consistent across
the text (all mentions of netbird-macos.mobileconfig, io.netbird.client.plist,
and netbird-macos.sh) and confirm the site builds with the updated links.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: d0a66cd0-4de3-416a-885d-c6277a484f9e
📒 Files selected for processing (2)
src/components/NavigationDocs.jsxsrc/pages/client/mdm-integration.mdx
| links: [ | ||
| { title: 'Profiles', href: '/client/profiles' }, | ||
| { title: 'Environment Variables', href: '/client/environment-variables' }, | ||
| { title: 'MDM Integration', href: '/client/mdm-integration' }, |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Run ESLint on the modified navigation file
npm run lint -- src/components/NavigationDocs.jsxRepository: netbirdio/docs
Length of output: 2055
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show lint script
echo "## package.json lint script"
cat package.json | sed -n '1,120p' | rg -n '"lint"\s*:'
# List likely eslint config entrypoints
echo "## Possible eslint config files"
ls -la . | rg -i 'eslint|eslintrc|prettier' || true
fd -t f -i '*eslint*' -a 2>/dev/null . || true
fd -t f -i '*eslintrc*' -a 2>/dev/null . || true
fd -t f -i 'eslint.config.*' -a 2>/dev/null . || true
# Print eslint config package versions (package-lock/pnpm-lock may be absent; best-effort)
echo "## eslint/eslintrc versions (if present)"
cat package.json | rg -n 'eslint|eslintrc' || trueRepository: netbirdio/docs
Length of output: 501
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "## package.json (relevant sections)"
cat package.json | sed -n '1,120p'
echo "## eslint.config.mjs (first 200 lines)"
sed -n '1,200p' eslint.config.mjs
echo "## run lint as-script (no extra args)"
npm run lintRepository: netbirdio/docs
Length of output: 5272
🏁 Script executed:
npm run lintRepository: netbirdio/docs
Length of output: 2021
Verify ESLint compliance.
npm run lint (eslint src/) currently fails with ESLint: 9.39.4 and TypeError: Converting circular structure to JSON while loading next/core-web-vitals from eslint.config.mjs, so linting can’t be used to confirm this change is clean. Fix the ESLint config/tooling crash, then rerun npm run lint.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/components/NavigationDocs.jsx` at line 749, ESLint is crashing when
loading the next/core-web-vitals config due to a circular structure in the
exported config; open eslint.config.mjs and remove any direct require/import
that injects complex module objects into the exported config (e.g., spreading a
require(...) result or exporting non-plain objects), and instead reference the
Next config by name in a plain extends array (use extends:
['next/core-web-vitals'] or the equivalent flat-config entry) so the exported
default is a simple serializable object; also ensure you aren’t exporting
functions or Next internals and that eslint-config-next / eslint-plugin-next
versions are compatible, then rerun npm run lint to confirm the crash is
resolved.
Source: Coding guidelines
| ### Group Policy (on-prem AD / local gpedit) | ||
|
|
||
| 1. Copy the ADMX/ADML files into the system Policy Definitions store: | ||
| - Place `netbird.admx` in `C:\Windows\PolicyDefinitions\`. | ||
| - Place `netbird.adml` in `C:\Windows\PolicyDefinitions\en-US\`. | ||
| 2. Open `gpedit.msc` (or the AD Group Policy Management Editor). | ||
| 3. Navigate to **Computer Configuration → Administrative Templates → | ||
| NetBird**. | ||
| 4. Edit any policy (e.g. **Management URL**), set it to **Enabled** | ||
| with the desired value, and click **OK**. | ||
| 5. Run `gpupdate /force` on each target device (or wait for the | ||
| periodic refresh). | ||
| 6. Verify with `reg query HKLM\Software\Policies\NetBird` — the values | ||
| you set should appear there. | ||
|
|
||
| The ADMX template is shipped in the NetBird repo at | ||
| `docs/netbird.admx` / `docs/netbird.adml`. | ||
|
|
||
| ### Microsoft Intune (ADMX ingestion) | ||
|
|
||
| Recommended for cloud-managed Windows fleets. | ||
|
|
||
| 1. In the Intune admin center, go to **Devices → Configuration → Import | ||
| ADMX**, upload `netbird.admx` together with `netbird.adml`. Wait for | ||
| the **Available** status. | ||
| 2. Create a new **Configuration Profile → Templates → Imported | ||
| Administrative templates → NetBird**. | ||
| 3. Configure the policies you want to enforce. | ||
| 4. Assign the profile to your device group(s) and save. | ||
|
|
||
| Devices pick up the policy on the next Intune sync (typically within | ||
| 8 hours, sooner if you trigger a manual sync from the device). The | ||
| values end up in `HKLM\Software\Policies\NetBird`. | ||
|
|
||
| ### Microsoft Intune (custom OMA-URI) | ||
|
|
||
| If you cannot ingest the ADMX template, you can push individual values | ||
| via OMA-URI under | ||
| `./Device/Vendor/MSFT/Policy/ConfigOperations/ADMXInstall/...` or via | ||
| the Registry CSP at | ||
| `./Device/Vendor/MSFT/Registry/HKEY_LOCAL_MACHINE/Software/Policies/NetBird/<ValueName>`. | ||
| ADMX ingestion is simpler and gives admins the same UI as on-prem GPO, | ||
| so prefer that. | ||
|
|
||
| ### `.reg` import (single source of truth) | ||
|
|
||
| For fleets without an MDM, or as a quick-test path, you can carry the | ||
| whole policy in a single `.reg` file: | ||
|
|
||
| 1. Configure the policy values on a reference machine (via `gpedit` or | ||
| `reg add`). | ||
| 2. Export the key: | ||
| ``` | ||
| reg export "HKLM\Software\Policies\NetBird" netbird-policy.reg /y | ||
| ``` | ||
| 3. Distribute the resulting file and apply with: | ||
| ``` | ||
| reg import netbird-policy.reg | ||
| ``` | ||
|
|
||
| A sample is in the NetBird repo at `docs/netbird-policy.reg`. | ||
|
|
||
| ### JumpCloud | ||
|
|
||
| NetBird ships a JumpCloud companion script at | ||
| `docs/netbird-policy.reg.ps1`. To use it: | ||
|
|
||
| 1. In the JumpCloud admin console, go to **Device Management → | ||
| Commands → +**. | ||
| 2. Type: **Windows PowerShell**. Run as: **SYSTEM**. | ||
| 3. Paste `netbird-policy.reg.ps1` verbatim into the command body. | ||
| 4. In the same command, attach the `netbird-policy.reg` file you | ||
| produced above. JumpCloud copies attached files into the command's | ||
| working directory before invoking the script. | ||
| 5. Bind the command to the target system group and run it. | ||
|
|
||
| The script wipes the existing `HKLM\Software\Policies\NetBird` key | ||
| before importing the `.reg`, so the `.reg` is the **single source of | ||
| truth** for that device. To unset all policy, attach an empty (header- | ||
| only) `.reg`; the daemon will pick up the absence on the next reload. | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify that the referenced Windows documentation files exist
echo "Checking for Windows MDM documentation files..."
for file in "docs/netbird.admx" "docs/netbird.adml" "docs/netbird-policy.reg" "docs/netbird-policy.reg.ps1"; do
if [ -f "$file" ]; then
echo "✓ Found: $file"
else
echo "✗ Missing: $file"
fi
doneRepository: netbirdio/docs
Length of output: 238
🏁 Script executed:
#!/bin/bash
# Search for the referenced files anywhere in the repo (in case they moved under different paths)
echo "Searching for referenced Windows MDM documentation files by name..."
for name in "netbird.admx" "netbird.adml" "netbird-policy.reg" "netbird-policy.reg.ps1"; do
echo "---- $name ----"
fd -a "$name" . || true
doneRepository: netbirdio/docs
Length of output: 234
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Checking under docs/ for similarly-named files..."
find . -type f \( \
-iname "*netbird*.admx*" -o \
-iname "*netbird*.adml*" -o \
-iname "*netbird*policy*.reg*" -o \
-iname "*netbird*policy*.ps1*" \
\) | sed 's|^\./||' | sort
echo
echo "Exact-path checks (as referenced in MDX):"
for file in "docs/netbird.admx" "docs/netbird.adml" "docs/netbird-policy.reg" "docs/netbird-policy.reg.ps1"; do
if [ -f "$file" ]; then
echo "✓ Found: $file"
else
echo "✗ Missing: $file"
fi
doneRepository: netbirdio/docs
Length of output: 283
Fix broken file references in mdm-integration.mdx (missing docs/ assets)
All referenced files are missing from the repository at the stated locations: docs/netbird.admx, docs/netbird.adml, docs/netbird-policy.reg, docs/netbird-policy.reg.ps1 (no similarly-named matches found under docs/). Update the links to the correct paths or add the referenced files.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/client/mdm-integration.mdx` around lines 119 - 199, The MDX
references to docs assets (netbird.admx, netbird.adml, netbird-policy.reg,
netbird-policy.reg.ps1) are broken in src/pages/client/mdm-integration.mdx;
either add the missing files to the docs/ directory with those exact names or
update the links in mdm-integration.mdx to point to the actual locations (e.g.,
repo paths that currently contain the ADMX/ADML and .reg/.ps1 samples);
specifically check and fix occurrences of "docs/netbird.admx",
"docs/netbird.adml", "docs/netbird-policy.reg", and
"docs/netbird-policy.reg.ps1" so they resolve to existing files in the repo.
| 1. Start from the template at `docs/netbird-macos.mobileconfig` in the | ||
| NetBird repo. Open it in your editor (or in | ||
| [iMazing Profile Editor](https://imazing.com/profile-editor) / | ||
| [ProfileCreator](https://github.com/ProfileCreator/ProfileCreator)). | ||
| 2. Inside the `mcx_preference_settings` dictionary, set the keys you | ||
| want to enforce. Keep the bundle id `io.netbird.client` as the | ||
| preference domain. | ||
| 3. Replace the placeholder `PayloadUUID` values with freshly generated | ||
| UUIDs (`uuidgen` on macOS) so each deployment has unique ids. | ||
| 4. (Optional, recommended for production) sign the profile with your | ||
| organization's Developer ID Installer certificate using | ||
| `productsign` — unsigned profiles on Sonoma/Sequoia/Tahoe require | ||
| an extra user confirmation on install. | ||
| 5. Upload the resulting `.mobileconfig` to your MDM as a **Custom | ||
| Configuration Profile** and scope it to the target device group. | ||
|
|
||
| Verify on a target device with: | ||
|
|
||
| ```bash | ||
| sudo defaults read "/Library/Managed Preferences/io.netbird.client" | ||
| ``` | ||
|
|
||
| The output should match the keys you set in the profile. | ||
|
|
||
| ### MDM-specific notes | ||
|
|
||
| - **Jamf Pro**: upload as **Computers → Configuration Profiles → New → | ||
| Application & Custom Settings → External Applications → Upload File | ||
| (Plist file)** for the preference domain `io.netbird.client`. | ||
| - **Kandji**: use the **Custom Profile** assignment library item. | ||
| - **Mosyle**: **Profiles → Add new profile → Custom Settings** with | ||
| domain `io.netbird.client`. | ||
| - **Microsoft Intune (for Mac)**: **Devices → Configuration → Create | ||
| profile → macOS → Templates → Custom**, upload the `.mobileconfig`. | ||
| - **Apple Configurator 2** (no MDM, ideal for testing on a tethered | ||
| device): drag the `.mobileconfig` onto the device in Configurator and | ||
| push. | ||
|
|
||
| ### JumpCloud | ||
|
|
||
| JumpCloud supports two delivery channels for the NetBird policy on | ||
| macOS. Pick whichever fits how your fleet is enrolled. | ||
|
|
||
| #### MDM Custom Configuration Profile (recommended for MDM-enrolled fleets) | ||
|
|
||
| If your Macs are MDM-enrolled with JumpCloud, push the policy as a | ||
| managed-preferences plist: | ||
|
|
||
| 1. In the JumpCloud admin console, open **Policy Management → | ||
| Policies → +** and choose the **Mac** platform. | ||
| 2. Pick the **MDM Custom Configuration Profile** policy template. | ||
| 3. Upload `docs/io.netbird.client.plist` from the NetBird repository | ||
| as the plist payload. Edit the file before upload to enable just | ||
| the keys you want to enforce — leave the rest commented out. | ||
| 4. Bind the policy to the target Device Group and save. | ||
|
|
||
| Notes: | ||
|
|
||
| - JumpCloud's **MDM Custom Configuration Profile** accepts a bare | ||
| managed-preferences plist (the inner Apple managed-prefs dictionary) | ||
| — **not** a full `.mobileconfig` envelope. Uploading | ||
| `netbird-macos.mobileconfig` will be rejected. Use the bare | ||
| `io.netbird.client.plist` for this code path; reserve | ||
| `netbird-macos.mobileconfig` for other MDMs that expect the full | ||
| Configuration Profile shape. | ||
| - Keep the filename as `io.netbird.client.plist`. The Apple | ||
| convention for managed-preferences plists is | ||
| `<bundle.id>.plist` (this is how macOS materializes the file at | ||
| `/Library/Managed Preferences/<bundle.id>.plist`), and JumpCloud's | ||
| policy form does not currently expose a separate bundle-identifier | ||
| field — keeping the canonical filename is the safest path. If your | ||
| JumpCloud console version surfaces a bundle-id / preference-domain | ||
| field elsewhere in the policy wizard, set it to `io.netbird.client` | ||
| too. | ||
|
|
||
| JumpCloud wraps the plist into an Apple Configuration Profile and | ||
| pushes it via the MDM channel. The OS materializes the file at | ||
| `/Library/Managed Preferences/io.netbird.client.plist`, where the | ||
| NetBird daemon picks it up within the next 1-minute reload tick. | ||
| Removing the policy from JumpCloud removes the file on the next sync, | ||
| which un-locks the corresponding fields on the client. | ||
|
|
||
| #### Shell Command (no MDM enrollment required) | ||
|
|
||
| If your fleet is JumpCloud-managed but not MDM-enrolled, NetBird ships | ||
| a companion script at `docs/netbird-macos.sh`. It is the macOS |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify that the referenced macOS documentation files exist
echo "Checking for macOS MDM documentation files..."
for file in "docs/netbird-macos.mobileconfig" "docs/io.netbird.client.plist" "docs/netbird-macos.sh"; do
if [ -f "$file" ]; then
echo "✓ Found: $file"
else
echo "✗ Missing: $file"
fi
doneRepository: netbirdio/docs
Length of output: 220
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Locating referenced files by name (any path)..."
for f in "netbird-macos.mobileconfig" "io.netbird.client.plist" "netbird-macos.sh"; do
echo "---- $f ----"
fd -a "$f" . || true
done
echo
echo "Checking for likely folder under docs/ that contains macOS MDM templates..."
ls -la docs || trueRepository: netbirdio/docs
Length of output: 454
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Searching entire repo for the referenced filenames (any path)..."
rg -n --hidden --no-ignore-vcs -S --files | rg -i 'netbird-macos\.mobileconfig|io\.netbird\.client\.plist|netbird-macos\.sh' || true
echo
echo "Searching for likely related patterns..."
rg -n --hidden --no-ignore-vcs -S --files | rg -i 'netbird-macos|managed preferences|io\.netbird\.client' || true
echo
echo "Listing contents of docs/integrations..."
ls -Rla docs/integrations || trueRepository: netbirdio/docs
Length of output: 888
Fix broken macOS template references in src/pages/client/mdm-integration.mdx
The MDX instructions reference the following files under docs/, but none of them exist in this repository:
docs/netbird-macos.mobileconfigdocs/io.netbird.client.plistdocs/netbird-macos.sh
Add these templates to the repo or update the MDX steps to point to the correct existing paths.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/client/mdm-integration.mdx` around lines 221 - 306, The MDX page
src/pages/client/mdm-integration.mdx references three non-existent template
files (docs/netbird-macos.mobileconfig, docs/io.netbird.client.plist,
docs/netbird-macos.sh); either add the missing template files under docs/ with
the expected names and contents, or update the references in mdm-integration.mdx
to point to the actual existing filenames/paths in the repo (and adjust the
JumpCloud instructions to reference the correct plist name if different); ensure
the chosen fix is consistent across the text (all mentions of
netbird-macos.mobileconfig, io.netbird.client.plist, and netbird-macos.sh) and
confirm the site builds with the updated links.
1 participant
Summary by CodeRabbit