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

Source: Dev.to

Introduction

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.

Managed vs. Self‑Hosted Overlay Networks

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

Netbird Architecture

┌─────────────────────────────────────────┐
│               Netbird                    │
│  ──► Control Plane (Management Server)   │
│  ──► Data Plane (WireGuard tunnels)      │
└─────────────────────────────────────────┘

Key Properties

• No traffic routing through the 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, etc.

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.

• Custom Log Parsing – Netbird’s Go‑based logging requires custom Grok patterns to detect authentication failures.
• Behavioral Analysis – leaky‑bucket scenarios identify repeated failed peer‑login attempts.
• Firewall Enforcement – direct iptables/nftables integration blocks malicious IPs before they reach application logic.
• 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.

Stack Overview

Configuration Philosophy

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

The full Docker‑Compose configuration is available in the repository:

➡️ Netbird‑self‑hosted‑stack on GitHub

Docker‑Compose Excerpt (Coturn)

coturn:
  image: coturn/coturn:latest
  restart: unless-stopped
  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

Why not network_mode: host?

• Keeps the container inside Docker’s bridge network.
• Allows CrowdSec firewall rules to apply uniformly across all services.
• Prevents accidental exposure of host services on ephemeral ports.

CrowdSec Integration

Netbird’s JSON‑formatted logs don’t match default CrowdSec parsers, so we provide custom Grok patterns.

Parser Example – netbird-auth.yaml

# /etc/crowdsec/parsers/s01-parse/netbird-auth.yaml
type: grok-patterns
name: netbird/auth-failure
description: Detect Netbird management authentication failures
grok:
  patterns:
    - '%{TIMESTAMP_ISO8601:timestamp} %{WORD:log_level} %{DATA:component} - Authentication failed for peer %{DATA:peer_id}'
  on_failure:
    - ignore

Corresponding Scenario – netbird-brute-force.yaml

# /etc/crowdsec/scenarios/netbird-brute-force.yaml
type: threshold
name: netbird/brute-force
description: Detect multiple authentication failures from the same IP
filter: "evt.Line contains 'Authentication failed'"
group_by: "source_ip"
threshold: 5
time_window: 30m
ban_duration: 48h

Full parser and scenario configurations are included in the repository.

Production Results (Hetzner VPS, Ubuntu 24.04 LTS)

Tip: Keep the .env file out of version control (git add .env → ignore via .gitignore).

Deploy the Stack

Use Docker Compose (or your preferred orchestrator) to bring up the services:

docker compose up -d
# or, if using Docker Swarm/Kubernetes, apply the provided manifests

Verify that all containers are running:

docker compose ps

Generate CrowdSec Bouncer Key

# Inside the CrowdSec container (or on the host if CrowdSec is installed locally)
docker exec -it crowdsec /usr/local/bin/crowdsec bouncer add
# The command will output a bouncer key, e.g.:
#   Bouncer key: 1234567890abcdef1234567890abcdef12345678

Copy the generated key.

Add Key to .env

Edit the .env file and set the CROWDSEC_BOUNCER_KEY variable:

CROWDSEC_BOUNCER_KEY=1234567890abcdef1234567890abcdef12345678

Restart the stack to apply the change:

docker compose restart crowdsec

Overview

Self‑hosting Netbird provides a production‑ready, compliant overlay network without sacrificing usability. By integrating CrowdSec, you gain security hardening through log‑based threat detection at the infrastructure layer—no custom application code required.

Why Use This Stack?

• Data sovereignty: Keeps all traffic and metadata within your controlled environment.
• Compliance: Meets strict public‑sector regulations (e.g., GDPR, NIS2).
• Flexibility: Works with existing CI/CD pipelines and on‑premise hardware.

Disclaimer: The configurations are provided as‑is for educational purposes. Review them against your organization’s security policies before deploying to production.

Further Reading

• Netbird Documentation
• CrowdSec Documentation

Happy networking! 🚀