% zelta-options(7) | System Manager's Manual
zelta-options - environment and policy options for Zelta behavior
Environment variables and policy configuration options.
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:
ZELTA_ (e.g., ZELTA_DEPTH=2)zelta.env, use KEY=value pairs (e.g., DEPTH=2)zelta policy additionally uses the YAML-like zelta.conf for granular settings per backup job with KEY: value pairs (e.g., DEPTH: 1)--depth)For on/off variable assignments, use "1" for true and "0" for false.
Options follow an override hierarchy to provide flexibility in all contexts.
zelta controller scriptzelta.env - Environment file (default: ~/.config/zelta/zelta.env if present, otherwise /usr/local/etc/zelta/zelta.env)zelta.conf - Policy configuration file (zelta policy only, default: /usr/local/etc/zelta/zelta.conf)ZELTA_)For example, running zelta policy --no-snapshot will ensure the all configured backups will run without taking snapshots regardless of snapshot configuration in other contexts.
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. If unset, Zelta uses ~/.local/share/zelta when it contains the installed helper scripts, otherwise /usr/local/share/zelta.
ZELTA_ETC
: The location of zelta.env and zelta.conf. If unset, Zelta uses ~/.config/zelta when present, otherwise /usr/local/etc/zelta.
ZELTA_ENV
: The exact path of zelta.env.
ZELTA_CONFIG
: The exact path of the policy configuration file. The default is zelta.conf under ZELTA_ETC.
ZELTA_DOC
: The manpath root for Zelta's manpages, containing man7 and man8 directories. If unset, Zelta uses ~/.local/share/zelta/doc when present, otherwise the system manual path.
LOG_FILE
: Append log output to the indicated file. In JSON mode, write the JSON output to this file while status messages remain separate on stderr.
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).
SYSTIME
: Override the system time function for JSON timestamps. Required for mawk users, as mawk's srand() does not reliably return epoch time. Set to date +%s for compatibility. Not needed with gawk or original-awk (nawk/bwk).
Example: `ZELTA_SYSTIME='date +%s'`
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).
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 pattern. See INCLUDE AND EXCLUDE PATTERNS below.
INCLUDE
: Include only datasets or source snapshots matching the specified pattern. See INCLUDE AND EXCLUDE PATTERNS below.
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.
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 --raw, equivalent to -Lce.
SEND_DECRYPTED
: Options used when an encrypted dataset must fall back to a decrypted incremental send. Defaults to -Lc. This preserves large blocks and existing send-stream compression. Use -L instead when the receiving side should recompress or encrypt from plaintext.
SEND_RAW
: Options used for encrypted datasets. Defaults to --raw.
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 --raw -s -R.
SEND_CHECK
: Attempt to detect and drop Zelta's default zfs send options (-L, -c, e) if the source does not support them.
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.
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_PREFIX
: Prefix generated snapshot names. If the resolved snapshot name starts with zelta, the prefix replaces zelta; otherwise the prefix is prepended verbatim. For example, --snap-prefix=daily changes the default name to daily_YYYY-MM-DD_HH.MM.SS, while SNAP_PREFIX="$(whoami)_" prefixes a custom generator with the current username.
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.
SNAP_TIME
: In IF_NEEDED mode, skip snapshot creation if every source dataset has a recent enough snapshots_changed timestamp. Bare numbers are Unix epoch seconds and are compared directly. Relative values use the same unambiguous duration syntax as zelta-prune(8): seconds, minutes, hours, days, weeks, months, or years may be abbreviated to any unambiguous prefix. The units m and M are invalid because they are ambiguous between minutes and months.
SNAP_SIZE
: In IF_NEEDED mode, skip snapshot creation if cumulative source writes are below the threshold. Bare numbers are bytes; supported suffixes are K, M, G, T, P, and E.
BOOKMARK_MODE
: After a successful receive, create a ZFS bookmark on each confirmed source snapshot. 0 (default) disables bookmarking; 1 bookmarks the latest confirmed source snapshot per successfully received dataset. Command-line: --bookmark, --no-bookmark, or --bookmark-mode.
BOOKMARK_PREFIX
: Prefix for replication-success bookmark names. Default is {targethost}_, producing names such as pool/ds#backuphost_snapname. Command-line: --bookmark-prefix.
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_DEFAULT
: Options for recursive cloning. Defaults to -po readonly=off.
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.
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.
web1:sink/source/dataset with BACKUP_ROOT: tank/backups:
0: tank/backups/dataset1: tank/backups/source/dataset-1: tank/backups/sink/source/datasettank/backups/web1/source/dataset.The INCLUDE and EXCLUDE options, or the arguments --include, --exclude, or -X, contain comma separated lists of patterns used to select datasets or source snapshots for operations. INCLUDE narrows operations to matching datasets or snapshots. EXCLUDE removes matching datasets or snapshots. Dataset filters cascade to child datasets.
Absolute Dataset Path
: Similar to zfs send --exclude, match the named source dataset.
Example: `tank/vm/swap` matches that specific dataset.
Relative Dataset Path
: Prefix with / to match the dataset suffix relative to the given dataset name.
Example: Given the dataset `sink/swap` and the pattern `/swap`: `sink/swap` will match, but `sink/vm/swap` will **not** match.
Relative Dataset Pattern
: Use glob-like matching of * (zero or more characters) or ? (single character). The pattern must start with '/' or '*' and must contain a '/'.
Examples, given the given _source_ of `sink/data`:
- `*/swap` would match `sink/data/one/swap`, `sink/data/two/swap`, and `sink/data/swap`
- `/*/swap` would match `sink/data/one/swap` and `sink/data/two/swap` but **not** `sink/data/swap`
- `/vm-*` would match `sink/data/vm-one` and its descendants, but **not** `sink/data/vm/one`
- `/test?` would match `sink/data/test1` but **not** `sink/data/test15`
Snapshot Name
: Match snapshots by name. Prefix with @ to indicate a snapshot.
Example: `@manual-backup` matches any snapshot named `manual-backup`.
Snapshot Pattern
: Use glob-like matching of * (zero or more characters) or ? (single character). Snapshot names must begin with @.
Examples:
- `@*_hourly` matches snapshots ending in `_hourly`
- `@snap-2024*` matches snapshots beginning with `snap-2024`
- `@auto-*00??` matches snapshots beginning with `auto-` and ending with 00 and two of any character
| Pattern Type | Example | Matches |
|---|---|---|
| Absolute dataset | tank/vm/swap |
Exact dataset |
| Relative dataset | /tmp |
Top dataset ending in /tmp |
| Relative dataset wildcard | */swap |
Any dataset ending in /swap |
| Snapshot name | @manual-backup |
Exact snapshot name |
| Snapshot wildcard | @*_hourly |
Snapshots matching pattern |
Datasets
Including a dataset selects that dataset and its matching snapshots. Excluding a dataset removes that dataset and its descendants.
Snapshots
For incremental replication, at least one common snapshot must remain between source and target. Therefore, snapshot include and exclude logic is only meaningful when applied to incremental source snapshots in incremental mode (SEND_INTR=0 or -i) or filtered intermediate backup streams. For example, snapshot filters are useful for skipping hourly snapshots but updating dailies.
zfs send -I streamSet 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
zelta(8), zelta-backup(8), zelta-clone(8), zelta-match(8), zelta-policy(8), zelta-rotate(8), cron(8), ssh(1), zfs(8)
Daniel J. Bell <bellhyve@zelta.space>