libvirt-vm-backup-borg

A bash script for backing up libvirt/KVM virtual machines using BorgBackup with automated snapshot management.

Features

• Snapshot or suspend mode: Choose between creating external snapshots or suspending VMs during backup
• BorgBackup integration: Deduplicated, compressed backups with efficient storage
• Flexible retention: Configurable daily, weekly, and monthly backup retention
• Environment-based config: All settings in external .env files
• VM state handling: Works with both running and shut off VMs
• Atomic operations: Safe snapshot creation and automatic cleanup

Requirements

• libvirt/KVM with virsh
• BorgBackup (borgbackup package)
• SSH access to backup storage
• SSH key for authentication

Setup

1. Copy the example environment file:

cp .env.example .env

2. Edit .env and configure:

# Borg backup configuration
BORG_REPO_BASE="ssh://user@host:port/./backups"
BORG_RSH="ssh -i ~/.ssh/backup"
BORG_RELOCATED_REPO_ACCESS_IS_OK="yes"
BORG_PASSPHRASE="your-secure-passphrase"

# Retention policy (leave empty to skip)
KEEP_DAILY="7"
KEEP_WEEKLY="4"
KEEP_MONTHLY="6"

3. Secure your .env file:

chmod 600 .env

Usage

./vm-backup <domain> <mode> <env-file>

Parameters:

• domain: Name of the libvirt VM domain
• mode: Either snapshot or suspend
  • snapshot: Creates external disk snapshots (VM keeps running)
  • suspend: Suspends VM during backup (brief downtime)
• env-file: Path to environment configuration file

Examples:

# Backup with snapshot (no downtime)
./vm-backup myvm snapshot .env

# Backup with suspend (brief downtime)
./vm-backup myvm suspend .env

# Use different env for specific VM
./vm-backup production snapshot /etc/vm-backup/prod.env

Configuration

Retention Strategies

You can configure different retention strategies by setting the KEEP_* variables in your .env file. Leave any parameter empty to skip it.

Daily backups (default):

KEEP_DAILY="7"
KEEP_WEEKLY="4"
KEEP_MONTHLY="6"

Weekly backups only:

KEEP_DAILY=""
KEEP_WEEKLY="8"
KEEP_MONTHLY=""

Monthly backups only:

KEEP_DAILY=""
KEEP_WEEKLY=""
KEEP_MONTHLY="12"

Mixed strategy:

KEEP_DAILY=""
KEEP_WEEKLY="4"
KEEP_MONTHLY="12"

Multiple VMs

You can create separate .env files for different VMs with different retention policies:

./vm-backup webserver snapshot .env.daily
./vm-backup database snapshot .env.hourly
./vm-backup archive suspend .env.weekly

How It Works

1. Loads configuration from specified .env file
2. Checks VM state (must be running or shut off)
3. Creates snapshot or suspends VM (if running)
4. Initializes Borg repository (first run only)
5. Creates compressed backup archive of:
   • All VM disk images
   • VM XML definition
6. Prunes old backups per configured retention policy
7. Merges snapshots back or resumes VM
8. Cleans up temporary files

Backup Retention

Retention is fully configurable via .env file. Set only the intervals you need:

• KEEP_DAILY: Number of daily backups to keep
• KEEP_WEEKLY: Number of weekly backups to keep
• KEEP_MONTHLY: Number of monthly backups to keep

Recovery

To restore a backup:

# List available archives
borg list ssh://user@host:port/./backups/myvm

# Extract specific archive
borg extract ssh://user@host:port/./backups/myvm::myvm-2025-12-29_10-30-00