Routing Peer Deployment Options

Executive Summary

NetBird routing peers can be deployed via Hyper-V VMs, Docker containers, or natively on pfSense. Each option carries meaningful trade-offs. The recommended architecture is Hyper-V VMs (Ubuntu 24.04) at both sites for maximum reliability, with Docker/Portainer as a viable secondary option. Azure Container Instances and Azure Container Apps are both non-viable because they do not support NET_ADMIN capabilities or privileged containers. The pfSense native option works but carries operational risk from packages being removed during pfSense upgrades.

Options Comparison

Boulder Site

Option	Pros	Cons	Recovery Time
Hyper-V VM (Ubuntu 24.04)	Full Linux support; systemd auto-restart; Hyper-V snapshots; standard apt update workflow; no upgrade removal risk	Requires dedicated VM	<2 min (automatic)
pfSense native (Netgate 6100)	Single device; pfSense UI integration; direct LAN access; AMD64 compatible	Package NOT in official repo; removed on pfSense upgrades; potential WireGuard package conflicts	15-60 min (manual after upgrades)
Docker/Portainer	Lightweight; managed via Portainer UI; easy redeployment	Documented routing issues (GitHub #947, #5391, #5593); host networking required; shared resources	1-5 min (crash) to investigation (routing bugs)
Azure Container Instance	Cloud-hosted	NON-VIABLE: No NET_ADMIN/privileged support	N/A
Azure Container Apps	Serverless	NON-VIABLE: No privileged mode or NET_ADMIN	N/A

Honolulu Site

Option	Pros	Cons	Recovery Time
Hyper-V VM (Ubuntu 24.04)	Same benefits as Boulder	Requires dedicated VM	<2 min (automatic)
Docker/Portainer	Lightweight; Portainer-managed	Same Docker routing concerns	1-5 min
Azure Container Instance / Apps	Cloud-hosted	NON-VIABLE	N/A

Note: No pfSense option for Honolulu since the PA-2020 is Palo Alto (not pfSense).

Hyper-V VM (Recommended)

Resource Requirements: 1 vCPU, 1-2 GB RAM, 10 GB disk (Ubuntu 24.04 minimal + NetBird)

Why this is the best option:

Linux is the primary supported platform for NetBird routing peers. All documented examples and community deployments use Linux.
Systemd service management provides automatic restart on crash. Hyper-V provides automatic VM startup on host boot.
Standard apt update && apt upgrade workflow. No special procedures.
Hyper-V checkpoints/snapshots enable instant rollback.
No risk of package removal during OS upgrades.
Minimal resource cost on existing Hyper-V infrastructure.

HA Recommendation: Deploy routing peers on BOTH Hyper-V hosts per site for automatic failover:

Boulder: Primary on DATA001, secondary on DATA007
Honolulu: Primary on DATA003, secondary on DATA004

NetBird automatically selects one routing peer based on metric priority and fails over to the backup if the primary becomes unavailable. This is a free community feature — no enterprise license required.

Docker Container Routing Peer

Officially supported by NetBird with the netbirdio/netbird Docker image.

Required docker-compose configuration:

services:
  netbird-client:
    container_name: netbird-client
    image: netbirdio/netbird:latest
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN
      - SYS_RESOURCE
    devices:
      - /dev/net/tun
    network_mode: host
    environment:
      - NB_SETUP_KEY=<SETUP KEY>
    volumes:
      - netbird-client:/var/lib/netbird
    restart: unless-stopped

Key requirements:

network_mode: host is critical — bridge mode causes namespace isolation issues
Host must have the TUN kernel module loaded (modprobe tun)
Recent Portainer versions handle cap_add correctly; older versions may not

Known Issues:

Recurring nftables bugs (GitHub #947, #5391, #5593 in v0.66.4): “ICMP works but TCP fails” pattern
Docker routing peers work for many users but carry higher risk than native Linux installations
Rootless mode available but has limitations (no DNS support, requires SOCKS5 proxy)

pfSense Native (Netgate 6100)

The Netgate 6100 uses an Intel Atom C3558 (AMD64/x86_64). Official x86_64 packages install directly.

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

Package	Version	Architectures
NetBird client	0.66.4	x86_64, aarch64
pfSense GUI package	0.2.2	x86_64, aarch64

Critical Limitation: Packages are removed during pfSense upgrades. Third-party packages installed from non-Netgate repositories are automatically removed during the upgrade process. After each pfSense upgrade: re-download packages, re-install via pkg add -f, verify configuration.

Additional Considerations:

Package is NOT in the official pfSense package manager (under review since Aug 2025)
FreeBSD routing peer support may require the “FakeBSD” workaround depending on management server version
Running two WireGuard management layers (pfSense WireGuard package + NetBird) on one system is untested
pfSense-netbird package at v0.1.25 is considered early-adopter status

Performance: Intel Atom C3558 handles NetBird routing peer easily (~50-100m CPU). No performance concerns alongside normal pfSense operations.

Azure Container Options (Non-Viable)

Azure Container Instances: Hyper-V isolation blocks all kernel operations. NET_ADMIN, SYS_ADMIN, privileged containers, and /dev/net/tun access are all prohibited.

Azure Container Apps: Sandboxed environment. Privileged mode and NET_ADMIN capability not supported. TUN/TAP interface creation fails with “Operation not permitted.”

Neither platform can host routing peers.

HA Routing Peer Failover

NetBird has native automatic failover for routing peers. This is a free community feature available in all editions.

How it works:

Create a network route (e.g., Boulder LAN 10.15.0.0/24)
Add multiple routing peers with different metrics (lower = higher priority)
Clients automatically select the best available routing peer
If the primary goes offline, clients failover to the next peer

Configuration approaches:

Routing Group: Group containing multiple routing peers. “Groups with multiple peers automatically provide high availability.”
Individual peers: Add multiple peers to the same route with different metrics.

Known issues: Route flapping reported with HA pairs when latency scores are similar (#2150, fixed). Intermittent connectivity loss to routing peers requiring manual restart reported (#4769, open).

Resource Requirements Summary

Deployment	CPU	RAM	Disk	Update Method
Hyper-V VM	1 vCPU	1-2 GB	10 GB	`apt update && apt upgrade`
Docker container	~100m	128 MB	Minimal	`docker pull` + redeploy
pfSense native	Minimal (shared)	Minimal (shared)	Minimal	Manual SSH + pkg reinstall

Gaps & Uncertainties

FreeBSD routing peer official support: Unclear if the official pfSense-netbird package v0.1.25 includes the FakeBSD workaround or if the management server natively supports FreeBSD routing peers.
Docker routing peer nftables bugs: Issues #5391 and #5593 (v0.66.4) show recurring problems in containers.
Portainer cap_add compatibility: Older versions had implementation issues; current versions should work.
pfSense package inclusion timeline: No public timeline for acceptance into the official pfSense package repository.

Sources

Official: docs.netbird.io (Docker install, pfSense install, FaaS, Kubernetes routing peers, network-routes)

GitHub: netbirdio/pfsense-netbird v0.1.25, nhdIT/pfsense-netbird (unofficial), issues #947, #2200, #3138, #5462, #5391, #5593

Azure: learn.microsoft.com (ACI best practices, Container Apps VPN limitations)

pfSense: docs.netgate.com (upgrade guide, upgrade troubleshooting)