BorgBackup Guide for RamNode VPS | RamNode Documentation

Introduction

BorgBackup (short for Borg) is a deduplicating backup program that offers efficient, secure, and space-saving backups. With features like compression, encryption, and data deduplication, Borg is an excellent choice for protecting your VPS data against loss or corruption.

Space Efficient

Deduplication stores only unique data chunks

Encrypted

AES-256 encryption protects your data at rest

Compression

Multiple algorithms (lz4, zstd, zlib) reduce storage

Verifiable

Built-in consistency checking ensures integrity

Install BorgBackup

Ubuntu/Debian

Install from package manager

# Update package list
sudo apt update

# Install BorgBackup
sudo apt install -y borgbackup

# Verify installation
borg --version

Rocky Linux/AlmaLinux/CentOS

Install on RHEL-based systems

# Enable EPEL repository
sudo dnf install -y epel-release

# Install BorgBackup
sudo dnf install -y borgbackup

borg --version

Install Latest Version (All Distributions)

Install via pip

# Install dependencies
# Ubuntu/Debian:
sudo apt install -y python3-pip python3-dev libssl-dev libacl1-dev libfuse-dev pkg-config

# Rocky/RHEL:
sudo dnf install -y python3-pip python3-devel openssl-devel libacl-devel fuse-devel pkgconfig

# Install BorgBackup
sudo pip3 install borgbackup
borg --version

Create a Backup Repository

Local Repository

Initialize local repository

sudo mkdir -p /backup/borg-repo
sudo borg init --encryption=repokey /backup/borg-repo

# You'll be prompted to create a passphrase - SAVE THIS SECURELY!

Remote Repository (SSH)

Initialize remote repository

borg init --encryption=repokey ssh://user@backup-server.com/~/backups/myserver

# Or with specific port
borg init --encryption=repokey ssh://user@backup-server.com:2222/~/backups/myserver

Encryption Modes

repokey: Encryption key stored in repository (requires passphrase)
keyfile: Encryption key stored locally in ~/.config/borg/keys/
repokey-blake2: Same as repokey but with BLAKE2b hashing (faster)
none: No encryption (not recommended)

For most use cases, repokey or repokey-blake2 is recommended.

Export Your Encryption Key!

Without the key and passphrase, your backups are unrecoverable.

borg key export /backup/borg-repo ~/borg-key-backup.txt
# Securely copy this file to multiple safe locations!

Create Your First Backup

Basic Backup Command

Create a backup

sudo borg create \
    --stats \
    --progress \
    --compression lz4 \
    /backup/borg-repo::backup-$(date +%Y%m%d-%H%M%S) \
    /home \
    /etc \
    /var/www \
    /root

# Enter your repository passphrase when prompted

Advanced Backup with Exclusions

Backup with exclusions

sudo borg create \
    --stats \
    --progress \
    --compression lz4 \
    --exclude '/home/*/.cache' \
    --exclude '*.tmp' \
    --exclude '/var/cache' \
    --exclude '/var/tmp' \
    /backup/borg-repo::backup-$(date +%Y%m%d-%H%M%S) \
    /home \
    /etc \
    /var/www \
    /root

Compression Options

lz4: Fast compression, moderate size reduction (recommended for most cases)
zstd,3: Balanced compression (good speed and size)
zlib,6: Better compression, slower
none: No compression

Managing Backups

List All Backups

List backups

borg list /backup/borg-repo

View Backup Contents

List files in backup

# List files in a specific backup
borg list /backup/borg-repo::backup-20250113-140000

# Search for specific files
borg list /backup/borg-repo::backup-20250113-140000 | grep nginx.conf

Check Repository Integrity

Verify repository

# Quick check
borg check /backup/borg-repo

# Thorough verification
borg check --verify-data /backup/borg-repo

Get Backup Statistics

Repository info

# Show space usage
borg info /backup/borg-repo

# Show stats for specific backup
borg info /backup/borg-repo::backup-20250113-140000

Restoring Data

Extract Entire Backup

Full restore

# Create restore directory
mkdir -p /restore

# Extract entire backup
cd /restore
sudo borg extract /backup/borg-repo::backup-20250113-140000

Restore Specific Files

Selective restore

# Restore single file
cd /restore
sudo borg extract /backup/borg-repo::backup-20250113-140000 etc/nginx/nginx.conf

# Restore directory
sudo borg extract /backup/borg-repo::backup-20250113-140000 var/www/html

Mount Backup for Browsing

Mount and browse

# Create mount point
mkdir -p /mnt/borg

# Mount backup
borg mount /backup/borg-repo::backup-20250113-140000 /mnt/borg

# Browse files
ls -la /mnt/borg

# Unmount when done
borg umount /mnt/borg

Pruning Old Backups

Regularly prune old backups to save space while maintaining backup history.

Standard Retention Policy

Prune with retention

