fsbackup iconfsbackup
Installation

Quick start

Get fsbackup running in under 20 minutes with the automated installer.

This guide gets fsbackup running on a bare-metal Linux server using the automated installer.

For detailed steps see Installation.

Prerequisites

  • Ubuntu 22.04+ or Debian 12+ (bare-metal or VM)
  • A ZFS pool with a snapshots dataset (see ZFS pool setup)
  • SSH access to the machines you want to back up

1. Run the installer

curl -fsSL https://raw.githubusercontent.com/fsbackup/fsbackup/main/bin/fs-install.sh | sudo bash

The installer will:

  1. Install required packages (rsync, jq, yq, zstd, age, awscli, zfsutils-linux)
  2. Create the fsbackup system user (UID 993)
  3. Install scripts to /opt/fsbackup/
  4. Create config skeleton in /etc/fsbackup/
  5. Set up ZFS delegation (zfs allow)
  6. Install and enable systemd units
  7. Apply schedule from fsbackup.conf
  8. Optionally set up the web UI

2. Create ZFS datasets for your targets

sudo /opt/fsbackup/bin/fs-provision.sh --dry-run   # preview
sudo /opt/fsbackup/bin/fs-provision.sh              # create

3. Edit config

sudo nano /etc/fsbackup/fsbackup.conf   # set S3_BUCKET, schedules, retention
sudo nano /etc/fsbackup/targets.yml     # define your backup targets

See fsbackup.conf reference and Targets for details.

4. Trust remote hosts

For each host you want to back up:

sudo /opt/fsbackup/utils/fs-trust-host.sh <hostname>

5. Apply ACLs for local paths

If any targets are local paths (e.g. Docker volumes on the same machine):

sudo /opt/fsbackup/bin/fs-fix-permissions.sh

fs-fix-permissions.sh applies setfacl -R -m u:fsbackup:rX to each local source path. Review each path before running — on Docker volume paths this grants the fsbackup user read access to all files inside the volume, including any secrets your containers may store there.

6. Verify and run

# Check target health
sudo -u fsbackup /opt/fsbackup/bin/fs-doctor.sh --class class1

# Dry run
sudo -u fsbackup /opt/fsbackup/bin/fs-runner.sh daily --class class1 --dry-run

# First real backup
sudo -u fsbackup /opt/fsbackup/bin/fs-runner.sh daily --class class1

7. Check the web UI

The web UI runs on port 8080. Open http://<your-server>:8080 in a browser.

Requirements & hardware

What you need to run fsbackup — software prerequisites, disk recommendations, and unsupported configurations.

ZFS pool setup

How to create and configure a ZFS pool for fsbackup snapshot storage.