Borg

Siehe auch

Verwandte Artikel
Offizielle Dokumentation
Linuxfabrik

Borg (offiziell BorgBackup, Kurzform borg) ist ein deduplizierendes Backup-Tool mit Verschlüsselung und Kompression. Es sichert Dateien, Verzeichnisse, symbolische und harte Links, FIFOs und Gerätedateien mit vollen Unix-Permissions in ein sogenanntes Repository, das lokal oder über SSH auf einem entfernten Host liegen kann. Die Deduplizierung arbeitet auf Chunk-Ebene: identische Datenblöcke werden nur einmal gespeichert, auch dateiübergreifend und über viele Backup-Läufe hinweg. Inkrementelle Sicherungen beanspruchen dadurch minimalen zusätzlichen Speicherplatz und laufen entsprechend schnell.

Borg existiert aktuell in zwei parallelen Strömungen: die stabile Serie 1.x mit borg init und klassischen Kommando-Namen, in EPEL und in allen grossen Distributionen verfügbar, sowie die neuere Serie 2.x (Beta, borg rcreate und umbenannte Kommandos). Unten stehen die 1.x-Kommandos, auf denen auch das Linuxfabrik-Setup aufsetzt.

Installation

dnf --assumeyes install borgbackup

Das Paket kommt aus EPEL und ist dort stets aktuell (Stand 2026-04 v1.4.x).

Repository anlegen und Schlüssel sichern

Ein Repository muss genau einmal initialisiert werden. Borg kennt mehrere Verschlüsselungsmodi; repokey speichert den Schlüssel im Repository und schützt ihn zusätzlich mit einer Passphrase, keyfile legt den Schlüssel separat auf dem Client ab. Für die meisten lokalen und per-SSH-Setups ist repokey der unkomplizierteste und sichere Default:

borg init --encryption=repokey /backup/borg/on-demand

Borg fragt interaktiv nach einer Passphrase. Für automatisierte Läufe setzt man BORG_PASSPHRASE oder besser BORG_PASSCOMMAND (ruft ein Skript auf, das die Passphrase zurückgibt).

Warnung

Ohne Schlüssel plus Passphrase ist ein Restore unmöglich - nicht schwierig, unmöglich. Das gilt gleichermassen für repokey und keyfile. Direkt nach der Initialisierung den Schlüssel exportieren und ausserhalb des Repositories aufbewahren:

borg key export /backup/borg/on-demand /root/borg-key-on-demand.txt

Die Passphrase gehört in den Passwortspeicher, der Key-Export an einen Ort, der ein Datencrash des Backup-Hosts überlebt. Import zurück ins Repository mit borg key import.

Backup erstellen

Jeder Aufruf von borg create legt ein neues Archiv im Repository an. Borg selbst entscheidet anhand der Chunks, was neu zu schreiben ist - die Begriffe „voll“ und „inkrementell“ existieren in diesem Modell nicht, aus Anwendersicht ist jedes Archiv ein vollständiger Snapshot:

borg create --stats --list --progress --compression=lz4 --one-file-system \
    /backup/borg/on-demand::manual-$(date +%F-%H%M%S) \
    /etc /home /opt /root /var/spool/cron

Wichtige Optionen:

  • --stats gibt am Ende Deduplizierungs- und Kompressions-Statistik aus.

  • --list protokolliert jede Datei mit Statusmarker (A neu, M geändert, U unverändert, E Fehler).

  • --progress zeigt den Fortschritt interaktiv; für Cron-Aufrufe weglassen.

  • --compression=lz4 ist der Linuxfabrik-Default: schnell, moderate Kompression. Alternativen: zstd,3, zstd,9, none.

  • --one-file-system verhindert, dass Borg in Mounts wie /proc, /sys oder eingehängte Netzwerklaufwerke hineinläuft.

  • --exclude (wiederholbar) oder --exclude-from=<datei> blendet Muster aus.

Um Backups für den regulären Betrieb niedrig zu priorisieren, lässt sich der gesamte Aufruf unter ionice und nice stellen:

ionice --class=3 nice --adjustment=19 borg create ...

Archive inspizieren

Liste aller Archive im Repository:

borg list /backup/borg/on-demand

Dateien innerhalb eines Archivs:

borg list /backup/borg/on-demand::manual-2026-03-19-091036

Detaillierte Statistik zum Repository oder zu einem einzelnen Archiv:

borg info /backup/borg/on-demand
borg info /backup/borg/on-demand::manual-2026-03-19-091036

Restore

Für einen gezielten Restore auf Datei-Ebene ist borg mount in der Regel komfortabler als borg extract, weil das Archiv als FUSE-Dateisystem browsebar wird:

mkdir --parents /mnt/borg
borg mount /backup/borg/on-demand /mnt/borg

# im Archiv stöbern, mit cp -a gewünschte Dateien herauskopieren
cp --archive /mnt/borg/manual-2026-03-19-091036/etc/ssh/sshd_config /restore/

umount /mnt/borg

Ist das komplette Archiv zurückzuholen, ist borg extract der schnellere Weg. borg extract schreibt in das aktuelle Arbeitsverzeichnis; das Zielverzeichnis muss vorher angelegt und per cd betreten sein:

mkdir --parents /restore
cd /restore
borg extract --dry-run /backup/borg/on-demand::manual-2026-03-19-091036
borg extract /backup/borg/on-demand::manual-2026-03-19-091036

