Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Self-Hosted Netbird VPN Setup Guide

A complete guide to setting up a self-hosted Netbird mesh VPN with Authentik SSO integration.

Table of Contents

  1. Prerequisites
  2. Server Setup (VPS)
  3. Authentik SSO Integration
  4. Homelab Gateway Setup
  5. Client Setup
  6. Troubleshooting

Prerequisites

Required Infrastructure

  • VPS/Server with public IP address running Linux
  • Domain name with DNS configured
  • Traefik reverse proxy with Let’s Encrypt SSL
  • Authentik SSO server (optional but recommended)
  • Docker and Docker Compose installed

Network Requirements

  • Ports required on VPS:
    • 80/tcp - HTTP (Traefik)
    • 443/tcp - HTTPS (Traefik)
    • 3478/udp - STUN
    • Optional: 51820/udp - WireGuard (if using relay)

Server Setup (VPS)

Step 1: Run Netbird Installation Script

SSH into your VPS and run the official installation script:

curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Step 2: Configuration Choices

During installation, you’ll be prompted for:

  1. Domain: Enter your Netbird domain (e.g., netbird.example.com)
  2. Reverse proxy: Select [1] Existing Traefik
  3. External network: Enter your Traefik network name (e.g., web)
  4. HTTPS entrypoint: Enter your Traefik HTTPS entrypoint (usually websecure)
  5. Certificate resolver: Enter your Let’s Encrypt resolver name (e.g., letsencrypt)

The script will generate:

  • /root/docker-compose.yml - Netbird server containers
  • /root/config.yaml - Netbird configuration
  • /root/dashboard.env - Dashboard environment variables

Step 3: Start Netbird Containers

cd /root
docker compose up -d

Verify containers are running:

docker ps | grep netbird

You should see:

  • netbird-server - Management + Signal + Relay
  • netbird-dashboard - Web UI

Step 4: Configure Traefik Routes

If using the Traefik Docker provider, the installation script created labels automatically. However, if using an HTTP provider or file-based configuration, you’ll need to add routes manually.

For Traefik file provider, edit your dynamic_config.yml:

http:
  routers:
    # gRPC routes (highest priority)
    netbird-grpc:
      rule: "Host(`netbird.example.com`) && (PathPrefix(`/signalexchange.SignalExchange/`) || PathPrefix(`/management.ManagementService/`))"
      service: netbird-server-h2c
      entryPoints:
        - websecure
      priority: 20
      tls:
        certResolver: letsencrypt

    # Backend API routes (medium priority)
    netbird-backend:
      rule: "Host(`netbird.example.com`) && (PathPrefix(`/api`) || PathPrefix(`/oauth2`) || PathPrefix(`/relay`) || PathPrefix(`/ws-proxy/`))"
      service: netbird-server
      entryPoints:
        - websecure
      priority: 10
      tls:
        certResolver: letsencrypt

    # Dashboard (lowest priority - catch-all)
    netbird-dashboard:
      rule: "Host(`netbird.example.com`)"
      service: netbird-dashboard
      entryPoints:
        - websecure
      priority: 1
      tls:
        certResolver: letsencrypt

  services:
    netbird-dashboard:
      loadBalancer:
        servers:
          - url: "http://netbird-dashboard:80"

    netbird-server:
      loadBalancer:
        servers:
          - url: "http://netbird-server:80"

    netbird-server-h2c:
      loadBalancer:
        servers:
          - url: "h2c://netbird-server:80"

Restart Traefik:

docker restart traefik

Step 5: Initial Setup

  1. Navigate to https://netbird.example.com
  2. You should see the Netbird setup page
  3. Create the first admin account:
    • Name: Your name
    • Email: Your email
    • Password: Strong password (temporary - we’ll switch to SSO)
  4. Complete the setup

Important: This creates a local account with embedded Dex authentication. We’ll replace this with Authentik SSO next.

Authentik SSO Integration

