Pangolin Stack Backup & Update Management Script- Beta-Version

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

  1. Download the script:
    Place the script in your Pangolin installation directory (where your docker-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
    
  2. Make it executable:

    chmod +x setup_backup_update_manager.sh
    
  3. 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

  1. Run the script: ./pangolin-backup-upgrade.sh
  2. Select option 1 from the main menu
  3. The script will create a backup of your Pangolin configuration in the configured backup directory
  4. 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

  1. Run the script: ./setup_backup_update_manager.sh
  2. Select option 3 from the main menu
  3. 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

  1. Run the script: ./setup_backup_update_manager.sh
  2. Select option 2 from the main menu
  3. You’ll see a list of available backups
  4. Enter the index of the backup to restore, or l for the latest backup
  5. Confirm the restore operation by typing YES when prompted
  6. Choose whether to stop running services before restore
  7. 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

  1. Run the script: ./setup_backup_update_manager.sh
  2. Select option 4 from the main menu
  3. You’ll see a list of available backups
  4. Enter the index of the backup to delete, multiple indexes separated by spaces, or a for all
  5. Confirm the deletion when prompted

Method 2: Command Line

Delete a specific backup by index:

./backup-update-master.sh delete 2

Configuring Backup Settings

  1. Run the script: ./setup_backup_update_manager.sh

  2. Select option 5 from the main menu

  3. 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)
    
  4. To change the backup directory:

    • Select option 1
    • Enter the new path (absolute or relative)
    • The script will validate and update the path
  5. To change retention period:

    • Select option 2
    • Enter the number of days to keep backups
    • Backups older than this will be automatically deleted
  6. 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
  7. Remember to select option 4 to save your configuration changes

Setting Up Automatic Backups

  1. Run the script: ./setup_backup_update_manager.sh

  2. Select option 6 from the main menu

  3. 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
    
  4. Select the desired schedule or choose option 4 for a custom cron expression

  5. Confirm the setup to create the scheduled backup job

Updating the Pangolin Stack

Basic Update (Without CrowdSec)

  1. Run the script: ./setup_backup_update_manager.sh
  2. Select option 7 from the main menu
  3. 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)

  1. Run the script: ./setup_backup_update_manager.sh
  2. Select option 8 from the main menu
  3. 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 backup
  • restore [DIR]: Restore from a backup
  • delete [INDEX]: Delete specific backup
  • update-basic: Update stack excluding CrowdSec
  • update-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

  1. Regular Backups: Configure a cron job for automatic, scheduled backups
  2. Test Restores: Periodically test the restore process to ensure backups are valid
  3. Multiple Backup Locations: Configure an external backup directory to keep backups separate from the Pangolin installation
  4. Before Major Changes:
    • Create a manual backup before making significant changes
    • Use the --dry-run option to simulate operations before running them
  5. 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.

6 Likes