Einzelne Datei aus einem Archiv holen (Pfad immer ohne führenden /):

cd /tmp/test1
borg extract /backup/borg/on-demand::manual-2026-03-19-091036 etc/ssh/sshd_config

Grundsätzlich gilt für alle borg-Aufrufe mit potenziell schreibendem Effekt: zuerst --dry-run.

Prune, Compact und Check

borg prune entfernt Archive nach einer definierten Retention-Policy. Der Linuxfabrik-Standard (und der Standard der Rolle borg_local) arbeitet mit --keep-within:

borg prune --list --stats --keep-within=90d /backup/borg/on-demand

--keep-within=90d behält alle Archive, die jünger als 90 Tage sind. Differenziertere Policies gehen mit --keep-hourly, --keep-daily, --keep-weekly, --keep-monthly und --keep-yearly. Jeder prune gehört produktiv erst mit --dry-run verifiziert, bevor er ohne läuft.

borg prune löscht seit Borg 1.2 nur die Archiv-Metadaten; der tatsächliche Speicherplatz wird erst mit borg compact freigegeben. Ohne compact wächst das Repository weiter, auch wenn prune laufen:

borg compact /backup/borg/on-demand

borg check verifiziert die Integrität von Repository und Archiven. Empfehlung: regelmässig (z.B. wöchentlich) ausführen, weil ein stilles Korruptionsproblem bei Backups fatal ist:

borg check --verify-data /backup/borg/on-demand

--verify-data rechnet die Chunks durch und kostet entsprechend Zeit. Ohne den Schalter prüft Borg nur die Metadaten.

Environment-Variablen

Für automatisierte Setups sind drei Variablen zentral:

  • BORG_REPO: Pfad zum Default-Repository. Ist sie gesetzt, fallen die Pfad-Argumente in den borg-Kommandos weg.

  • BORG_PASSPHRASE: Passphrase für verschlüsselte Repositories. Sinnvoll nur, wenn sie aus einer gesicherten Quelle geladen wird (z.B. source /etc/borg/borg.conf mit chmod 0600).

  • BORG_PASSCOMMAND: Alternative zu BORG_PASSPHRASE. Borg ruft das angegebene Kommando auf und erwartet die Passphrase auf stdout. Damit lässt sich die Passphrase aus einem externen Secret-Store oder per pass/gopass holen, ohne sie in einer Datei abzulegen.

Linuxfabrik-Konvention

Die LFOps-Rolle borg_local legt auf dem zu sichernden Host die Struktur an, mit der die Linuxfabrik ihre Backup-Setups standardisiert:

  • Basisverzeichnis /backup (Variable borg_local__backup_dir).

  • Drei Repositories nebeneinander: /backup/daily, /backup/hourly und /backup/on-demand. daily und hourly werden per systemd-Timer gefahren, on-demand steht für manuelle und Ad-hoc-Backups bereit.

  • Retention über --keep-within je Repo: 14d für daily, 99H für hourly.

  • Konfiguration in /etc/borg/borg.conf (source /etc/borg/borg.conf liefert BACKUP_DIR, BORG_REPO, BORG_PASSPHRASE, RETENTION_*, FILES_INCLUDE, FILES_EXCLUDE).

  • Ausführung über /usr/local/bin/borg-backup {daily|hourly|<beliebiger-string>}.

  • Default-Include: /etc, /home, /opt, /root, /var/spool/cron.

  • Default-Backup-Optionen: --stats --progress --one-file-system --compression lz4 --checkpoint-interval 86400.

  • Läuft auf dem Host clamd@scan.service, wird er während des Backups temporär gestoppt und per Icinga-API mit einer Downtime versehen, damit kein False-Positive-Alarm entsteht.

Für Restores aus einem von borg_local verwalteten Repo reicht der Drei-Zeiler aus der Rolle:

source /etc/borg/borg.conf
BORG_REPO="$BACKUP_DIR/daily"
borg mount "$BORG_REPO" /mnt/borg

Troubleshooting

Failed to create/acquire the lock

Ein anderer Borg-Prozess hält gerade das Repository, oder ein früherer Lauf ist abgestürzt und hat den Lock im Verzeichnis <repo>/lock.exclusive/ liegen lassen. Prüfen, ob tatsächlich ein Prozess läuft (pgrep --list-full borg). Ist keiner aktiv, den Lock mit borg break-lock /backup/borg/on-demand lösen.

Repository ... is not a valid repository. Check repo config.

Meist ein falscher Pfad oder ein leeres Verzeichnis. Borg-Repositories enthalten config, data/, index.*. Pfad verifizieren, notfalls borg init auf einem anderen Pfad und Daten neu sichern; ein defektes Repository ohne Key-Backup und ohne Snapshots von aussen ist nicht reparierbar.

Kein Platz im Repository, obwohl prune gelaufen ist

Seit Borg 1.2 gibt prune den Platz nicht mehr automatisch frei. Fehlendes borg compact /backup/borg/on-demand nachholen.

Remote: Borg <version> is too old bei SSH-Repos

Client- und Server-Borg müssen kompatibel sein. Auf dem SSH-Ziel borg --version ausführen; die meisten Versions-Kompatibilitäts-Probleme lösen sich durch ein Upgrade der jeweils älteren Seite.