nextcloud-borg-backup/Dokumentation.md

Dokumentation: nextcloud-borg-backup

Ziel

Diese Anwendung sichert den via rclone gemounteten Ordner /home/johannes/Nextcloud regelmäßig auf den via autofs erreichbaren Synology-Pfad /net/thor/volume1/NetBackup/Nextcloud.

Die Sicherung verwendet Borg, weil Borg inkrementelle, deduplizierte und verschlüsselte Archive erstellt. Dadurch bleiben tägliche Backups platzsparend und einzelne Dateien können aus älteren Ständen wiederhergestellt werden.

Architektur

Bestandteile:

• scripts/nextcloud-borg-backup: Haupt-CLI für Backup, Restore, Suche, Mount, Check und Retention.
• etc/config.example: Beispielkonfiguration mit den produktiven Standardpfaden.
• systemd/user/nextcloud-borg-backup.service: systemd User Service für einen Backup-Lauf.
• systemd/user/nextcloud-borg-backup.timer: täglicher Timer.
• scripts/install.sh: Installation in das Home-Verzeichnis des Users.
• scripts/uninstall.sh: Entfernt Service, Timer und Executable, lässt Daten bewusst bestehen.

Die Anwendung läuft als User johannes. Das ist für diesen Fall sinnvoll, weil die Quelle ein rclone/FUSE-Mount unterhalb des Home-Verzeichnisses ist. Ein root-Service könnte je nach FUSE-Konfiguration keine stabilen Leserechte auf diesen Mount haben.

Pfade

Standardkonfiguration:

SOURCE_DIR="${HOME}/Nextcloud"
REPO_DIR="/net/thor/volume1/NetBackup/Nextcloud/borg-repo"
ARCHIVE_PREFIX="nextcloud"
RETENTION_WITHIN="4w"

Lokale Laufzeitdaten:

~/.config/nextcloud-borg-backup/config
~/.config/nextcloud-borg-backup/passphrase
~/.config/nextcloud-borg-backup/excludes
~/.local/state/nextcloud-borg-backup/logs/
~/Nextcloud-Restore/

Installation

cd /home/johannes/localdev/nextcloud-borg-backup
./scripts/install.sh

Der Installer:

1. kopiert die CLI nach ~/.local/bin/nextcloud-borg-backup,
2. legt die Konfiguration an, falls sie noch nicht existiert,
3. erzeugt eine Borg-Passphrase, falls noch keine existiert,
4. installiert systemd-User-Service und Timer,
5. aktiviert den Timer.

Für automatische Läufe ohne aktive Anmeldung:

sudo loginctl enable-linger johannes

Erster Backup-Lauf

systemctl --user start nextcloud-borg-backup.service

Logs:

journalctl --user -u nextcloud-borg-backup.service -f
ls -lah ~/.local/state/nextcloud-borg-backup/logs/

Status:

nextcloud-borg-backup status
nextcloud-borg-backup list

Zeitplanung

Der Timer läuft täglich:

OnCalendar=*-*-* 03:15:00
Persistent=true
RandomizedDelaySec=30m

Persistent=true sorgt dafür, dass ein verpasster Lauf nachgeholt wird, sobald der User-systemd-Manager wieder aktiv ist.

Retention

Die Aufbewahrung ist auf vier Wochen ausgelegt:

RETENTION_WITHIN="4w"

Nach jedem Backup läuft:

borg prune --keep-within 4w
borg compact
borg check --repository-only

Damit bleiben alle Archive der letzten vier Wochen erhalten. Bei einem täglichen Timer sind dadurch mindestens tägliche Wiederherstellungspunkte über rund einen Monat verfügbar. Manuelle Zusatzläufe innerhalb der vier Wochen werden ebenfalls behalten.

Resilienzmaßnahmen

Die Anwendung bricht bewusst ab, wenn eine Sicherheitsannahme nicht erfüllt ist:

• Quelle ist nicht erreichbar oder nicht lesbar.
• Quelle wirkt leer und ALLOW_EMPTY_SOURCE=false.
• Synology-Ziel ist nicht erreichbar oder nicht beschreibbar.
• Freier Platz am Ziel liegt unter MIN_FREE_REPO_GB.
• Borg-Passphrase fehlt bei verschlüsseltem Repository.
• Ein anderer Backup-Lauf hält bereits den Lock.

