Netbird/scripts/readme.md

Netbird Docker Compose - Backup & Restore Guide

Complete documentation for backing up and restoring your Netbird Docker Compose installation.

---

📋 Table of Contents

• Overview
• Prerequisites
• Backup Script
• Restore Script
• Automated Backups
• Best Practices
• Troubleshooting

---

🎯 Overview

This package includes two powerful scripts to manage your Netbird installation:

• backup-netbird.sh - Creates timestamped backups of your entire Netbird setup
• restore-netbird.sh - Restores your Netbird installation from any backup

Both scripts handle Docker services automatically and include comprehensive error handling.

---

⚙️ Prerequisites

• Root or sudo access
• Docker and Docker Compose installed
• Netbird installation at /home/Dejan/Docker/Netbird-compose
• Sufficient disk space for backups

---

💾 Backup Script

What Gets Backed Up

The backup script saves:

• All configuration files (.env, dashboard.env, zitadel.env, etc.)
• Docker Compose configuration (docker-compose.yml)
• SSL certificates and keys (acme.json, machinekey/)
• Management configuration (management.json)
• Traefik configuration files
• All custom scripts
• Zitadel logs

Excluded from backups:

• The backup/ directory itself
• .git/ directory (if present)
• Old .tar.gz files

How to Use

Basic Usage

# Navigate to your Netbird directory
cd /home/Dejan/Docker/Netbird-compose

# Make the script executable (first time only)
chmod +x backup-netbird.sh

# Run the backup
./backup-netbird.sh

What Happens During Backup

1. Validation - Checks for root access and directory existence
2. Service Stop - Gracefully stops all Docker Compose services
3. Archive Creation - Creates a compressed tar.gz archive with timestamp
4. Service Restart - Brings all services back online
5. Verification - Shows backup size and location

Backup Output

Backups are saved in the backup/ directory with timestamps:

backup/
├── netbird-backup-20241127_143022.tar.gz
├── netbird-backup-20241127_180530.tar.gz
└── netbird-backup-20241128_020000.tar.gz

Filename format: netbird-backup-YYYYMMDD_HHMMSS.tar.gz

Backup Script Features

• ✅ Automatic service management
• ✅ Timestamped backups
• ✅ Colored console output
• ✅ Size reporting
• ✅ Error handling at each step
• ✅ Automatic backup directory creation
• ✅ List of recent backups after completion

Optional: Automatic Cleanup

To keep only the last 5 backups, uncomment these lines in the script:

KEEP_BACKUPS=5
print_msg "Cleaning old backups, keeping last $KEEP_BACKUPS..."
cd "$BACKUP_DIR"
ls -t netbird-backup-*.tar.gz | tail -n +$((KEEP_BACKUPS + 1)) | xargs -r rm

---

🔄 Restore Script

How to Use

Basic Usage

# Make the script executable (first time only)
chmod +x restore-netbird.sh

# Restore from a specific backup
./restore-netbird.sh netbird-backup-20241127_143022.tar.gz

Alternative Ways to Specify Backup

# Using just the filename (searches in backup/ directory)
./restore-netbird.sh netbird-backup-20241127_143022.tar.gz

# Using relative path
./restore-netbird.sh backup/netbird-backup-20241127_143022.tar.gz

# Using absolute path
./restore-netbird.sh /home/Dejan/Docker/Netbird-compose/backup/netbird-backup-20241127_143022.tar.gz

List Available Backups

# Show usage and list available backups
./restore-netbird.sh

What Happens During Restore

1. Validation - Verifies backup file exists and is valid
2. Preview - Shows backup contents (first 20 files)
3. Safety Backup - Creates a pre-restore backup (recommended)
4. Confirmation - Asks for your approval before proceeding
5. Service Stop - Stops all running Docker services
6. File Removal - Removes current files (except backup/ directory)
7. Extraction - Extracts all files from backup archive
8. Permissions - Sets correct file permissions
9. Verification - Checks that critical files were restored
10. Service Start - Brings all services back online
11. Status Report - Shows running services status

Interactive Prompts

The restore script will ask you two questions:

Do you want to create a safety backup before restoring? (recommended) [Y/n]

Recommended: Press Enter or type Y to create a safety backup

Are you sure you want to restore from this backup? [y/N]

Type y to proceed with the restore

Restore Script Features

• ✅ Multiple backup file path formats supported
• ✅ Automatic backup file search
• ✅ Pre-restore safety backup
• ✅ Backup content preview
• ✅ Interactive confirmation prompts
• ✅ Automatic permission fixing
• ✅ Critical file verification
• ✅ Service status display
• ✅ Comprehensive error handling

Safety Backups

When you create a safety backup, it's saved as:

backup/pre-restore-backup-YYYYMMDD_HHMMSS.tar.gz

This allows you to roll back if something goes wrong during restore.

---

⏰ Automated Backups

Using Cron

Set up automatic backups using crontab:

# Edit root's crontab
sudo crontab -e

# Add one of these lines:

# Daily backup at 2:00 AM
0 2 * * * /home/Dejan/Docker/Netbird-compose/backup-netbird.sh >> /var/log/netbird-backup.log 2>&1

# Every 6 hours
0 */6 * * * /home/Dejan/Docker/Netbird-compose/backup-netbird.sh >> /var/log/netbird-backup.log 2>&1

# Weekly on Sunday at 3:00 AM
0 3 * * 0 /home/Dejan/Docker/Netbird-compose/backup-netbird.sh >> /var/log/netbird-backup.log 2>&1

