Synopsis #
ZFS replication tools coordinate snapshots, incremental send streams, retries, retention, and reporting. They do not turn an online replica into an independent backup. Credentials that can overwrite the destination, untested restores, and shared failure domains remain architectural risks regardless of the scheduler.
Establish one successful full and incremental transfer with ZFS replication over SSH before selecting automation. That exercise exposes the dataset hierarchy, encryption mode, delegation, and recovery behavior that an automation tool must preserve.
Compare the operating models #
| Approach | Model | Strong fit | Principal cost |
|---|---|---|---|
| Native script | zfs snapshot, zfs send, zfs receive, SSH, and a scheduler | Small, stable dataset set with locally reviewable code | Retention, resume state, locking, and observability must be engineered |
| zrepl | Long-running jobs for snapshotting, push or pull replication, pruning, and monitoring | Multiple datasets needing managed replication state and structured status | Another daemon and configuration format; upstream documents no stability guarantee |
| zfs-autobackup | Command-driven policy with dataset properties and a scheduler | Property-selected datasets and a comparatively small operational surface | Python runtime, command-line policy, and locally designed scheduling and alerting |
| Sanoid and Syncoid | Policy-driven snapshots plus a command-line replication utility | Existing Sanoid retention policy and explicit Syncoid jobs | FreeBSD-specific shell and installation behavior must be qualified |
No row is a popularity ranking. Select the smallest model that supplies required failure handling without hiding state that cannot be recovered during an incident.
Preserve the same safety contract #
Every candidate should be evaluated against one written contract:
- source datasets and recursive child behavior;
- snapshot names, application quiescence, and retention on each side;
- full and incremental stream behavior;
- native encryption and whether raw sends are required;
- push or pull credentials and their delegated ZFS permissions;
- resume behavior after process, network, or destination failure;
- treatment of destination-only snapshots and dataset divergence;
- capacity thresholds and last-success alerts;
- restore procedure and test frequency.
Retention is a destructive operation. Test pruning against disposable datasets before granting an automation account permission to destroy snapshots. Keep the destination unmounted or isolated when it is not intended to serve production data.
Keep native automation transparent #
A native script can be appropriate when the dataset set is small and the operator is prepared to own every state transition. It should refuse to proceed when a prerequisite is ambiguous rather than guessing.
At minimum, the script must:
- take a lock so runs cannot overlap;
- identify and verify the last common snapshot;
- estimate the intended stream before sending it;
- distinguish a resumable receive from a new transfer;
- verify the received snapshot before pruning either side;
- emit machine-observable success, failure, duration, and byte counts;
- return a nonzero status on partial work.
Do not parse human-oriented zfs list output without selecting stable fields. Do not use zfs receive -F as a routine divergence fix; it can destroy destination changes. The snapshot and replication guide
covers the base mechanism.
Qualify zrepl #
Current zrepl documentation describes periodic snapshots, push and pull replication, SSH and authenticated TCP transports, resumable transfers, automatic holds and bookmarks, flexible pruning, structured logs, zrepl status, and a Prometheus endpoint.
Those features make zrepl suitable where replication cursor protection and observable job state would otherwise become substantial local code. Its upstream documentation also states that the project remains under active development and does not guarantee RPC or configuration-format stability. Package and configuration upgrades therefore require changelog review and a staged test.
Verify which side controls pruning, how remote authorization is constrained, and how a job is reconstructed from configuration plus on-disk holds and bookmarks. Do not manually remove zrepl-managed holds or bookmarks during ordinary cleanup.
Qualify zfs-autobackup #
The zfs-autobackup upstream project states that it is tested with FreeBSD and selects datasets through a ZFS property. It provides snapshot thinning, holds, resumable transfers, rate limiting, test output, and local or remote modes, while needing installation on only one side.
This model can be easier to audit than a two-ended daemon when a scheduler and alert transport already exist. Qualification should still prove the exact OpenZFS feature combination on both endpoints, especially when operating-system versions differ. Upstream documents that unsupported received properties can cause cross-platform transfer errors.
Keep the complete command line, property selection, scheduler entry, and retention decision in version control. A command that works interactively but lacks a durable schedule and failure alert is not backup automation.
Qualify Sanoid and Syncoid #
Sanoid manages snapshot creation, thinning, and monitoring from policy. Syncoid is its command-line replication utility and can push or pull through SSH without a Sanoid configuration file.
The upstream repository includes a FreeBSD-specific note: Syncoid expects a Bourne-style remote shell, while the traditional FreeBSD root shell is not necessarily compatible with its redirects. The same note describes path adjustments needed by direct upstream installations. Prefer the maintained FreeBSD package when available, and verify the installed scripts and remote shell rather than applying historical upstream edits blindly.
Sanoid and Syncoid are a useful fit when policy-driven local snapshots and individually scheduled replication jobs are desired. Their two responsibilities remain distinct: a Sanoid retention policy does not establish a remote authorization boundary, and a successful Syncoid run does not prove a restore.
Prove recovery before migration #
Run the chosen candidate against disposable source and destination datasets. Exercise:
- initial replication and two incrementals;
- an interrupted stream and documented resume behavior;
- source snapshot pruning around the last common point;
- a destination capacity failure;
- an authentication failure;
- a restored clone or isolated receive with representative application data.
Migration from another tool must account for its snapshots, holds, bookmarks, resume tokens, and destination properties. Running two pruning engines over the same snapshot namespace is unsafe unless their ownership rules have been designed to coexist.
See restore files from a snapshot and plan a home server for recovery and failure-domain context.