# BorgBackup — Deduplizierte, verschlüsselte Backups

> Praxis-Guide zu BorgBackup: deduplizierte, komprimierte und verschlüsselte Backups, die nur geänderte Daten-Chunks speichern — ideal für große Datenbestände.

Source: https://www.jpkc.com/db/cheatsheets/backup-sync/borgbackup/

<!-- PROSE:intro -->
BorgBackup (Binary `borg`) ist ein dedupliziertes Backup-Werkzeug: Es zerlegt deine Daten in Chunks und speichert jeden Block nur ein einziges Mal — egal, in wie vielen Archiven oder über wie viele Läufe er vorkommt. Das spart drastisch Platz, und in Kombination mit Kompression und authentifizierter Verschlüsselung bekommst du Backups, die sich auch auf nicht vertrauenswürdigem Speicher oder per SSH auf einem Remote-Server gut aufgehoben fühlen. Dieser Guide führt dich vom Anlegen eines Repositorys über das Erstellen und Wiederherstellen von Archiven bis zu Aufbewahrungsregeln und Automatisierung.
<!-- PROSE:intro:end -->

## Repository anlegen

`borg init --encryption=repokey <path>` — Legt ein neues lokales Repository mit Verschlüsselung an. Der Schlüssel wird im Repository selbst gespeichert.

```bash
borg init --encryption=repokey /mnt/backup/myrepo
```

`borg init --encryption=keyfile <path>` — Legt ein Repository mit Verschlüsselung an. Der Schlüssel liegt in ~/.config/borg/keys (sicherer für ausgelagerte Repositories).

```bash
borg init --encryption=keyfile /mnt/backup/myrepo
```

`borg init --encryption=none <path>` — Legt ein Repository ohne Verschlüsselung an. Für sensible Daten nicht empfohlen.

```bash
borg init --encryption=none /tmp/testrepo
```

`borg init --encryption=repokey-blake2 <path>` — Legt ein Repository mit repokey-Verschlüsselung an, die BLAKE2b nutzt (auf moderner Hardware schneller als SHA-256).

```bash
borg init --encryption=repokey-blake2 /mnt/backup/myrepo
```

`borg init --encryption=repokey <user>@<host>:<path>` — Legt ein Repository auf einem entfernten Server per SSH an.

```bash
borg init --encryption=repokey user@server.com:/backup/repo
```

## Archive erstellen

`borg create <repo>::<archive> <path>` — Erstellt ein neues Archiv im Repository. Archivnamen müssen eindeutig sein.

```bash
borg create /mnt/backup/repo::home-2024-01-15 /home/user
```

`borg create <repo>::'{hostname}-{now:%Y-%m-%d}' <path>` — Erstellt ein Archiv mit automatischem Namen über Platzhalter für Hostname und Datum.

```bash
borg create /mnt/backup/repo::'{hostname}-{now:%Y-%m-%d}' /home/user
```

`borg create --stats <repo>::<archive> <path>` — Zeigt nach Abschluss Backup-Statistiken an (Originalgröße, komprimierte Größe, deduplizierte Größe).

```bash
borg create --stats /mnt/backup/repo::backup-today /home
```

`borg create --progress <repo>::<archive> <path>` — Zeigt den Fortschritt während der Backup-Erstellung an.

```bash
borg create --progress /mnt/backup/repo::daily-backup /home
```

`borg create --exclude <pattern> <repo>::<archive> <path>` — Schließt Dateien, die auf ein Muster passen, vom Archiv aus.

```bash
borg create --exclude '/home/*/.cache' /mnt/backup/repo::home-backup /home
```

`borg create --exclude-from <file> <repo>::<archive> <path>` — Liest Ausschlussmuster aus einer Datei.

```bash
borg create --exclude-from /etc/borg/excludes /mnt/backup/repo::daily /home
```

`borg create --compression lz4 <repo>::<archive> <path>` — Nutzt LZ4-Kompression (schnell). Optionen: none, lz4, zstd, zlib, lzma.

```bash
borg create --compression lz4 /mnt/backup/repo::home-daily /home
```

`borg create --compression zstd,<level> <repo>::<archive> <path>` — Nutzt Zstandard-Kompression mit der angegebenen Stufe (1–22). Stufe 3 ist ein guter Standardwert.

```bash
borg create --compression zstd,3 /mnt/backup/repo::home-daily /home
```

`borg create -n <repo>::<archive> <path>` — Probelauf: zeigt, was archiviert würde, ohne das Archiv tatsächlich anzulegen.

```bash
borg create -n /mnt/backup/repo::test-dry-run /home/user
```

## Archive auflisten

`borg list <repo>` — Listet alle Archive im Repository auf.

```bash
borg list /mnt/backup/repo
```

`borg list --short <repo>` — Listet nur die Archivnamen auf, einen pro Zeile (praktisch für Skripte).

```bash
borg list --short /mnt/backup/repo
```

`borg list <repo>::<archive>` — Listet alle Dateien innerhalb eines bestimmten Archivs auf.

```bash
borg list /mnt/backup/repo::home-2024-01-15
```

