MDM Integration

Updated October 8, 2026

Installing NetBird on a few hundred laptops is the easy half of a rollout. The hard half is everything that happens afterwards: a user points the client at a different server, creates a second profile, turns on an SSH server, or switches off a setting your security posture depends on. Fixing that one machine at a time does not scale, and asking users nicely is not a control.

The NetBird client solves this by honoring MDM policy: settings your device management tool writes to the operating system's own managed-configuration store. The client reads that store, applies what it finds on top of every other setting, and locks those settings so nobody on the device can change them. NetBird adds no agent or connector of its own. If your MDM can write to the store, it can manage NetBird.

This page is in four parts:

1. What you can achieve: the goals you can reach with a policy, and the setting for each.
2. Recommended policies: a starting policy for user devices, shared devices, and routing peers.
3. How the client applies a policy: the mental model, and what a user sees on a managed device.
4. Policy keys reference, then verifying enforcement and troubleshooting.

How to deliver a policy is specific to each operating system, so it has its own page:

Linux and Android have no MDM channel today. See When not to use MDM policy.

To plan a whole rollout, from installing the client to users signing in and a policy in place, follow Roll Out NetBird Across Your Organization with MDM, which walks through it with Intune.

What you can achieve

Find what you want to do, set the key, and deliver it with your MDM (see the platform pages above). Each key links to its full entry in the Policy keys reference.

Include only the keys you mean to pin. A key you set is locked, even when you set it to false; a key you leave out stays the user's to change.

Set the server and startup

Lock the client app

None of these settings stops a user from disconnecting NetBird. See What a policy does not do.

Control what the device exposes

Encrypt the tunnel

Support and monitoring

Tune the connection

Recommended policies

Start from the column that matches the device group, then add or remove keys for your own posture. Send each policy to one device group, and keep routing peers out of every group that gets blockInbound or disableServerRoutes.

Why each column looks the way it does:

• User devices, such as laptops and desktops, consume resources and never serve them, so disableServerRoutes stops one that is wrongly assigned as a routing peer from carrying other peers' traffic. Add blockInbound if nothing ever needs to reach these devices. Leave it out if IT reaches them over NetBird SSH, and control inbound access with access policies instead. Add disableNetworks to stop users choosing networks and exit nodes (the ones the dashboard assigns keep working), and disableAdvancedView to hide the Peers and Resources lists.
• Shared or kiosk devices should leave the user as little as possible to change: no network or exit node choice, no advanced view, and a connection at every boot.
• Routing peers and servers must keep forwarding traffic and accepting connections, so they never get blockInbound or disableServerRoutes. This column only applies to Windows and macOS machines; Linux has no MDM channel, so configure Linux routing peers with CLI flags.
• Remote jobs are optional in every column. Turn on allowRemoteJobs wherever your support team collects debug bundles remotely, and always pin debugBundleUploadURL with it, so bundles go to an upload server you control. Routing peers are often the first place to look when a resource is unreachable or relayed.

Leave these keys out unless you have a specific reason:

• preSharedKey, rosenpassEnabled, rosenpassPermissive: each has to match on every peer, or devices lose their connections. See Encryption keys.
• disableClientRoutes: cuts a device off from every network resource and exit node.
• wireguardPort: the default suits almost every fleet.
• lazyConnection: leave lazy connections to the account setting, so one dashboard switch controls the whole fleet. Push false only for devices that must hold every connection open.
• enableLocalMetrics, localMetricsAddress: only for devices you scrape with Prometheus.
• splitTunnelMode, splitTunnelApps, disableMetricsCollection: no effect yet.

The user device baseline

The three keys every column above shares make the usual starting policy, and the platform pages use it as their example. With a self-hosted management server:

On NetBird Cloud, use https://api.netbird.io:443. Send the policy only to the device group that holds your user devices, so routing peers and servers stay out of it.

How the client applies a policy

Think of a policy as a set of pinned switches. Every key in the payload pins one setting to the value you chose and takes it out of the user's reach. Every key you leave out stays an ordinary setting that the user, the CLI, or the dashboard controls as usual. A key that is absent is not pinned, and a key that is present is pinned, whatever its value.

On Windows and macOS, the client daemon reads the policy at startup and again every minute. Each time:

1. It applies the policy on top of every other configuration layer. Defaults, the on-disk profile, environment variables, and CLI or app input all apply first; the policy is applied last and wins. A policy also overrides the service-install flags --disable-update-settings, --disable-profiles, and --disable-networks: pushing disableNetworks: false re-enables network selection even on a device installed with --disable-networks. One exception: the NB_LAZY_CONN environment variable takes precedence over the lazyConnection key.
2. It locks the pinned settings. A request that tries to change a pinned setting to a different value, from the desktop app, the CLI (netbird login --flag, or netbird up --flag on a disconnected client) or the daemon API, is rejected as a whole with fields managed by MDM cannot be modified: [<keys>]. None of its other fields are applied either. A request that repeats the pinned value is accepted, because it changes nothing. These locks read the policy file on every request, so they apply as soon as the file changes; the disableUpdateSettings, disableProfiles, and disableNetworks gates apply at the next reload. Two keys only change what the app shows or does, and lock nothing: disableAutostart and disableAdvancedView.
3. It never writes policy values to disk. The on-disk profile keeps the device's own settings. When you remove a key from the policy, the setting falls back to that on-disk value on the next reload and becomes editable again, with nothing left behind.

When a reload finds that the policy has changed, the client restarts its connection to apply it. Expect a brief interruption on every policy change (typically a second or two), and plan larger changes outside working hours. The desktop app then shows a notification: NetBird settings updated, "Your NetBird configuration was updated by your IT policy."

On iOS the timing is different: the app passes the policy to the tunnel only while the app is running. See Enforce settings on iOS.

What a user sees

Since NetBird v0.75.0, the desktop app hides the controls for pinned settings rather than greying them out. With the user device baseline, the server address field is gone. Read-only mode removes the Network, Security, SSH, and Advanced settings tabs, and disableProfiles removes the Profiles tab. General, Troubleshooting, and About remain, and the Connect button still works.

On the CLI, changing a pinned setting fails with the error above. The disableUpdateSettings, disableProfiles, and disableNetworks keys have errors of their own, listed under Troubleshooting.

What a policy does not do

A policy pins the client's configuration. It does not make the tunnel mandatory: a user can still disconnect with netbird down or the Disconnect button, no key blocks netbird logout of the active profile (which removes the peer from your account), and anyone with administrator rights on the device can stop the service, uninstall the client, or edit the registry or the managed-preferences file. NetBird has no always-on mode. Enforce that layer with the operating system: give users standard accounts, manage the NetBird service with your MDM, and write your access policies so that disconnecting from NetBird costs a user access to company resources rather than freeing them from restrictions.

Policy keys reference

The client recognizes 23 keys. They are grouped below by the job they do, starting with the ones nearly every rollout needs. A key that has no meaning on a platform (for example allowServerSSH on iOS) is ignored there, so one payload is safe to send to every platform.

Key names are camelCase in plist and app-configuration payloads. On Windows, the registry value names and the Group Policy templates use PascalCase (ManagementURL, BlockInbound); both forms are recognized, and names are matched without regard to case. In the Group Policy editor, each policy is named after its key in plain words, such as Block inbound for blockInbound.

Value types:

• boolean: a native boolean (<true/> or <false/> in a plist), or one of the strings true/false, 1/0, yes/no, on/off. An integer (0 is false, anything else is true) also works on Windows (REG_DWORD) and iOS, but not on macOS: there, a boolean written as <integer> is listed as managed and locked, but never applied, so the setting is frozen at whatever the device had.
• string: a string. An empty string counts as not set.
• integer: an integer, or a string of decimal digits.

The registry type for each key on Windows is on Enforce settings on Windows.

Server and startup keys

Nearly every rollout sets managementURL. The other two keys decide whether NetBird connects, and whether its app opens, on their own.

• managementURL pins the server, not the account. NetBird Cloud serves every account from https://api.netbird.io:443, so on Cloud this key stops a user from pointing the client at another server, but not from signing in to another Cloud account. No key pins the account: even with managementURL, disableProfiles, and disableUpdateSettings all pinned, netbird logout followed by netbird up --setup-key <key> moves the device to another account on the same server. A device signed in to another account has no access to your resources, because your access policies do not apply to it.
• disableAutostart only acts when the app starts. The Launch NetBird UI at Login switch in the app's settings stays usable. A user who turns it back on gets the app at their next login, and the app removes the entry again as soon as it opens. Pushing false does not turn launch-at-login on; it only stops the app from removing the entry.

