DAS Backup Manager

Version: 0.7.23.0

DAS backup manager with btrbk integration, SQLite FTS5 content indexing, KDE Plasma GUI with full backup management, D-Bus privilege escalation, and an interactive installer for the full backup pipeline.

Scope

This project manages backups to Direct-Attached Storage (DAS) using the BTRFS filesystem. That's it. That's the scope.

The following are permanently out of scope and will never be added:

• NAS (Network-Attached Storage)
• SAN (Storage Area Network)
• Cloud storage (S3, Azure Blob, GCS, Backblaze, etc.)
• Any filesystem other than BTRFS (ext4, XFS, ZFS, NTFS, etc.)

This is not a general-purpose backup tool. It is a DAS + BTRFS backup tool. If you need support for other storage architectures or filesystems, you are welcome to write your own application that covers whichever and however many storage backends your heart desires.

That said, suggestions, recommendations, and requests that fall within this narrow scope are very welcome and will be happily entertained.

Features

• btrbk Backup Orchestration — Nightly incremental BTRFS snapshot backups to DAS enclosure
• Multi-Target Architecture — Configurable primary and mirror roles across any number of DAS drives
• Boot Subvolume Archival — Archives old boot subvolumes with timestamps (configurable retention). Every run, incremental or full, creates a missing boot subvolume from the latest snapshot; only a full run (or btrdasd backup boot-archive) archives and replaces an existing one. The GUI and backup-run.sh apply the same rule
• Scheduled BTRFS Scrub (btrdasd scrub) — Monthly integrity scrub of all DAS backup filesystems, with health-check integration and email reports
• Automatic Subvolume Adoption (btrdasd subvol sync) — Every backup run adds an entry for each new subvolume on a source volume (unless excluded by [subvolumes].exclude), retires entries whose subvolume is gone, and later expires the retired subvolume's backups once the retention window has passed
• Subvolume Drift Detector (btrdasd doctor --check-drift) — Weekly check comparing every source filesystem's actual subvolumes against config.toml, catching silent backup gaps (missing) and stale entries (removed), with email alerts. New subvolumes are adopted by the backup run itself, so a finding means that step failed
• Email Reports — Automated backup status reports with throughput metrics and SMART status
• ButteredDASD Content Indexer (buttered_dasd library + btrdasd CLI) — Rust library and CLI with SQLite FTS5 database tracking every file across all snapshots
• Auto-Mount/Unmount — RAII MountGuard finds each target by its mount_uuid or drive serial (the same rule as backup-run.sh), auto-mounts BTRFS partitions before operations, and unmounts on completion, retrying a busy target; one it cannot release fails the operation with still mounted: <path> (all D-Bus methods and CLI commands)
• Targets Hidden From Desktop Automount — a generated udev rule marks every backup target as ignored by udisks2, so nothing mounts it under /run/media; only the backup run and btrdasd mount targets (btrdasd setup --check reads back whether each attached target carries the flag)
• D-Bus Privileged Helper (btrdasd-helper) — polkit-authorized daemon with 25 methods for backup, restore, config, schedule, health, index read and recovery-OS update operations
• KDE Plasma GUI (btrdasd-gui) — Native Qt6/KF6 full backup management application with sidebar navigation, Dolphin-style file browser, backup operations, health dashboard, config editor, desktop notifications, and system tray
• USB SMART Passthrough — Health queries use -d sat for USB-attached DAS drives to read SMART data through USB-SATA bridges
• Interactive Installer (btrdasd setup) — 9-step wizard with 5 modes: install, modify, upgrade, uninstall, check
• Shell Completions — btrdasd completions generates completions for bash, zsh, fish, elvish, and PowerShell
• Distro-Agnostic — Supports systemd, sysvinit, and OpenRC init systems
• Native Packaging — Packaging recipes for Arch (PKGBUILD), Debian/Ubuntu (dpkg), Fedora (RPM), Flatpak, and Snap — all build-tested on their respective distributions before each release

Components

Component	Description	Status
scripts/backup-run.sh	btrbk backup orchestrator: subvolume sync before btrbk, retired-subvolume expiry after, recovery OS check, email reporting	Active
scripts/backup-verify.sh	DAS drive health and btrbk status verification	Active
scripts/boot-archive-cleanup.sh	Prune old boot subvolume archives (retention: 60 days default; invoked automatically by backup-run.sh every run; skips role=mirror targets)	Active
scripts/das-wipe-all-drives-and-partition-from-scratch.sh	DAS drive partitioning utility	Active
scripts/install-backup-timer.sh	Former timer installer: now prints a pointer to btrdasd setup, which writes and enables the timers, and exits 1	Deprecated
scripts/recovery-os-vm.sh	Lends one recovery drive, whole, to its own recovery-os-updater-<label> VM (template packaging/libvirt/recovery-os-updater.xml) to update its own OS without rebooting the workstation; the host is kept off the drive meanwhile by the maintenance lock and an O_EXCL claim, and btrbk is kept from running in its OS by a per-session guard	Active
config/btrbk.conf	Reference btrbk configuration	Active
indexer/	ButteredDASD (buttered_dasd lib + btrdasd CLI + btrdasd-helper D-Bus daemon)	Active (v0.7.0+)
gui/	Qt6/KDE Plasma full backup management GUI (18 C++ components)	Active (v0.7.0+)
dbus/	D-Bus system bus configuration and service activation files	Active (v0.7.0+)
polkit/	Polkit policy for privilege escalation (8 actions: backup, restore, config, config.read, index, index.read, health, recovery-os)	Active (v0.7.0+)

