Deployment & Operations

Deployment Strategy, TacticalRMM, Multi-Site Operations, and Migration

Executive Summary

This report covers operational deployment of NetBird across GSISG’s two-site infrastructure (Honolulu 10.100.7.0/24, Boulder 10.15.0.0/24) using TacticalRMM for endpoint deployment. Key findings:

1. Windows MSI silent deployment is well-supported with SETUP_KEY and MANAGEMENT_URL MSI properties, plus /qn /norestart flags.
2. TacticalRMM deploys NetBird via PowerShell scripts run against bulk agents, executing as SYSTEM.
3. The Netgate 6100 at Boulder uses an Intel Atom C3558 (AMD64/x86_64). Official NetBird pfSense packages (v0.1.25) install directly on this hardware. A Linux VM on Hyper-V is a valid alternative.
4. Multi-site routing works automatically — each routing peer advertises its local subnet; clients route to the correct site via longest-prefix match.
5. NetBird CAN replace IPsec site-to-site tunnels using bidirectional network routes.
6. On-premises detection uses Posture Checks (Peer Network Range) to block routes when a client is on the office subnet.
7. Auto-update exists (v0.61.0+) for Windows/macOS but has known bugs.
8. GlobalProtect and NetBird CAN coexist with --network-monitor=false workaround.
9. REST API provides peer status but NOT bandwidth/transfer stats.

---

Findings

1. Windows MSI Silent Deployment

MSI Properties

Property	Purpose	Example
SETUP_KEY	Pre-authenticates the peer with a setup key	SETUP_KEY=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
MANAGEMENT_URL	Points to management server	MANAGEMENT_URL=https://netbird.gsisg.com:443

Silent Install Command

msiexec.exe /i "netbird_installer_0.66.4_windows_amd64.msi" /qn /norestart SETUP_KEY=<KEY> MANAGEMENT_URL=https://netbird.gsisg.com:443

The MSI installs a Windows service that auto-starts at boot. Install path: C:\Program Files\NetBird. If SETUP_KEY is not passed as an MSI property, a post-install step is required:

& "C:\Program Files\NetBird\netbird.exe" up --setup-key <KEY> --management-url <URL>

---

2. TacticalRMM Deployment

The TacticalRMM agent runs under the SYSTEM security context. Scripts are transferred via NATS, executed, and output captured.

Recommended: PowerShell Script via Bulk Script

# NetBird Silent Deployment via TacticalRMM
param(
    [string]$SetupKey = "YOUR_SETUP_KEY_HERE",
    [string]$ManagementUrl = "https://netbird.gsisg.com:443"
)

$InstallerUrl = "https://github.com/netbirdio/netbird/releases/latest/download/netbird_installer_0.66.4_windows_amd64.msi"
$InstallerPath = "$env:TEMP\netbird_installer.msi"

if (Test-Path "C:\Program Files\NetBird\netbird.exe") {
    Write-Host "NetBird already installed"
    & "C:\Program Files\NetBird\netbird.exe" version
    exit 0
}

Invoke-WebRequest -Uri $InstallerUrl -OutFile $InstallerPath -UseBasicParsing
$MsiArgs = @("/i", $InstallerPath, "/qn", "/norestart")
if ($SetupKey) { $MsiArgs += "SETUP_KEY=$SetupKey" }
if ($ManagementUrl) { $MsiArgs += "MANAGEMENT_URL=$ManagementUrl" }

$proc = Start-Process "msiexec.exe" -ArgumentList $MsiArgs -Wait -PassThru
if ($proc.ExitCode -ne 0) {
    Write-Error "Installation failed with exit code $($proc.ExitCode)"
    exit 1
}

Start-Sleep -Seconds 5
if (Test-Path "C:\Program Files\NetBird\netbird.exe") {
    Write-Host "NetBird installed successfully"
    & "C:\Program Files\NetBird\netbird.exe" status
}

Remove-Item $InstallerPath -Force -ErrorAction SilentlyContinue

Deploy via Tools > Bulk Script or create an Automation Policy. Alternative: Chocolatey (choco install netbird -y).

---

3. pfSense NetBird Package Installation

The NetBird pfSense package is NOT in the official pfSense package manager. Installation is manual via SSH.

Current Package Versions (v0.1.25, March 15, 2026):

Package	Version	Architecture
NetBird client	0.66.4	x86_64 and aarch64
pfSense GUI package	0.2.2	x86_64 and aarch64

The Netgate 6100 uses an Intel Atom C3558 (AMD64/x86_64). The official x86_64 packages install directly. No workaround or additional infrastructure is needed.

Installation Process:

ssh admin@<pfsense-ip>
fetch https://github.com/netbirdio/pfsense-netbird/releases/download/v0.1.25/netbird-0.66.4-x86_64.pkg
fetch https://github.com/netbirdio/pfsense-netbird/releases/download/v0.1.25/pfSense-pkg-NetBird-0.2.2-x86_64.pkg
pkg add -f netbird-0.66.4-x86_64.pkg
pkg add -f pfSense-pkg-NetBird-0.2.2-x86_64.pkg

Post-Install Configuration:

1. Navigate to VPN > NetBird in pfSense GUI
2. Enter Management URL and Setup Key, click Save
3. Assign the wt0 interface: Interfaces > Assignments
4. Create firewall rules on the NetBird interface
5. Configure Outbound NAT: Add a Static Port rule for improved NAT traversal

Fallback option: Linux VM on Hyper-V (DATA001 or DATA007), 1 vCPU / 512 MB RAM / 8 GB disk. This avoids third-party packages on the production firewall and provides full Linux routing peer support.

---

4. Multi-Site Routing with Routing Peers

Destination-based routing works automatically:

1. Honolulu routing peer advertises 10.100.7.0/24 as a network route
2. Boulder routing peer advertises 10.15.0.0/24 as a network route
3. Both routes are distributed to peers in the specified Distribution Groups
4. A remote user’s client receives both routes and installs them in the local routing table
5. Access to 10.100.7.x routes to Honolulu; access to 10.15.x.x routes to Boulder
6. This is automatic — standard longest-prefix-match IP routing

Each route operates independently. A user can simultaneously access resources at both sites.

---

5. Replacing Existing IPsec Site-to-Site

NetBird explicitly supports “Link branch offices” and “Bridge on-premise data centers” as core use cases. Deploy a routing peer at each site, create bidirectional network routes, and configure masquerade (ON for simplicity, OFF for source IP transparency with static routes on each router).

Access Control Caveat: Network Routes bypass ACL rules by default. For site-to-site with access control, use the Networks feature instead or create explicit policies.

---

6. On-Premises Detection

NetBird does NOT have a built-in “trusted network” auto-disconnect feature. The solution is Posture Checks:

1. Create a Peer Network Range posture check that blocks traffic when on 10.100.7.0/24 or 10.15.0.0/24
2. Attach to a policy governing the route to the routing peer
3. Result: When on the office LAN, the posture check blocks the route; traffic stays local

This prevents hairpin routing but does NOT fully disconnect NetBird. The WireGuard tunnel stays up; only routes are removed.

---

7. Client Update Mechanism

Setting	Detail
Minimum client version	v0.61.0
Supported platforms	Windows and macOS only (Linux requires package manager)
Default state	Disabled — must be enabled in dashboard
Options	Latest stable, pin to version, force updates

Known Issues:

• Settings reset after update (#5128) — open
• No server version pinning (#5236) — open

TacticalRMM provides a more controlled alternative: choco upgrade netbird -y or MSI reinstall via scheduled task.

---

8. GlobalProtect Coexistence

Both can be installed and run simultaneously, with a known issue requiring a workaround.

When GP connects, it adds routes that trigger NetBird’s network monitor to restart the WireGuard interface, killing active TCP sessions (GitHub #5077). Workaround: netbird up --network-monitor=false.

PR Status (March 2026):

• PR #5155: CLOSED (not merged) — test failures
• PR #5156: OPEN (not merged) — awaiting maintainer approval

Side effects of --network-monitor=false: Wi-Fi network switches may take 25+ seconds to reconnect instead of instant re-detection. Manageable for most users.

The routes do not actually conflict: GP handles corporate subnets; NetBird handles 100.64.0.0/10 overlay. The issue is the network monitor detection, not routing.

Migration Strategy:

1. Install NetBird alongside GP with --network-monitor=false
2. Test NetBird routing for non-critical resources
3. Gradually shift traffic to NetBird
4. After stable operation, disable GP auto-connect
5. Uninstall GP; remove --network-monitor=false

---

9. Windows Firewall and AV/EDR

NetBird automatically creates Windows Firewall rules allowing incoming traffic on the wt0 interface. Known AV/EDR conflicts:

Product	Issue	Resolution
Bitdefender MDR	Flags notification PowerShell script	Whitelist the script
Symantec	May block NetBird traffic	Add process exception
CrowdStrike	May interfere with WireGuard	Add exception for NetBird process

General recommendation: Add C:\Program Files\NetBird\ to AV/EDR exclusion lists before deployment.

---

10. Monitoring, Alerting, and API

REST API: GET /api/peers with Authorization: Token <API_TOKEN> returns peer metadata (id, name, ip, connected, last_seen, os, version, groups, etc.). Bandwidth/transfer stats are NOT available via API.

CLI: netbird status -d provides per-peer connection type, handshake times, transfer data, and latency.

Zabbix: No native template. Use HTTP Agent items polling /api/peers with JSONPath preprocessing.

---

Gaps & Uncertainties

Gap	Impact	Mitigation
GP coexistence fix (PR #5156) timeline	MEDIUM	Use --network-monitor=false workaround
Auto-update settings-reset bug (#5128)	MEDIUM	Pin version; use TacticalRMM for controlled updates
MANAGEMENT_URL MSI property compatibility	MEDIUM	Fall back to post-install CLI if needed
pfSense packages removed on upgrades	MEDIUM	Reinstall after each pfSense upgrade, or use Linux VM alternative

---

Sources

NetBird: docs.netbird.io (Windows install, pfSense install, network-routes, auto-update, posture-checks, peers API, troubleshooting)

TacticalRMM: docs.tacticalrmm.com (install_agent, scripting, howitallworks)

GitHub: #5077, #5155, #5156, #5128, #5236, #1229, netbirdio/pfsense-netbird releases