Initial commit; base scripting and systemd user event code for borg based backup
This commit is contained in:
@@ -0,0 +1,283 @@
|
||||
# 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/<Archivname>/
|
||||
```
|
||||
|
||||
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 <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`.
|
||||
Reference in New Issue
Block a user