NetBird Windows GPO Deployment

Deploy NetBird to Windows domain clients via Group Policy with a hardened security posture.

What It Does

Two PowerShell scripts work together across boot/login cycles to:

1. Silently install NetBird from a network share (first boot, runs as SYSTEM)
2. Connect with security flags and trigger SSO authentication (first login, runs as user)
3. Lock down settings so users cannot modify them (second boot, runs as SYSTEM)

After deployment, the client has these restrictions enforced and locked:

Flag	Effect
--block-inbound	No inbound connections to the peer
--block-lan-access	Peer cannot access the local LAN
--disable-server-routes	Peer cannot act as a routing peer
--disable-auto-connect	User must manually connect/disconnect
--disable-update-settings	GUI settings are read-only
--disable-profiles	Cannot switch NetBird accounts

How It Works

The deployment uses two GPO scripts that work together across two boot/login cycles:

Step	When	What Happens
1	First boot	Startup script silently installs NetBird
2	First login	Logon script runs netbird up with security flags, user completes SSO in browser
3	Second boot	Startup script detects flags were applied and locks down the client settings
4	All future logins	Everything is in place, scripts detect this and skip all steps

Prerequisites

• NetBird installer (netbird_installer_x.x.x_windows_amd64.exe) hosted on a network share accessible by domain computers
• GPO permissions to create Computer and User policies
• NetBird Cloud account with Microsoft SSO configured

Scripts

• Deploy-NetBird-Startup.ps1 — Installs NetBird and applies settings lockdown. Runs as SYSTEM via GPO Computer Startup.
• Deploy-NetBird-Logon.ps1 — Connects with security flags and triggers SSO. Runs as the logged-in user via GPO User Logon.

GPO Setup Instructions

Step 1: Host the Files

1. Copy the NetBird installer to a network share accessible by domain computers (e.g., \\server\share\)
2. Copy both .ps1 scripts to a share accessible by GPO (e.g., \\domain\SYSVOL\yourdomain\scripts\)
3. Update $installerPath in Deploy-NetBird-Startup.ps1 to match your share path

Step 2: Create the GPO

1. Open Group Policy Management Console
2. Create a new GPO (e.g., "NetBird Deployment") and link it to the OU containing your target computers

Step 3: Configure the Startup Script

1. Edit the GPO
2. Navigate to Computer Configuration > Policies > Windows Settings > Scripts > Startup
3. Go to the PowerShell Scripts tab
4. Click Add and browse to Deploy-NetBird-Startup.ps1

Step 4: Configure the Logon Script

1. Navigate to User Configuration > Policies > Windows Settings > Scripts > Logon
2. Go to the PowerShell Scripts tab
3. Click Add and browse to Deploy-NetBird-Logon.ps1

Step 5: Set Execution Policy (if needed)

If your environment restricts PowerShell execution, add this GPO setting:

• Computer Configuration > Administrative Templates > Windows Components > Windows PowerShell
• Set Turn on Script Execution to Enabled and select Allow all scripts

Alternatively, scope it tighter with Allow local scripts and remote signed scripts and sign both scripts.

Troubleshooting

All activity is logged to C:\ProgramData\Netbird\deploy.log with timestamps and script source labels ([Startup] or [Logon:username]).

Common Issues

Issue	Cause	Fix
NetBird not installing	Installer path incorrect or inaccessible	Verify $installerPath and share permissions for the computer account
SSO prompt not appearing	Logon script ran before install	Will resolve on next login after install completes
Settings not locked	Only one boot cycle completed	Lockdown applies on the second boot after first login. Reboot once more.
Need to re-apply lockdown	After reinstall	Delete .lockdown-applied and .flags-applied from C:\ProgramData\Netbird\
Need to temporarily unlock settings for support	Planned maintenance	Delete .lockdown-applied, run netbird service reconfigure (no flags), restart service

Verifying Deployment

From another NetBird peer, ping the deployed machine's NetBird IP. If BlockInbound is active, the ping will time out.

On the client, run:

netbird status -d

This shows the current connection state and active settings.

Note

The NetBird team is working on an updated management GUI that will make configuring lockdown policies like these easier to manage at scale. These scripts are a stopgap for organizations that need this functionality today via GPO.

Security Notes

• No inbound firewall ports are needed on any peer when using NetBird Cloud. All connections use outbound NAT traversal.
• BlockInbound and BlockLANAccess ensure the laptop cannot be used as a gateway to the user's home or office network.
• DisableServerRoutes prevents the client from acting as a routing peer.
• DisableAutoConnect ensures tunnels are only active when the user explicitly connects.
• --disable-update-settings locks the GUI so users cannot change any of these settings.
• --disable-profiles prevents users from switching to a different NetBird account.
• RDP over NetBird will be blocked by BlockInbound. If remote support is needed, the user can be instructed to temporarily re-enable server routes once settings are unlocked by an admin.