Weitere Maßnahmen:

• Borg-Repo wird bei Bedarf einmalig initialisiert.
• Borg verwendet deduplizierte Archive statt Vollkopien.
• Nach dem Backup läuft Retention und Kompaktierung.
• Nach dem Backup läuft ein Repository-Check.
• Optional kann regelmäßig ein vollständiger Datencheck aktiviert werden:

FULL_CHECK_VERIFY_DATA="true"
FULL_CHECK_INTERVAL_DAYS="7"

Ein vollständiger borg check --verify-data kann bei großen Repositories lange dauern.

Dateien suchen

Über alle Archive suchen:

nextcloud-borg-backup search "Steuer"

Nur in einem bestimmten Archiv suchen:

nextcloud-borg-backup search "Steuer" nextcloud-2026-07-10_03-15-00

Die Ausgabe enthält bei archivübergreifender Suche den Archivnamen und den Pfad.

Archive mounten

Alle Archive als lesbare Struktur mounten:

nextcloud-borg-backup mount

Standard-Mountpunkt:

${XDG_RUNTIME_DIR}/nextcloud-borg-backup-mount

Ein einzelnes Archiv mounten:

nextcloud-borg-backup mount nextcloud-2026-07-10_03-15-00

Unmount:

nextcloud-borg-backup umount

Falls borg mount nicht verfügbar ist, muss auf Arch Linux das passende FUSE-Paket installiert sein.

Restore

Neuestes Archiv komplett wiederherstellen:

nextcloud-borg-backup restore

Ziel:

~/Nextcloud-Restore/<Archivname>/

Bestimmten Pfad aus dem neuesten Archiv wiederherstellen:

nextcloud-borg-backup restore "" "Dokumente/Projekt"

Bestimmten Pfad aus einem bestimmten Archiv wiederherstellen:

nextcloud-borg-backup restore nextcloud-2026-07-10_03-15-00 "Dokumente/Projekt" ~/Restore-Test

Wichtig: Die Anwendung extrahiert standardmäßig nicht direkt zurück in den produktiven Nextcloud-Ordner. Das reduziert das Risiko, versehentlich aktuelle Dateien zu überschreiben. Nach Prüfung können die wiederhergestellten Dateien gezielt zurückkopiert werden.

Disaster Recovery

Für eine Wiederherstellung auf einem neuen System werden benötigt:

1. das Borg-Repository unter /net/thor/volume1/NetBackup/Nextcloud/borg-repo,
2. die Borg-Passphrase aus ~/.config/nextcloud-borg-backup/passphrase,
3. Borg selbst.

Minimaler Restore:

export BORG_PASSCOMMAND='cat /pfad/zur/passphrase'
borg list /net/thor/volume1/NetBackup/Nextcloud/borg-repo
borg extract /net/thor/volume1/NetBackup/Nextcloud/borg-repo::ARCHIVNAME

Die Passphrase sollte separat sicher abgelegt werden. Ohne Passphrase ist ein verschlüsseltes Repository nicht nutzbar.

Wartung

Manueller Repository-Check:

nextcloud-borg-backup check

Vollständiger Datencheck:

nextcloud-borg-backup check --verify-data

Borg-Lock lösen, falls ein Lauf hart abgebrochen wurde und sicher kein Backup mehr läuft:

nextcloud-borg-backup break-lock

Timer deaktivieren:

systemctl --user disable --now nextcloud-borg-backup.timer

Deinstallation der lokalen Anwendung:

./scripts/uninstall.sh

Die Deinstallation löscht bewusst nicht:

• Borg-Repository,
• Passphrase,
• Konfiguration,
• Logs,
• Restore-Verzeichnis.

Gitea-Upload

Das Verzeichnis /home/johannes/localdev/nextcloud-borg-backup ist als eigenständiges Projekt vorbereitet. Vor dem Push:

cd /home/johannes/localdev/nextcloud-borg-backup
git init
git add .
git commit -m "Initial nextcloud borg backup application"
git remote add origin <gitea-url>
git push -u origin main

Keine lokalen Geheimnisse werden im Projekt abgelegt. Die produktive Passphrase entsteht erst bei der Installation unter ~/.config/nextcloud-borg-backup/passphrase.