Cron Schedule Examples

Schedule	Cron Expression	Description
Every day at 2 AM	0 2 * * *	Daily backup during low traffic
Every 12 hours	0 */12 * * *	Twice daily backups
Every 6 hours	0 */6 * * *	Four times daily
Weekly (Sunday 3 AM)	0 3 * * 0	Weekly backup
Every hour	0 * * * *	Hourly backup (generates many files)

Monitoring Automated Backups

# View backup log
tail -f /var/log/netbird-backup.log

# List recent backups
ls -lht /home/Dejan/Docker/Netbird-compose/backup/ | head -10

# Check cron is running
sudo systemctl status cron

# View crontab entries
sudo crontab -l

---

🎯 Best Practices

Backup Strategy

1. Regular Backups

   • Set up daily automated backups via cron
   • Create manual backups before major changes

2. Retention Policy

   • Keep at least 7 daily backups
   • Keep at least 4 weekly backups
   • Store critical backups off-site

3. Before Updates

   • Always backup before updating Docker images
   • Always backup before modifying configuration
   • Always backup before system maintenance

4. Test Restores

   • Periodically test restore process
   • Verify backup integrity
   • Document restore procedures

Storage Management

# Check backup directory size
du -sh /home/Dejan/Docker/Netbird-compose/backup/

# Find backups older than 30 days
find /home/Dejan/Docker/Netbird-compose/backup/ -name "*.tar.gz" -mtime +30

# Remove backups older than 30 days (use with caution!)
find /home/Dejan/Docker/Netbird-compose/backup/ -name "*.tar.gz" -mtime +30 -delete

Security

• Keep backups in a secure location
• Consider encrypting sensitive backups
• Restrict backup file permissions: chmod 600 *.tar.gz
• Store off-site copies for disaster recovery

---

🔧 Troubleshooting

Common Issues

"Failed to stop services"

Problem: Docker services won't stop

Solution:

# Force stop all containers
docker-compose down --remove-orphans

# Or force remove
docker-compose rm -f -s -v

"Backup file not found"

Problem: Restore script can't find the backup

Solution:

# Check backup directory
ls -la /home/Dejan/Docker/Netbird-compose/backup/

# Use absolute path
./restore-netbird.sh /full/path/to/backup.tar.gz

"Permission denied"

Problem: Script can't be executed

Solution:

# Make scripts executable
chmod +x backup-netbird.sh restore-netbird.sh

# Run with sudo
sudo ./backup-netbird.sh

"No space left on device"

Problem: Insufficient disk space for backup

Solution:

# Check disk space
df -h

# Clean old backups
rm /home/Dejan/Docker/Netbird-compose/backup/netbird-backup-OLD*.tar.gz

# Clean Docker system
docker system prune -a

Verify Backup Integrity

# Test if backup archive is valid
tar -tzf backup/netbird-backup-20241127_143022.tar.gz > /dev/null

# List backup contents
tar -tzf backup/netbird-backup-20241127_143022.tar.gz | less

# Extract specific file from backup (without full restore)
tar -xzf backup/netbird-backup-20241127_143022.tar.gz docker-compose.yml

Manual Restore Steps

If the restore script fails, you can restore manually:

# 1. Stop services
cd /home/Dejan/Docker/Netbird-compose
docker-compose down

# 2. Backup current state (optional)
tar -czf /tmp/emergency-backup.tar.gz .

# 3. Extract backup
tar -xzf backup/netbird-backup-YYYYMMDD_HHMMSS.tar.gz

# 4. Fix permissions
chmod +x *.sh
chmod 600 acme.json
chmod 777 machinekey/

# 5. Start services
docker-compose up -d

---

📊 Script Workflow Diagrams

Backup Process

Start
  ↓
Check root access
  ↓
Create backup directory (if needed)
  ↓
Stop Docker Compose services
  ↓
Create tar.gz archive with timestamp
  ↓
Restart Docker Compose services
  ↓
Display backup info and size
  ↓
List recent backups
  ↓
End

Restore Process

Start
  ↓
Check root access
  ↓
Validate backup file exists
  ↓
Show backup contents preview
  ↓
Prompt: Create safety backup? (Y/n)
  ↓
Create pre-restore backup (if yes)
  ↓
Prompt: Confirm restore? (y/N)
  ↓
Stop Docker Compose services
  ↓
Remove current files
  ↓
Extract backup archive
  ↓
Set file permissions
  ↓
Verify critical files
  ↓
Start Docker Compose services
  ↓
Display service status
  ↓
End

---

📝 File Permissions Reference

After restore, these permissions are automatically set:

File/Directory	Permission	Purpose
*.sh	755 (rwxr-xr-x)	Executable scripts
machinekey/	777 (rwxrwxrwx)	Machine key storage
acme.json	600 (rw-------)	SSL certificates
Other files	644 (rw-r--r--)	Configuration files

---

🆘 Support

Getting Help

1. Check the troubleshooting section above
2. Verify Docker and Docker Compose are running
3. Check system logs: journalctl -xe
4. Check Docker logs: docker-compose logs

Useful Commands

# Check script status
./backup-netbird.sh
./restore-netbird.sh

# View Docker services
docker-compose ps

# View Docker logs
docker-compose logs -f

# Check disk space
df -h

# List all backups with sizes
ls -lh backup/

---

📄 License

These scripts are provided as-is for use with Netbird Docker Compose installations.

---

Last Updated: November 2024
Version: 1.0
Compatible with: Netbird Docker Compose installations