Each script's version is the # Version: line in its own header — the one place it is kept.

Project Structure

DAS-Backup-Manager/
├── scripts/           # Shell scripts (backup, verify, cleanup, partition, recovery OS VM)
├── config/            # btrbk.conf reference template
├── indexer/           # ButteredDASD — Rust library + CLI + D-Bus helper
│   ├── src/           # Library modules (22): adopt, backup, btrbk_conf, caldate, config, db, doctor, expire, forget, fsutil, health, indexer, mount, progress, reconcile, recovery_os, report, restore, scanner, schedule, scrub, subvol
│   ├── src/setup/     # Binary-only: interactive installer (wizard, templates, detection)
│   ├── src/bin/       # btrdasd-helper D-Bus daemon
│   └── completions/   # Shell completion installation instructions
├── gui/               # Qt6/KDE Plasma GUI (18 C++ components)
│   └── src/           # MainWindow, Sidebar, DBusClient, panels, dialogs, models
├── dbus/              # D-Bus bus config and service activation
├── polkit/            # Polkit privilege escalation policy
├── packaging/         # Distro packaging (Arch, Debian, Fedora, Flatpak, Snap); libvirt/ the recovery OS VM
├── docs/              # Architecture, installation, dependencies, recovery, man page
└── CMakeLists.txt     # Build system (BUILD_GUI, BUILD_INDEXER, BUILD_HELPER)

Minimum Requirements

• Linux with BTRFS support (kernel 5.15+)
• DAS enclosure (any manufacturer, any interface -- USB, Thunderbolt, eSATA)
• One or more BTRFS-formatted drives (any technology: HDD, SSD, NVMe)
• btrbk 0.32+, smartmontools
• Rust 1.88+ with Cargo (needs let-chains; not compile-tested below 1.98.1) for building the indexer and installer
• Optional: Qt6 6.6+ (with Qt6::DBus), KDE Frameworks 6.0+ (with KNotifications, KStatusNotifierItem), CMake 3.25+ (for the GUI)

Installation

Recommended: Full Build (CLI + GUI + Helper)

# Build everything (Rust CLI, D-Bus helper, KDE GUI)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Install all components (binaries, scripts, the helper's unit, D-Bus, polkit, icons, man page)
sudo cmake --install build

# Run the interactive setup wizard to configure backups
sudo btrdasd setup

The wizard configures backup sources, targets, retention, scheduling, and email — then generates all configuration files, writes the backup, scrub and drift-check units, and enables their timers. cmake --install installs no backup unit: setup's are the only ones.

CLI-Only (no GUI dependencies)

cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_GUI=OFF
cmake --build build
sudo cmake --install build
sudo btrdasd setup

See docs/INSTALL.md for all installation methods including native distro packages, manual setup, and CMake build options.

Design Philosophy

• Security-first: Rust for the data pipeline (no buffer overflows, use-after-free, or data races). C++20 RAII with -Werror for the GUI. Exclusive prepared statements for all SQL.
• Memory safety: Minimal unsafe in Rust (single-call libc wrappers: time/localtime_r, gethostname, statvfs, syncfs, flock, geteuid). No raw pointers in C++ GUI code. Smart pointers exclusively.
• Efficiency: Span-based deduplication compresses file presence across snapshots. Incremental indexing skips already-processed snapshots. Nine targeted performance indexes.
• Stability: Indexing errors never abort backups (soft-fail). GUI gracefully handles missing or locked databases.
• Privacy: File metadata only — no file contents are ever read or stored. No telemetry or network connections.

Documentation

• Architecture — System design, data flow, security decisions, encryption assessment
• Installation Guide — All installation methods, config reference
• ButteredDASD Indexer — CLI usage, schema, span logic, development
• Dependencies — Rust crates, system deps, build deps, GUI deps
• Backup Planning — Capacity planning, drive selection, retention worksheet
• Disaster Recovery Guide — Step-by-step recovery procedures
• Storage Architecture & Recovery — BTRFS RAID concepts, failure detection, recovery procedures
• DAS Bay Mapping — How to map and document physical drive locations
• Throughput Baseline — What a healthy run looks like, and why link speed rather than throughput is the health signal
• Reference Examples — Author's hardware setup as a worked example

License

MIT — See LICENSE for details.

---

(A note on versioning: Rust's Cargo.toml enforces strict 3-part semver — no x.y.z.w fourth segment allowed. This means non-functional changes like removing a dead Dockerfile or swapping an internal widget layout strategy each burn a full patch version. On 2026-03-07, this project went through v0.7.7, v0.7.8, AND v0.7.9 in a single evening — three patch releases that should have been one tweak bump from v0.7.7 to v0.7.7.3. >:| )