# 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: ```bash SOURCE_DIR="${HOME}/Nextcloud" REPO_DIR="/net/thor/volume1/NetBackup/Nextcloud/borg-repo" ARCHIVE_PREFIX="nextcloud" RETENTION_WITHIN="4w" ``` Lokale Laufzeitdaten: ```bash ~/.config/nextcloud-borg-backup/config ~/.config/nextcloud-borg-backup/passphrase ~/.config/nextcloud-borg-backup/excludes ~/.local/state/nextcloud-borg-backup/logs/ ~/Nextcloud-Restore/ ``` ## Installation ```bash 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: ```bash sudo loginctl enable-linger johannes ``` ## Erster Backup-Lauf ```bash systemctl --user start nextcloud-borg-backup.service ``` Logs: ```bash journalctl --user -u nextcloud-borg-backup.service -f ls -lah ~/.local/state/nextcloud-borg-backup/logs/ ``` Status: ```bash nextcloud-borg-backup status nextcloud-borg-backup list ``` ## Zeitplanung Der Timer läuft täglich: ```ini 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: ```bash RETENTION_WITHIN="4w" ``` Nach jedem Backup läuft: ```bash 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: ```bash 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: ```bash nextcloud-borg-backup search "Steuer" ``` Nur in einem bestimmten Archiv suchen: ```bash 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: ```bash nextcloud-borg-backup mount ``` Standard-Mountpunkt: ```bash ${XDG_RUNTIME_DIR}/nextcloud-borg-backup-mount ``` Ein einzelnes Archiv mounten: ```bash nextcloud-borg-backup mount nextcloud-2026-07-10_03-15-00 ``` Unmount: ```bash 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: ```bash nextcloud-borg-backup restore ``` Ziel: ```bash ~/Nextcloud-Restore// ``` Bestimmten Pfad aus dem neuesten Archiv wiederherstellen: ```bash nextcloud-borg-backup restore "" "Dokumente/Projekt" ``` Bestimmten Pfad aus einem bestimmten Archiv wiederherstellen: ```bash 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: ```bash 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: ```bash nextcloud-borg-backup check ``` Vollständiger Datencheck: ```bash nextcloud-borg-backup check --verify-data ``` Borg-Lock lösen, falls ein Lauf hart abgebrochen wurde und sicher kein Backup mehr läuft: ```bash nextcloud-borg-backup break-lock ``` Timer deaktivieren: ```bash systemctl --user disable --now nextcloud-borg-backup.timer ``` Deinstallation der lokalen Anwendung: ```bash ./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: ```bash cd /home/johannes/localdev/nextcloud-borg-backup git init git add . git commit -m "Initial nextcloud borg backup application" git remote add origin 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`.