How To Install Borgmatic on Ubuntu 24.04 LTS

Data protection remains one of the most critical responsibilities for Linux administrators and users alike. In an era where digital assets form the backbone of personal and business operations, having a robust backup strategy isn’t optional—it’s essential. Ubuntu 24.04 LTS users seeking an enterprise-grade backup solution will find Borgmatic to be an exceptional choice that combines simplicity with powerful automation capabilities.

This comprehensive guide walks you through the complete process of installing and configuring Borgmatic on Ubuntu 24.04 LTS. You’ll learn everything from basic installation to advanced automation techniques, ensuring your data remains protected through reliable, encrypted backups.

What is Borgmatic?

Borgmatic serves as a sophisticated Python wrapper for the renowned Borg backup software, transforming complex command-line operations into straightforward, configuration-driven backup workflows. Unlike traditional backup utilities that require extensive manual intervention, Borgmatic automates the entire backup lifecycle through declarative YAML configuration files.

The software excels at creating encrypted, deduplicated archives that significantly reduce storage requirements while maintaining military-grade security. Borgmatic automatically handles backup creation, implements retention policies for old archives, and performs consistency checks to ensure data integrity. This automation eliminates the potential for human error that often plagues manual backup procedures.

What sets Borgmatic apart from other backup solutions is its ability to handle both file system backups and database dumps within a single, unified workflow. Whether you’re protecting configuration files, user data, or critical databases, Borgmatic provides a centralized approach to comprehensive data protection.

The software integrates seamlessly with third-party monitoring services, sending notifications when backups succeed or fail. This integration capability makes it an ideal choice for production environments where backup monitoring is crucial for operational continuity.

Why Choose Borgmatic for Ubuntu 24.04 LTS?

Ubuntu 24.04 LTS provides an exceptional foundation for running Borgmatic due to its long-term support commitment extending until 2029. This extended support timeline ensures your backup infrastructure remains stable and receives security updates throughout its operational lifecycle.

The distribution includes Borgmatic in its official repositories, simplifying installation and ensuring compatibility with the underlying system components. This native package availability eliminates dependency conflicts that often arise with third-party installations.

Advantages Over Alternative Solutions

Traditional backup tools often require complex scripting or lack the advanced features necessary for modern data protection requirements. Borgmatic addresses these limitations by providing enterprise-ready functionality in an open-source package that’s both cost-effective and highly customizable.

The software’s configuration-driven approach means you can define sophisticated backup strategies without writing complex shell scripts. Everything from source selection to retention policies gets defined in human-readable YAML files that are easy to maintain and version control.

Remote backup capabilities enable geographic distribution of your archives, supporting the industry-standard 3-2-1 backup rule. Whether you’re backing up to local storage, network-attached devices, or cloud repositories, Borgmatic handles the complexity seamlessly.

Prerequisites for Installation

Before installing Borgmatic on Ubuntu 24.04 LTS, ensure your system meets the necessary requirements and you have the appropriate permissions for backup operations.

System Requirements

Your Ubuntu 24.04 LTS system should have adequate resources for backup operations. A minimum of 1GB RAM suffices for basic backup tasks, though larger datasets or concurrent operations may require additional memory. Ensure sufficient storage capacity exists for your backup repositories, considering that Borg’s deduplication typically achieves 30-50% space savings compared to traditional backup methods.

Network connectivity becomes essential when using remote backup repositories. Test your connection to any cloud storage services or remote servers before proceeding with configuration.

Required Permissions

Administrative access through sudo privileges is necessary for system-wide Borgmatic installation. Root access enables backing up system directories like /etc, /var, and other protected locations that contain critical configuration data.

For personal data backups, standard user permissions suffice, allowing you to protect home directories and user-specific applications without elevated privileges.

Dependency Overview

Ubuntu 24.04 LTS includes Python 3.10 by default, meeting Borgmatic’s Python 3.8+ requirement. The system’s package management infrastructure handles most dependencies automatically during installation.