Step 1: Create OAuth2 Provider in Authentik

  1. Log into Authentik (https://auth.example.com)
  2. Navigate to Applications → Providers → Create
  3. Select OAuth2/OpenID Provider
  4. Configure:
    • Name: Netbird
    • Authentication flow: default-authentication-flow
    • Authorization flow: default-provider-authorization-explicit-consent
    • Client type: Confidential
    • Redirect URIs/Origins (RegEx): 
      https://netbird.example.com/oauth2/callback
https://netbird.example.com/auth
https://netbird.example.com/silent-auth
    • Signing Key: authentik Self-signed Certificate
  5. Click Create
  6. Copy the Client ID and Client Secret - you’ll need these

Step 2: Create Application in Authentik

  1. Navigate to Applications → Applications → Create
  2. Configure:
    • Name: Netbird
    • Slug: netbird
    • Provider: Select the Netbird provider you just created
  3. Click Create

Step 3: Add Authentik as Identity Provider in Netbird

  1. Log into Netbird dashboard (https://netbird.example.com)
  2. Navigate to Settings → Identity Providers
  3. Click Add Identity Provider
  4. Select Authentik
  5. Configure:
    • Name: Authentik
    • Issuer URL: https://auth.example.com/application/o/netbird/
    • Client ID: Paste from Authentik
    • Client Secret: Paste from Authentik
    • Redirect/Callback URL: Copy this URL - you may need to add it to Authentik
  6. Click Add Provider

Step 4: Switch to Authentik Authentication

  1. Log out of Netbird
  2. Log back in using Authentik
  3. After successful login, navigate to Settings → Users
  4. Transfer ownership from the local admin account to your Authentik account
  5. Delete the local admin account

Netbird now uses Authentik SSO exclusively!

Homelab Gateway Setup

The gateway peer routes traffic from your VPN clients to your homelab network.

Step 1: Generate Setup Key

  1. In Netbird dashboard, navigate to Setup Keys
  2. Click Add Setup Key
  3. Configure:
    • Name: Homelab Gateway
    • Reusable: Enable (so you can use it multiple times)
    • Expires in: 7 days (or longer)
    • Ephemeral Peers: Disable (you want permanent registration)
  4. Click Create
  5. Copy the setup key

Step 2: Install Netbird Client on Homelab Server

For Docker/TrueNAS (recommended):

Create a new stack in Dockge or docker-compose:

services:
  netbird-client:
    image: netbirdio/netbird:latest
    container_name: netbird-client
    hostname: homelab-gateway
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN
      - SYS_RESOURCE
    devices:
      - /dev/net/tun
    environment:
      - NB_SETUP_KEY=YOUR_SETUP_KEY_HERE
      - NB_MANAGEMENT_URL=https://netbird.example.com
    volumes:
      - netbird-client:/var/lib/netbird

volumes:
  netbird-client:

Replace YOUR_SETUP_KEY_HERE with your actual setup key.

Deploy:

docker compose up -d

For native Linux installation:

curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --setup-key YOUR_SETUP_KEY_HERE --management-url https://netbird.example.com

Step 3: Configure Network Route

  1. In Netbird dashboard, navigate to Network Routes
  2. Click Add Route
  3. Configure:
    • Network: Your homelab subnet (e.g., 192.168.50.0/24)
    • Description: Homelab Network
    • Routing Peer: Select homelab-gateway
    • Metric: 9999 (low priority)
    • Distribution Groups: Leave empty (all peers can use it)
  4. Click Create

Now any Netbird client can access your entire homelab network through this gateway!

Client Setup

Mobile (Android/iOS)

  1. Install Netbird from:
    • Android: Google Play Store or F-Droid
    • iOS: App Store
  2. Open the app
  3. Configure:
    • Management URL: https://netbird.example.com
  4. Click Login
  5. Authenticate via Authentik SSO
  6. Grant VPN permissions when prompted

The app will connect automatically and you can now access your homelab from your phone!

Laptop (Linux)

Installation

Arch Linux:

yay -S netbird
# or
paru -S netbird

Debian/Ubuntu:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Any Linux:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Connect with DNS Disabled

To avoid DNS conflicts with your local/work network:

sudo netbird up --disable-dns

This connects to Netbird while preserving your local DNS settings.

Make DNS Disable Permanent

To automatically connect on boot without DNS override:

sudo systemctl edit netbird

Add:

[Service]
ExecStart=
ExecStart=/usr/bin/netbird service run --disable-dns

Save and exit, then:

sudo systemctl daemon-reload
sudo systemctl enable netbird
sudo systemctl start netbird

Verify Connection

netbird status

You should see:

  • Management: Connected
  • Signal: Connected
  • Peers: Shows your gateway and other clients
  • Networks: 192.168.50.0/24 (or your homelab subnet)

Test homelab access:

ping 192.168.50.1  # Replace with your homelab IP

Laptop (macOS)

  1. Download Netbird from netbird.io
  2. Install the .dmg package
  3. Open Netbird from Applications
  4. Configure:
    • Management URL: https://netbird.example.com
  5. Click Login
  6. Authenticate via Authentik
  7. Grant VPN permissions

Laptop (Windows)

  1. Download Netbird from netbird.io
  2. Run the installer
  3. Open Netbird from Start Menu
  4. Configure:
    • Management URL: https://netbird.example.com
  5. Click Login
  6. Authenticate via Authentik
  7. Grant VPN permissions

Troubleshooting

Server Issues

Dashboard not accessible:

  1. Check containers are running: docker ps | grep netbird
  2. Check Traefik routes are configured correctly
  3. Verify DNS points to your VPS IP
  4. Check Traefik logs: docker logs traefik

502 Bad Gateway:

  1. Ensure netbird-server and netbird-dashboard containers are running
  2. Verify they’re on the correct Docker network
  3. Check Traefik can reach the containers

OAuth errors during Authentik login:

  1. Verify redirect URIs match exactly in Authentik provider
  2. Check Client ID and Secret are correct
  3. Ensure Issuer URL ends with / (e.g., https://auth.example.com/application/o/netbird/)

Client Issues

Can’t connect to management server:

  1. Verify management URL: https://netbird.example.com
  2. Check firewall allows outbound HTTPS
  3. Ensure SSL certificate is valid

DNS broken after connecting (Linux):

  1. Disconnect: sudo netbird down
  2. Reconnect with DNS disabled: sudo netbird up --disable-dns
  3. Make it permanent using systemd override (see Linux client setup)

Can’t reach homelab:

  1. Verify network route exists in Netbird dashboard
  2. Check gateway peer is connected: netbird status
  3. Ping gateway peer: ping 100.86.236.236 (use actual gateway Netbird IP)
  4. Verify homelab subnet is correct (e.g., 192.168.50.0/24)

Connection shows as “Relayed” instead of “P2P”:

  • This is normal for peers behind symmetric NAT
  • Traffic goes through your VPS relay server
  • Still secure and functional, just slightly higher latency

Network Route Not Working

  1. Check route is enabled in Netbird dashboard
  2. Verify gateway peer is online
  3. Ensure gateway peer accepted the network route
  4. Check routing peer has proper network access
  5. Verify firewall on gateway allows traffic forwarding

Security Best Practices

  1. Use Authentik SSO: Centralized authentication with MFA support
  2. Enable MFA: Configure YubiKey or TOTP in Authentik
  3. Limit network routes: Only expose necessary subnets
  4. Use access control: Configure peer groups and policies in Netbird
  5. Monitor logs: Regularly check Netbird and Authentik logs
  6. Rotate setup keys: Set expiration dates on setup keys
  7. Review peer list: Regularly audit connected peers

Advanced Configuration

Multiple Network Routes

You can expose multiple networks:

  1. Create separate network routes for each subnet
  2. Assign different routing peers if needed
  3. Use distribution groups to control which clients can access which networks

Peer Groups and Policies

Control which peers can communicate:

  1. Create peer groups in Netbird dashboard
  2. Define access control policies
  3. Restrict peer-to-peer connections as needed

Custom DNS

Configure Netbird’s DNS for internal name resolution:

  1. Navigate to DNS in Netbird dashboard
  2. Add DNS nameservers
  3. Configure custom domains

High Availability

For production deployments:

  1. Run multiple Netbird server instances
  2. Use external PostgreSQL database
  3. Configure load balancer for management API
  4. Deploy multiple relay servers

Appendix: Architecture Overview

Network Topology

┌─────────────────┐
│   VPS Server    │
│  ┌───────────┐  │
│  │  Netbird  │  │
│  │  Server   │  │
│  └─────┬─────┘  │
│        │        │
└────────┼────────┘
         │
    ┌────┴────┐
    │         │
┌───▼──┐  ┌──▼───┐
│Client│  │Client│
│Peer 1│  │Peer 2│
└──────┘  └──┬───┘
             │
        ┌────▼─────┐
        │ Homelab  │
        │ Gateway  │
        └────┬─────┘
             │
      ┌──────▼──────┐
      │   Homelab   │
      │   Network   │
      │192.168.50.x │
      └─────────────┘

Component Responsibilities

Netbird Server (VPS):

  • Management API - peer registration and configuration
  • Signal server - WebRTC signaling for P2P connections
  • Relay server - fallback relay for NAT traversal
  • STUN server - NAT type detection

Netbird Dashboard:

  • Web UI for administration
  • User and peer management
  • Network route configuration
  • Access control policies

Gateway Peer:

  • Routes traffic to homelab network
  • Runs as Docker container or native service
  • Requires network_mode: host for routing

Client Peers:

  • Connect to Netbird management server
  • Establish P2P or relayed connections
  • Route homelab traffic through gateway
  • Optional: –disable-dns to preserve local DNS