# Keep: 7 daily, 4 weekly, 6 monthly backups
sudo borg prune --list --keep-daily=7 --keep-weekly=4 --keep-monthly=6 /backup/borg-repo

Retention Strategy Examples

Conservative (more history)

borg prune --keep-daily=14 --keep-weekly=8 --keep-monthly=12 --keep-yearly=2

Aggressive (less storage)

borg prune --keep-daily=3 --keep-weekly=2 --keep-monthly=3

Automation with Systemd

Create Backup Script

/usr/local/bin/borg-backup.sh

#!/bin/bash
# BorgBackup script for automated backups

# Repository location
BORG_REPO="/backup/borg-repo"

# Passphrase (consider using a more secure method in production)
export BORG_PASSPHRASE='your-secure-passphrase'

# Directories to backup
BACKUP_PATHS="/home /etc /var/www /root"

# Exclusions
EXCLUDE_PATTERNS="--exclude /home/*/.cache --exclude '*.tmp' --exclude /var/cache --exclude /var/tmp"

# Create backup
borg create --verbose --stats --compression lz4 ${EXCLUDE_PATTERNS} ${BORG_REPO}::backup-$(date +%Y%m%d-%H%M%S) ${BACKUP_PATHS}

# Prune old backups
borg prune --verbose --list --keep-daily=7 --keep-weekly=4 --keep-monthly=6 ${BORG_REPO}

# Check repository
borg check ${BORG_REPO}

# Unset passphrase
unset BORG_PASSPHRASE

Make executable

sudo chmod +x /usr/local/bin/borg-backup.sh

Create Systemd Service

/etc/systemd/system/borg-backup.service

[Unit]
Description=BorgBackup Service
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/borg-backup.sh
Nice=19
IOSchedulingClass=2
IOSchedulingPriority=7

[Install]
WantedBy=multi-user.target

Create Systemd Timer

/etc/systemd/system/borg-backup.timer

[Unit]
Description=BorgBackup Timer
Requires=borg-backup.service

[Timer]
# Run daily at 2 AM
OnCalendar=daily
OnCalendar=02:00
Persistent=true

[Install]
WantedBy=timers.target

Enable and start timer

# Reload systemd
sudo systemctl daemon-reload

# Enable timer to start on boot
sudo systemctl enable borg-backup.timer

# Start timer
sudo systemctl start borg-backup.timer

# Check timer status
sudo systemctl status borg-backup.timer

# List all timers
systemctl list-timers --all | grep borg

Remote Backup Configuration

Setting Up SSH Keys

Configure SSH

# Generate SSH key (if not already done)
ssh-keygen -t ed25519 -C "borg-backup"

# Copy public key to remote server
ssh-copy-id user@backup-server.com

# Test connection
ssh user@backup-server.com

SSH Config for Simplified Access

~/.ssh/config

Host borgbackup
    HostName backup-server.com
    User backupuser
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    Compression yes
    ServerAliveInterval 60

Now you can use: borg create borgbackup:repo::backup-$(date +%Y%m%d)

Monitoring and Notifications

Email Notifications

Install mail utility

sudo apt install -y mailutils

Add to backup script

# At the end of script
if [ $? -eq 0 ]; then
    echo "Backup completed successfully" | mail -s "Borg Backup Success" admin@example.com
else
    echo "Backup failed! Check logs." | mail -s "Borg Backup FAILED" admin@example.com
fi

Healthchecks.io Integration

Add to script

# Add at start of script
curl -fsS -m 10 --retry 5 https://hc-ping.com/YOUR-UUID/start

# Add at end of script
curl -fsS -m 10 --retry 5 https://hc-ping.com/YOUR-UUID

Troubleshooting

Repository is Locked

# Check for stale locks
borg break-lock /backup/borg-repo

# Verify no other borg processes are running
ps aux | grep borg

Insufficient Space

# Check space usage
df -h /backup

# Prune more aggressively
borg prune --keep-daily=3 /backup/borg-repo

# Compact repository (Borg 1.2+)
borg compact /backup/borg-repo

Slow Backups

# Use faster compression
--compression lz4

# Exclude cache directories
--exclude-caches

# Check disk I/O
iostat -x 1

Verify Backup Integrity

# Quick check
borg check /backup/borg-repo

# Full verification
borg check --verify-data /backup/borg-repo

# Repair if issues found
borg check --repair /backup/borg-repo

Best Practices

Test Restores Regularly

Schedule monthly test restores to verify backup integrity.

Store Keys Securely

Keep backup encryption keys in multiple secure locations.

Monitor Disk Space

Set up alerts for backup destination capacity.

Use Remote Storage

Always maintain off-site backups for disaster recovery.

You're All Set!

BorgBackup provides a robust, efficient, and secure backup solution for your RamNode VPS.

Key takeaways:

Always test your backups with regular restore drills
Store encryption keys securely in multiple locations
Monitor backup jobs and disk space usage
Maintain off-site backups for true disaster recovery

View VPS Plans Official BorgBackup Docs