Skip to content
DatuX edited this page Nov 13, 2026 · 72 revisions

Look at the README.md for the introduction.

Getting started

zfs-autobackup makes ZFS snapshots on a source machine and replicates them to a target machine via SSH.

Install it on the source or on the target, not on both:

  • On the source, zfs-autobackup pushes snapshots to the target.
  • On the target, zfs-autobackup pulls snapshots from the source.

Installation

Method Command Beta version
pip (recommended) pip install --upgrade zfs-autobackup Add --pre
pipx (newer distributions) pipx install zfs-autobackup Add --pip-args=--pre
Docker or Podman (for example TrueNAS SCALE) See zfs-autobackup-docker

The pip command also upgrades zfs-autobackup to the newest stable version.

To run zfs-autobackup from the sources, or to change the code, see Development.

Example

In this example, the machine backup pulls backups from the machine pve01.

Most examples use root on the source and the target. To use a normal user, see Running without root.

Set up SSH login

zfs-autobackup runs many commands via SSH. Thus, set up a login without a password.

  1. On backup, make an SSH key. Do this one time only. Keep the passphrase empty:

    root@backup:~# ssh-keygen
  2. Copy the public key to pve01. ssh-copy-id asks for your password one time:

    root@backup:~# ssh-copy-id root@pve01

backup can now log in to pve01 as root without a password.

Select the datasets to back up

Give the datasets a backup name. In this example, the backup name is offsite1. Use the same name each time.

On the source, set the ZFS property autobackup:offsite1 to true:

[root@pve01 ~]# zfs set autobackup:offsite1=true rpool

Child datasets inherit ZFS properties. Thus, this selects the full pool.

To exclude a dataset, set the property to false:

[root@pve01 ~]# zfs set autobackup:offsite1=false rpool/tmp
[root@pve01 ~]# zfs get -t filesystem,volume autobackup:offsite1
NAME                      PROPERTY             VALUE                SOURCE
rpool                     autobackup:offsite1  true                 local
rpool/ROOT                autobackup:offsite1  true                 inherited from rpool
rpool/ROOT/pve-1          autobackup:offsite1  true                 inherited from rpool
rpool/data                autobackup:offsite1  true                 inherited from rpool
rpool/data/vm-100-disk-0  autobackup:offsite1  true                 inherited from rpool
rpool/data/vm-101-disk-0  autobackup:offsite1  true                 inherited from rpool
rpool/tmp                 autobackup:offsite1  false                local

The property can have these values:

Value Backs up
true The dataset and all its children.
false Nothing. This excludes the dataset and all its children.
child Only the children, not the dataset.
parent Only the dataset, not the children. (v3.2 or higher)

Notes:

  • Use the zfs command to set the property. Do not use the zpool command.
  • To remove the property: zfs inherit autobackup:offsite1 rpool
  • To back up different sets of datasets in different ways, use more than one backup name.

Run zfs-autobackup

Run zfs-autobackup on backup. --ssh-source tells it where to pull from:

[root@backup ~]# zfs-autobackup -v --clear-mountpoint --ssh-source pve01 offsite1 data/backup/pve01
  ...
  #### Selecting
  [Source] rpool: Selected
  [Source] rpool/ROOT: Selected
  [Source] rpool/ROOT/pve-1: Selected
  [Source] rpool/data: Selected
  [Source] rpool/data/vm-100-disk-0: Selected
  [Source] rpool/data/vm-101-disk-0: Selected
  [Source] rpool/tmp: Excluded
  
  #### Snapshotting
  [Source] Creating snapshots offsite1-20220107131107 in pool rpool
  ...
  #### Synchronising
  [Target] data/backup/pve01/rpool@offsite1-20220107131107: receiving full
  [Target] data/backup/pve01/rpool/ROOT@offsite1-20220107131107: receiving full
  ...
  #### All operations completed successfully

The results

zfs-autobackup keeps the full path of the source. For example:

rpool/data/vm-100-disk-0 becomes data/backup/pve01/rpool/data/vm-100-disk-0

For a backup, it is useful to keep the original structure.

Stripping the path

Use --strip-path=N to remove the first N parts of the source path.

If two source datasets get the same target path, zfs-autobackup shows an error (v3.1.2 and higher).

Making source and target paths look the same

To make the target structure the same as the source:

  1. Select the full source pool: zfs set autobackup:offsite1=true rpool
  2. Exclude the datasets that you do not want. Do this before the first real run.
  3. Use --strip-path=1.
  4. Use the target pool as the target path. In this example: data.
  5. Do a test run with --test and without --force.
  6. If necessary, use --force one time to overwrite the existing target pool.

