sendnrw/netbird
2
0
Fork 0
mirror of https://github.com/netbirdio/netbird.git synced 2026-07-20 15:31:30 +02:00
Code Issues Packages Projects Releases Wiki Activity

[client] add MDM configuration profile support (Windows registry + macOS plist) (#6374)

Browse Source 
* Initial scaffolding

* Applies MDM override

* Unit tests

* Helpers business logic

* Return error if trying to modify any config that is gated by MDM

* Add ManagedFields to returned config over GetConfig

* Adds initial 101 MDM policy business logic testing

* gRPC MDM changes

* MDM Name scoping for clarity

* Implements windows loading of MDM policy

* Adds missing WGPort config

* Cleanup setupKey to align to linear

* Align split tunnel code

* Adds some log

* Prefix every log with MDM

* Adds debug config cobra command

This can be useful for troubleshooting and checking config
now that its resolution is not trivial

defaults > config > env cars > CLI/UI > MDM

* Adds MDM 1m diff checker & reloader

* Adds also up/start after cancel

* Publishes event for UI to sync upon MDM changes

* Add events to resync UI to actual config

This also provide fixup for UI no aligning to changed config when coming from cli up with config flags.

* UI behavior conflicts relaxation

UI sends full config snapshot with all values. It doesn't
make sense to block it if the values are aligned with the
values constrained by the MDM policy. It's just simplier
to allow values that are compliant. (this goes for the CLI
as well at this point)

* Lock toggle Settngs

* Advanced Settings locking

* Fixup presharedkey

* Apply MDM locks

* Toggle gray in/out for Advanced Settings

* Adds support for disabling of Profiles and UpdateSettings feature flags

* Adds Gate Login as well when --disable-update-settings=true is given to service

This commit tries to settle things with an old PR-4237 which had relaxed
the case where the SetConfig returned an `Unavailable` code error.

Under this circumnstance the PR allowed the upFunc to just emit a warning and
progress further with the login gRPC. Since the login call is consuming
the --management-url coming from the `up` command, it might be possible
to abuse the "Unavailable" code to inject a management URL that is different
from the configured one even though the --disable-update-settings is set
to true (?)

* Evaluate disable-update-settings errors only when there's an actual override

* [UI] Fixup advanced Settings

* [UI] Fixup for preshared key

* [UI] Fixup for profile enable/disable toggle

We need to align the initial state to evaluate the delta in case.

The initial state has to be "true" since the profile starts visible.
Then we receive MDM and transition the cache bool value to the actual
MDM imposed state

* Enforces disable networks

* [UI] Aligns to "enable/disable once on change only"

* Fixup: MDM wins. always

* Removes --disable-advanced-settings

It was a typo in our meetings. the actual thing is --disable-update-settings

* [PROTO] Removes --disable-advanced-settings

* [UI] Removes --disable-advanced-settings

* Pins feat profile retrieval to notif event

* [UI] Fix for "hide" not working when propagating to parent with children

* Adds dep for reading plist files

* Introduces support for darwing plist loading

* Tests MDM config reload via ticker

* [PROVISIONING] ADMX/ADML/PS/bash scripts/templates

* CI fixes

- Add docstrings to `mdm_integration`
- refactor for cognitive complexity
- mod tidy

* Linting

* Add docstrings to `mdm_integration`

* nil,nil is no policy and no error. Allow it

* nil,nil is no policy and no error. Allow it

* exclude MDM profile adminstrated keys data from debug bundle

* Fixes Rosenpass left disable after MDM unlock

* Partial revert coderabbit added docstrings

* Renaming fix

* Avoid locking on clientRunning bool when the connection is aborted for whatever reason

We want to just signal this through the giveUpChan, we will manage the signal from
the waiter side and in case set it to false there. THis way we avoid locking,
which should allow the MDM down+wait_for_term_chan_signal_+up procedure

clientRunning is used to signal two different conditions here:

1. the initialization procedure is over (we have an engine)
2. the connection being up (or being attempted)

Probably these two functionalities should not alias, and the failure of the second condition
(because of any error) should just drive a reconnection (currently it's not happening,
and we silently go idle).
OR, mor probably, the two things are the SAME and there should not exist a case where
we did the "Up" initialization and connection attempt but we are not still attempting it.

* Moves test helper at te very bottom

* Addresses github comments

* No lock no copy

* Prevents engine not stopping within 10 secs from being paired by another instance

We instead juts SKIP updating the policy, so
1. the MDM ticker will kick in 1 minute time,
2. find the policy misaligned,
3. enter the onMDMPolicyChange,
4. find the s.clientRunning == true
   (because it is set to false only in server cleanupConnection,
   and not by s.actCancel())
5. call s.actCancel() again if not nil
6. immediately return from <-s.clientGiveUpChan
7. finally call s.restartEngineForMDMLocked()

* Since we ARE running there should be a config

If the config was cancelled midflight, connect will abort later on

* DisableAutoConnect should not stop a running connection.

DisableAutoConnect should just avoid the connection attempts *when the service starts*.
If we are started and we are up and running, DisableAutoConnect should not kick in.

Another PR will follow about this topic

* Removes unused vars

* Moves callback into Run method arg

* align comment to removal of DisableAutoConnect

DisableAutoConnect should just avoid the connection attempts *when the service starts*.
If we are started and we are up and running, DisableAutoConnect should not kick in

* Removes unused managed_fields data.

This was initially used to drive the UI but approach changed
to reload config/features upon notifications which makes this data redundant.

* Reorder stuff

* Unexport unrequired vars/functions

PoliciesEqual → policiesEqual
AllKeys → allKeys

* Adds list of MDM managed fields in the debug bundle
This commit is contained in:
Riccardo Manfrin
2026-06-12 12:28:49 +02:00
committed by GitHub
parent 8ff3b06cf1
commit 2bcea9d582
33 changed files with 3476 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
docs/io.netbird.client.plist Normal file
View File

@@ -0,0 +1,126 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!--
NetBird MDM preferences (macOS) — bare plist for MDM platforms that
accept a managed-preferences plist tied to a bundle identifier
(e.g. JumpCloud "Mac Application Custom Settings", Mosyle "Custom
Settings", Jamf "Application & Custom Settings" → External
Application).
Bundle identifier (preference domain): io.netbird.client
The MDM provider will wrap this plist into a Configuration Profile
payload of type com.apple.ManagedClient.preferences and push it to
target devices via the Apple MDM protocol. The OS materializes the
final file at:
/Library/Managed Preferences/io.netbird.client.plist
which is what the NetBird daemon's client/mdm/policy_darwin.go
loader reads on every 1-minute MDM reload tick.
For MDM platforms that expect a full Configuration Profile instead
of a bare plist (Custom Configuration Profile / .mobileconfig upload),
use docs/netbird-macos.mobileconfig — same keys, additional Payload*
envelope.
Editing this file:
- Remove or comment out any key you do NOT want to enforce. The
daemon treats an absent key as "no enforcement" for that field.
- Keep the document well-formed XML. Validate locally with:
plutil -lint docs/io.netbird.client.plist
- Keys are camelCase; values are typed (<string>, <true/>, <false/>,
<integer>). See docs/src/pages/client/mdm-integration.mdx (the
public docs page) for the full reference.
Persistence caveat:
macOS wipes /Library/Managed Preferences/ at every boot on
devices that are NOT MDM-enrolled. This plist only sticks across
reboots when delivered through a real MDM channel. For local
testing on an un-enrolled host, write the file manually as root
and accept it will not survive the next boot.
-->
<plist version="1.0">
<dict>
<!-- ===== Identity / auth ===== -->
<key>managementURL</key>
<string>https://api.netbird.io:443</string>
<!--
Pre-shared key: secret. Remove the entry entirely when not used;
do NOT leave an empty <string></string>, which the daemon would
otherwise treat as a deliberate empty-PSK enforcement.
-->
<!--
<key>preSharedKey</key>
<string>REPLACE_ME</string>
-->
<!-- ===== Engine / runtime behavior =====
Each key is optional. Remove or comment out to leave the
field unmanaged on the client. -->
<key>allowServerSSH</key>
<true/>
<!--
<key>disableAutoConnect</key>
<false/>
<key>disableClientRoutes</key>
<false/>
<key>disableServerRoutes</key>
<false/>
<key>blockInbound</key>
<false/>
<key>rosenpassEnabled</key>
<true/>
<key>rosenpassPermissive</key>
<false/>
-->
<!-- ===== WireGuard UDP port =====
Range 1-65535. Omit to keep the daemon default. -->
<!--
<key>wireguardPort</key>
<integer>51820</integer>
-->
<!-- ===== UI / lockdown kill switches =====
disableUpdateSettings : block every config change from UI and CLI
on this device (Settings view stays
readable but read-only).
disableProfiles : hide the profile menu, reject profile CRUD.
disableNetworks : hide the Networks / Exit Node menus,
reject the related RPCs.
disableMetricsCollection: opt out of anonymous usage telemetry. -->
<!--
<key>disableUpdateSettings</key>
<true/>
<key>disableProfiles</key>
<true/>
<key>disableNetworks</key>
<true/>
<key>disableMetricsCollection</key>
<false/>
-->
<!-- ===== Split tunnel =====
Android-only at the client level. Safe to ship on macOS for
mixed-platform fleets; the macOS daemon parses and ignores. -->
<!--
<key>splitTunnelMode</key>
<string>allow</string>
<key>splitTunnelApps</key>
<string>com.acme.app1,com.acme.app2</string>
-->
</dict>
</plist>

159
docs/netbird-macos.mobileconfig Normal file
View File

@@ -0,0 +1,159 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<!--
NetBird MDM configuration profile (macOS).
Wraps a `com.apple.ManagedClient.preferences` payload that pushes the
NetBird MDM policy into:
/Library/Managed Preferences/io.netbird.client.plist
Read at runtime by the netbird daemon's macOS loader
(client/mdm/policy_darwin.go — Phase 2). Key names match the canonical
lowerCamelCase form used in docs/netbird.admx and the mdm.Key*
constants in client/mdm/policy.go.
Bundle identifier: io.netbird.client
(confirm against the signed pkg before fleet roll-out)
Distribution:
- sign with `productsign --sign "Developer ID Installer: ..." ...`
before fleet roll-out (Apple-Configurator-2 won't install an
unsigned profile on Sonoma+ without user override).
- For local dev install: `sudo profiles install -path netbird-macos.mobileconfig`.
- For MDM (Jamf/Kandji/Mosyle/Intune): upload as a Custom Profile.
Editing:
- Replace UUID placeholders below with fresh UUIDs (`uuidgen` on
macOS) when forking this template for a real fleet — each
deployment should have unique UUIDs so the OS treats it as a
distinct profile.
- Tune the PayloadContent values to the policy you want to enforce.
- Remove any key you do NOT want to enforce (the daemon treats an
absent key as "no enforcement" for that field).
iOS note:
This file is macOS-specific. iOS uses managed app config via
UserDefaults[com.apple.configuration.managed] under a different
payload type (com.apple.app.configuration.managed); the wrapper
structure is the same but the inner payload dictionary differs.
See docs/netbird-ios.mobileconfig (Phase 5) when shipped.
-->
<plist version="1.0">
<dict>
<!-- Outer profile envelope -->
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>PayloadIdentifier</key>
<string>io.netbird.client.mdm</string>
<key>PayloadUUID</key>
<string>11111111-1111-1111-1111-111111111111</string>
<key>PayloadDisplayName</key>
<string>NetBird MDM Policy</string>
<key>PayloadDescription</key>
<string>Enforces NetBird client configuration. Values written here override any local user / CLI / on-disk setting and are re-applied at every daemon boot and on every 1-minute MDM reload tick.</string>
<key>PayloadOrganization</key>
<string>NetBird</string>
<key>PayloadScope</key>
<string>System</string>
<key>PayloadRemovalDisallowed</key>
<false/>
<key>PayloadContent</key>
<array>
<dict>
<!-- Managed preferences payload: writes /Library/Managed Preferences/io.netbird.client.plist -->
<key>PayloadType</key>
<string>com.apple.ManagedClient.preferences</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>PayloadIdentifier</key>
<string>io.netbird.client.mdm.preferences</string>
<key>PayloadUUID</key>
<string>22222222-2222-2222-2222-222222222222</string>
<key>PayloadDisplayName</key>
<string>NetBird Managed Preferences</string>
<key>PayloadEnabled</key>
<true/>
<key>PayloadContent</key>
<dict>
<key>io.netbird.client</key>
<dict>
<key>Forced</key>
<array>
<dict>
<key>mcx_preference_settings</key>
<dict>
<!-- ===== Identity / auth (strings) ===== -->
<key>managementURL</key>
<string>https://api.netbird.io:443</string>
<!-- Pre-shared key: secret. Remove the entry entirely
when not used; do NOT leave an empty string. -->
<!--
<key>preSharedKey</key>
<string>REPLACE_ME</string>
-->
<!-- ===== Engine / runtime behavior (bool) =====
Remove any key to leave the field unmanaged. -->
<!--
<key>disableAutoConnect</key>
<false/>
<key>disableClientRoutes</key>
<false/>
<key>disableServerRoutes</key>
<false/>
<key>blockInbound</key>
<false/>
-->
<key>allowServerSSH</key>
<true/>
<!--
<key>rosenpassEnabled</key>
<true/>
<key>rosenpassPermissive</key>
<false/>
-->
<!-- ===== WireGuard UDP port (int) =====
Range 1-65535. Omit to keep the default. -->
<!--
<key>wireguardPort</key>
<integer>51820</integer>
-->
<!-- ===== Split tunnel (Android-only at the daemon level)
Pushed harmlessly on macOS for fleets with mixed
desktop+mobile devices; the macOS daemon ignores it. -->
<!--
<key>splitTunnelMode</key>
<string>allow</string>
<key>splitTunnelApps</key>
<string>com.acme.app1,com.acme.app2</string>
-->
<!-- ===== UI / kill switches (bool) ===== -->
<!--
<key>disableUpdateSettings</key>
<true/>
<key>disableProfiles</key>
<true/>
<key>disableNetworks</key>
<true/>
<key>disableMetricsCollection</key>
<false/>
-->
</dict>
</dict>
</array>
</dict>
</dict>
</dict>
</array>
</dict>
</plist>

189
docs/netbird-macos.sh Normal file
View File

@@ -0,0 +1,189 @@
#!/bin/bash
#
# SYNOPSIS
# Push the NetBird MDM policy to a macOS device via JumpCloud Commands.
#
# DESCRIPTION
# This is the macOS counterpart of docs/netbird-policy.reg.ps1.
# It writes the values declared in the "POLICY VALUES" block below to
# the managed-preferences plist that the NetBird daemon's
# client/mdm/policy_darwin.go loader reads on every 1-minute MDM
# reload tick:
#
# /Library/Managed Preferences/io.netbird.client.plist
#
# Once the plist lands, the daemon picks up the new values without
# restart (the ticker calls Config.apply() → applyMDMPolicy() and
# restarts the engine on diff).
#
# DEPLOYMENT (JumpCloud)
# 1. Admin Console -> Device Management -> Commands -> +.
# 2. Type: Mac, Shell, Run as: root.
# 3. Paste this file verbatim into the command body.
# 4. Bind to the target system group, save, run.
#
# IMPORTANT: PERSISTENCE
# macOS wipes /Library/Managed Preferences/ at every boot on devices
# that are NOT MDM-enrolled. For a persistent fleet rollout, push the
# companion docs/netbird-macos.mobileconfig as a Custom Configuration
# Profile (Admin Console -> MDM -> Mac Custom Configuration Profiles)
# instead of this script. Use this script when:
# - the device is MDM-enrolled (file survives reboots), or
# - you need a one-shot test push before reboot, or
# - you orchestrate via JumpCloud Commands and want the same
# variable-driven workflow as the Windows .ps1 sibling.
#
# IDEMPOTENCY: re-running with the same values is a no-op from the
# daemon's point of view (the 1-minute reload ticker diff returns empty).
#
# SECURITY: PreSharedKey is redacted in this script's log output.
set -euo pipefail
### POLICY VALUES — EDIT THIS BLOCK ###########################################
#
# Set each variable below to the desired value. Set to empty string ""
# or to NULL to omit a key entirely (the daemon treats an absent key
# as "no enforcement" for that field). Booleans use "true"/"false"
# (lowercase). Integers as decimal.
#
# Reference for key names + accepted values:
# client/mdm/policy.go (Key* constants)
# docs/netbird-macos.mobileconfig (sample profile)
# docs/netbird.admx + .adml (Windows ADMX schema)
#
NULL='__UNSET__'
managementURL='https://api.netbird.io:443'
preSharedKey="$NULL" # secret; redacted in log
allowServerSSH='true'
blockInbound="$NULL"
disableAutoConnect="$NULL"
disableClientRoutes="$NULL"
disableServerRoutes="$NULL"
disableMetricsCollection="$NULL"
disableUpdateSettings="$NULL"
disableProfiles="$NULL"
disableNetworks="$NULL"
rosenpassEnabled="$NULL"
rosenpassPermissive="$NULL"
wireguardPort='51820'
splitTunnelMode="$NULL" # "allow" or "disallow", Android-only at the daemon level
splitTunnelApps="$NULL" # comma-separated app IDs, Android-only
##############################################################################
readonly PLIST_DIR='/Library/Managed Preferences'
readonly PLIST_PATH="$PLIST_DIR/io.netbird.client.plist"
readonly LOG_TAG='netbird-mdm'
# log sends a message to the system logger using the configured tag and echoes the message to stdout prefixed by an ISO 8601 UTC timestamp and the tag.
log() {
/usr/bin/logger -t "$LOG_TAG" "$*"
printf '%s [%s] %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$LOG_TAG" "$*"
}
# is_set returns success if the provided value is non-empty and is not equal to the special NULL marker.
is_set() {
local value="$1"
[[ -n "$value" && "$value" != "$NULL" ]]
}
# start_plist creates the temporary plist file at "$PLIST_PATH.tmp" containing the XML plist header and opening `<dict>` for the policy plist.
start_plist() {
cat > "$PLIST_PATH.tmp" <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
EOF
}
# end_plist appends the closing `</dict>` and `</plist>` tags to the temporary plist file.
end_plist() {
cat >> "$PLIST_PATH.tmp" <<'EOF'
</dict>
</plist>
EOF
}
# emit_string appends a plist `<key>`/`<string>` entry for the given key and value to "$PLIST_PATH.tmp", XML-escaping `&`, `<`, and `>`, and logs the assignment (masking the logged value as `********** (secret)` when the key is `preSharedKey`).
emit_string() {
local key="$1" value="$2" log_value="$2"
# Escape XML entities in the value
local escaped
escaped="$(printf '%s' "$value" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g')"
printf ' <key>%s</key>\n <string>%s</string>\n' "$key" "$escaped" >> "$PLIST_PATH.tmp"
if [[ "$key" == "preSharedKey" ]]; then
log_value='********** (secret)'
fi
log "set $key = $log_value"
}
# emit_bool writes a boolean plist entry for a given key into the temporary plist file.
# emit_bool writes a boolean plist entry for a key when the provided value matches an accepted boolean token; logs an error and skips the key on invalid input.
emit_bool() {
local key="$1" value="$2"
local xml_bool
case "$value" in
true|True|TRUE|1|yes) xml_bool='<true/>' ; value='true' ;;
false|False|FALSE|0|no) xml_bool='<false/>' ; value='false' ;;
*) log "invalid boolean for $key: $value (must be true/false); skipping"; return ;;
esac
printf ' <key>%s</key>\n %s\n' "$key" "$xml_bool" >> "$PLIST_PATH.tmp"
log "set $key = $value"
}
# emit_int validates that VALUE contains only decimal digits and, if valid, appends an `<integer>` plist entry for KEY to the temporary plist (`$PLIST_PATH.tmp`) and logs the assignment; on invalid input it logs a skip and does not emit the key.
emit_int() {
local key="$1" value="$2"
if ! [[ "$value" =~ ^[0-9]+$ ]]; then
log "invalid integer for $key: $value (must be decimal); skipping"
return
fi
printf ' <key>%s</key>\n <integer>%s</integer>\n' "$key" "$value" >> "$PLIST_PATH.tmp"
log "set $key = $value"
}
# main builds the NetBird MDM plist from configured policy variables, validates and installs it to /Library/Managed Preferences/io.netbird.client.plist (root:wheel, 644) and optionally triggers the NetBird daemon to reload.
main() {
log "applying NetBird MDM policy to $PLIST_PATH"
/bin/mkdir -p "$PLIST_DIR"
start_plist
is_set "$managementURL" && emit_string managementURL "$managementURL"
is_set "$preSharedKey" && emit_string preSharedKey "$preSharedKey"
is_set "$allowServerSSH" && emit_bool allowServerSSH "$allowServerSSH"
is_set "$blockInbound" && emit_bool blockInbound "$blockInbound"
is_set "$disableAutoConnect" && emit_bool disableAutoConnect "$disableAutoConnect"
is_set "$disableClientRoutes" && emit_bool disableClientRoutes "$disableClientRoutes"
is_set "$disableServerRoutes" && emit_bool disableServerRoutes "$disableServerRoutes"
is_set "$disableMetricsCollection" && emit_bool disableMetricsCollection "$disableMetricsCollection"
is_set "$disableUpdateSettings" && emit_bool disableUpdateSettings "$disableUpdateSettings"
is_set "$disableProfiles" && emit_bool disableProfiles "$disableProfiles"
is_set "$disableNetworks" && emit_bool disableNetworks "$disableNetworks"
is_set "$rosenpassEnabled" && emit_bool rosenpassEnabled "$rosenpassEnabled"
is_set "$rosenpassPermissive" && emit_bool rosenpassPermissive "$rosenpassPermissive"
is_set "$wireguardPort" && emit_int wireguardPort "$wireguardPort"
is_set "$splitTunnelMode" && emit_string splitTunnelMode "$splitTunnelMode"
is_set "$splitTunnelApps" && emit_string splitTunnelApps "$splitTunnelApps"
end_plist
if ! /usr/bin/plutil -lint "$PLIST_PATH.tmp" >/dev/null 2>&1; then
log "ERROR: generated plist failed plutil lint; not installing"
/usr/bin/plutil -lint "$PLIST_PATH.tmp" >&2 || true
/bin/rm -f "$PLIST_PATH.tmp"
exit 1
fi
/bin/mv -f "$PLIST_PATH.tmp" "$PLIST_PATH"
/usr/sbin/chown root:wheel "$PLIST_PATH"
/bin/chmod 644 "$PLIST_PATH"
log "policy installed; NetBird daemon will pick it up within the next 1-minute reload tick"
# Optional: kick the daemon for an immediate apply. Safe — does
# nothing on a host where NetBird is not yet installed.
/bin/launchctl kickstart -k system/io.netbird.client 2>/dev/null || true
}
main "$@"

