NAME

SYNOPSIS

 --man                  show man-page and exit
 --version              print version and exit
 -h,--help              display this help and exit
 -d,--debug             print debug messages to STDERR
 -n,--noaction          run in simulation mode: does no changes to filesystems
 --nodelay              if a backup plan has a zend_delay defined, ignore it
 --nodestroy            does all changes to the filesystem except destroy
 --forbidDestRollback   forbids forcing destination dataset rollback and
                        removal of datasets/snapshots not present on source
 --logto=x              select where to log (syslog::<facility> or <filepath>)
 --loglevel=x           define the log level
 --pidfile=x            write a pid file when running in daemon mode
 --daemonize            fork into the background
 --runonce=[x]          run one round on the optionally provided dataset
 -r,--recursive         recurse from the given "run-once" dataset
 --inherited            allow "run-once" on dataset which only inherits a plan
 --since=x              allow to consider a non-automatic common snapshot "x" as a starting point
 --sinceForced=x        same as --since=x but also make sure "x" exists on
                        destination (can cause removal of newer snapshots)
 --forcedSnapshotSuffix=x  use non-generated snapshot suffix for this "run-once"
 --features=x           comma separated list of features to be enabled
                        (detailed in man page):
    oracleMode recvu compressed sendRaw lowmemRecurse zfsGetType
    skipIntermediates sendIntermediates forbidDestRollback
 -i/-I                  a "zfs send" compatible on/off for skipIntermediates
 --rootExec=x           exec zfs with this command to obtain root privileges
                        (sudo or pfexec)
 --connectTimeout=x     sets the ConnectTimeout for ssh commands
 --autoCreation         automatically create dataset on destination if it does
                        not exist
 --timeWarp=x           shift znapzend's sense of NOW into the future
                        by x seconds
 --skipOnPreSnapCmdFail skip snapshots if the pre-snap-command fails
 --skipOnPreSendCmdFail skip replication if the pre-send-command fails
 --cleanOffline         clean up source snapshots even if a destination was offline
 --mailErrorSummaryTo=rcpt  if "send task(s) failed", mail a summary to rcpt

DESCRIPTION

ZnapZend reads its configuration from custom properties in the dataset. Use znapzendzetup to set and list these properties.

-d, --debug

talk a lot while running. Sends debug messages to stderr.

-n, --noaction

don't do any actions which have lasting effect. Ideal to try out new configurations together with --debug

--nodelay

if a backup plan has a zend_delay defined, ignore it (should help when debugging the backup plan configurations, without waiting for hours to run them during experiments)

--nodestroy

do all changes to the filesystem except destroying old snapshots after a successful run to snapshot and replicate to backup destinations

--forbidDestRollback

by default znapzend uses zfs recv -F which rolls back destination to the most recent snapshot, and in case of incremental replication streams can also destroy snapshots and other child datasets not present in the source.

The --forbidDestRollback option allows to not enforce this mode, so znapzend would instead report errors if destination is not ready to receive data without applying such operations. This can be useful for maintenance of backup destinations, but can be counter-productive for regularly scheduled operations.

--logto={syslog::facility|filepath}

send logs out to either syslog or a logfile. Default is to send logs to syslog::daemon when running daemonized. When running in debug mode, the logs will go to STDERR by default.

Examples:

 --logto=/var/log/znapzend.log
 --logto=syslog::daemon
    

--loglevel={debug|info|warning|err|alert}

Define the log level when logging to file. Default is debug.

--pidfile=path

write a pid file when running in daemon mode pidfile defaults to /var/run/znapzend.pid if no pidfile is given

--daemonize

Fork into the background.

--runonce=[dataset]

run one round on source dataset or on all datasets if empty. This is very useful for testing. Use it in connection with --noaction and --debug while testing your new configuration, or with --recursive for quick back up of whatever has backup plans in a single pool or dataset tree.

--forcedSnapshotSuffix=snapsuffix

for this round of --runonce create the specified snapshot suffix, rather than one generated by a pattern managed by 'znapzend'. Note it would not get automatically cleaned per retention policy, either. This is primarily intended for manual operations where a sysadmin wants for mark the certain data state of local significance while making an unscheduled backup.