Pull or push?

This example is a pull backup: the target pulls the data from the source. Usually this is the better method.

Method Who has SSH access to whom How
Pull The target has access to the source. Run on the target with --ssh-source.
Push The source has access to the target. Run on the source with --ssh-target. Set up the SSH keys in the opposite direction.

You can change between pull and push at any time.

Pull+push (zero trust)

A third server can pull from the source and push to the target in one stream. The source and the target then do not have access to each other. If an attacker gets access to one server, the attacker cannot get access to the other server.

Install zfs-autobackup on the third server only. Use --ssh-source and --ssh-target together.

Local Usage

Without --ssh-source and --ssh-target, zfs-autobackup works locally. For example, to back up to the pool backups on the same server:

zfs-autobackup -v local backups/autobackup

You can then send these backups to a remote server with a second backup name:

zfs-autobackup -v --ssh-target root@backupserver remote data/backup/pve01

Automatic backups

Each run makes a new snapshot and replicates the data. The Thinner destroys old snapshots. --keep-source and --keep-target control this.

When your settings are correct, put the command in a cron job or in a script.

Avoid parallel jobs

If a job takes too long, cron can start the next job before the previous job is finished. This does not cause permanent damage. But backups can fail and the IO load increases. If many jobs run at the same time, the server can run out of memory.

Use flock to prevent parallel jobs:

22 * * * * flock -n /var/backups.lock zfs-autobackup backup1 rpool/backup -v --ssh-target=....

When flock skips a job, you do not get a snapshot for that time. To prevent this, use a separate snapshot job and a separate send job. See below.

Splitting up snapshot and backup jobs

For example: make snapshots each weekday, and transfer the data only at the weekend.

On weekdays, use --no-send:

zfs-autobackup -v --ssh-source pve01 offsite1 data/backup/pve01 --no-send

At the weekend:

zfs-autobackup -v --ssh-source pve01 offsite1 data/backup/pve01

Use as a snapshot tool

Without a target path, zfs-autobackup only makes snapshots and thins them:

zfs-autobackup -v --ssh-source pve01 offsite1

Use this when you do not want a backup, or when the target is not always available. For offline backups, read Common snapshots and holds.

Monitoring

Monitor the results of your backups. See Monitoring.

Use alongside other snapshot tools

You can use zfs-autobackup together with other snapshot tools, for example zfs-auto-snapshot. zfs-autobackup only thins its own snapshots.

Specifying ssh port or options

Put SSH settings in ~/.ssh/config:

Host smartos04
    Hostname 1.2.3.4
    Port 1234
    User root

Then use smartos04 as the host name. See man ssh_config for all options.

Multiple backups of the same data

To send the same data to more than one target, use a different backup name for each target. For example: autobackup:offsite and autobackup:local. Each job only destroys its own snapshots, so the jobs do not interfere.

Using the same backup name

Since v4.0, you can also use the same backup name for more than one target. zfs-autobackup makes a bookmark on the source for each target. The bookmark has the GUID of the target dataset. Thus, the jobs do not interfere.

In older versions, one job could destroy the common snapshot of the other job. You had to prevent this with --keep-source, or run the jobs at a short interval.

Different backup names are still easier to understand.

Tips

  • Use --clear-mountpoint to prevent many problems. See Mounting.
  • Use --debug to see the commands that zfs-autobackup runs. It stops at the first error.
  • Use --force, --destroy-incompatible and --rollback only one time, when necessary. Do not put them in your script. If you need them again and again, find the cause.
  • Set readonly=on on the target dataset. This prevents changes to the contents of the target. A change on the target causes the next backup to fail. (zfs rollback on the target usually repairs this.) zfs-autobackup can still receive new datasets and change properties.
  • Use --clear-refreservation to save space on the backup machine.
  • zfs-autobackup uses holds. Thus zfs destroy of a snapshot can give "dataset is busy". See Problems.

Restore example

Use normal ZFS commands to restore. For example:

root@fs1:~# zfs send fs1/zones/backup/zfsbackups/server01/vm01@offsite1-20220110230003 | ssh root@2.2.2.2 "zfs recv rpool/restore"

More information

Read the Full manual to learn how zfs-autobackup works.

Or go to:

If you like Alpine Linux and want to use it with ZFS, see my other project: https://github.com/psy0rz/alpinebox

Clone this wiki locally