`borg list <repo>::<archive> --pattern 'sh:<glob>'` — Listet Dateien in einem Archiv auf, die auf ein Shell-Glob-Muster passen.

```bash
borg list /mnt/backup/repo::home-2024-01-15 --pattern 'sh:*.conf'
```

`borg list --json <repo>` — Gibt die Archive als JSON aus (für Skripte).

```bash
borg list --json /mnt/backup/repo | jq '.archives[-1].name'
```

## Archive wiederherstellen

`borg extract <repo>::<archive>` — Entpackt das vollständige Archiv in das aktuelle Verzeichnis.

```bash
borg extract /mnt/backup/repo::home-2024-01-15
```

`borg extract <repo>::<archive> <path>` — Entpackt nur einen bestimmten Pfad oder eine Datei aus dem Archiv.

```bash
borg extract /mnt/backup/repo::home-2024-01-15 home/user/Documents
```

`borg extract --strip-components <n> <repo>::<archive>` — Entfernt beim Entpacken die ersten n Pfadkomponenten.

```bash
borg extract --strip-components 2 /mnt/backup/repo::home-2024-01-15
```

`borg extract --dry-run <repo>::<archive>` — Zeigt vorab, was entpackt würde, ohne tatsächlich Dateien zu schreiben.

```bash
borg extract --dry-run /mnt/backup/repo::home-2024-01-15
```

`borg extract --stdout <repo>::<archive> <file> | <command>` — Entpackt eine einzelne Datei und leitet ihren Inhalt nach stdout weiter.

```bash
borg extract --stdout /mnt/backup/repo::home-2024-01-15 home/user/db.sql | mysql -u root mydb
```

## Archive einhängen (FUSE)

`borg mount <repo> <mountpoint>` — Hängt alle Archive des Repositorys als virtuelles Dateisystem ein (erfordert FUSE).

```bash
borg mount /mnt/backup/repo /mnt/borg
```

`borg mount <repo>::<archive> <mountpoint>` — Hängt ein einzelnes Archiv als virtuelles Dateisystem ein.

```bash
borg mount /mnt/backup/repo::home-2024-01-15 /mnt/borg
```

`borg umount <mountpoint>` — Hängt ein zuvor eingehängtes Borg-Dateisystem wieder aus.

```bash
borg umount /mnt/borg
```

## Aufräumen & Löschen

> **Achtung – destruktiv:** `borg prune`, `borg delete` und `borg compact` entfernen Archive bzw. Daten endgültig. Vorher immer mit `--dry-run` (und bei `prune` mit `--list`) prüfen, was wegfällt.

`borg prune --keep-daily <n> --keep-weekly <n> --keep-monthly <n> <repo>` — Wendet eine Aufbewahrungsregel auf das Repository an. Archive außerhalb der Regel werden gelöscht.

```bash
borg prune --keep-daily 7 --keep-weekly 4 --keep-monthly 6 /mnt/backup/repo
```

`borg prune --dry-run --keep-daily 7 --keep-weekly 4 <repo>` — Zeigt vorab, welche Archive die Aufbewahrungsregel entfernen würde.

```bash
borg prune --dry-run --keep-daily 7 --keep-weekly 4 /mnt/backup/repo
```

`borg prune --stats --keep-daily 7 <repo>` — Räumt auf und zeigt Statistiken zum freigegebenen Speicher an.

```bash
borg prune --stats --keep-daily 7 /mnt/backup/repo
```

`borg prune --keep-daily 7 --prefix <prefix> <repo>` — Wendet die Aufbewahrungsregel nur auf Archive an, deren Namen mit dem angegebenen Präfix beginnen.

```bash
borg prune --keep-daily 7 --prefix 'home-' /mnt/backup/repo
```

`borg prune --keep-daily 7 --glob-archives '<pattern>' <repo>` — Wendet die Aufbewahrungsregel nur auf Archive an, die auf ein Glob-Muster passen.

```bash
borg prune --keep-daily 7 --glob-archives 'web-*' /mnt/backup/repo
```

`borg delete <repo>::<archive>` — Löscht ein bestimmtes Archiv aus dem Repository. Der Speicher wird erst nach `borg compact` freigegeben.

```bash
borg delete /mnt/backup/repo::home-2023-01-01
```

`borg compact <repo>` — Gibt nach dem Löschen von Archiven ungenutzten Speicher frei. Nach `prune` oder `delete` ausführen.

```bash
borg compact /mnt/backup/repo
```

## Repository-Informationen

`borg info <repo>` — Zeigt Statistiken zum Repository an (Gesamtgröße, eindeutige Chunks, Verschlüsselung).

```bash
borg info /mnt/backup/repo
```

`borg info <repo>::<archive>` — Zeigt detaillierte Statistiken zu einem bestimmten Archiv an.

```bash
borg info /mnt/backup/repo::home-2024-01-15
```

`borg check <repo>` — Prüft das Repository auf Konsistenz und Integrität.

```bash
borg check /mnt/backup/repo
```

`borg check --verify-data <repo>` — Verifiziert alle Daten, indem jeder Chunk entschlüsselt und dekomprimiert wird (langsam, aber gründlich).

