NetBird MSP Appliance

🚀 Self-Hosted Multi-Tenant NetBird Management Platform

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

---

📋 Table of Contents

• Features
• Architecture
• System Requirements
• Quick Start
• Configuration
• Usage
• API Documentation
• Troubleshooting
• Contributing
• License

---

✨ Features

• 🎯 Multi-Tenant Management: Manage 100+ isolated NetBird instances from one dashboard
• 🔒 Complete Isolation: Each customer gets their own NetBird instance with separate databases
• 🌐 Nginx Proxy Manager Integration: Automatic SSL certificate management and reverse proxy setup
• 🐳 Docker-Based: Everything runs in containers for easy deployment and updates
• 📊 Web Dashboard: Modern, responsive UI for managing customers and deployments
• 🚀 One-Click Deployment: Deploy new customer instances in under 2 minutes
• 📈 Monitoring: Real-time status monitoring and health checks
• 🔄 Automated Updates: Bulk update NetBird containers across all customers
• 💾 Backup & Restore: Built-in backup functionality for all customer data
• 🔐 Secure by Default: Encrypted credentials, API tokens, and secrets management

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    NetBird MSP Appliance                    │
│                                                             │
│  ┌──────────────┐    ┌──────────────┐   ┌───────────────┐ │
│  │   Web GUI    │───▶│  FastAPI     │──▶│   SQLite DB   │ │
│  │  (Bootstrap) │    │   Backend    │   │               │ │
│  └──────────────┘    └──────────────┘   └───────────────┘ │
│                             │                              │
│         ┌───────────────────┼───────────────────┐         │
│         ▼                   ▼                   ▼          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐   │
│  │   Docker    │    │    NPM      │    │  Firewall   │   │
│  │   Engine    │    │     API     │    │   Manager   │   │
│  └─────────────┘    └─────────────┘    └─────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┴───────────────────┐
        ▼                                       ▼
┌──────────────────┐                  ┌──────────────────┐
│  Customer 1      │                  │  Customer 100    │
│  ┌────────────┐  │                  │  ┌────────────┐  │
│  │ Management │  │                  │  │ Management │  │
│  │   Signal   │  │       ...        │  │   Signal   │  │
│  │   Relay    │  │                  │  │   Relay    │  │
│  │  Dashboard │  │                  │  │  Dashboard │  │
│  └────────────┘  │                  │  └────────────┘  │
└──────────────────┘                  └──────────────────┘
  kunde1.domain.de                      kunde100.domain.de
  UDP 3478                              UDP 3577

Components per Customer Instance:

• Management Service: API and network state management
• Signal Service: WebRTC signaling for peer connections
• Relay Service: STUN/TURN server for NAT traversal (requires public UDP port)
• Dashboard: Web UI for end-users

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

---

💻 System Requirements

For 100 Customers (10-20 devices per customer)

Component	Minimum	Recommended	Notes
CPU	8 cores	16 cores	More cores = better concurrent deployment performance
RAM	64 GB	128 GB	~600 MB per customer instance + OS overhead
Storage	500 GB SSD	1 TB NVMe SSD	Fast I/O critical for Docker performance
Network	100 Mbps	1 Gbps	Dedicated server recommended
OS	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS	Other Debian-based distros work too

Resource Calculation Formula:

Per Customer Instance:
- Management: ~100 MB RAM
- Signal: ~50 MB RAM
- Relay: ~150 MB RAM
- Dashboard: ~100 MB RAM
Total: ~400-600 MB RAM per customer

For 100 customers: 40-60 GB RAM + 8 GB for OS + 8 GB for Appliance = ~64 GB minimum

Port Requirements:

• TCP 8000: NetBird MSP Appliance Web UI
• UDP 3478-3577: STUN/TURN relay ports (one per customer)
  • Customer 1: UDP 3478
  • Customer 2: UDP 3479
  • ...
  • Customer 100: UDP 3577

⚠️ Important: Your firewall must allow UDP ports 3478-3577 for full NetBird functionality!

Prerequisites:

• Docker Engine 24.0+ with Docker Compose plugin
• Nginx Proxy Manager (running separately or on same host)
• Domain with wildcard DNS (e.g., *.yourdomain.com → your server IP)
• Root or sudo access to the Linux VM

---

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/netbird-msp-appliance.git
cd netbird-msp-appliance

2. Run the Installation Script

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

The installer will:

• ✅ Check system requirements
• ✅ Install Docker if needed
• ✅ Create Docker network
• ✅ Generate secure secrets
• ✅ Build and start all containers
• ✅ Initialize the database

3. Complete the Setup Wizard

Open your browser and navigate to:

http://your-server-ip:8000

On first access, you'll be guided through:

1. Admin Account Creation: Set your admin username and password
2. System Configuration:
   • Base Domain (e.g., yourdomain.com)
   • Admin Email
   • NPM API URL (e.g., http://npm-host:81/api)
   • NPM API Token
3. Firewall Rules: Instructions for opening required UDP ports

4. Deploy Your First Customer

1. Click "New Customer" button
2. Fill in customer details:
   • Name
   • Subdomain (e.g., customer1 → customer1.yourdomain.com)
   • 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
• Start Docker containers
• Create NPM proxy hosts with SSL
• Provide the setup URL

---

⚙️ Configuration

Environment Variables

Create a .env file (or use the one generated by installer):

# Security
SECRET_KEY=your-secure-random-key-here
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password

# Nginx Proxy Manager
NPM_API_URL=http://nginx-proxy-manager:81/api
NPM_API_TOKEN=your-npm-api-token

# System
DATA_DIR=/opt/netbird-instances
DOCKER_NETWORK=npm-network
BASE_DOMAIN=yourdomain.com
ADMIN_EMAIL=admin@yourdomain.com

# NetBird Images (optional - defaults to latest)
NETBIRD_MANAGEMENT_IMAGE=netbirdio/management:latest
NETBIRD_SIGNAL_IMAGE=netbirdio/signal:latest
NETBIRD_RELAY_IMAGE=netbirdio/relay:latest
NETBIRD_DASHBOARD_IMAGE=netbirdio/dashboard:latest

# Database
DATABASE_PATH=/app/data/netbird_msp.db

# Logging
LOG_LEVEL=INFO

System Configuration via Web UI

All settings can be configured through the web interface under Settings → System Configuration:

• Base Domain
• Admin Email
• NPM Integration
• Docker Images
• Port Ranges
• Data Directories

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

• Click the action buttons in the customer list
• Or use the detail view for more control

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, disk usage
• Container Status: Running/stopped/failed
• Recent Activity: Deployment logs and events

Bulk Operations

Select multiple customers using checkboxes:

• Bulk Update: Update NetBird images across selected customers
• Bulk Restart: Restart all selected instances
• Bulk Backup: Create backups of selected customers

Backups

Manual Backup

docker exec netbird-msp-appliance python -m app.backup --customer-id 1

Automatic Backups

Configure in Settings → Backup:

• Schedule: Daily/Weekly
• Retention: Number of backups to keep
• Destination: Local path or remote storage

---

🔌 API Documentation

The appliance provides a REST API for automation.

Authentication

# Get API token (after login)
curl -X POST http://localhost:8000/api/auth/token \
  -d "username=admin&password=yourpassword"

API Endpoints

Full interactive documentation available at:

http://your-server:8000/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
GET    /api/customers/{id}/logs    # Get container logs
GET    /api/customers/{id}/health  # Health check

GET    /api/status                 # System status

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

Common Issues

1. Customer deployment fails

Symptom: Status shows "error" after deployment

Solutions:

• Check Docker logs: docker logs netbird-msp-appliance
• Verify NPM is accessible: curl http://npm-host:81/api
• Check available UDP ports: netstat -ulnp | grep 347
• View detailed logs in the customer detail page

2. NetBird clients can't connect

Symptom: Clients show "relay unavailable"

Solutions:

• Most common: UDP port not open in firewall

  # Check if port is open
  sudo ufw status
  
  # Open the relay port
  sudo ufw allow 3478/udp
  

• Verify relay container is running: docker ps | grep relay
• Test STUN server: Use online STUN tester with your port

3. NPM integration not working

Symptom: SSL certificates not created

Solutions:

• Verify NPM API token is correct
• Check NPM is on same Docker network: npm-network
• Test NPM API manually:

  curl -X GET http://npm-host:81/api/nginx/proxy-hosts \
    -H "Authorization: Bearer YOUR_TOKEN"
  

4. Out of memory errors

Symptom: Containers crashing, system slow

Solutions:

• Check RAM usage: free -h
• Reduce number of customers or upgrade RAM
• Stop inactive customer instances
• Configure swap space:

  sudo fallocate -l 16G /swapfile
  sudo chmod 600 /swapfile
  sudo mkswap /swapfile
  sudo swapon /swapfile
  

Debug Mode

Enable debug logging:

# Edit .env
LOG_LEVEL=DEBUG

# Restart
docker-compose restart

View detailed logs:

docker logs -f netbird-msp-appliance

Getting Help

1. Check the logs: Most issues are explained in the logs
2. GitHub Issues: Search existing issues or create a new one
3. NetBird Community: For NetBird-specific questions
4. Documentation: Read the full docs in /docs folder

---

🔄 Updates

Updating the Appliance

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

Updating NetBird Images

Via Web UI:

1. Settings → System Configuration
2. Update image tags
3. Click "Save"
4. Use Bulk Update for customers

Via CLI:

# Update all customer instances
docker exec netbird-msp-appliance python -m app.update --all

---

🛡️ Security Best Practices

1. Change default credentials immediately after installation
2. Use strong passwords (20+ characters, mixed case, numbers, symbols)
3. Keep NPM API token secure - never commit to git
4. Enable firewall and only open required ports
5. Regular updates - both the appliance and NetBird images
6. Backup regularly - automate daily backups
7. Use HTTPS - always access the web UI via HTTPS (configure reverse proxy)
8. Monitor logs - check for suspicious activity
9. Limit 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

---

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• NetBird Team - for the amazing open-source VPN solution
• FastAPI - for the high-performance Python framework
• Nginx Proxy Manager - for easy reverse proxy management

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@yourdomain.com

---

Made with ❤️ for MSPs and System Administrators