Client app keys

These keys decide how much of the app a user can touch. The user device baseline uses the first two.

• disableUpdateSettings covers settings no key names. The DNS, firewall, interface, and SSH sub-options have no key of their own, so the only way to stop users changing them is read-only mode. On a device with disableUpdateSettings: true, an administrator who needs to change one of those settings has to lift the policy first.
• disableNetworks plus an exit node pins the device to that exit node. With an exit node that has Auto Apply enabled, the exit node is applied automatically and the user cannot deselect it. See Enforcing the exit node on managed devices for the full recipe, including why the policy has to reach the devices before users touch the exit node switch.

Device exposure keys

These keys decide what reaches the device, and what the device passes on. Each pins a client-side setting that also exists in the app and the CLI, and each one wins over what the dashboard configures: routes, routing-peer assignments, SSH, and access policies.

• The two route keys are easy to mix up. "Client" and "server" describe the device's role in a route, not the direction of the traffic. disableClientRoutes stops the device using routes, which is what an end-user laptop does. disableServerRoutes stops the device providing routes, which is what a routing peer does. On a laptop, disableClientRoutes: true cuts it off from every network resource and exit node, which is rarely what you want. disableServerRoutes: true is the safe choice for laptops, because it stops a laptop that has been wrongly assigned as a routing peer from carrying other peers' traffic.
• Do not send blockInbound or disableServerRoutes to routing peers. A routing peer with either key set stops forwarding. If it is the only routing peer for a network, that network becomes unreachable for everyone. Scope these keys to a device group that excludes routing peers and servers.
• blockInbound is not a kill switch. It blocks connections to the device, not traffic from it, and it does not keep the tunnel up. Use it for devices that only ever consume resources, such as most end-user laptops, and never for a device other peers need to reach.

Encryption keys

These keys change how connections are encrypted. A pre-shared key, and Rosenpass outside permissive mode, have to match on both ends of a connection, so a key sent to only part of a fleet can cut that part off from the rest.

• A pre-shared key splits your network in two. Devices that have the key and devices that do not cannot connect to each other. If you pushed a preSharedKey to your laptops only, they would lose every routing peer and server that does not carry the same key. Only use it when every peer, including routing peers and servers, gets the same key.
• The pre-shared key is not hidden from local users. By default, standard users can read the NetBird policy key on Windows, and the macOS managed-preferences file is readable by every user. Treat the key as an extra layer of protection, never as a credential that only administrators know.
• To roll out Rosenpass, start in permissive mode. Push rosenpassEnabled: true with rosenpassPermissive: true, so devices that do not have Rosenpass yet can still connect. Remove permissive mode once every peer runs Rosenpass.

Support and monitoring keys

These keys turn on remote diagnostics and local metrics. Both features expose information about the device, so the safe default is to leave them off and pin them on only where you need them.

• Pin the upload URL wherever you allow remote jobs. A debug bundle holds peer names, IP addresses, and logs. Setting debugBundleUploadURL to an upload server you run keeps bundles on infrastructure you control.
• Keep the metrics endpoint on loopback. The endpoint has no authentication. A user without administrator rights can only bind it to a loopback address, but a policy value is applied exactly as written. A non-loopback localMetricsAddress publishes peer names and connection state to anything that can reach the port.

Connection tuning keys

Most fleets never need these keys.

Set wireguardPort only when another program on the device needs the default port, or your firewall rules expect a specific one.

Keys with no effect yet

The client recognizes these keys, so they do no harm in a payload, but none of them changes anything today.

Verifying enforcement

On Windows and macOS, ask the daemon what it is enforcing:

netbird debug config

This prints the resolved configuration as JSON, after every layer including the policy. Its mDMManagedFields array lists every key in the policy the client reads. For the user device baseline it reads:

"mDMManagedFields": [
  "disableProfiles",
  "disableUpdateSettings",
  "managementURL"
]

If a key you sent is missing from the array, the policy did not reach the device, or it used a name the client does not recognize.

