Kartoza ZFS Backup Tool

A beautiful TUI (Terminal User Interface) for managing ZFS backups, built with Bubble Tea and Lipgloss.

📖 Full Documentation

Features

• Incremental Backups - Efficient snapshots with syncoid integration
• Force Backup - Destructive backup option for out-of-sync scenarios
• Restore Files - Dual-panel file explorer to browse snapshots and restore files
• Pool Information - View detailed pool structure, health, datasets, and snapshots
• Pool Maintenance - Start, stop, and monitor scrub operations
• Device Preparation - Create encrypted ZFS pools with AES-256-GCM
• Safe Unmounting - Properly export pools and power off USB drives
• CLI Mode - Command-line arguments for automation and scripting

Quick Start

Install

# Download binary (Linux x86_64)
curl -L https://github.com/timlinux/zfs-backup/releases/latest/download/zfs-backup-linux-amd64 -o zfs-backup
chmod +x zfs-backup
sudo mv zfs-backup /usr/local/bin/

# Or with Nix
nix run github:timlinux/zfs-backup

See Installation Guide for more options including NixOS, Arch (AUR), Debian, Fedora, Snap, and Flatpak.

Run

# Interactive mode
sudo zfs-backup

# CLI mode
sudo zfs-backup --backup      # Run incremental backup
sudo zfs-backup --unmount     # Safely unmount backup drive
sudo zfs-backup --help        # Show help

Requirements

• Linux with ZFS filesystem
• syncoid (from sanoid package)
• Root privileges or ZFS delegation configured
• External drive with encrypted ZFS pool (for backups)

Menu Options

Option	Description
Backup ZFS (incremental)	Run efficient incremental backup using syncoid
Restore Files	Browse snapshots and restore individual files
Show zpool info	View pool structure, health, datasets, and snapshots
Pool Maintenance	Start/stop scrubs, monitor pool health
Unmount Backup Disk	Safely export pool and power off USB drive
Prepare Backup Device	Create new encrypted ZFS pool on external drive
Force Backup (destructive)	Reset backup when incremental chain is broken

Keyboard Shortcuts

Navigation

Key	Action
↑/k ↓/j	Navigate
Enter	Select
Esc	Go back
q	Quit

Scrollable Views (Pool Info, Maintenance, Results)

Key	Action
j/k	Scroll line
Ctrl+u/d	Page up/down
g/G	Top/bottom

Restore Mode

Key	Action
Tab or h/l	Switch panels
Space	Toggle selection
y	Copy selected files
/	Search
m	Create directory

See Full Keyboard Reference.

Documentation

• Getting Started
• Backup Operations
• Restore Files
• Pool Information
• Pool Maintenance
• Installation Guide
• ZFS Delegation

Architecture

zfs-backup/
├── main.go       # Bubble Tea TUI and main application logic
├── zfs.go        # ZFS operations (backup, prepare, unmount)
├── state.go      # Backup state management for resume
├── restore.go    # Restore mode with dual-panel explorer
├── flake.nix     # Nix flake configuration
└── docs/         # MkDocs documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

See Contributing Guide.

License

MIT License - see LICENSE file for details.

---

Made with <3 by Kartoza | Donate! | GitHub