Repository navigation
Home
Look at the README.md for the introduction.
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.
| 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.
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.
zfs-autobackup runs many commands via SSH. Thus, set up a login without a password.
-
On
backup, make an SSH key. Do this one time only. Keep the passphrase empty:root@backup:~# ssh-keygen
-
Copy the public key to
pve01.ssh-copy-idasks for your password one time:root@backup:~# ssh-copy-id root@pve01
backup can now log in to pve01 as root without a password.
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 rpoolChild 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 localThe 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
zfscommand to set the property. Do not use thezpoolcommand. - 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 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 successfullyzfs-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.
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).
To make the target structure the same as the source:
- Select the full source pool:
zfs set autobackup:offsite1=true rpool - Exclude the datasets that you do not want. Do this before the first real run.
- Use
--strip-path=1. - Use the target pool as the target path. In this example:
data. - Do a test run with
--testand without--force. - If necessary, use
--forceone time to overwrite the existing target pool.
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.
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.
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/autobackupYou can then send these backups to a remote server with a second backup name:
zfs-autobackup -v --ssh-target root@backupserver remote data/backup/pve01Each 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.
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.
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-sendAt the weekend:
zfs-autobackup -v --ssh-source pve01 offsite1 data/backup/pve01Without a target path, zfs-autobackup only makes snapshots and thins them:
zfs-autobackup -v --ssh-source pve01 offsite1Use this when you do not want a backup, or when the target is not always available. For offline backups, read Common snapshots and holds.
Monitor the results of your backups. See Monitoring.
You can use zfs-autobackup together with other snapshot tools, for example zfs-auto-snapshot. zfs-autobackup only thins its own snapshots.
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.
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.
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.
- Use
--clear-mountpointto prevent many problems. See Mounting. - Use
--debugto see the commands that zfs-autobackup runs. It stops at the first error. - Use
--force,--destroy-incompatibleand--rollbackonly one time, when necessary. Do not put them in your script. If you need them again and again, find the cause. - Set
readonly=onon the target dataset. This prevents changes to the contents of the target. A change on the target causes the next backup to fail. (zfs rollbackon the target usually repairs this.) zfs-autobackup can still receive new datasets and change properties. - Use
--clear-refreservationto save space on the backup machine. - zfs-autobackup uses holds. Thus
zfs destroyof a snapshot can give "dataset is busy". See Problems.
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"Read the Full manual to learn how zfs-autobackup works.
Or go to:
- Performance tips (recommended)
- Common problems and errors
- Thinning out obsolete snapshots
- Handling ZFS encryption
- Transfer buffering, compression and rate limiting
- Custom pre- and post-snapshot commands
- Monitoring
- Proxmox example
If you like Alpine Linux and want to use it with ZFS, see my other project: https://github.com/psy0rz/alpinebox
zfs-autobackup:
- Introduction (README.md)
- Getting started
- Full manual
- Mounting backup datasets
- Performance tips (recommended)
- Common problems and errors
- Thinning out obsolete snapshots
- Common snapshots, holds and bookmarks
- Handling ZFS encryption
- Transfer buffering, compression and rate limiting.
- Custom Pre- and post-snapshot commands
- Monitoring
Examples: