Netbird/scripts/readme.md

# NetBird Backup & Restore Scripts

Comprehensive backup and restore solution for NetBird Docker deployments with Zitadel integration.

## Overview

These scripts provide automated backup and restore functionality for your NetBird installation, including:
- Docker volumes (database, management data, certificates)
- Configuration files (docker-compose, environment variables)
- Traefik reverse proxy configuration
- Zitadel authentication data

## Prerequisites

- Docker and Docker Compose installed
- NetBird deployed via Docker Compose
- Sufficient disk space for backups
- Root or sudo access for Docker operations

## Files

### 1. `backup-netbird.sh`
Creates timestamped backups of your complete NetBird installation.

### 2. `restore-netbird.sh`
Restores NetBird from a backup archive.

## Installation

1. Place both scripts in your NetBird installation directory:
   ```bash
   /home/Dejan/Docker/Netbird-compose/
   ```

2. Make scripts executable:
   ```bash
   chmod +x backup-netbird.sh restore-netbird.sh
   ```

3. Ensure the backup directory exists:
   ```bash
   mkdir -p /home/Dejan/Docker/Netbird-compose/backup
   ```

## Usage

### Creating a Backup

Run the backup script from your NetBird directory:

```bash
cd /home/Dejan/Docker/Netbird-compose
./backup-netbird.sh
```

**What happens during backup:**
1. Creates backup directory if it doesn't exist
2. Stops the NetBird Docker stack
3. Exports all Docker volumes to compressed archives
4. Archives configuration files
5. Restarts the NetBird stack
6. Creates a timestamped backup file: `netbird_backup_YYYY-MM-DD_HH-MM-SS.tar.gz`

**Backup includes:**
- Docker volumes: `netbird_zdb_data`, `netbird_management`, `netbird_zitadel_certs`
- Configuration: `docker-compose.yml`, `*.env` files
- NetBird config: `management.json`, `turnserver.conf`
- Authentication: `machinekey` directory
- Reverse proxy: `traefik-stack` directory
- The backup script itself

### Restoring from Backup

#### Option 1: Restore latest backup (automatic)
```bash
cd /home/Dejan/Docker/Netbird-compose
./restore-netbird.sh
```

#### Option 2: Restore specific backup
```bash
./restore-netbird.sh netbird_backup_2024-11-24_14-30-00.tar.gz
```

Or with full path:
```bash
./restore-netbird.sh /home/Dejan/Docker/Netbird-compose/backup/netbird_backup_2024-11-24_14-30-00.tar.gz
```

**What happens during restore:**
1. Validates backup file exists
2. Extracts backup to temporary directory
3. Stops current NetBird stack
4. Restores all Docker volumes
5. Restores configuration files
6. Cleans up temporary files
7. Starts NetBird stack with restored data

## Backup Schedule

### Manual Backups
Run before major changes:
- System updates
- Configuration modifications
- Docker Compose upgrades

### Automated Backups (Recommended)

Add to crontab for automatic daily backups:

```bash
crontab -e
```

Add this line for daily backup at 2 AM:
```cron
0 2 * * * /home/Dejan/Docker/Netbird-compose/backup-netbird.sh >> /var/log/netbird-backup.log 2>&1
```

For weekly backups (Sunday at 3 AM):
```cron
0 3 * * 0 /home/Dejan/Docker/Netbird-compose/backup-netbird.sh >> /var/log/netbird-backup.log 2>&1
```

## Backup Management

### View Available Backups
```bash
ls -lh /home/Dejan/Docker/Netbird-compose/backup/
```

### Delete Old Backups
Keep only last 7 backups:
```bash
cd /home/Dejan/Docker/Netbird-compose/backup
ls -1t netbird_backup_*.tar.gz | tail -n +8 | xargs rm -f
```

### Backup Retention Script
Create `cleanup-old-backups.sh`:
```bash
#!/bin/bash
BACKUP_DIR="/home/Dejan/Docker/Netbird-compose/backup"
KEEP_LAST=7
cd "$BACKUP_DIR"
ls -1t netbird_backup_*.tar.gz | tail -n +$((KEEP_LAST + 1)) | xargs -r rm -f
echo "Cleaned up old backups, kept last $KEEP_LAST"
```

## Troubleshooting

### Backup Script Fails
- **Insufficient disk space**: Check available space with `df -h`
- **Docker not running**: Start Docker service: `sudo systemctl start docker`
- **Permission denied**: Run with sudo: `sudo ./backup-netbird.sh`

### Restore Script Fails
- **Backup file not found**: Verify path and filename
- **Volume restore fails**: Check Docker is running and volumes are accessible
- **Stack won't start**: Check logs: `docker compose logs`

### Common Issues

**Stack doesn't start after restore:**
```bash
# Check container logs
docker compose logs -f

# Verify volumes exist
docker volume ls | grep netbird

# Try manual restart
docker compose down
docker compose up -d
```

**Configuration mismatch:**
```bash
# Verify restored files
ls -la /home/Dejan/Docker/Netbird-compose/

# Check environment variables
cat .env
```

## Important Notes

- **Downtime**: Both backup and restore scripts stop the NetBird stack temporarily
- **Backup size**: Varies based on database size and user count (typically 100MB-1GB)
- **Storage**: Ensure adequate backup storage space
- **Testing**: Test restore process in a development environment first
- **Security**: Backup files contain sensitive data - secure appropriately

## Backup Security

Protect your backups:

1. **Restrict permissions:**
   ```bash
   chmod 700 /home/Dejan/Docker/Netbird-compose/backup
   chmod 600 /home/Dejan/Docker/Netbird-compose/backup/*.tar.gz
   ```

2. **Encrypt backups (optional):**
   ```bash
   gpg --symmetric --cipher-algo AES256 netbird_backup_*.tar.gz
   ```

3. **Off-site backup:**
   ```bash
   # Example: rsync to remote server
   rsync -avz backup/ user@backup-server:/backups/netbird/
   ```

## Migration Guide

To migrate NetBird to a new server:

1. **On old server:** Create backup
   ```bash
   ./backup-netbird.sh
   ```

2. **Transfer backup file:**
   ```bash
   scp backup/netbird_backup_*.tar.gz user@new-server:/tmp/
   ```

3. **On new server:** Install Docker, Docker Compose, and NetBird structure

4. **Restore backup:**
   ```bash
   ./restore-netbird.sh /tmp/netbird_backup_*.tar.gz
   ```

5. **Update DNS/IP** if necessary

## Support

For issues or questions:
- Check NetBird documentation: https://docs.netbird.io
- Review Docker Compose logs: `docker compose logs`
- Verify volume integrity: `docker volume inspect <volume_name>`

## Version History

- **v1.0** - Initial backup and restore scripts with full volume and config support

---

**Created for NetBird deployment at:** `/home/Dejan/Docker/Netbird-compose/`  
**Last updated:** November 2024