```bash
borg check --verify-data /mnt/backup/repo
```

`borg check --archives-only <repo>` — Prüft nur die Archiv-Metadaten, nicht die Daten-Chunks.

```bash
borg check --archives-only /mnt/backup/repo
```

## Schlüsselverwaltung

`borg key export <repo> <keyfile>` — Exportiert den Verschlüsselungsschlüssel des Repositorys in eine Datei. Bewahre sie sicher und ausgelagert auf.

```bash
borg key export /mnt/backup/repo ~/borg-key-backup.txt
```

`borg key import <repo> <keyfile>` — Importiert einen zuvor exportierten Schlüssel zurück ins Repository.

```bash
borg key import /mnt/backup/repo ~/borg-key-backup.txt
```

`borg key change-passphrase <repo>` — Ändert die Passphrase, die den Verschlüsselungsschlüssel schützt.

```bash
borg key change-passphrase /mnt/backup/repo
```

## Umgebungsvariablen

`export BORG_REPO=<path>` — Setzt den Standard-Repository-Pfad, sodass er in Befehlen entfallen kann.

```bash
export BORG_REPO=/mnt/backup/repo
```

`export BORG_PASSPHRASE=<passphrase>` — Setzt die Repository-Passphrase für unbeaufsichtigte/automatisierte Backups. Vorsicht: im Klartext sichtbar — besser `BORG_PASSCOMMAND` verwenden.

```bash
export BORG_PASSPHRASE=mysecretpassword
```

`export BORG_PASSCOMMAND=<command>` — Führt einen Befehl aus und nutzt dessen stdout als Passphrase.

```bash
export BORG_PASSCOMMAND='pass show borg/main'
```

`export BORG_RSH='ssh -i <keyfile>'` — Nutzt einen bestimmten SSH-Schlüssel für die Verbindung zu einem entfernten Borg-Repository.

```bash
export BORG_RSH='ssh -i ~/.ssh/borg_backup_key'
```

`export BORG_REMOTE_PATH=<path>` — Pfad zur borg-Programmdatei auf dem entfernten Server.

```bash
export BORG_REMOTE_PATH=/usr/local/bin/borg
```

## Praxis-Rezepte

`borg create --stats --compression zstd,3 --exclude '/home/*/.cache' <repo>::'{hostname}-{now:%Y-%m-%dT%H:%M}' /home` — Produktiv-Backup: zeitgestempeltes Archiv mit Zstandard-Kompression und Cache-Ausschluss.

```bash
borg create --stats --compression zstd,3 --exclude '/home/*/.cache' /mnt/backup/repo::'{hostname}-{now:%Y-%m-%dT%H:%M}' /home
```

`borg prune --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --stats && borg compact` — Wendet die Aufbewahrungsregel an und gibt den Speicher frei. In einem Cron-Job an das Backup anhängen.

```bash
borg prune --keep-daily 7 --keep-weekly 4 --keep-monthly 12 --stats /mnt/backup/repo && borg compact /mnt/backup/repo
```

`borg list --short <repo> | tail -1` — Ermittelt den Namen des neuesten Archivs.

```bash
borg list --short /mnt/backup/repo | tail -1
```

`borg create <repo>::<archive> <path> 2>&1 | grep -E '(Duration|Original|Compressed|Deduplicated)'` — Erstellt ein Backup und filtert aus der Ausgabe nur die Zusammenfassung zu Größe und Dauer heraus.

```bash
borg create /mnt/backup/repo::daily-$(date +%F) /home 2>&1 | grep -E '(Duration|Original|Compressed|Deduplicated)'
```

<!-- PROSE:outro -->
## Fazit

BorgBackup verbindet Deduplizierung, Kompression und Verschlüsselung zu einer effizienten, alltagstauglichen Backup-Lösung — gerade für große, sich häufig ändernde Datenbestände. Behandle Passphrase und exportierten Schlüssel mit derselben Sorgfalt wie das Repository selbst: Ohne sie sind verschlüsselte Archive unwiederbringlich verloren. Und prüfe destruktive Schritte wie `prune` oder `delete` stets vorab mit `--dry-run`, bevor `compact` den Speicher endgültig freigibt.

## Weiterführende Links

- [BorgBackup — Dokumentation](https://borgbackup.readthedocs.io/) — vollständiges Handbuch, Quickstart und FAQ (englisch)
- [BorgBackup auf GitHub](https://github.com/borgbackup/borg) — Quellcode, Releases und Issue-Tracker (englisch)
<!-- PROSE:outro:end -->

## Verwandte Kommandos

- [duplicity](https://www.jpkc.com/db/cheatsheets/backup-sync/duplicity/) – verschlüsselte, inkrementelle Backups im GnuPG-Format
- [rclone](https://www.jpkc.com/db/cheatsheets/backup-sync/rclone/) – synchronisiert Dateien mit Cloud-Speicher-Diensten
- [rdiff-backup](https://www.jpkc.com/db/cheatsheets/backup-sync/rdiff-backup/) – inkrementelle Backups mit umkehrbaren Diffs