For advanced features like mounting backup archives, additional packages including libfuse-dev, fuse, pkg-config, and python3-pyfuse3 may be required. These packages enable Borg’s mount functionality, allowing you to browse backup archives as if they were regular directories.

Installing Borgmatic on Ubuntu 24.04 LTS

Multiple installation methods provide flexibility depending on your specific requirements and preferences. Each approach offers distinct advantages for different use cases.

Method 1: Ubuntu Package Installation (Recommended)

The simplest and most reliable installation method uses Ubuntu’s official package repositories. This approach ensures proper integration with the system’s package management infrastructure.

Begin by updating your package cache to access the latest available versions:

sudo apt update

Install Borgmatic along with its dependencies:

sudo apt install borgmatic

This command automatically installs Borg backup as a dependency, ensuring compatibility between the wrapper and underlying backup engine. The package manager handles all dependency resolution, preventing version conflicts that might arise with manual installations.

Verify the installation by checking the installed version:

borgmatic --version

The Ubuntu repositories typically provide version 1.7.9, which offers stable functionality suitable for most backup requirements. While this version may not include the latest features available in newer releases, it provides proven reliability for production environments.

Method 2: pipx Installation for Latest Features

Users requiring the latest Borgmatic features can install using pipx, Python’s recommended tool for installing applications in isolated environments. This method provides access to the most recent releases while avoiding conflicts with system packages.

First, install pipx using the package manager:

sudo apt update
sudo apt install pipx

For system-wide installation with root privileges:

sudo pipx ensurepath
sudo pipx install borgmatic

Verify the root installation:

sudo su -
borgmatic --version

For user-specific installation:

pipx ensurepath
pipx install borgmatic

Test the user installation:

borgmatic --version

The pipx method provides the latest available version, typically offering enhanced features and bug fixes not yet available in distribution packages.

Method 3: Installing Additional Dependencies

Enhanced functionality requires additional packages, particularly for mounting backup archives and working with FUSE filesystems.

Install the complete dependency set:

sudo apt install borgbackup borgmatic libfuse-dev fuse pkg-config python3-pyfuse3

Enable FUSE for non-root users by adding your user to the fuse group:

sudo usermod -a -G fuse $USER

Log out and back in for group membership changes to take effect.

Post-Installation Verification

Comprehensive testing ensures your installation functions correctly across all intended use cases.

Test basic functionality:

borgmatic --version
borg --version

Verify sudo access works properly:

sudo borgmatic --version

Test configuration generation capabilities:

borgmatic config generate --help

If any commands fail, review the PATH configuration and ensure all dependencies are properly installed.

Initial Configuration Setup

Borgmatic’s power lies in its configuration-driven approach, allowing you to define complex backup strategies through structured YAML files. Proper configuration ensures reliable, automated backups tailored to your specific requirements.

Generating the Configuration File

Create your initial configuration using Borgmatic’s built-in generator:

sudo borgmatic config generate

This command creates a comprehensive configuration file at /etc/borgmatic/config.yaml with detailed comments explaining each option. The generated file serves as both a functional starting point and comprehensive documentation of available features.

For user-specific configurations:

borgmatic config generate --destination ~/.config/borgmatic/config.yaml

Essential Configuration Sections

The configuration file contains several critical sections that define your backup strategy. Understanding these sections enables you to create tailored backup solutions.

Source Directories Configuration

Define which directories to include in your backups:

source_directories:
    - /home
    - /etc
    - /var/log
    - /opt
    - /srv

Choose source directories based on your data protection requirements. System administrators typically include /etc for configuration files, /home for user data, and application-specific directories under /opt or /srv.

Repository Configuration

Specify where backup archives will be stored:

repositories:
    - path: /var/lib/backups/local.borg
      label: local
    - path: ssh://user@backup-server:22/./backups.borg
      label: remote

Multiple repositories enable redundant storage, supporting comprehensive disaster recovery strategies. Local repositories provide fast backup and restore operations, while remote repositories protect against site-wide disasters.

Repository Initialization

Before creating backups, initialize each repository with appropriate encryption:

For local repositories:

