NetBird MSP Appliance

Self-Hosted Multi-Tenant NetBird Management Platform

A management solution for running isolated NetBird instances for your MSP business. Manage all your customers' NetBird networks from a single web interface.

---

Table of Contents

• Features
• Architecture
• System Requirements
• Prerequisites
• Quick Start
• Configuration
• Usage
• API Documentation
• Troubleshooting
• Updates
• Security Best Practices
• License

---

Features

Core

• Multi-Tenant Management — Deploy and manage isolated NetBird instances per customer
• Complete Isolation — Each customer gets their own NetBird stack with separate data
• One-Click Deployment — Deploy new customer instances in under 2 minutes
• Nginx Proxy Manager Integration — Automatic SSL certificates and reverse proxy setup
• SSL Certificate Modes — Choose between per-customer Let's Encrypt certificates or a shared wildcard certificate
• Docker-Based — Everything runs in containers for easy deployment

Dashboard

• Modern Web UI — Responsive Bootstrap 5 interface
• Real-Time Monitoring — Container status, health checks, resource usage
• Container Logs — View logs per container directly in the browser
• Start / Stop / Restart — Control customer instances from the dashboard
• Customer Status Tracking — Automatic status sync (active / inactive / error)

Multi-Language (i18n)

• English and German — Full UI translation
• Global Default Language — Set a system-wide default language in Settings > Branding
• Per-User Language — Each user can have their own preferred language
• Language Priority — User preference > System default > Browser language

Customization

• Branding — Configure platform name, subtitle, and logo via Settings
• Login Page — Branding is applied to the login page automatically
• Configurable Docker Images — Use custom or specific NetBird image versions

Security

• JWT Authentication — Token-based API authentication
• Multi-Factor Authentication (MFA) — Optional TOTP-based MFA for all local users, activatable in Security settings
• Azure AD / OIDC — Optional single sign-on via Microsoft Entra ID (exempt from MFA)
• Encrypted Credentials — NPM passwords, relay secrets, and TOTP secrets are Fernet-encrypted at rest
• User Management — Create, edit, delete admin users, reset passwords and MFA

---

Architecture

+-------------------------------------------------------------+
|                    NetBird MSP Appliance                      |
|                                                               |
|  +--------------+    +--------------+   +---------------+    |
|  |   Web GUI    |--->|  FastAPI     |-->|   SQLite DB   |    |
|  |  (Bootstrap) |    |   Backend    |   |               |    |
|  +--------------+    +--------------+   +---------------+    |
|                             |                                 |
|         +-------------------+-------------------+            |
|         v                   v                   v             |
|  +-------------+    +-------------+    +---------------+     |
|  |   Docker    |    |    NPM      |    |   Template    |     |
|  |   Engine    |    |     API     |    |   Renderer    |     |
|  +-------------+    +-------------+    +---------------+     |
+-------------------------------------------------------------+
                            |
        +-------------------+-------------------+
        v                                       v
+------------------+                  +------------------+
|  Customer 1      |                  |  Customer N      |
|  +------------+  |                  |  +------------+  |
|  | Management |  |                  |  | Management |  |
|  | Signal     |  |      ...        |  | Signal     |  |
|  | Relay      |  |                  |  | Relay      |  |
|  | Dashboard  |  |                  |  | Dashboard  |  |
|  | Caddy      |  |                  |  | Caddy      |  |
|  +------------+  |                  |  +------------+  |
+------------------+                  +------------------+
  kunde1.domain.de                      kundeN.domain.de
  UDP 3478                              UDP 3478+N-1

Components per Customer Instance (5 containers):

• Management — API and network state management
• Signal — WebRTC signaling for peer connections
• Relay — STUN/TURN server for NAT traversal (requires public UDP port)
• Dashboard — Web UI for end-users
• Caddy — Reverse proxy / entry point for the customer stack

All services are accessible via HTTPS through Nginx Proxy Manager, except the Relay STUN port which requires direct UDP access.

---

System Requirements

Hardware Scaling

Based on real-world measurements: 2 customers (11 containers) use ~220 MB RAM.

Per customer instance (5 containers): ~100 MB RAM

Customers	Container RAM	Recommended Total	vCPU	Storage
10	~1.0 GB	2 GB	2	20 GB
25	~2.5 GB	4 GB	2	50 GB
50	~5.0 GB	8 GB	4	100 GB
100	~10.0 GB	16 GB	8	200 GB
200	~20.0 GB	32 GB	16	500 GB

Note: "Recommended Total" includes OS overhead and headroom. SSD/NVMe storage is recommended for Docker performance.

Port Requirements

Port	Protocol	Purpose
8000	TCP	NetBird MSP Appliance Web UI
9000+	TCP	NetBird Web Management per customer (only internal, one per customer, increments by 1)
3478+	UDP	STUN/TURN relay per customer (one per customer, increments by 1)

Example for 3 customers:

Customer	Dashboard (TCP)	Relay (UDP)
Kunde 1	9001	3478
Kunde 2	9002	3479
Kunde 3	9003	3480

Your firewall must allow both the TCP dashboard ports and the UDP relay ports!

---

Prerequisites

The following tools and services must be available before running the installer.

Required on the Host

Tool	Purpose	Check Command
Linux OS	Ubuntu 22.04+, Debian 12+, or similar	cat /etc/os-release
sudo / root	Installation requires root privileges	sudo -v
curl	Used by the installer to install Docker	curl --version
git	Clone the repository	git --version
openssl	Generate encryption keys during install	openssl version

Installed Automatically

Tool	Purpose	Notes
Docker Engine 24.0+	Container runtime	Installed by install.sh if missing
Docker Compose Plugin	Multi-container orchestration	Installed with Docker

External Services

Service	Purpose	Notes
Nginx Proxy Manager	Reverse proxy + SSL certificates	Must be running and accessible from the host. Can be on the same server or a separate one.
Wildcard DNS	Route *.yourdomain.com to the server	Configure *.yourdomain.com as an A record pointing to your server IP

Install Prerequisites (Ubuntu/Debian)

sudo apt update
sudo apt install -y curl git openssl

---

Quick Start

1. Clone the Repository

git clone https://git.0x26.ch/BurgerGames/NetBirdMSP-Appliance.git
cd NetBirdMSP-Appliance

2. Run the Interactive Installation Script

chmod +x install.sh
sudo ./install.sh

The installer will interactively ask you for:

• Admin username and password
• Admin email address
• Base domain (e.g., yourdomain.com)
• Nginx Proxy Manager API URL, email, and password
• Data directory location
• NetBird Docker images (optional customization)

No manual .env file editing required! All configuration is stored in the database and editable via the Web UI.

The installer will then:

• Check system requirements
• Install Docker if needed
• Create directories and Docker network
• Generate encryption keys
• Build and start all containers
• Seed configuration into the database
• Optionally configure the firewall (ufw)

3. Access the Web Interface

After installation completes, open your browser:

http://your-server-ip:8000

Login with the credentials you provided during installation.

4. Deploy Your First Customer

1. Click "New Customer" button
2. Fill in customer details (name, subdomain, email, max devices)
3. Click "Deploy"
4. Wait ~60-90 seconds
5. Done!

The system will automatically:

• Assign a unique UDP port for the relay
• Generate all config files from templates
• Start the 5 Docker containers
• Create NPM proxy hosts with SSL
• Provide the setup URL for the customer

---

Configuration

Environment Variables

The installer generates a minimal .env file with container-level variables only:

SECRET_KEY=<auto-generated>
DATABASE_PATH=/app/data/netbird_msp.db
DATA_DIR=/opt/netbird-instances
DOCKER_NETWORK=npm-network
LOG_LEVEL=INFO
WEB_UI_PORT=8000
HOST_IP=<your-server-ip>

All application settings (domain, NPM credentials, Docker images, branding, etc.) are stored in the SQLite database and editable via the Web UI under Settings.

Web UI Settings

Available under Settings in the web interface:

Tab	Settings
System	Base domain, admin email, Docker images, port ranges, data directory
NPM Integration	NPM API URL, login credentials, SSL certificate mode (Let's Encrypt / Wildcard), wildcard certificate selection
Branding	Platform name, subtitle, logo upload, default language
Users	Create/edit/delete admin users, per-user language preference, MFA reset
Azure AD	Azure AD / Entra ID SSO configuration
Security	Change admin password, enable/disable MFA globally, manage own TOTP
Monitoring	System resources, Docker stats

Changes are applied immediately without restart.

---

Usage

Managing Customers

Create a New Customer

1. Dashboard > New Customer
2. Fill in details
3. Click Deploy
4. Share the setup URL with your customer

View Customer Details

• Click on customer name in the list
• See deployment status, container health, logs
• Copy setup URL and credentials

Start / Stop / Restart Containers

• Use the action buttons in the customer detail view
• Stopping all containers sets the customer status to "inactive"
• Starting containers sets the status back to "active"

Delete a Customer

• Click Delete > Confirm
• All containers, data, and NPM entries are removed

Monitoring

The dashboard shows:

• System Overview — Total customers, active/inactive, errors
• Resource Usage — RAM, CPU per container
• Container Health — Running/stopped per container with color-coded status
• Deployment Logs — Action history per customer

Language Settings

• Switch language — Use the language switcher in the top navigation bar
• Per-user default — Set in Settings > Users during user creation
• System default — Set in Settings > Branding

Multi-Factor Authentication (MFA)

TOTP-based MFA can be enabled globally for all local users. Azure AD users are not affected (they use their own MFA).

Enable MFA

1. Go to Settings > Security
2. Toggle "Enable MFA for all local users"
3. Click "Save MFA Settings"

First Login with MFA

When MFA is enabled and a user logs in for the first time:

1. Enter username and password as usual
2. A QR code is displayed — scan it with an authenticator app (Google Authenticator, Microsoft Authenticator, Authy, etc.)
3. Enter the 6-digit code from the app to complete setup

Subsequent Logins

1. Enter username and password
2. Enter the 6-digit code from the authenticator app

Admin MFA Management

• Reset a user's MFA — In Settings > Users, click "Reset MFA" to force re-enrollment on next login
• Disable own TOTP — In Settings > Security, click "Disable my TOTP" to remove your own MFA setup
• Disable MFA globally — Uncheck the toggle in Settings > Security to allow login without MFA

SSL Certificate Mode

The appliance supports two SSL certificate modes for customer proxy hosts, configurable under Settings > NPM Integration:

Let's Encrypt (default)

Each customer gets an individual Let's Encrypt certificate via HTTP-01 validation. This is the default behavior and requires no additional setup beyond a valid admin email.

Wildcard Certificate

Use a pre-existing wildcard certificate (e.g. *.yourdomain.com) already uploaded in NPM. All customer proxy hosts share this certificate — no per-customer LE validation needed.

Setup:

1. Upload a wildcard certificate in Nginx Proxy Manager (e.g. via DNS challenge)
2. Go to Settings > NPM Integration
3. Set SSL Mode to "Wildcard Certificate"
4. Click the refresh button to load certificates from NPM
5. Select your wildcard certificate from the dropdown
6. Click Save NPM Settings

New customer deployments will automatically use the selected wildcard certificate.

---

API Documentation

The appliance provides a REST API.

Authentication

curl -X POST http://localhost:8000/api/auth/token \
  -d "username=admin&password=yourpassword"

Endpoints

Full interactive documentation available at:

http://your-server:8000/api/docs

Common Endpoints:

POST   /api/customers              # Create customer + deploy
GET    /api/customers              # List all customers
GET    /api/customers/{id}         # Get customer details
PUT    /api/customers/{id}         # Update customer
DELETE /api/customers/{id}         # Delete customer

POST   /api/customers/{id}/start   # Start containers
POST   /api/customers/{id}/stop    # Stop containers
POST   /api/customers/{id}/restart # Restart containers
GET    /api/customers/{id}/logs    # Get container logs
GET    /api/customers/{id}/health  # Health check

GET    /api/settings/branding      # Get branding (public, no auth)
GET    /api/settings/npm-certificates # List NPM SSL certificates
PUT    /api/settings               # Update system settings
GET    /api/users                  # List users
POST   /api/users                  # Create user
POST   /api/users/{id}/reset-mfa   # Reset user's MFA

POST   /api/auth/mfa/setup         # Generate TOTP secret + QR code
POST   /api/auth/mfa/setup/complete # Verify first TOTP code
POST   /api/auth/mfa/verify        # Verify TOTP code on login
GET    /api/auth/mfa/status        # Get MFA status
POST   /api/auth/mfa/disable       # Disable own TOTP

Example: Create Customer via API

curl -X POST http://localhost:8000/api/customers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "subdomain": "acme",
    "email": "admin@acme.com",
    "max_devices": 20
  }'