BIN
docs/netbird-policy.reg Normal file
View File

Binary file not shown.

94
docs/netbird-policy.reg.ps1 Normal file
View File

@@ -0,0 +1,94 @@
#requires -Version 5.1
<#
.SYNOPSIS
Push the NetBird MDM policy to a Windows device via JumpCloud Commands
by importing a sidecar netbird-policy.reg file.
.DESCRIPTION
Windows counterpart of docs/netbird-macos.sh. Outcome:
HKLM\Software\Policies\NetBird populated from the attached
netbird-policy.reg file, daemon picks up the change via the
1-minute MDM reload ticker.
Deployment:
1. Admin Console -> Device Management -> Commands -> +.
2. Type: Windows PowerShell. Run as: SYSTEM.
3. Paste this file verbatim into the command body.
4. In the same command, attach `netbird-policy.reg` as a file.
JumpCloud copies attached files into the command's working
directory before invoking the script, so `$PSScriptRoot` or
Get-Location resolves to where the .reg lives.
5. Bind to the target system group, save, run.
Producing the .reg file:
On a reference machine, after configuring the policy values either
via gpedit (GPO) or manual `reg add`, export with:
reg export "HKLM\Software\Policies\NetBird" netbird-policy.reg /y
Then attach the resulting file to the JumpCloud command.
Semantics:
- The script nukes the existing HKLM\Software\Policies\NetBird key
before importing the .reg, so the .reg is the SINGLE SOURCE OF
TRUTH. Any value present in the registry but absent from the .reg
is removed. This is what an MDM admin almost always wants.
- Setting the .reg to an empty (header-only) file effectively unsets
the policy.
Idempotency: re-running the script with the same .reg is a no-op from
the daemon's perspective (values identical → 1-min ticker sees no
diff → engine not restarted).
Exit codes: 0 = success; 1 = .reg missing or reg.exe error.
#>
$ErrorActionPreference = "Stop"
$RegFileName = "netbird-policy.reg"
$RegKey = "HKLM\Software\Policies\NetBird"
# Resolve the attached .reg file: JumpCloud copies command attachments
# into C:\Windows\Temp\ before invoking the script. Cwd / $PSScriptRoot
# fallbacks cover the local-dev case where you might dot-source this
# from elsewhere.
$candidates = @(
(Join-Path "$env:WINDIR\Temp" $RegFileName)
(Join-Path (Get-Location) $RegFileName)
(Join-Path $PSScriptRoot $RegFileName)
) | Where-Object { Test-Path $_ }
if ($candidates.Count -eq 0) {
Write-Error "[netbird-mdm] $RegFileName not found in working directory or `$PSScriptRoot. Attach the file to the JumpCloud command."
exit 1
}
$regFile = $candidates[0]
Write-Host "[netbird-mdm] using $regFile"
# Wipe the existing policy key so the .reg is authoritative.
$existed = Test-Path "Registry::HKEY_LOCAL_MACHINE\Software\Policies\NetBird"
if ($existed) {
& reg.exe delete $RegKey /f | Out-Null
if ($LASTEXITCODE -ne 0) {
Write-Error "[netbird-mdm] failed to clear $RegKey before import (exit $LASTEXITCODE)"
exit 1
}
Write-Host "[netbird-mdm] cleared previous values under $RegKey"
}
# Import. reg.exe writes both data and (re-)creates the key if needed.
& reg.exe import $regFile
if ($LASTEXITCODE -ne 0) {
Write-Error "[netbird-mdm] reg import failed (exit $LASTEXITCODE)"
exit 1
}
# Audit dump so the JumpCloud per-execution log captures the applied state.
Write-Host "[netbird-mdm] final policy state under $RegKey :"
& reg.exe query $RegKey /s
# Daemon's 1-min reload ticker picks up the change automatically.
# Uncomment to force immediate convergence (skips the ticker wait):
# Restart-Service netbird -Force -ErrorAction SilentlyContinue
exit 0