This option is not valid if the run-once mode is not requested.

While basic sanity checks are done, it is up to the caller to specify a correct string value according to the rules of their ZFS version, and to take care that it is unique (no snapshots with such suffix already exist).

See also --since=snapsuffix

--since=snapsuffix, --sinceForced=snapsuffix

Enables to see a snapshot named snapsuffix in the history of the dataset under source and target pools, which should be a common snapshot present on both (or only on the source pool), and may be their newest common snapshot (that would otherwise be blocking the sync as something that needs to be removed for a full auto-creation replication and/or a usual replication).

If the target dataset does not have this named snapshot, but the otherwise discovered history of automatic snapshots allows to include it into the usual replication, it will be sent (and a newer automatically-named snapshot would be made and sent). In other cases, it is up to the systems administrator to make the original systems data consistent with that on their remote ZFS pool.

One could then use --sinceForced=snapsuffix variant that can remove from destination any snapshots that are newer than snapsuffix to make way if needed, and ensure that this snapshot appears in destination's history; by default with --since=snapsuffix such removals should not happen.

Unlike the --forcedSnapshotSuffix=snapsuffix, this option does not define how the new snapshot made during this run would be called (it would be named by common timestamp-based pattern to not get in the way of subsequent regular replications).

The dataset name provided in this argument will never be removed during this run-once (even if it matches the configured znapzend timestamp-based snapshot naming pattern and is old enough to rotate away in other circumstances).

Example:

  znapzend --runonce=rpool/ROOT --since=20200101-01-finallyStableSetup
    

-r, --recursive

when backing up a particular dataset with --runonce=[dataset], do not just look at this dataset's backup plan, but iterate into its children that might have any. Useful for quick backups of a pool whose root dataset has no znapzendzetup configurations defined, but some trees under it do.

See below for interaction with --inherited option and examples.

--inherited

when backing up a particular dataset with --runonce=[dataset], do not require that the provided dataset directly has a locally defined backup plan configuration (sanity check that it is not "received" via ZFS replication). With this option in place, allow also to quickly snapshot and/or replicate datasets of subtrees which inherit a backup plan from a dataset which has it in its attributes whose source is "local".

--inherited and --recursive together

At this time, the --inherited is "sort of exclusive" vs. --recursive mode, and if both are specified the behavior depends on whether the requested dataset has some (local or inherited-from-local) backup plan. If a dataset without a backup plan is passed, the script should effectively ignore the --inherited option and just recurse until it finds some dataset(s) with proper locally defined backup plan(s) (note that finding inherited plans first is highly unlikely due to ZFS attribute inheritance from parents to children).

Examples below assume the following dataset layout:

+ tank (no znapzend config) | + export (local znapzend config) | | + home (inherited znapzend config from local tank/export) | | + user (inherited znapzend config from local tank/export) | | + sources (inherited znapzend config from local tank/export) | | + documents (inherited znapzend config from local tank/export) | | + pictures (inherited znapzend config from local tank/export) | + var (local znapzend config) + usbbackup (no znapzend config) + snapshots (no znapzend config) + export (received znapzend config) | + home (inherited from received usbbackup/snapshots/export) | + user (inherited from received usbbackup/snapshots/export) | + sources (inherited from received usbbackup/snapshots/export) | + documents (inherited from received usbbackup/snapshots/export) | + documents (inherited from received usbbackup/snapshots/export) + var (received znapzend config)

Examples:

  znapzend --recursive --runonce=tank
    