netbird debug config reads the policy file at the moment you run it, so it shows a change straight away. The daemon applies the change at its next reload, within a minute, and logs it: MDM policy changed: added=[...] removed=[...] changed=[...], followed, while the client is connected, by MDM policy changed; restarting engine to apply new configuration. Those lines are the confirmation that the policy is enforced, not just delivered. The client log records the same information on every reload: one MDM enrolled with N managed key(s): [...] line, and one MDM override <key> = <value> line for each setting it overrode, with secrets redacted. The log is /var/log/netbird/client.log on macOS and C:\ProgramData\Netbird\client.log on Windows.

On iOS there is no CLI. See Verifying on a device.

Troubleshooting

Problems specific to one delivery channel, such as a Group Policy that never reaches the registry or a macOS profile that disappears after a reboot, are covered on the Windows, macOS, and iOS pages. The problems below look the same on every platform.

mDMManagedFields is empty or missing keys. Start at the source. Confirm the values are in the registry or the managed-preferences file, using the commands on the platform page. If they are, look for MDM ignoring unknown in the client log: the value name does not match any key in the reference. Names are matched without regard to case, but must otherwise be exact. WireGuardPort, for example, matches; WgPort does not.

A key is listed in mDMManagedFields but the setting did not change. The value is the wrong type or out of range. The key still counts as managed, so users cannot change the setting, but the client keeps its previous value. The client log has a warning such as MDM management URL "..." invalid or MDM wireguard port ... out of range. On Windows, check that the value has the registry type the key expects: a managementURL stored as a REG_DWORD, for example, is ignored. On macOS, check that booleans are <true/> or <false/>, not <integer>; the client logs no warning for those.

A user gets fields managed by MDM cannot be modified: [...]. The policy is working: the user, or a script, tried to change a pinned setting. The keys in the brackets are the pinned settings involved. Change those settings through your MDM instead.

netbird up --flag prints Already connected and changes nothing. On a connected client, netbird up ignores its flags, whether or not a policy is in place. Run netbird down first. On a managed device, the change is then rejected if the policy pins that setting.

A user gets update settings are disabled, you cannot use this feature without update settings enabled. disableUpdateSettings is on, or the service was installed with --disable-update-settings. Every settings change is rejected, including changes to settings no key names. Lift the policy to make the change.

A user gets profiles are disabled, you cannot use this feature without profiles enabled. disableProfiles is on, or the service was installed with --disable-profiles. The device stays on its current profile.

A user gets network selection is disabled by the administrator. disableNetworks is on, or the service was installed with --disable-networks.

Lazy connections do not follow the policy. The NB_LAZY_CONN environment variable is set on the device, and it takes precedence over lazyConnection. Remove it from the service environment.

Devices lost access to network resources after a policy change. Check for disableClientRoutes: true or a preSharedKey in the policy. The first stops the device using routes; the second stops it connecting to any peer that does not have the same key. See Device exposure keys and Encryption keys.

A network became unreachable for everyone after a policy change. A routing peer received blockInbound: true or disableServerRoutes: true, and stopped forwarding. Take routing peers out of the policy's scope.

My MDM is not mentioned on these pages. Any MDM that can write a registry value on Windows, push a configuration profile on macOS, or send an app configuration on iOS works, because the mechanism belongs to the operating system, not to NetBird.

When not to use MDM policy

• Linux and Android devices. Neither has an MDM channel in NetBird today. On Linux, set the same options with netbird up flags or the service-install flags (netbird service install --disable-update-settings --disable-profiles --disable-networks), or bootstrap the client from a config file.
• One device, one change. To change a setting on a single machine you manage by hand, use the app or the CLI. A policy is for settings that must hold across a fleet and must not drift.
• Access control. A policy configures the client on one device. Which peers can reach which resources belongs in access policies, which apply to every device and do not depend on an MDM.

TL;DR

• Find the goal, set the key. What you can achieve maps each goal to a setting, and the user device baseline (managementURL, disableUpdateSettings, disableProfiles) is the usual start.
• Present means pinned, even as false. Every key you leave out stays the user's. The client applies the policy last, locks what it pins, re-reads it every minute, and restarts the connection briefly when it changes.
• Keep routing peers out of the wrong policy. Never send them blockInbound or disableServerRoutes, and send a preSharedKey to every peer or none.
• Verify with netbird debug config, then the log. mDMManagedFields shows the policy the client reads; the MDM policy changed log line confirms it is enforced.