Skip to content

borgbackup.md

Latest commit

 

History

History
174 lines (117 loc) · 4.36 KB

borgbackup.md

File metadata and controls

174 lines (117 loc) · 4.36 KB
Raw

Borgbackup

Overview

Setup for using Borgbackup with Hetzner Storage Box. I use Hetzner's Storage Box solution (Robot) for my backups. Borgbackup is a deduplicating backup program that provides efficient and secure backups.

Key features:

  • Deduplication (saves storage space)
  • Compression
  • Encryption
  • Incremental backups
  • Remote backup support

Backup Process

Backups are performed by the Clan framework using clan.core.state.<SERVICENAME>. This allows executing actions before the backup and after restoration of files.

The backup process:

  1. Stops services (systemd services or podman containers)
  2. Creates a synchronized copy in /var/backup/<SERVICENAME>
  3. Restarts services
  4. Backs up the /var/backup/<SERVICENAME> data using Borgbackup to Hetzner Storage Box

Backup Maintenance

Manual Backup

To manually trigger a backup for a server:

clan backups create <SERVERNAME>

This will backup all configured services on the specified server.

List Backups

List all available backups:

clan backups list <SERVERNAME>

Example output:

storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::<SERVERNAME>-storagebox-2025-07-24T01:00:00
storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::<SERVERNAME>-storagebox-2025-07-24T06:02:35
storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::<SERVERNAME>-storagebox-2025-07-25T01:00:02

Manual Restoration

Single Service Restoration

To restore only one specific service:

clan backups restore --service <SERVICENAME> <SERVERNAME> borgbackup \
  storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::<SERVERNAME>-storagebox-2025-07-24T06:02:35

This is useful when you only need to restore a specific application (e.g., dokuwiki, lldap).

Full Restoration

To restore all services from a backup:

clan backups restore <SERVERNAME> borgbackup \
  storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::<SERVERNAME>-storagebox-2025-07-24T06:02:35

Warning: This will restore ALL services and may overwrite current data.

List All Scheduled Backups

To see when the next automatic backups are scheduled:

# On the host server
systemctl list-timers | grep -E 'NEXT|borg'

This shows all borgbackup timers and their next execution time.

Hetzner Storage Box Setup

Order a Storage Box

  1. Go to https://robot.hetzner.com/
  2. Order a new Storage Box
  3. You will receive:
    • Account ID (e.g., u444061)
    • URL: <USERNAME>.your-storagebox.de
    • Initial password

Configure SSH Access

To simplify backup management, I use a single SSH key shared across the homelab infrastructure. This allows services to move between hosts without changing SSH keys.

The SSH key and Borg passphrase are generated by Clan and shared across hosts.

Install SSH Key on Storage Box

# Deploy the server configuration (generates SSH keys)
clan machines update <SERVERNAME>

# Install the public key on the Storage Box
clan vars get <SERVERNAME> borgbackup/borgbackup/borgbackup.ssh.pub | \
  ssh -p23 <USERNAME>.your-storagebox.de install-ssh-key

Replace <USERNAME> with your actual Storage Box username (e.g., u444061).

Test SSH Access

Verify that SSH access is working correctly:

# Test SSH connection
clan vars get <SERVERNAME> borgbackup/borgbackup/borgbackup.ssh > /tmp/ssh && \
  chmod 600 /tmp/ssh && \
  ssh -i /tmp/ssh -p23 <USERNAME>@<USERNAME>.your-storagebox.de ls -alh && \
  rm -f /tmp/ssh

If successful, you should see a directory listing from the Storage Box.

Troubleshooting

Backup Fails with "Connection Refused"

Check that:

  1. SSH key is properly installed on Storage Box
  2. Storage Box is accessible: ping <USERNAME>.your-storagebox.de
  3. Port 23 is not blocked by firewall

Check Backup Status

# Check backup service status
systemctl status borgbackup-<SERVICENAME>

# View backup logs
journalctl -u borgbackup-<SERVICENAME> -f

Repository Locked Error

If you get a "repository is locked" error:

# List locks
borg list storagebox::u444061@u444061.your-storagebox.de:/./borgbackup

# Break lock (use with caution!)
borg break-lock storagebox::u444061@u444061.your-storagebox.de:/./borgbackup

Warning: Only break locks if you're certain no backup is running.