This should walk all filesystem or volume datasets defined anywhere under tank (root dataset of same-named pool) and snapshot/replicate the found datasets that have a backup plan configured "locally", such as tank/export and tank/var, according to configuration (e.g. with children and beyond if the corresponding backup plan's recursive=on option is specified). It should not waste time looking for datasets under the usbbackup pool.

  znapzend --runonce=tank/export/home/user/documents
    

Given that only tank/export "locally" defines a znapzend backup plan, the default znapzend behavior with a descendant dataset would be to find no configuration (sourced as "local" right in it) and so would "run-once" nothing.

  znapzend --recursive --runonce=tank/export/home
    

Same (no config found) for recursion starting from a dataset with inherited backup plan configuration (assuming none of its descendants have a "local" config of their own).

  znapzend --inherited --runonce=tank/export/home/user/documents
    

With the --inherited option however it would recognize this descendant dataset as having a backup plan configuration inherited from tank/export, would then look at tank/export and confirm that it has this configuration from a "local" source, and should znapzend runonce just this dataset and its descendants (so including tank/export/home/user/documents/pictures, but not including siblings like tank/export/home/user/sources).

  znapzend --inherited --recursive --runonce=tank
    

Since tank has no backup plan, znapzend should recurse and find the nearest datasets with configured plans, tank/export and tank/var, and process them according to configuration.

  znapzend --inherited --recursive --runonce=tank/export
    

Since tank/export has a locally defined backup plan, znapzend should process it according to configuration.

  znapzend --inherited --recursive --runonce=tank/export/home
    

Since tank/export/home has a backup plan inherited from a locally defined one in tank/export, znapzend should process it according to configuration.

  znapzend --recursive --runonce=usbbackup
  znapzend --inherited --runonce=usbbackup/snapshots
  znapzend --inherited --recursive --runonce=usbbackup/snapshots/export/home
    

Neither of these runs should do anything, because all datasets involved (including those found by a recursive walk) under usbbackup have neither a local definition of a backup plan, nor one inherited from a local definition.

--features=feature1,feature2,...

enables enhanced zfs features not supported by all zfs implementations. Do not enable features unless you are sure your zfs supports (or requires) it

Available features:

--rootExec={sudo|pfexec}

Execute zfs with this command, 'sudo' or 'pfexec', to obtain root privileges. This is often necessary when running znapzend as a non-privileged user with a zfs install that doesn't support finer permission controls. This also applies to the zfs commands ran on remote servers over ssh.

For sudo, the /etc/sudoers file will need to be modified to allow for passwordless access to zfs commands if znapzend is to be ran as a daemon or the system will be used as a remote. Many ZFS installations include an /etc/sudoers.d/zfs file as an example.

--connectTimeout=timeout

sets the ssh connection timeout (in seconds)

--autoCreation

Automatically create a dataset on a destination host if it's not there yet.

--timeWarp=x

Shift ZnapZends sense of time into the future by x seconds.

The practical application if this function is to determine what will happen at some future point in time. This can be useful for testing but also when running in noaction and debug mode to determine which snapshots would be created and removed at some future point in time.

--skipOnPreSnapCmdFail

Prevent snapshots of a dataset from being taken when it has a pre-snap-command defined and the command returns a non-zero exit code or is killed by a signal.

--skipOnPreSendCmdFail

Prevent snapshots of a dataset from being replicated to a destination when it has a pre-snap-command defined and the command returns a non-zero exit code or is killed by a signal.

--cleanOffline

Clean snapshots of a source dataset even if one or more destination datasets failed during replication for whatever reason (destination offline, destination full, destination pool became read-only due to storage issues, source too full to make a snapshot, etc.).

The most recent common snapshot for each destination (as tracked on source for resilience) will not be deleted from source, but this is still a potentially dangerous option: if the preserved snapshot somehow gets deleted from the destination, it may require a full re-replication the next time it is online.

--mailErrorSummaryTo=rcpt(@domain),...

If this argument is passed, a copy of error summary would be sent there by your system's command line mailer program. It is then up to this program and system setup to validate the recipient names (local or domain-suffixed) and deliver the message to some mailbox.

This feature relies on a program which supports standard sendmail-like CLI.

EXAMPLE

 znapzend --debug --noaction --runonce=tank/test

To see what is going to happen in one hour:

 znapzend --debug --noaction --timeWarp=3600 --runonce=tank/test

To run as a daemon:

 znapzend --daemonize --pidfile=/var/run/znapzend.pid --logto=syslog::daemon

COPYRIGHT

LICENSE

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

HISTORY

 2014-06-01 had Multi destination backup
 2014-05-30 had Initial Version