95
docs/netbird.adml Normal file
View File

@@ -0,0 +1,95 @@
<?xml version="1.0" encoding="utf-8"?>
<policyDefinitionResources xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
revision="1.0"
schemaVersion="1.0"
xmlns="http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions">
<displayName>NetBird Client Policies</displayName>
<description>Group Policy template for NetBird client MDM-managed settings. Values are written under HKLM\Software\Policies\NetBird and consumed by the netbird daemon at startup and every 1-minute reload tick.</description>
<resources>
<stringTable>
<!-- Categories -->
<string id="NetBird_Category">NetBird</string>
<string id="SUPPORTED_NetBird_All">NetBird Client 0.40+</string>
<!-- Identity / auth -->
<string id="ManagementURL_Name">Management URL</string>
<string id="ManagementURL_Help">URL of the NetBird management server. Format: https://host[:port]. When set, users cannot override this value via UI or CLI.</string>
<string id="PreSharedKey_Name">Pre-shared key</string>
<string id="PreSharedKey_Help">WireGuard pre-shared key used as an additional symmetric secret on every peer-to-peer tunnel. Secret value.</string>
<!-- Settings: engine / runtime behavior -->
<string id="DisableAutoConnect_Name">Disable auto-connect</string>
<string id="DisableAutoConnect_Help">When enabled, the NetBird tunnel does not auto-connect at daemon startup. Equivalent to --disable-auto-connect.</string>
<string id="DisableClientRoutes_Name">Disable client routes</string>
<string id="DisableClientRoutes_Help">When enabled, this client will not consume routes advertised by routing peers. Equivalent to --disable-client-routes.</string>
<string id="DisableServerRoutes_Name">Disable server routes</string>
<string id="DisableServerRoutes_Help">When enabled, this client will not act as a routing peer for other clients. Equivalent to --disable-server-routes.</string>
<string id="BlockInbound_Name">Block inbound</string>
<string id="BlockInbound_Help">When enabled, the client firewall blocks all inbound peer traffic on the WireGuard interface. Equivalent to --block-inbound.</string>
<string id="AllowServerSSH_Name">Allow server SSH</string>
<string id="AllowServerSSH_Help">When enabled, this client accepts incoming SSH sessions via NetBird SSH. Equivalent to --allow-server-ssh.</string>
<string id="RosenpassEnabled_Name">Enable Rosenpass</string>
<string id="RosenpassEnabled_Help">Enables Rosenpass post-quantum key exchange on WireGuard tunnels. Both peers must support it.</string>
<string id="RosenpassPermissive_Name">Rosenpass permissive</string>
<string id="RosenpassPermissive_Help">When enabled, the client falls back to plain WireGuard if a peer does not support Rosenpass; otherwise it refuses the connection.</string>
<string id="WireguardPort_Name">WireGuard port</string>
<string id="WireguardPort_Help">UDP port used by the local WireGuard interface. Allowed range: 1-65535.</string>
<string id="SplitTunnel_Name">Split tunnel</string>
<string id="SplitTunnel_Help">Restrict the NetBird tunnel to or from a chosen list of application package names. Choose either the allow mode (only the listed apps route through NetBird) or the disallow mode (the listed apps bypass NetBird; everything else routes through). The mode is mutually exclusive — only one can be active at a time. Android-only at the daemon level; Windows/macOS/iOS clients ignore this policy.</string>
<string id="SplitTunnel_Allow">Allow only listed apps (everything else bypasses)</string>
<string id="SplitTunnel_Disallow">Disallow listed apps (everything else routes)</string>
<!-- UI -->
<string id="DisableUpdateSettings_Name">Disable update settings</string>
<string id="DisableUpdateSettings_Help">When enabled, blocks every configuration change from the client UI and from the CLI (netbird up / login / setconfig). The Settings view stays viewable but read-only. Equivalent to --disable-update-settings.</string>
<string id="DisableProfiles_Name">Disable profiles</string>
<string id="DisableProfiles_Help">When enabled, the client UI/CLI cannot list, create, switch or remove NetBird connection profiles. Equivalent to --disable-profiles.</string>
<string id="DisableNetworks_Name">Disable networks</string>
<string id="DisableNetworks_Help">When enabled, the client UI/CLI cannot list, select or deselect NetBird networks (the corresponding daemon RPCs return Unavailable). Equivalent to --disable-networks.</string>
<string id="DisableMetricsCollection_Name">Disable metrics collection</string>
<string id="DisableMetricsCollection_Help">When enabled, the client does not collect or report local usage metrics.</string>
</stringTable>
<presentationTable>
<presentation id="ManagementURL_Pres">
<textBox refId="ManagementURL_Text">
<label>Management URL:</label>
<defaultValue>https://api.netbird.io:443</defaultValue>
</textBox>
</presentation>
<presentation id="PreSharedKey_Pres">
<textBox refId="PreSharedKey_Text">
<label>Pre-shared key:</label>
</textBox>
</presentation>
<presentation id="WireguardPort_Pres">
<decimalTextBox refId="WireguardPort_Decimal" defaultValue="51820">WireGuard UDP port:</decimalTextBox>
</presentation>
<presentation id="SplitTunnel_Pres">
<dropdownList refId="SplitTunnel_Mode" defaultItem="0">Mode:</dropdownList>
<textBox refId="SplitTunnel_Apps">
<label>Package names (comma-separated):</label>
</textBox>
</presentation>
</presentationTable>
</resources>
</policyDefinitionResources>

