From e2b4bb14132bf94af3f4da1347eb3873a3a265e5 Mon Sep 17 00:00:00 2001 From: x3 Date: Mon, 7 Sep 2026 17:23:39 +0000 Subject: [PATCH] docs: add README with layout diagrams, architecture, and usage guide --- README.md | 216 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c1074eb --- /dev/null +++ b/README.md @@ -0,0 +1,216 @@ +# x3-Backup + +GTK3 Backup/Snapshot-Tool mit rsync Backend. + +Erstellt platzsparende Snapshots via Hardlink-Delta, durchstoebern und wiederherstellen von Einzeldateien oder ganzen Systemen. + +## Features + +- **rsync Snapshots** — Hardlink-Delta fuer platzsparende inkrementelle Backups +- **Snapshot Sidebar** — Alle Snapshots chronologisch sortiert +- **File Browser** — Dateien/Ordner durchsuchen mit Berechtigungen (rwx) +- **Restore** — Einzeldateien oder ganze Verzeichnisse wiederherstellen +- **System Tray** — Icon im Panel mit Status und Kontextmenue +- **Live Log** — Echtzeit-Ausgabe waehrend Backup/Restore +- **History Log** — Komplettes Log durchsuchbar +- **Cronjob** — Geplante Backups direkt aus dem Programm +- **System Backup** — Komplettes Root-Filesystem sichern +- **System Restore** — Aus Live-ISO wiederherstellen +- **CLI Modus** — `--backup`, `--system-backup` fuer Cron/Automation + +## Installation + +```bash +autoreconf -fi +./configure +make -j$(nproc) +sudo make install +``` + +Oder lokal bauen und starten: +```bash +autoreconf -fi && ./configure && make -j$(nproc) +./src/x3-backup +``` + +## Deinstallation + +```bash +sudo ./uninstall.sh +``` + +## Layout + +``` ++------------------------------------------------------------------+ +| x3-Backup [─] [□] [×] | ++------------------------------------------------------------------+ +| File | Backup | System | Help | ++------------------------------------------------------------------+ +| [New Backup] [Restore] [Delete] | [Settings] [========] 0% | ++------------------------------------------------------------------+ +| | | +| Snapshots | [↑] [/home/user/documents] | +| | Select a snapshot to browse | +| ┌────────┐ | ┌──────────────────────────────────────────────────┐| +| │2026-09 │ | │ Name │ Size │ Permissions │ Modified │| +| │07 16:30│ | ├─────────────────┼────────┼─────────────┼──────────┤| +| │ │ | │ Documents │ - │ drwxr-xr-x │ │| +| ├────────┤ | │ Pictures │ - │ drwxr-xr-x │ │| +| │2026-09 │ | │ .bashrc │ 3.4 KB │ -rw-r--r-- │ │| +| │06 02:00│ | │ .ssh │ - │ drwx------ │ │| +| │ │ | │ notes.txt │ 12 KB │ -rw-r--r-- │ │| +| ├────────┤ | │ config.json │ 1.2 KB │ -rw-r--r-- │ │| +| │2026-09 │ | └──────────────────────────────────────────────────┘| +| │05 02:00│ | | +| └────────┘ | ┌──────────────────────────────────────────────────┐| +| | │ Live Log: │| +| | │ [cmd] rsync -aAX --info=progress2 --delete ... │| +| | │ [info] Syncing: /home/user/Documents/project/ │| +| | │ [done] Snapshot created: 2026-09-07_16-30-00 │| +| | │ │| +| | │ [Clear] │| +| | └──────────────────────────────────────────────────┘| ++------------------------------------------------------------------+ +| x3-Backup - Idle Status Message| ++------------------------------------------------------------------+ +``` + +## Dateisystem-Struktur + +### Konfiguration + +``` +~/.config/x3-backup/ +├── settings.json # Einstellungen +├── x3-backup.log # Log-Datei +``` + +### Backup-Destination + +``` +/mnt/backups/ # oder konfigurierter Pfad +├── snapshots/ +│ ├── 2026-09-07_16-30-00/ # Snapshot 1 (Hardlinks) +│ │ ├── home/ +│ │ │ └── user/ +│ │ │ ├── documents/ +│ │ │ ├── .bashrc +│ │ │ └── ... +│ │ ├── etc/ +│ │ └── ... +│ ├── 2026-09-06_02-00-00/ # Snapshot 2 (nur Aenderungen) +│ │ └── ... +│ └── 2026-09-05_02-00-00/ # Snapshot 3 (aehnlich) +│ └── ... +└── metadata/ + ├── 2026-09-07_16-30-00.json # Metadaten + ├── 2026-09-06_02-00-00.json + └── 2026-09-05_02-00-00.json +``` + +### Hardlink-Prinzip + +``` +Snapshot 1 (voll): Snapshot 2 (delta): + fileA (100KB) ──inode1 fileA (100KB) ──inode1 (identisch, Hardlink) + fileB (50KB) ──inode2 fileB (75KB) ──inode3 (geaendert, neue Datei) + fileC (200KB) ──inode3 fileC (200KB) ──inode3 (identisch, Hardlink) + fileD (30KB) ──inode4 (neu) + +Platzbedarf: voll + delta (statt 2x voll) +``` + +## Config (settings.json) + +```json +{ + "backup_dest": "/mnt/backups", + "source_path": "/", + "exclude_patterns": [ + "/mnt", + "/proc", + "/sys", + "/dev", + "/run", + "/tmp", + "/lost+found" + ], + "preserve_permissions": true, + "preserve_acls": true, + "preserve_xattrs": true, + "delete_removed": true, + "retention_days": 30, + "retention_count": 10, + "cron_enabled": false, + "cron_schedule": "0 2 * * *", + "cron_label": "x3-backup-auto" +} +``` + +## CLI Nutzung + +```bash +# Backup jetzt erstellen und beenden +x3-backup --backup + +# System-Backup (von Live-ISO) +x3-backup --system-backup + +# Log auf STDOUT ausgeben +x3-backup --backup --log + +# Hilfe +x3-backup --help +``` + +## Cronjob Beispiel + +```bash +# Taeglich um 2:00 Uhr +0 2 * * * /usr/local/bin/x3-backup --backup & + +# Alle 6 Stunden +0 */6 * * * /usr/local/bin/x3-backup --backup & + +# Woechentlich Sonntag 3:00 Uhr +0 3 * * 0 /usr/local/bin/x3-backup --backup & +``` + +## Log Format + +``` +[2026-09-07 16:30:00] [INFO] x3-backup: === x3-backup started === +[2026-09-07 16:30:00] [INFO] x3-backup: Log file: ~/.config/x3-backup/x3-backup.log +[2026-09-07 16:30:01] [INFO] x3-backup: rsync cmd: rsync -aAX --info=progress2 ... +[2026-09-07 16:30:15] [INFO] x3-backup: [done] Snapshot created: 2026-09-07_16-30-00 +``` + +## Rechte und Wiederherstellung + +| Aktion | Benoetigte Rechte | +|---|---| +| Backup erstellen | Normaler User (nur lesend auf Quelle) | +| Datei wiederherstellen | sudo (fuer Root-Berechtigungen) | +| System wiederherstellen | sudo | +| Cronjob installieren | Normaler User (crontab -e) | + +## Abhaengigkeiten + +- GTK+ 3.0 (>= 3.24) +- json-glib-1.0 +- rsync +- crontab (optional) + +## Architektur + +``` +┌─────────────┐ ┌──────────────┐ ┌──────────────┐ +│ MainWindow │───▶│SnapshotManager│───▶│ RsyncManager │ +│ (GTK UI) │ │ (Snapshots) │ │ (rsync) │ +└──────┬──────┘ └──────────────┘ └──────────────┘ + │ + ├── SystemTray (Tray-Icon) + ├── SettingsDialog (Einstellungen) + └── Config (JSON) +```