sudo borg init --encryption=repokey /var/lib/backups/local.borg

For remote repositories:

sudo borg init --encryption=repokey ssh://user@backup-server:22/./backups.borg

Choose encryption methods based on your security requirements:

• repokey: Stores encryption key within the repository
• keyfile: Stores encryption key separately for enhanced security
• authenticated: Provides authentication without encryption

Retention Policy Configuration

Define how long to keep different backup generations:

retention:
    keep_daily: 7
    keep_weekly: 4
    keep_monthly: 6
    keep_yearly: 1

This configuration maintains recent daily backups while preserving longer-term archives at weekly, monthly, and yearly intervals. Adjust these values based on your recovery requirements and available storage capacity.

Exclude Patterns for Optimization

Improve backup performance by excluding unnecessary files:

exclude_patterns:
    - /home/*/.cache
    - /home/*/.local/share/Trash
    - '*.tmp'
    - '*.log'
    - /proc
    - /sys
    - /dev

Excluding cache directories, temporary files, and virtual filesystems significantly reduces backup time and storage requirements without sacrificing data protection.

Configuration Validation

Validate your configuration before running backups:

sudo borgmatic config validate

Test the configuration with a dry run:

sudo borgmatic --dry-run --verbosity 2

The dry run shows what actions would be performed without actually creating backups, allowing you to verify the configuration works as expected.

Running Your First Backup

With configuration complete, create your first backup to verify everything functions correctly. This initial backup establishes your baseline archive and confirms the backup workflow operates as designed.

Pre-Backup Checklist

Verify repository accessibility:

sudo borg list /var/lib/backups/local.borg

Check available storage space:

df -h /var/lib/backups/

For remote repositories, test SSH connectivity:

ssh user@backup-server

Executing the First Backup

Run your first backup with verbose output to monitor progress:

sudo borgmatic --verbosity 2

Borgmatic performs three default actions in sequence:

1. Prune: Removes old archives according to retention policy
2. Create: Generates new backup archive
3. Check: Verifies archive integrity

Monitor the output carefully during this first run. The initial backup typically takes the longest time as it processes all data without deduplication benefits.

Understanding Backup Output

Borgmatic provides detailed progress information during backup operations:

Starting backup for repository: /var/lib/backups/local.borg
Creating archive at /var/lib/backups/local.borg::hostname-2024-07-20T12:30:00
Backing up /home (45.2 GB)
Backing up /etc (23.4 MB)
Archive created successfully

The output shows processed directories, data volumes, and completion status. Archive names include timestamps for easy identification and sorting.

Backup Verification

After backup completion, verify the created archives:

sudo borgmatic list

View detailed archive information:

sudo borgmatic info

Check backup integrity:

sudo borgmatic check

These verification commands confirm your backup completed successfully and archives are accessible for future restore operations.

Testing Restore Capabilities

Test restore functionality to ensure backups are usable:

sudo borgmatic extract --archive hostname-2024-07-20T12:30:00 --destination /tmp/restore-test --path /etc/hostname

This command extracts a specific file from the archive to verify restore operations work correctly. Always test restore procedures before relying on backups for disaster recovery.

Advanced Backup Rotation and Pruning

Effective backup management requires sophisticated retention policies that balance data protection requirements with storage constraints. Borgmatic’s flexible pruning system enables complex retention strategies tailored to your specific needs.

Understanding Retention Strategies

Backup retention policies determine how long to preserve different archive generations. Well-designed policies provide comprehensive recovery options while managing storage growth over time.

The retention configuration supports multiple time intervals:

retention:
    keep_secondly: 60
    keep_minutely: 60
    keep_hourly: 24
    keep_daily: 7
    keep_weekly: 4
    keep_monthly: 6
    keep_yearly: 2

This granular control enables precise retention management, keeping frequent backups for recent timeframes while preserving less frequent archives for longer periods.

Repository-Specific Retention Policies

Different repositories may require different retention strategies based on their purpose and storage constraints:

repositories:
    - path: /var/lib/backups/local.borg
      label: local
    - path: ssh://user@backup-server/./backups.borg
      label: remote

retention:
    local:
        keep_daily: 14
        keep_weekly: 8
        keep_monthly: 12
    remote:
        keep_daily: 7
        keep_weekly: 4
        keep_monthly: 6
        keep_yearly: 3

Local repositories with faster access might retain more frequent backups, while remote repositories focus on longer-term preservation.

Monitoring Pruning Operations

Execute pruning operations manually to understand their impact:

sudo borgmatic prune --dry-run --verbosity 2

The dry run shows which archives would be removed without actually deleting them. Review this output carefully before allowing automatic pruning.

Monitor actual pruning operations:

sudo borgmatic prune --verbosity 2

Pruning output indicates which archives are removed and how much storage space is recovered.

Leveraging Hooks for Automation

Borgmatic’s hook system enables sophisticated automation by executing custom commands at specific points in the backup workflow. This capability transforms simple backup operations into comprehensive system maintenance procedures.

Pre-Backup Automation

Execute preparation tasks before backup operations begin:

hooks:
    before_backup:
        - systemctl stop nginx
        - systemctl stop mysql
        - pg_dumpall > /tmp/database_backup.sql

These hooks ensure services are in consistent states and databases are properly dumped before file system backup begins.

Post-Backup Cleanup

Restore normal operations after backup completion:

hooks:
    after_backup:
        - systemctl start mysql
        - systemctl start nginx
        - rm -f /tmp/database_backup.sql

Post-backup hooks restart services and clean up temporary files created during the backup process.

Notification Integration

Integrate with monitoring services for backup status notifications:

hooks:
    ntfy:
        topic: backup-notifications
        finish:
            title: "Backup Complete"
            message: "System backup completed successfully"
            priority: default
        fail:
            title: "Backup Failed"
            message: "System backup encountered errors"
            priority: high

Notification hooks provide immediate feedback on backup operations, enabling rapid response to failures.

Custom Script Development

Develop custom scripts for complex automation requirements:

#!/bin/bash
# /usr/local/bin/pre-backup-checks.sh

# Check disk space
AVAILABLE=$(df /var/lib/backups | tail -1 | awk '{print $4}')
if [ "$AVAILABLE" -lt 1048576 ]; then
    echo "Insufficient disk space for backup"
    exit 1
fi

# Verify network connectivity for remote backups
ping -c 3 backup-server.example.com > /dev/null 2>&1
if [ $? -ne 0 ]; then
    echo "Cannot reach backup server"
    exit 1
fi

echo "Pre-backup checks completed successfully"

Reference custom scripts in your configuration:

hooks:
    before_backup:
        - /usr/local/bin/pre-backup-checks.sh

Database Backup Integration

Borgmatic’s built-in database support eliminates the complexity of coordinating database dumps with file system backups. This integration ensures transactional consistency and simplifies restore procedures.

PostgreSQL Configuration

Configure PostgreSQL database backups:

postgresql_databases:
    - name: production
      username: backup_user
      password: secure_password
      hostname: localhost
      port: 5432
      options: --clean --create
    - name: all
      username: postgres
      options: --clean --create --if-exists

The all database specification creates comprehensive dumps of all databases, while individual database entries provide granular control over backup parameters.

MySQL/MariaDB Integration

Set up MySQL database backups:

mysql_databases:
    - name: wordpress
      username: backup_user
      password: secure_password
      hostname: localhost
      port: 3306
      options: --single-transaction --routines --triggers

Include authentication configuration in /root/.my.cnf for enhanced security:

[client]
user = backup_user
password = secure_password

MongoDB Backup Configuration

Configure MongoDB backups for NoSQL databases:

mongodb_databases:
    - name: application_data
      hostname: localhost
      port: 27017
      username: backup_user
      password: secure_password
      authentication_database: admin
      options: --gzip

MongoDB backups support authentication mechanisms and compression options to optimize storage utilization.

Database Backup Verification

Test database backup functionality independently:

sudo borgmatic --verbosity 2 --create --dry-run

