Switch to terraform
This commit is contained in:
Prox
292
ansible/netbird/README.md
Normal file
292
ansible/netbird/README.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# NetBird Deployment
|
||||
|
||||
Self-hosted NetBird VPN with embedded IdP (no external SSO required).
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
cd ansible/deployments/netbird
|
||||
|
||||
# 1. Generate secrets
|
||||
./generate-vault.sh
|
||||
ansible-vault encrypt group_vars/vault.yml
|
||||
|
||||
# 2. Deploy
|
||||
ansible-playbook playbook-ssl.yml -i inventory.yml --ask-vault-pass
|
||||
|
||||
# 3. Create admin (manual - see below)
|
||||
|
||||
# 4. Create PAT (manual - see below)
|
||||
|
||||
# 5. Provision groups and users
|
||||
ansible-playbook setup-groups.yml -i inventory.yml --ask-vault-pass
|
||||
ansible-playbook setup-users.yml -i inventory.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Ubuntu 22.04+ VPS with public IP
|
||||
- Ports 80, 443, 3478 (TCP/UDP) open
|
||||
- Ansible 2.14+
|
||||
|
||||
## Deployment Modes
|
||||
|
||||
| Playbook | Use Case |
|
||||
| --------------------- | ------------------------------------------------------------------------ |
|
||||
| `playbook-ssl-ip.yml` | HTTPS with self-signed cert on IP (recommended for isolated deployments) |
|
||||
| `playbook-ssl.yml` | HTTPS with Let's Encrypt (requires domain) |
|
||||
| `playbook-no-ssl.yml` | HTTP only (not recommended) |
|
||||
|
||||
## Full Workflow
|
||||
|
||||
### Step 1: Configure Inventory
|
||||
|
||||
Edit `inventory.yml`:
|
||||
|
||||
```yaml
|
||||
all:
|
||||
children:
|
||||
netbird_servers:
|
||||
hosts:
|
||||
netbird-vps:
|
||||
ansible_host: YOUR_SERVER_IP
|
||||
ansible_user: root
|
||||
ansible_python_interpreter: /usr/bin/python3
|
||||
```
|
||||
|
||||
### Step 2: Generate Secrets
|
||||
|
||||
```bash
|
||||
./generate-vault.sh
|
||||
ansible-vault encrypt group_vars/vault.yml
|
||||
```
|
||||
|
||||
This creates:
|
||||
|
||||
- `vault_turn_password` - TURN server authentication
|
||||
- `vault_relay_secret` - Relay server secret
|
||||
- `vault_encryption_key` - Embedded IdP encryption (BACK THIS UP!)
|
||||
- `vault_admin_password` - Initial admin password
|
||||
- `vault_netbird_service_pat` - Leave empty for now
|
||||
|
||||
### Step 3: Deploy NetBird
|
||||
|
||||
```bash
|
||||
ansible-playbook playbook-ssl-ip.yml -i inventory.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
Wait for deployment to complete. Dashboard will be available at `https://YOUR_IP`.
|
||||
|
||||
### Step 4: Create Admin User (Manual)
|
||||
|
||||
1. Open `https://YOUR_IP` in browser (accept certificate warning)
|
||||
2. Create admin account:
|
||||
- **Email**: `admin@achilles.local` (from `group_vars/netbird_servers.yml`)
|
||||
- **Password**: Use `vault_admin_password` from vault
|
||||
|
||||
```bash
|
||||
# View password
|
||||
ansible-vault view group_vars/vault.yml | grep vault_admin_password
|
||||
```
|
||||
|
||||
### Step 5: Create Service User & PAT (Manual)
|
||||
|
||||
After logging in as admin:
|
||||
|
||||
1. Go to **Team** → **Service Users**
|
||||
2. Click **Create Service User**
|
||||
- Name: `Automation Service`
|
||||
- Role: `Admin`
|
||||
3. Click on the created service user
|
||||
4. Click **Create Token**
|
||||
- Name: `ansible-automation`
|
||||
- Expiration: 365 days
|
||||
5. **Copy the token** (shown only once!)
|
||||
|
||||
### Step 6: Store PAT in Vault
|
||||
|
||||
```bash
|
||||
ansible-vault edit group_vars/vault.yml
|
||||
```
|
||||
|
||||
Set:
|
||||
|
||||
```yaml
|
||||
vault_netbird_service_pat: "nbp_xxxxxxxxxxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
### Step 7: Create Groups
|
||||
|
||||
```bash
|
||||
ansible-playbook setup-groups.yml -i inventory.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
This creates:
|
||||
|
||||
- Battalion groups: `battalion-1-pilots`, `battalion-1-ground-stations`, etc.
|
||||
- Dev team group: `dev-team`
|
||||
- Setup keys for each group
|
||||
- Access policies (battalion isolation + dev access)
|
||||
|
||||
### Step 8: Provision Users
|
||||
|
||||
Edit `group_vars/netbird_servers.yml` to define users:
|
||||
|
||||
```yaml
|
||||
netbird_users:
|
||||
# Dev team (full access)
|
||||
- email: "vlad.stus@achilles.local"
|
||||
name: "Vlad Stus"
|
||||
role: "admin"
|
||||
auto_groups:
|
||||
- "dev-team"
|
||||
|
||||
# Battalion users
|
||||
- email: "pilot1.bat1@achilles.local"
|
||||
name: "Pilot One B1"
|
||||
role: "user"
|
||||
battalion: "battalion-1"
|
||||
type: "pilot"
|
||||
|
||||
- email: "gs-operator1.bat1@achilles.local"
|
||||
name: "GS Operator One B1"
|
||||
role: "user"
|
||||
battalion: "battalion-1"
|
||||
type: "ground-station"
|
||||
```
|
||||
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
ansible-playbook setup-users.yml -i inventory.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
**Dry run** (preview without creating):
|
||||
|
||||
```bash
|
||||
ansible-playbook setup-users.yml -i inventory.yml --ask-vault-pass -e "dry_run=true"
|
||||
```
|
||||
|
||||
Credentials are saved to `files/credentials/users-YYYY-MM-DD.yml`.
|
||||
|
||||
## User Roles
|
||||
|
||||
| Role | Permissions |
|
||||
| ------- | ------------------------------------------ |
|
||||
| `owner` | Full control, can delete account |
|
||||
| `admin` | Manage users, groups, policies, setup keys |
|
||||
| `user` | Connect peers, view own peers |
|
||||
|
||||
## User Types (for battalion assignment)
|
||||
|
||||
| Type | Auto-Group |
|
||||
| ---------------- | ----------------------------- |
|
||||
| `pilot` | `{battalion}-pilots` |
|
||||
| `ground-station` | `{battalion}-ground-stations` |
|
||||
|
||||
## Backup & Restore
|
||||
|
||||
**Create backup** (downloads to `~/achilles-backups/netbird/`):
|
||||
|
||||
```bash
|
||||
ansible-playbook backup.yml -i inventory.yml
|
||||
```
|
||||
|
||||
**Restore latest backup**:
|
||||
|
||||
```bash
|
||||
ansible-playbook restore.yml -i inventory.yml
|
||||
```
|
||||
|
||||
**Restore specific backup**:
|
||||
|
||||
```bash
|
||||
ansible-playbook restore.yml -i inventory.yml -e "backup_file=netbird-backup-20250116T120000.tar.gz"
|
||||
```
|
||||
|
||||
Backups include:
|
||||
|
||||
- Management SQLite database (peers, routes, policies, users)
|
||||
- Configuration files (docker-compose.yml, Caddyfile, etc.)
|
||||
|
||||
## Cleanup
|
||||
|
||||
**Soft cleanup** (stop containers, keep data):
|
||||
|
||||
```bash
|
||||
ansible-playbook cleanup-soft.yml -i inventory.yml
|
||||
```
|
||||
|
||||
**Full cleanup** (remove everything including data):
|
||||
|
||||
```bash
|
||||
ansible-playbook cleanup-full.yml -i inventory.yml
|
||||
```
|
||||
|
||||
## Connecting Peers
|
||||
|
||||
After provisioning, users connect with:
|
||||
|
||||
```bash
|
||||
# Using setup key (for automated deployments)
|
||||
netbird up --management-url https://YOUR_IP --setup-key SETUP_KEY
|
||||
|
||||
# Using user credentials (interactive)
|
||||
netbird up --management-url https://YOUR_IP
|
||||
# Then login with email/password in browser
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
ansible/deployments/netbird/
|
||||
├── backup.yml # Backup management DB and config
|
||||
├── cleanup-full.yml # Remove everything
|
||||
├── cleanup-soft.yml # Stop containers only
|
||||
├── generate-vault.sh # Generate random secrets
|
||||
├── group_vars/
|
||||
│ ├── netbird_servers.yml # Main configuration
|
||||
│ ├── vault.yml # Encrypted secrets
|
||||
│ └── vault.yml.example # Template for vault
|
||||
├── inventory.yml # Server inventory
|
||||
├── playbook-no-ssl.yml # HTTP deployment
|
||||
├── playbook-ssl-ip.yml # HTTPS with self-signed (IP)
|
||||
├── playbook-ssl.yml # HTTPS with Let's Encrypt
|
||||
├── restore.yml # Restore from backup
|
||||
├── setup-bootstrap.yml # Bootstrap admin (if API available)
|
||||
├── setup-groups.yml # Create groups, keys, policies
|
||||
├── setup-users.yml # Provision users
|
||||
├── templates/ # Jinja2 templates
|
||||
└── files/
|
||||
└── credentials/ # Generated user passwords (gitignored)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Certificate Warning
|
||||
|
||||
Expected for SSL-IP mode. Accept the self-signed certificate in your browser.
|
||||
|
||||
### "Unauthenticated" after login
|
||||
|
||||
JWKS race condition bug in NetBird. Wait 30 seconds and try again, or restart the management container:
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_IP "cd /opt/netbird && docker compose restart management"
|
||||
```
|
||||
|
||||
### API returns 404 on /api/instance/setup
|
||||
|
||||
The bootstrap API isn't exposed in all NetBird versions. Create admin manually in the dashboard.
|
||||
|
||||
### View logs
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_IP "cd /opt/netbird && docker compose logs -f"
|
||||
```
|
||||
|
||||
### Check container status
|
||||
|
||||
```bash
|
||||
ssh root@YOUR_IP "cd /opt/netbird && docker compose ps"
|
||||
```
|
||||
Reference in New Issue
Block a user