Pangolin Stack Backup & Update Management Script
Tested on Debian, Alma, and Ubuntu 24.04(Prefered)
Introduction
This guide explains how to use the Pangolin Stack Backup & Management Script, a utility for managing Docker-based Pangolin deployments with automated backup, restore, and update functionality.
Prerequisites
Before using the script, ensure you have:
- Pangolin and/or Crowdsec installed
- Sufficient disk space for backups
- Proper permissions to run Docker commands
- The script file with execute permissions (
chmod +x pangolin-backup-upgrade.sh
)
Basic Usage Guide
Getting Started
-
Download the script:
Place the script in your Pangolin installation directory (where yourdocker-compose.yml
file is located).curl -o setup_backup_update_manager.sh https://gist.githubusercontent.com/hhftechnology/e8fcb9ac1f823b277987142d802d4109/raw/573e937d1812642cdf44b8580c630ece251062f4/setup_backup_update_manager.sh
-
Make it executable:
chmod +x setup_backup_update_manager.sh
-
Run the script in interactive mode:
./setup_backup_update_manager.sh
Interactive Menu Navigation
When you run the script without arguments, you’ll see the main menu with these options:
PANGOLIN BACKUP & UPDATE MANAGEMENT UTILITY
==================================
Current Configuration:
Backup Directory: /path/to/pangolin/backups
Retention Period: 60 days
Backup Items: 2 items
Backup & Restore Options:
1. Create Backup
2. Restore from Backup
3. List Available Backups
4. Delete Specific Backups
5. Configure Backup Settings
6. Setup Cron Job
Update Options:
7. Update Stack (excluding CrowdSec)
8. Update Stack (including CrowdSec)
9. Exit
Enter your choice [1-9]:
Detailed Feature Walkthrough
Creating Backups
Method 1: Interactive Menu
- Run the script:
./pangolin-backup-upgrade.sh
- Select option
1
from the main menu - The script will create a backup of your Pangolin configuration in the configured backup directory
- Upon completion, you’ll see a success message with the backup location
Method 2: Command Line
./backup-update-master.sh backup
For non-interactive use (like in cron jobs):
./backup-update-master.sh --cron backup
What Gets Backed Up
By default, the script backs up:
- Your
docker-compose.yml
file - The entire
config
directory
Listing Backups
Method 1: Interactive Menu
- Run the script:
./setup_backup_update_manager.sh
- Select option
3
from the main menu - You’ll see a list of all available backups with indexes
Method 2: Command Line
This must be run in interactive mode:
./backup-update-master.sh list
Restoring Backups
Method 1: Interactive Menu
- Run the script:
./setup_backup_update_manager.sh
- Select option
2
from the main menu - You’ll see a list of available backups
- Enter the index of the backup to restore, or
l
for the latest backup - Confirm the restore operation by typing
YES
when prompted - Choose whether to stop running services before restore
- After restore completes, choose whether to start services again
Method 2: Command Line
Restore from a specific backup:
./backup-update-master.sh restore backups/pangolin_backup_20250101_120000.tar.gz
Deleting Backups
Method 1: Interactive Menu
- Run the script:
./setup_backup_update_manager.sh
- Select option
4
from the main menu - You’ll see a list of available backups
- Enter the index of the backup to delete, multiple indexes separated by spaces, or
a
for all - Confirm the deletion when prompted
Method 2: Command Line
Delete a specific backup by index:
./backup-update-master.sh delete 2
Configuring Backup Settings
-
Run the script:
./setup_backup_update_manager.sh
-
Select option
5
from the main menu -
The configuration menu offers these options:
BACKUP CONFIGURATION ==================== Current Configuration: 1. Backup Directory: /path/to/pangolin/backups 2. Retention Period: 60 days 3. Backup Items: 2 items Options: 1. Change Backup Directory 2. Change Retention Period 3. Manage Backup Items 4. Save Configuration 5. Return to Main Menu 6. Cancel (Discard Changes)
-
To change the backup directory:
- Select option
1
- Enter the new path (absolute or relative)
- The script will validate and update the path
- Select option
-
To change retention period:
- Select option
2
- Enter the number of days to keep backups
- Backups older than this will be automatically deleted
- Select option
-
To manage backup items:
- Select option
3
- You’ll see the Manage Backup Items submenu:
MANAGE BACKUP ITEMS ================== Current Backup Items: [0] docker-compose.yml [1] config Options: 1. Add Item 2. Remove Item 3. Clear All Items 4. Restore Default Items 5. Return to Configuration Menu 6. Cancel (Discard Changes)
- Add custom paths to include in backups
- Remove items you don’t want to back up
- Reset to defaults if needed
- Select option
-
Remember to select option
4
to save your configuration changes
Setting Up Automatic Backups
-
Run the script:
./setup_backup_update_manager.sh
-
Select option
6
from the main menu -
You’ll see the cron job setup options:
CRON JOB SETUP ============== This will setup a cron job to automatically run backups. The script will run in cron mode with current settings. Current cron jobs for this script: No cron jobs found. Schedule Options: 1. Daily (at midnight) 2. Every 3 days (at midnight) 3. Weekly (Sunday at midnight) 4. Custom schedule 5. Remove existing cron job 6. Cancel
-
Select the desired schedule or choose option
4
for a custom cron expression -
Confirm the setup to create the scheduled backup job
Updating the Pangolin Stack
Basic Update (Without CrowdSec)
- Run the script:
./setup_backup_update_manager.sh
- Select option
7
from the main menu - The script will:
- Check your current docker image tags
- Ask for new versions for each component
- Backup your current configuration
- Pull new images
- Stop and restart services with the new versions
Full Update (With CrowdSec)
- Run the script:
./setup_backup_update_manager.sh
- Select option
8
from the main menu - Follow the same process as the basic update, but including CrowdSec
Update Process Notes
- You can press Enter to keep the current version of any component
- Type
c
at any prompt to cancel the update - The script creates a backup before updating
- If services fail to start after update, you’ll be offered recovery options
Command Line Reference
The script supports these command-line options:
./backup-update-master.sh [OPTIONS] [COMMAND]
Options
--cron
: Run in non-interactive mode (for cron jobs)--dry-run
: Simulate actions without making actual changes--config FILE
: Use alternative config file--dir PATH
: Override backup directory--help
: Show help message
Commands
backup
: Create a backuprestore [DIR]
: Restore from a backupdelete [INDEX]
: Delete specific backupupdate-basic
: Update stack excluding CrowdSecupdate-full
: Update stack including CrowdSec
Examples
- Create backup in cron mode:
./backup-update-master.sh --cron backup
- Restore from specific backup:
./backup-update-master.sh restore backups/pangolin_backup_20250101_120000.tar.gz
- Simulate an update:
./backup-update-master.sh --dry-run update-full
Troubleshooting Tips
Permissions Issues
- Ensure the script has execute permissions
- Make sure you have permissions to run Docker commands
- Check the backup directory is writable
Docker Not Running
- The script will warn you if Docker is not running
- Start Docker and try again
Backup/Restore Issues
- If restore fails, the script will keep a backup of your current configuration
- If paths have changed, adjust the backup items accordingly
Update Problems
- If services fail to start after an update, check logs with Docker Compose
- Use the script’s recovery options to restore from a backup
- Try updating individual services if a full update fails
Best Practices
- Regular Backups: Configure a cron job for automatic, scheduled backups
- Test Restores: Periodically test the restore process to ensure backups are valid
- Multiple Backup Locations: Configure an external backup directory to keep backups separate from the Pangolin installation
- Before Major Changes:
- Create a manual backup before making significant changes
- Use the
--dry-run
option to simulate operations before running them
- Cleanup Old Backups: Review and delete unnecessary backups to save disk space
By following this guide, you should be able to effectively manage your Pangolin installation, keeping it backed up and up-to-date.