Verify database dumps are created properly:

sudo borgmatic --verbosity 2 --create
sudo borgmatic list --archive latest --path '*.sql'

This verification ensures database dumps are included in backup archives and accessible for restore operations.

Automating Backups with systemd

Ubuntu 24.04 LTS’s systemd integration provides robust scheduling capabilities for automated backup operations. Proper automation ensures backups run consistently without manual intervention.

Creating Service Files

Create a systemd service for backup operations:

sudo nano /etc/systemd/system/borgmatic-backup.service

Service file content:

[Unit]
Description=Borgmatic Backup
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/borgmatic --verbosity 1 --stats
User=root
Group=root

# Security settings
NoNewPrivileges=yes
ProtectHome=read-only
ProtectSystem=strict
ReadWritePaths=/var/lib/backups /tmp

# Resource limits
TimeoutStartSec=3600

Timer Configuration

Create a corresponding timer for scheduled execution:

sudo nano /etc/systemd/system/borgmatic-backup.timer

Timer file content:

[Unit]
Description=Run borgmatic backup daily
Requires=borgmatic-backup.service

[Timer]
OnCalendar=daily
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target

The RandomizedDelaySec option prevents multiple systems from starting backups simultaneously, reducing network congestion in managed environments.

Enabling Automated Backups

Enable and start the timer:

sudo systemctl daemon-reload
sudo systemctl enable borgmatic-backup.timer
sudo systemctl start borgmatic-backup.timer

Verify timer status:

sudo systemctl status borgmatic-backup.timer
sudo systemctl list-timers borgmatic-backup

Advanced Scheduling Options

Configure multiple backup schedules for different data sets:

[Timer]
OnCalendar=Mon,Wed,Fri 02:00
OnCalendar=Sat 22:00
Persistent=true

This configuration runs incremental backups on weekdays and comprehensive backups on weekends.

Monitoring Automated Backups

Monitor backup execution through systemd logs:

sudo journalctl -u borgmatic-backup.service -f

Check recent backup status:

sudo systemctl status borgmatic-backup.service

Set up log rotation to manage disk space:

sudo journalctl --vacuum-time=30d

Troubleshooting Common Issues

Despite careful configuration, backup operations occasionally encounter problems. Understanding common issues and their solutions ensures reliable backup operations over time.

Installation Problems

Package dependency conflicts:
When mixing installation methods, dependency conflicts may arise. Resolve by removing conflicting packages:

sudo apt remove borgmatic
pipx uninstall borgmatic
sudo pipx install borgmatic

Python path issues:
If borgmatic isn’t found after pipx installation, update your PATH:

echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
source ~/.bashrc

Repository Access Issues

SSH authentication failures:
Test SSH connectivity independently:

ssh -v user@backup-server

Configure SSH key authentication:

ssh-keygen -t ed25519 -C "backup@$(hostname)"
ssh-copy-id user@backup-server

Repository lock conflicts:
If backups fail due to lock conflicts, identify and remove stale locks:

sudo borg break-lock /var/lib/backups/local.borg

Only break locks when certain no other backup operation is running.

Performance Optimization

High memory usage:
Limit memory consumption for large repositories:

borg_base_directory: /tmp/borg

Configure temporary directory on fast storage to improve performance.

Network timeout issues:
Increase timeout values for slow connections:

ssh_command: ssh -o ConnectTimeout=60 -o ServerAliveInterval=60

Backup Verification Problems

Archive corruption detection:
Run comprehensive repository checks:

sudo borgmatic check --repository /var/lib/backups/local.borg --archives --verify-data

This command performs thorough integrity verification but requires significant time for large repositories.

Restore verification:
Periodically test restore operations to ensure backups remain usable:

sudo borgmatic extract --archive latest --destination /tmp/restore-test --strip-components 1

Repository Maintenance

Repository growth management:
Monitor repository size and growth patterns:

sudo borg info /var/lib/backups/local.borg

Implement additional compression if storage becomes constrained:

compression: auto,zstd,10

