NAME

zelta-options - environment and policy options for Zelta behavior

SYNOPSIS

Environment variables and policy configuration options.

DESCRIPTION

Zelta’s behavior can be modified through environment variables, command-line arguments, and policy configuration files. This manual documents all available options and their effects.

Options are set differently based on context:

• Shell environment: Environment variables must be prefixed with ZELTA_ (e.g., ZELTA_DEPTH=2)
• Environment file: In zelta.env, use KEY=value pairs (e.g., DEPTH=2)
• Policy file: zelta policy additionally uses the YAML-like zelta.conf for granular settings per backup job with KEY: value pairs (e.g., DEPTH: 1)
• Command-line arguments: Options map to double-dash arguments (e.g., --depth)

For on/off variable assignments, use “1” for true and “0” for false.

SETUP AND ENVIRONMENT-ONLY OPTIONS

The following options should be modified in the environment to ensure proper installation and startup of the zelta script. Typically, these should be defined in the user’s shell rc script. In particular, ZELTA_AWK and ZELTA_ENV will be used prior to loading zelta.env so they must be exported beforehand.

ZELTA_AWK

The awk executable. The default is the awk in the path. Example: ZELTA_AWK='mawk -Wi'.

ZELTA_SHARE

The location of Zelta assets including the AWK scripts and data files. The default is /usr/local/share/zelta.

ZELTA_ETC

The location of zelta.env and zelta.conf. The default is /usr/local/etc/zelta.

ZELTA_ENV

The exact path of zelta.env.

ZELTA_DOC

The location of Zelta’s manpages. Default is unset, using the system-wide manual.

LOGGING OPTIONS

LOG_FILE

Divert all output into the indicated file.

LOG_LEVEL

Specify a log level value 0-4: errors (0), warnings (1), notices (2, default), info (3, verbose), and debug (4).

LOG_MODE

Enable the specified log modes. Currently supported: `text' (default) and `json' (zelta backup related verbs only).

SSH OPTIONS

REMOTE_COMMAND

The remote shell command. Defaults to ssh.

REMOTE_DEFAULT

The default remote shell command used for misc operations which should prevent reading from stdin. Defaults to REMOTE_COMMAND -n (ssh -n).

REMOTE_SEND

The remote shell command used for zfs send. Defaults to REMOTE_COMMAND (ssh).

REMOTE_RECV

The remote shell command used for zfs recv. Defaults to REMOTE_DEFAULT (ssh -n).

GENERAL OPTIONS

DEPTH

Limit the recursion depth of operations to the number of levels indicated. For example, a depth of 1 will only include the indicated source dataset. Has no effect with REPLICATE enabled.

EXCLUDE

Exclude datasets or source snapshots matching the specified exclusion pattern. See EXCLUSION PATTERNS below.

ZELTA MATCH OPTIONS

SCRIPTING_MODE

Suppress column headers and separate columns with a single tab. Useful for parsing output in scripts.

PARSABLE

Output sizes in exact numbers instead of human-readable values like 1M.

PROPLIST

Specify a list of zelta match columns. See zelta-match(8) for more detail.

LIST_WRITTEN

Calculate data sizes for datasets and snapshots in the summary. Enabled by default.

CHECK_TIME

Calculate the time of each zfs list operation.

ZFS SEND/RECEIVE OPTIONS

SEND_OVERRIDE

Override all zfs send options with those indicated. For precise and flexible configuration for different circumstances, use the SEND_* variables below instead.

SEND_DEFAULT

Options used for unencrypted filesystems and volumes. Defaults to -Lce.

SEND_RAW

Options used for encrypted datasets. Defaults to -Lw.

SEND_NEW

Additional option used for new datasets. Defaults to -p.

SEND_INTR

Toggle option to transmit intermediate snapshots (1, the default) or incremental (0).

SEND_REPLICATE

Options to use in zelta backup -R mode. Defaults to zfs send -LsRw.

SEND_CHECK

