Getting Started
What is fsbackup?
An overview of fsbackup — what it does, how it works, and what it's designed for.
fsbackup is an rsync-based snapshot backup system for home labs. It runs as a Docker container and pulls backups from remote hosts over SSH, storing them as hard-linked directory snapshots on a local drive.
How it works
fsbackup uses rsync's --link-dest option to create space-efficient snapshots. Each snapshot is a full directory tree, but unchanged files are hard-linked to the previous snapshot — so only new or changed data takes up additional space.
Snapshots are organized into tiers:
| Tier | Frequency | Retention |
|---|---|---|
| Daily | Every day | 14 days |
| Weekly | Promoted on Monday | 8 weeks |
| Monthly | Promoted on the 1st | 12 months |
| Annual | Promoted from December | Indefinite |
Data classes
Backup targets are grouped into classes. Each class has its own schedule and can be configured independently:
- class1 — application data, databases, personal files (daily)
- class2 — infrastructure config: Docker stacks, nginx, DNS zones (daily)
- class3 — large photo archives (monthly, not mirrored)
What runs in the container
The Docker image contains:
- All backup scripts (
fs-runner.sh,fs-mirror.sh,fs-doctor.sh, etc.) - supercronic for cron scheduling
- A FastAPI + HTMX web UI for monitoring and management
- rsync, age, zstd, and AWS CLI for S3 export
What stays on the host
- Config files (
/etc/fsbackup/) - SSH keys and AWS credentials (
/var/lib/fsbackup/) - Snapshot storage (
/backup/snapshots,/backup2/snapshots) - Prometheus metrics files (
/var/lib/node_exporter/textfile_collector/)
All of these are bind-mounted into the container — the container itself is stateless.