Backup consistency issues:
If backups show inconsistent sizes, investigate excluded patterns:

sudo borgmatic --dry-run --verbosity 2 --list --files

This output shows exactly which files would be included in the backup.

Upgrading and Maintenance

Keeping Borgmatic and Borg updated ensures access to security fixes, performance improvements, and new features. Regular maintenance prevents issues and optimizes backup performance.

Planning Upgrades

Before upgrading, verify version compatibility between Borg and Borgmatic:

borgmatic --version
borg --version

Check release notes for breaking changes or configuration syntax updates.

Backup current configuration files:

sudo cp /etc/borgmatic/config.yaml /etc/borgmatic/config.yaml.backup

Executing Upgrades

Ubuntu package upgrades:

sudo apt update
sudo apt upgrade borgmatic borgbackup

pipx upgrades:

pipx upgrade borgmatic

Manual Borg updates:

sudo pipx install --force borgbackup

Post-Upgrade Verification

Test configuration compatibility:

sudo borgmatic config validate
sudo borgmatic --dry-run --verbosity 1

Verify repository accessibility:

sudo borgmatic list
sudo borgmatic info

Run test backup to confirm functionality:

sudo borgmatic --verbosity 2

Repository Maintenance Tasks

Periodic repository maintenance optimizes performance and reliability:

sudo borg compact /var/lib/backups/local.borg

The compact operation reclaims space from deleted archives and optimizes repository structure.

Check repository consistency:

sudo borg check --verify-data /var/lib/backups/local.borg

This comprehensive check verifies all data integrity but requires significant time for large repositories.

Best Practices and Security Considerations

Implementing robust backup strategies requires attention to security, reliability, and operational procedures. Following established best practices ensures your backup system provides reliable data protection over time.

Security Implementation

Encryption key management:
Store encryption keys separately from backup repositories. Consider using hardware security modules or encrypted key storage solutions for enhanced protection.

Create key recovery documentation:

sudo borg key export /var/lib/backups/local.borg backup-key.txt
sudo gpg --cipher-algo AES256 --compress-algo 1 --symmetric backup-key.txt

Access control:
Limit backup system access through proper user permissions and sudo configuration:

sudo visudo

Add specific borgmatic permissions:

backup-user ALL=(root) NOPASSWD: /usr/bin/borgmatic

Network security:
Use SSH key authentication with restricted commands for remote backups:

command="borg serve --restrict-to-path ./backups",restrict ssh-ed25519 AAAAC3...

Operational Best Practices

3-2-1 backup rule implementation:
Maintain three copies of critical data: one primary copy and two backups, with one backup stored offsite. Borgmatic’s multi-repository support facilitates this strategy.

Regular testing procedures:
Establish monthly restore testing procedures to verify backup integrity and recovery processes:

#!/bin/bash
# Monthly restore test script
RESTORE_DIR="/tmp/restore-test-$(date +%Y%m%d)"
mkdir -p "$RESTORE_DIR"
sudo borgmatic extract --archive latest --destination "$RESTORE_DIR" --path /etc/passwd
diff /etc/passwd "$RESTORE_DIR/etc/passwd"

Documentation maintenance:
Maintain comprehensive documentation of backup procedures, including:

• Configuration file explanations
• Recovery procedures
• Emergency contact information
• Infrastructure dependencies

Monitoring and Alerting

Integration with monitoring systems:
Configure comprehensive monitoring for backup operations:

hooks:
    healthchecks: https://hc-ping.com/your-unique-uuid
    cronitor: https://cronitor.link/your-monitor-id

Log analysis:
Implement log analysis for backup operations:

sudo journalctl -u borgmatic-backup.service --since "1 week ago" | grep -E "(ERROR|CRITICAL|Failed)"

Capacity planning:
Monitor storage growth and plan capacity expansion:

sudo borg info /var/lib/backups/local.borg | grep "Original size"

Congratulations! You have successfully installed Borgmatic. Thanks for using this tutorial for installing the Borgmatic backup program on your Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official Borgmatic website.