Attempt to drop unsupported zfs send options using a no-op test prior to replication. This feature is not fully implemented.

RECV_OVERRIDE

Override all zfs receive options with those indicated. For precise and flexible configuration, use the RECV_* variables instead.

RECV_DEFAULT

Default zfs recv options. Defaults to none.

RECV_TOP

Additional options for the top dataset during new (full) backup. Defaults to -o readonly=on.

RECV_FS

Additional options for filesystems during a new (full) backup. Defaults to -u -x mountpoint -o canmount=noauto.

RECV_VOL

Additional options for volumes new (full). Defaults to none.

RECV_PROPS_ADD

Add the list of `zfs recv -o' properties in the form property=value. See `zfs-receive(8)'.

RECV_PROPS_DEL

Add the list of `zfs recv -x' excluded properties. See `zfs-receive(8)'.

RECV_PARTIAL

Additional options if RESUME is enabled. Defaults to -s.

RECV_PREFIX

Pipe output through the indicated command, such as dd status=progress.

RESUME

Enable (1, the default) or disable automatic resume of interrupted syncs.

REPLICATION OPTIONS

SNAP_NAME

Specify a snapshot name. Use the form $(my_snapshot_program) to use a dynamically generated snapshot. The default is $(date -u +zelta_%Y-%m-%d_%H.%M.%S).

SNAP_MODE

Specify when to snapshot during a zelta backup operation. Options: 0 (never), IF_NEEDED (default, only if source has new data), or ALWAYS.

SYNC_DIRECTION

If both endpoints are remote, use PULL (the default) or PUSH sync. If set to 0, traffic will stream through the local host. Note that this feature PUSH and PULL features require appropriate ssh configurations with keys properly installed and/or ssh agent forwarding enabled.

CLONE OPTIONS

CLONE_DEFAULT

Options for recursive cloning. Defaults to -po readonly=off.

POLICY OPTIONS

The following options only effect zelta policy operations.

RETRY

Retry failed syncs the indicated number of times.

JOBS

Run the indicated number of policy jobs concurrently, one for each Site in the configuration.

BACKUP_ROOT

The relative target path for backup jobs. For example, bkhost:tank/Backups would place backups below that dataset (if not overridden by policy).

ARCHIVE_ROOT

NOT YET IMPLEMENTED. The relative target path used for rotated clones.

ADD_HOST_PREFIX

Include the source hostname as a parent of the synced target.

•

Example: Source web1:sink/dataset with BACKUP_ROOT: tank/backups becomes tank/backups/web1/dataset.

ADD_DATASET_PREFIX

Similar to zfs recv -d, include the indicated number of parent dataset labels for the BACKUP_ROOT’s (or specified target’s) name. If set to -1 all labels up to the pool name will be attached to the target name.

•

Example: Source web1:sink/source/dataset with BACKUP_ROOT: tank/backups:

•

ADD_HOST_PREFIX stacks with ADD_DATASET_PREFIX. With both enabled, the hostname is prepended first: tank/backups/web1/source/dataset.

EXCLUSION PATTERNS

The EXCLUDE option, or the arguments --exclude or -X, contain a comma separated list of patterns to exclude datasets or source snapshots from operations. Excluding a dataset will also exclude its children.

EXAMPLES

Set options via environment for a one-off run:

export ZELTA_LOG_LEVEL=4
export ZELTA_REMOTE_COMMAND="ssh -p 2202"
zelta backup pool/dataset remote:pool/backup
    

Configure zelta.conf:

# In zelta.conf, variables act as policy scopes but
# use the same option names.
LOG_MODE: json
JOBS: 2
NYC1:


  BACKUP_ROOT: backuphost:tank/Backups


  RETRY: 3
    

SEE ALSO

zelta(8), zelta-backup(8), zelta-clone(8), zelta-match(8), zelta-policy(8), zelta-rotate(8), zelta-sync(8), cron(8), ssh(1), zfs(8)

AUTHORS

Daniel J. Bell <bellhyve@zelta.space>

WWW

https://zelta.space