---

Troubleshooting

Customer deployment fails

Symptom: Status shows "error" after deployment

Solutions:

• Check Docker logs: docker logs netbird-msp-appliance
• Verify NPM is accessible from the appliance container
• Check available UDP ports: ss -ulnp | grep 347
• View detailed logs in the customer detail page (Logs tab)

NetBird clients can't connect

Symptom: Clients show "relay unavailable"

Solutions:

• Most common: UDP port not open in firewall

  sudo ufw allow 3478/udp
  

• Verify relay container is running: docker ps | grep relay

NPM integration not working

Symptom: Proxy hosts or SSL certificates not created

Solutions:

• Verify NPM email and password are correct in Settings
• Check NPM is on same Docker network (npm-network)
• Check NPM logs for errors

Debug Mode

Enable debug logging:

# In your .env file:
LOG_LEVEL=DEBUG

# Restart the appliance:
docker compose restart

View logs:

docker logs -f netbird-msp-appliance

---

Updates

Updating the Appliance

cd /opt/netbird-msp
git pull
docker compose down
docker compose up -d --build

The database migrations run automatically on startup.

Updating NetBird Images

Via the Web UI:

1. Settings > System Configuration
2. Change image tags (e.g., netbirdio/management:0.35.0)
3. Click "Save"
4. Re-deploy individual customers to apply the new images

---

Security Best Practices

1. Enable MFA — activate TOTP-based multi-factor authentication in Settings > Security
2. Change default credentials immediately after installation
3. Use strong passwords (12+ characters recommended)
4. Keep NPM credentials secure — they are stored encrypted in the database
5. Enable firewall and only open required ports (TCP 8000, UDP relay range)
6. Use HTTPS — put the MSP appliance behind a reverse proxy with SSL
7. Regular updates — both the appliance and NetBird images
8. Backup your database — data/netbird_msp.db contains all configuration
9. Monitor logs — check for suspicious activity
10. Restrict access — use VPN or IP whitelist for the management interface

---

Performance Tuning

For 100+ Customers

# Increase Docker ulimits — add to /etc/docker/daemon.json
{
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 64000,
      "Soft": 64000
    }
  }
}

# Restart Docker
sudo systemctl restart docker

# Increase inotify limits
echo "fs.inotify.max_user_instances=512" | sudo tee -a /etc/sysctl.conf
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

---

License

MIT License — see LICENSE file for details.

---

Built With AI

This software was developed with Claude Code (Anthropic Claude Opus 4.6) — from architecture and backend logic to frontend UI and deployment scripts.

Acknowledgments

• Claude Code — AI-powered software development by Anthropic
• NetBird — Open-source VPN solution
• FastAPI — High-performance Python framework
• Nginx Proxy Manager — Reverse proxy management