NetBird Platform
NetBird Platform Features & Architecture
Section titled “NetBird Platform Features & Architecture”Executive Summary
Section titled “Executive Summary”NetBird is a mature, actively-developed open-source WireGuard-based mesh VPN platform with 23,700+ GitHub stars, 131+ contributors, and 306+ releases as of March 2026. The latest version is v0.66.4 (March 11, 2026) with releases averaging 2-3 per week. The project is backed by a German company that received funding from the German Federal Ministry of Education and Research through the StartUpSecure program (November 2022), in partnership with CISPA Helmholtz Center for Information Security.
NetBird is a strong candidate for replacing Palo Alto GlobalProtect for GSISG’s 100+ user deployment. Its self-hosted architecture can run on modest hardware (1 vCPU / 2GB RAM minimum), it supports pfSense integration (via manual install, not yet in the official pfSense package manager), and it provides split DNS, network routing, and a built-in reverse proxy feature. The pfSense package (v0.1.25, March 15, 2026) ships both x86_64 and aarch64 builds with client v0.66.4 and GUI package v0.2.2. For a 100+ user deployment across two offices, the self-hosted option is viable on an Azure B2s (2 vCPU / 4GB RAM) VM with the embedded relay, using SQLite as the default database.
Findings
Section titled “Findings”1. Project Maturity & Release Status
Section titled “1. Project Maturity & Release Status”| Metric | Value |
|---|---|
| GitHub Stars | ~23,700 |
| Contributors | 131+ |
| Total Releases | 306+ |
| Latest Version | v0.66.4 (March 11, 2026) |
| Release Cadence | 2-3 per week (avg every 2-4 days) |
| Language | Go (96.5%) |
| License | BSD-3-Clause (client) + AGPLv3 (management/signal/relay, since v0.53.0) |
| Backing | German Federal Ministry of Education and Research / CISPA (StartUpSecure program, Nov 2022) |
The project is very actively maintained with a rapid release cadence. Major features ship roughly monthly (v0.60 in Nov 2025, v0.62 in Jan 2026, v0.65 in Feb 2026, v0.66 in late Feb 2026).
2. Self-Hosted Deployment Components
Section titled “2. Self-Hosted Deployment Components”| Component | Description | Required? | Resource Notes |
|---|---|---|---|
| Management Server | Core control plane — peer registration, auth, network map, policy enforcement, API | Yes | Lightweight Go binary; main CPU consumer during peer sync |
| Signal Server | WebRTC-style signaling for peer connection negotiation; encrypted candidate exchange | Yes | Low resource; embedded in combined server |
| Relay Server | QUIC/WebSocket relay for peers that cannot establish direct P2P | Yes | Embedded in combined server; most resource-intensive under load |
| STUN Server | Embedded in relay server; used for NAT type discovery and public IP detection | Yes (embedded) | Minimal overhead |
| Dashboard | Web UI for administration (embedded nginx) | Yes | Static files; minimal resources |
| Traefik | Reverse proxy for TLS termination (ports 80/443) | Yes (for self-hosted) | Standard Traefik resource profile |
| Identity Provider (IdP) | SSO authentication; embedded (v0.62+) or external | Optional | Embedded: minimal; External (Authentik/Keycloak): 2 vCPU + 2GB RAM additional |
| Database | SQLite (default) or PostgreSQL (for 300+ peers) | Yes | SQLite for most deployments; PostgreSQL for large scale |
Architecture (v0.62+):
The unified netbird-server container combines management, signal, relay, and embedded STUN. Built-in local user management eliminates the mandatory external IdP. Total: 3-4 containers (server, dashboard, traefik, optional DB), ~1GB RAM minimum.
Minimum Infrastructure Requirements (from official docs):
- 1 Linux VM with at least 1 vCPU and 2GB RAM
- TCP ports 80, 443 publicly accessible
- UDP port 3478 publicly accessible
- A public domain name pointing to the VM’s IP
- Docker Compose installed
3. Azure VM Sizing for 100+ Peers
Section titled “3. Azure VM Sizing for 100+ Peers”B2s (2 vCPU, 4GB RAM) is the recommended VM size. B1ms (1 vCPU, 2GB RAM) meets the official minimum for the management plane but is risky under relay load or mass reconnection events. The extra $15/month eliminates scaling risk.
| Factor | B1ms (1 vCPU / 2 GB) | B2s (2 vCPU / 4 GB) |
|---|---|---|
| Normal operation | Sufficient | Comfortable |
| Mass reconnection event | CPU-constrained | Handles gracefully |
| Relay under load | Risk of CPU starvation | Adequate headroom |
| Future growth (150-250 peers) | Requires migration | Handles without changes |
| Monthly cost (pay-as-you-go) | ~$15.11 | ~$30.37 |
SQLite is adequate for 100-150 peers with periodic events.db cleanup. PostgreSQL becomes necessary at 300+ peers or 100+ policies.
The embedded relay handles the ~5-15% of connections that require relaying at this scale. A separate relay server is unnecessary and adds $15-30/month with no benefit.
Total Azure cost: ~$39/month pay-as-you-go or ~$28/month with 1-year reserved instance.
4. pfSense Package Status
Section titled “4. pfSense Package Status”The NetBird pfSense package is NOT in the official pfSense package manager but is available via manual installation.
| Detail | Status |
|---|---|
| Official pfSense repo | NOT available — PR submitted ~1 year ago (Aug 2025), pending review |
| Installation method | Manual pkg add from GitHub releases |
| pfSense package version | v0.1.25 (March 15, 2026) |
| Bundled NetBird client version | v0.66.4 |
| GUI package version | v0.2.2 |
| Architectures supported | x86_64 and aarch64 |
| FreeBSD ports | NetBird accepted into FreeBSD ports repository (Jun 2025) |
| Update mechanism | Manual download and reinstall of .pkg files |
Known Limitations on pfSense:
- NAT traversal conflict: pfSense’s automatic outbound NAT randomizes source ports, which can break NetBird’s NAT traversal. Requires manual static port NAT rule configuration.
- No automatic updates: Must manually download and install new versions.
- Packages removed on pfSense upgrades: Third-party packages are automatically removed during pfSense upgrades and must be reinstalled.
- WireGuard package conflicts: Installing NetBird alongside the existing pfSense WireGuard package is untested territory, as both manage WireGuard interfaces.
The Netgate 6100 at Boulder uses an Intel Atom C3558 (AMD64/x86_64). The official x86_64 packages install directly on this hardware with no workarounds required. ARM64 Netgate models (SG-1100, SG-2100, SG-3100) also have official aarch64 packages available.
5. Always-On Mode & Management Server Resilience
Section titled “5. Always-On Mode & Management Server Resilience”Always-On Mode
Section titled “Always-On Mode”Setup Key Peers (servers, routing peers, headless devices):
- No login expiration — tunnels stay up indefinitely
- No SSO interaction required
- Automatically reconnects after reboots (daemon auto-starts)
- Setup keys can be one-off or reusable, with optional expiration dates
SSO Peers (user workstations):
- Default session expiration: 24 hours (configurable from 1 hour to 180 days)
- Session expiration can be disabled globally or per-peer
- When session expires, tunnel is torn down and user must re-authenticate via browser
Management Server Down — What Happens?
Section titled “Management Server Down — What Happens?”| Scenario | Behavior |
|---|---|
| Existing P2P tunnels | Survive — WireGuard data plane is independent of management server |
| Existing relayed connections | Continue working as long as relay server is reachable |
| New peer connections | Cannot be established — peers need management server for initial configuration |
| Policy changes | Cannot be applied until management server returns |
| Peer reconnection after brief glitch | Generally works automatically |
| Peer reconnection after prolonged outage | Known issue — clients sometimes stay offline and require manual netbird up |
The management server maintains a control channel to each peer for configuration sync, not for data plane traffic. The data plane (WireGuard tunnels) operates independently once established.
6. NAT Traversal Capabilities
Section titled “6. NAT Traversal Capabilities”NetBird uses ICE (Interactive Connectivity Establishment) — the same protocol underlying WebRTC — for NAT traversal.
| NAT Type | P2P Likelihood | NetBird Behavior |
|---|---|---|
| Easy/Full Cone NAT (home routers) | High | Direct P2P via STUN discovery |
| Port-Restricted Cone NAT | Medium-High | P2P usually succeeds with hole punching |
| Symmetric NAT (corporate firewalls) | Low | Falls back to relay |
| CGNAT (mobile/ISP) | Low-Medium | Often relayed |
| 1:1 NAT (cloud VMs) | High | Behaves like easy NAT |
Relay System:
- Primary transport: QUIC (UDP-based, high performance)
- Fallback transport: WebSocket over TCP port 443 (for networks that block UDP)
- Both protocols are raced simultaneously — whichever succeeds first is used
- Relay traffic remains end-to-end encrypted via WireGuard
- Estimated >90% direct P2P in favorable conditions (based on similar technology benchmarks)
7. Networks vs. Network Routes
Section titled “7. Networks vs. Network Routes”| Feature | Networks (newer) | Network Routes (legacy) |
|---|---|---|
| Access control | Enforced by default | Bypassed by default |
| Resource types | IPs, domains, subnets | CIDR ranges only |
| Domain-based routing | Yes | No |
| Exit nodes | No | Yes |
| Overlapping routes | Limited | Full support |
| Recommended for new setups | Yes | Only for unsupported scenarios |
Networks is the recommended approach for GSISG’s site-to-site deployment. Each office would have a routing peer, a Network defined for the office LAN subnet, resources representing internal services, and policies controlling which users/groups can access which resources.
8. Split DNS Support
Section titled “8. Split DNS Support”NetBird fully supports split DNS (split-horizon DNS). Configure primary nameservers for internet DNS and match domain nameservers for internal domains. Custom DNS Zones (v0.63+) allow defining records directly in NetBird without external DNS infrastructure. Search domain expansion, distribution group-based application, and DNS failover are all supported.
Limitations: No query caching, match domain support requires macOS/Windows 10+/Linux with systemd-resolved, Android requires Private DNS disabled.
9. Built-in Reverse Proxy (v0.65+)
Section titled “9. Built-in Reverse Proxy (v0.65+)”Introduced in v0.65.0 (February 2026), the built-in reverse proxy exposes internal services to the public internet with automatic TLS, optional SSO/password/PIN authentication, and WireGuard tunnel routing. Available for both self-hosted (beta) and cloud. Could replace Cloudflare Tunnels for authenticated service exposure. Still in beta with known deployment issues.
10. Known Limitations
Section titled “10. Known Limitations”vs. Tailscale: Auto-reconnection less reliable, no Windows SYSTEM service mode (feature request open), smaller ecosystem, HA requires enterprise license, younger client with more rough edges.
NetBird Advantages over Tailscale: Full control plane self-hosting, complete data sovereignty, built-in reverse proxy with custom domains, GUI-based policy management, fully open server code, native MSP multi-tenant portal.
vs. Traditional VPNs (GlobalProtect): Less mature admin console, no FIPS 140-2/Common Criteria, no 24/7 TAC equivalent, no inline DLP/threat prevention, single flat IPv4 network (100.64.0.0/10), no IPv6 overlay, self-hosted HA requires enterprise license.
General Limitations:
- Single flat IPv4 network — all peers share 100.64.0.0/10
- No IPv6 overlay support
- Persistent keepalive fixed at 25 seconds (not configurable)
- Self-hosted HA requires enterprise license
- Some enterprise features are cloud-only
- DNS roaming issues possible when switching networks
Gaps & Uncertainties
Section titled “Gaps & Uncertainties”- Exact resource consumption at 100+ peers — No official benchmarks. Community reports are anecdotal.
- Direct vs. relayed connection percentages — No official statistics published.
- Enterprise license pricing — Custom pricing only; not publicly available.
- Management server HA architecture — Enterprise HA implementation details not publicly documented.
- Reverse proxy production readiness — Beta status with known authentication bugs.
Sources
Section titled “Sources”Official Documentation: docs.netbird.io (selfhosted-quickstart, scaling, networks, DNS, network-routes, pfSense install, NAT, reverse proxy, FAQ, CLI reference)
GitHub: github.com/netbirdio/netbird (releases, issues #1824, #5492), github.com/netbirdio/pfsense-netbird (releases)
Community: NetBird Forum, NetBird Knowledge Hub, comparison articles (shellfire.net, wz-it.com, algustionesa.com, defguard.net), self-hosting guides (dev.to, carlpearson.net)