% zelta-rotate(8) | System Manager's Manual
zelta rotate - recover sync continuity by renaming, cloning, and incrementally syncing a ZFS replica
zelta rotate [OPTIONS] source target
zelta rotate renames a target replica and performs a multi-way clone and sync operation to restore sync continuity when a source and target have diverged. The operation considers up to four dataset states: the current source, the current target, the source's origin (if cloned), and the target's origin, finding the optimal sync path between them.
This technique is a non-destructive alternative to zfs rollback and zfs recv -F, useful for maintaining forensic evidence in recovery scenarios and advanced iterative infrastructure workflows.
As with zelta backup, zelta rotate works recursively on dataset trees. Both source and target may be local or remote via ssh(1).
The rotate operation syncs the minimum data necessary to complete the task, targeting the next available snapshot for incremental replication. After successful rotation, run zelta backup with your preferred settings to ensure full consistency.
zelta rotate performs these operations:
--no-snapshot is specified).pool/ds with matching snapshot @yesterday becomes pool/ds_yesterday. Note that no properties, including mountpoint and readonly status, are altered.If the topmost target dataset has no common snapshot with either the source or source origin, zelta rotate will not continue. In this case, manually rename the diverged target and use zelta backup to perform a full replication.
Remote endpoint names follow scp(1) conventions. Dataset names follow zfs(8) naming conventions. The target must be a replica of the source.
Examples:
Local: pool/dataset
Remote: user@example.com:pool/dataset
Endpoint Arguments (Required)
If both endpoints are remote, the default behavior is pull replication (--pull). This requires that the target user have ssh access to the source, typically provided by ssh keys or agent forwarding. For advanced ssh configuration, see https://zelta.space.
source
: The dataset to replicate. The source origin, if needed, is automatically detected.
target
: The replica dataset to be rotated.
Output Options
-v, --verbose
: Increase verbosity. Specify once for operational detail, twice (-vv) for debug output.
-q, --quiet
: Quiet output. Specify once to suppress warnings, twice (-qq) to suppress errors.
-n, --dryrun, --dry-run
: Display zfs commands without executing them.
Connection Options
--push, --pull, --sync-direction DIRECTION
: When both endpoints are remote, use PULL (default) or PUSH sync direction.
Snapshot Options
--no-snapshot
: Do not create snapshots. If a snapshot is needed for rotation, the operation will fail.
--snapshot
: Force snapshot creation even if the source has no uncommitted changes.
--snap-name NAME
: Specify snapshot name. Use $(command) for dynamic generation. Default: $(date -u +zelta_%Y-%m-%d_%H.%M.%S).
A common workflow after accidentally diverging a source from its backup:
First, rewind the source to its previous snapshot state using a rename and clone operation:
zelta revert sink/source/dataset
Then rotate the target replica, performing a 4-way incremental sync to match the reverted source:
zelta rotate sink/source/dataset backup-host.example:tank/target/dataset
Finally, ensure full consistency between source and target:
zelta backup sink/source/dataset backup-host.example:tank/target/dataset
The original diverged datasets remain accessible as sink/source/dataset_<snapshot> and tank/target/dataset_<snapshot> for forensic analysis.
Returns 0 on success, non-zero on error.
See zelta-options(7) for environment variables, zelta.env configuration, and zelta policy integration.
zelta(8), zelta-options(7), zelta-match(8), zelta-backup(8), zelta-policy(8), zelta-clone(8), zelta-revert(8), ssh(1), zfs(8), zfs-allow(8)
Daniel J. Bell <bellhyve@zelta.space>