DEV Community

Cover image for Self-Hosting Netbird: A Privacy-First Alternative to Managed Overlay Networks
patrickbloem-it
patrickbloem-it

Posted on

Self-Hosting Netbird: A Privacy-First Alternative to Managed Overlay Networks

#networking #security #devops #opensource

Self-Hosting Netbird: A Privacy-First Alternative to Managed Overlay Networks

As infrastructure engineers in regulated environments, we often face a dilemma: modern overlay network solutions like Tailscale and Twingate offer excellent user experience, but their centralized control planes raise compliance concerns. For organizations operating under strict data governance frameworks (GDPR, BSI IT-Grundschutz, sector-specific regulations), self-hosted alternatives become a necessity rather than a preference.

This article documents a production-ready deployment of Netbird, an open-source WireGuard-based overlay network with a self-hosted management server, hardened using CrowdSec for threat detection.

Why Self-Hosted Overlay Networks?

The Managed Service Trade-Off

Managed solutions like Tailscale and Twingate provide:

  • Zero-configuration deployment
  • Automatic NAT traversal
  • Centralized access control
  • Enterprise SSO integration

However, they introduce architectural dependencies:

Aspect Managed (Tailscale/Twingate) Self-Hosted (Netbird)
Control Plane Location US/Cloud Provider On-premises/Private VPS
Metadata Exposure Connection logs, peer IPs visible to provider Fully isolated
Data Sovereignty Dependent on provider's infrastructure Complete control
Vendor Lock-In Proprietary coordination protocol Open protocol (WireGuard)
Audit Trail Provider-controlled Self-managed

For public sector entities or organizations handling sensitive data, the control plane location becomes a compliance blocker.

Netbird Architecture Overview

Netbird decouples the control plane from the data plane:

┌─────────────────────────────────────────┐
│ Management Server (Self-Hosted) │
│ ├─ Peer Registration & Authentication │
│ ├─ Network Policy Distribution │
│ └─ STUN/TURN Coordination (Coturn) │
└─────────────────────────────────────────┘
↓ (Metadata only)
┌─────────────────────────────────────────┐
│ Peer-to-Peer WireGuard Tunnels │
│ (Direct connections, no relay) │
└─────────────────────────────────────────┘

Key Properties:

  • No traffic routing through management server: After initial coordination, peers establish direct WireGuard tunnels.
  • STUN/TURN fallback: Only used when direct connections fail (corporate firewalls, symmetric NAT).
  • Identity Provider integration: Uses OIDC (OpenID Connect) for authentication—works with Zitadel, Keycloak, Authentik.

Security Hardening with CrowdSec

Standard Netbird deployments expose management APIs and STUN/TURN services to the internet. To mitigate brute-force attacks and resource exhaustion, we integrate CrowdSec, a collaborative intrusion prevention system.

CrowdSec Integration Benefits

  1. Custom Log Parsing: Netbird's Go-based logging requires custom Grok patterns to detect authentication failures.
  2. Behavioral Analysis: Leaky bucket scenarios identify repeated failed peer login attempts.
  3. Firewall Enforcement: Direct iptables/nftables integration blocks malicious IPs before they reach application logic.
  4. Community Intelligence: Shares threat data with CrowdSec's global blocklist (opt-in).

Example Scenario: Detect 5+ Netbird peer authentication failures within 30 minutes → ban source IP for 48 hours.

Deployment Architecture

The stack I maintain consists of:

  • Caddy: Reverse proxy with automatic TLS (Let's Encrypt).
  • Netbird Management: Peer coordination, policy enforcement.
  • Zitadel: Self-hosted OIDC identity provider (can be replaced with Authentik/Keycloak).
  • Coturn: STUN/TURN server for NAT traversal (network-isolated via explicit port bindings).
  • CrowdSec + Firewall Bouncer: Real-time threat blocking.

Configuration Philosophy:

  • Avoid network_mode: host for service isolation.
  • Use explicit IPv4/IPv6 port bindings instead of wildcard listeners.
  • Log rotation limits (100MB per container) to prevent disk exhaustion.

The full Docker Compose configuration is available in my repository:

→ Netbird-self-hosted-stack on GitHub

Coturn Hardening: A Critical Detail

Many Netbird guides recommend deploying Coturn with network_mode: host for simplicity. This bypasses Docker's network isolation and exposes the host directly.

Our approach: Explicit port binding to public IP addresses only.

coturn:
image: coturn/coturn:latest
networks: [netbird]
ports:

  • '${PUBLIC_IP}:3478:3478/udp'
  • '${PUBLIC_IP}:3478:3478/tcp'
  • '${PUBLIC_IP}:5349:5349/tcp'
  • '${PUBLIC_IP}:49152-65535:49152-65535/udp' volumes:
  • ./config/turnserver.conf:/etc/turnserver.conf:ro

Impact:

  • Container remains within Docker's bridge network.
  • CrowdSec firewall rules apply uniformly across all services.
  • No accidental exposure of host services on ephemeral ports.

CrowdSec Custom Parsers

Netbird's JSON-formatted logs don't match default CrowdSec parsers. Custom Grok patterns are required.

Example: Netbird Management Authentication Failure Parser

/etc/crowdsec/parsers/s01-parse/netbird-auth.yaml
filter: "evt.Parsed.program == 'netbird-management'"
name: patrickbloem/netbird-auth-parser
nodes:

grok:
pattern: '%{TIMESTAMP_ISO8601:timestamp}.failed logging in peer %{DATA:peer_id}.: %{GREEDYDATA:failure_reason}'
apply_on: message
statics:

meta: log_type
value: netbird_auth_failure

Corresponding Scenario:

/etc/crowdsec/scenarios/netbird-brute-force.yaml
type: leaky
name: patrickbloem/netbird-auth-brute-force
filter: "evt.Meta.log_type == 'netbird_auth_failure'"
leakspeed: "30m"
capacity: 5
labels:
remediation: true

Full parser configurations are included in the repository.

Operational Results

After deploying this stack on a Hetzner VPS (Ubuntu 24.04 LTS):

  • Resource Usage: 0.12 load average, ~12% RAM utilization.
  • Threat Mitigation: ~28,000 IPs blocked via CrowdSec (CAPI + local decisions).
  • SSH Attack Reduction: Changing SSH to port 2222 + CrowdSec reduced attacks from ~40/day to <1/day.
  • Zero False Positives: No legitimate Netbird clients blocked after 3 months of operation.

Comparison: Netbird vs. Tailscale vs. Twingate

Feature Netbird (Self-Hosted) Tailscale Twingate
Data Plane Direct WireGuard Direct WireGuard Relay-based (no P2P)
Control Plane Location Self-hosted Tailscale Inc. (US) Twingate Inc. (US)
Authentication Self-hosted OIDC Tailscale SSO Twingate SSO
Metadata Visibility Zero (internal only) Provider has access Provider has access
Cost (10 users) VPS cost (~€5/month) Free tier Starts at $5/user/month
Audit Compliance Full control Trust-based Trust-based
Custom Policies ACL rules (JSON) ACL tags Application policies

When to Choose Self-Hosting

Self-hosting Netbird makes sense when:

  1. Regulatory Compliance: You operate under GDPR, HIPAA, or government-specific frameworks requiring data sovereignty.
  2. Zero Trust Architecture: You need proof that no third party can access connection metadata.
  3. Audit Requirements: Internal security audits demand full control over authentication logs.
  4. Cost Optimization: You already maintain infrastructure (VPS/on-prem servers) and can absorb operational overhead.

When managed services are better:

  • Small teams (<20 users) without dedicated DevOps resources.
  • Organizations comfortable with US-based SaaS providers.
  • Environments requiring enterprise support SLAs.

Getting Started

The deployment process is documented in the repository README:

  1. Clone the repository:
    git clone https://github.com/patrickbloem-it/Netbird-self-hosted-stack.git
    cd Netbird-self-hosted-stack

  2. Initialize directory structure:
    chmod +x init.sh
    ./init.sh

  3. Configure environment variables:
    cp .env.example .env
    nano .env # Set DOMAIN, PUBLIC_IP, secrets

  4. Deploy the stack:
    docker compose up -d

  5. Generate CrowdSec bouncer key:
    docker compose exec crowdsec cscli bouncers add firewall-bouncer

Add key to .env as CROWDSEC_BOUNCER_KEY
docker compose up -d --force-recreate cs-firewall-bouncer

Conclusion

Self-hosting Netbird provides a viable path to compliant overlay networking without sacrificing usability. The integration with CrowdSec demonstrates that security hardening can be achieved without custom application code—by leveraging log-based threat detection at the infrastructure layer.

For organizations where data sovereignty is non-negotiable, this stack offers a production-ready alternative to managed services.

Repository: github.com/patrickbloem-it/Netbird-self-hosted-stack

This article reflects lessons learned from deploying overlay networks in public sector environments. Configurations are provided as-is for educational purposes and should be reviewed against your organization's specific security policies before production deployment.

Top comments (0)