223
docs/netbird.admx Normal file
View File

@@ -0,0 +1,223 @@
<?xml version="1.0" encoding="utf-8"?>
<policyDefinitions xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
revision="1.0"
schemaVersion="1.0"
xmlns="http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions">
<policyNamespaces>
<target prefix="netbird" namespace="NetBird.Policies.Client" />
</policyNamespaces>
<resources minRequiredRevision="1.0" />
<supportedOn>
<definitions>
<definition name="SUPPORTED_NetBird_All" displayName="$(string.SUPPORTED_NetBird_All)" />
</definitions>
</supportedOn>
<categories>
<category name="NetBird" displayName="$(string.NetBird_Category)" />
</categories>
<policies>
<!-- ============================================================ -->
<!-- TOP-LEVEL: foundational identity / authentication -->
<!-- ============================================================ -->
<policy name="ManagementURL"
class="Machine"
displayName="$(string.ManagementURL_Name)"
explainText="$(string.ManagementURL_Help)"
key="Software\Policies\NetBird"
presentation="$(presentation.ManagementURL_Pres)">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<elements>
<text id="ManagementURL_Text" valueName="ManagementURL" required="true" />
</elements>
</policy>
<policy name="PreSharedKey"
class="Machine"
displayName="$(string.PreSharedKey_Name)"
explainText="$(string.PreSharedKey_Help)"
key="Software\Policies\NetBird"
presentation="$(presentation.PreSharedKey_Pres)">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<elements>
<text id="PreSharedKey_Text" valueName="PreSharedKey" />
</elements>
</policy>
<!-- ============================================================ -->
<!-- SETTINGS: engine / runtime / connection behavior -->
<!-- ============================================================ -->
<policy name="DisableAutoConnect"
class="Machine"
displayName="$(string.DisableAutoConnect_Name)"
explainText="$(string.DisableAutoConnect_Help)"
key="Software\Policies\NetBird"
valueName="DisableAutoConnect">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="DisableClientRoutes"
class="Machine"
displayName="$(string.DisableClientRoutes_Name)"
explainText="$(string.DisableClientRoutes_Help)"
key="Software\Policies\NetBird"
valueName="DisableClientRoutes">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="DisableServerRoutes"
class="Machine"
displayName="$(string.DisableServerRoutes_Name)"
explainText="$(string.DisableServerRoutes_Help)"
key="Software\Policies\NetBird"
valueName="DisableServerRoutes">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="BlockInbound"
class="Machine"
displayName="$(string.BlockInbound_Name)"
explainText="$(string.BlockInbound_Help)"
key="Software\Policies\NetBird"
valueName="BlockInbound">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="AllowServerSSH"
class="Machine"
displayName="$(string.AllowServerSSH_Name)"
explainText="$(string.AllowServerSSH_Help)"
key="Software\Policies\NetBird"
valueName="AllowServerSSH">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="RosenpassEnabled"
class="Machine"
displayName="$(string.RosenpassEnabled_Name)"
explainText="$(string.RosenpassEnabled_Help)"
key="Software\Policies\NetBird"
valueName="RosenpassEnabled">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="RosenpassPermissive"
class="Machine"
displayName="$(string.RosenpassPermissive_Name)"
explainText="$(string.RosenpassPermissive_Help)"
key="Software\Policies\NetBird"
valueName="RosenpassPermissive">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="WireguardPort"
class="Machine"
displayName="$(string.WireguardPort_Name)"
explainText="$(string.WireguardPort_Help)"
key="Software\Policies\NetBird"
presentation="$(presentation.WireguardPort_Pres)">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<elements>
<decimal id="WireguardPort_Decimal" valueName="WireguardPort"
minValue="1" maxValue="65535" required="true" />
</elements>
</policy>
<policy name="SplitTunnel"
class="Machine"
displayName="$(string.SplitTunnel_Name)"
explainText="$(string.SplitTunnel_Help)"
key="Software\Policies\NetBird"
presentation="$(presentation.SplitTunnel_Pres)">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<elements>
<enum id="SplitTunnel_Mode" valueName="SplitTunnelMode" required="true">
<item displayName="$(string.SplitTunnel_Allow)"><value><string>allow</string></value></item>
<item displayName="$(string.SplitTunnel_Disallow)"><value><string>disallow</string></value></item>
</enum>
<text id="SplitTunnel_Apps" valueName="SplitTunnelApps" required="true" />
</elements>
</policy>
<!-- ============================================================ -->
<!-- UI: visibility / UX kill switches -->
<!-- ============================================================ -->
<policy name="DisableUpdateSettings"
class="Machine"
displayName="$(string.DisableUpdateSettings_Name)"
explainText="$(string.DisableUpdateSettings_Help)"
key="Software\Policies\NetBird"
valueName="DisableUpdateSettings">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="DisableProfiles"
class="Machine"
displayName="$(string.DisableProfiles_Name)"
explainText="$(string.DisableProfiles_Help)"
key="Software\Policies\NetBird"
valueName="DisableProfiles">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="DisableNetworks"
class="Machine"
displayName="$(string.DisableNetworks_Name)"
explainText="$(string.DisableNetworks_Help)"
key="Software\Policies\NetBird"
valueName="DisableNetworks">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
<policy name="DisableMetricsCollection"
class="Machine"
displayName="$(string.DisableMetricsCollection_Name)"
explainText="$(string.DisableMetricsCollection_Help)"
key="Software\Policies\NetBird"
valueName="DisableMetricsCollection">
<parentCategory ref="NetBird" />
<supportedOn ref="SUPPORTED_NetBird_All" />
<enabledValue><decimal value="1" /></enabledValue>
<disabledValue><decimal value="0" /></disabledValue>
</policy>
</policies>
</policyDefinitions>