`zfs-assistant.toml(5)`

The machine configuration of ZFS Assistant

NAME

zfs-assistant.toml - the machine configuration of ZFS Assistant

SYNOPSIS

/etc/zfs-assistant/zfs-assistant.toml (Linux)
/usr/local/etc/zfs-assistant/zfs-assistant.toml (FreeBSD)

DESCRIPTION

This TOML file holds the snapshot policies, backups, remotes, scrub and trim schedules and general settings of zfs-assistant-helper(8). The window, zfs-assistant(1), and zfsa(1) change it through the helper, which keeps your comments and any keys it does not know. You can also edit it by hand as root. The daemon doesn't watch the file: a hand edit takes effect at the next change made through the helper, when the idle helper starts again, and in every scheduled job, which reads the file itself.

The file and its directory must belong to root and must not be writable by anyone else; the helper refuses to use them otherwise. A problem in one section never stops the others from working: the section with the problem is left out and the problem is reported with its line number. After a hand edit, run zfsa --local settings show as root to see the problems.

Durations are written as a number and a unit: s (seconds), m (minutes), h (hours) or d (days), such as 30m. Keys that are left out take their defaults, except the ones marked as required. The file installed with the package shows every key commented out.

[general]

scheduler = "auto": What runs the scheduled jobs: auto, systemd or cron. auto uses systemd timers when the system booted with systemd and cron otherwise.
cron_style = "auto": Where cron lines go: auto, cron.d or crontab.
catch_up = true: With cron, run overdue scrubs on the next snapshot run.
snapshot_prefix = "auto": The start of the names of policy snapshots, which are PREFIX_TIME with the time in UTC. Lowercase letters, digits and -.
grant_idle_timeout = "30m": How long an unused administrator authorization lasts, from 1m to 24h.
helper_idle_exit = "60s": How long the idle helper waits before it exits, from 5s to 1h.

[paths]

Only needed when a tool is not in its standard location. Each value is an absolute path. The keys are zfs, zpool, ssh, ssh-keygen, ssh-keyscan, crontab, mount and umount. The helper never looks programs up in PATH.

[[policy]]

A snapshot policy. A dataset belongs to at most one policy.

name: Required. Lowercase letters, digits, _ and -. A policy's name identifies its snapshots, so it can't be changed; make another policy instead.
datasets: Required: the datasets it covers, such as ["rpool/home"].
recursive = true: Also the datasets inside them, including ones made later.
exclude = []: Datasets to leave out.
snapshot = true: false makes a policy that only prunes.
received = false: true prunes snapshots that arrived by replication, for a backup destination.
interval = "15m": How often to take snapshots. Under 15m it must divide an hour.
keep_frequent, keep_hourly, keep_daily, keep_weekly, keep_monthly, keep_yearly: How many snapshots to keep at the interval, and per hour, day, week, month and year. The defaults are 4, 24, 7, 4, 0 and 0. Pruning never deletes the newest snapshot, held snapshots, clone origins or the base a backup still needs, and never touches snapshots taken by hand.
min_age = "1h": Younger snapshots are never pruned.
skip_unchanged = false: Skip datasets that haven't changed since their last snapshot.
prune_when_pool_above = 0: A percentage: prune more when the pool is fuller than this. 0 turns it off.
keep_minimum = 3: The snapshots per dataset that pruning for space always leaves.
pre_hook, post_hook: Programs to run before and after the snapshots, for example to quiesce a database. When pre_hook fails no snapshots are taken. post_hook runs also when taking them failed. Hooks can only be set in this file, never from a client. Each is an absolute path to a regular file that belongs to root, is executable and is not writable by its group or others, in directories that are root's and not writable by others. Symbolic links are refused. A hook runs with no arguments and a cleared environment except ZFSA_HOOK (pre or post), ZFSA_POLICY, ZFSA_SNAPSHOT and, for post_hook, ZFSA_RESULT (ok or failed).
hook_timeout = "60s": How long each hook may run, from 1s to 1h.

[[policy.copy]]

Where the snapshots of the policy above it are copied.

to: Required: a [[remote]] by name, or local for another pool on this computer.
target: Required: the dataset the copies go under.
frequency = "every-run": every-run, hourly or daily.
keep_frequent ... keep_yearly: As for the policy. Without them the destination keeps what the policy keeps.

[[maintenance]]

A scheduled scrub or trim. Exactly one of schedule, oncalendar and cron is set.

id: Required: the job's name, such as scrub-rpool.
kind: Required: scrub or trim.
pool: Required: the pool.
schedule: A schedule such as "monthly first sun 03:00", "weekly sat 04:00" or "every 15m", in local time.
oncalendar: A raw systemd OnCalendar value. Works with the systemd scheduler only.
cron: A raw cron expression of five fields. Works with cron only.

[[remote]]

A computer that snapshots are copied to.

name, host, user: Required: its name in this file, its host name or address, and the user there that receives backups, such as zfsbackup.
port = 22: The SSH port.
mode = "shim": shim (recommended) when the remote runs ZFS Assistant: its restricted key reaches only root and can't open a shell. plain needs only ZFS and SSH on the remote, but its key can open a shell.
root: Shim only: the dataset the remote allows. Every copy's target must be inside it.
append_only = true: Shim only: the remote refuses deletes, so it must prune by itself, for example with a received policy.
bandwidth_limit: Bytes per second, such as "20M". Empty for no limit.
source_address: This computer's address as the remote sees it, for from= in the remote's authorized_keys.

EXAMPLES

A policy that takes snapshots of the home datasets every 15 minutes and copies them to a remote once a day:

[[policy]]
name = "home"
datasets = ["rpool/home"]
keep_daily = 14

[[policy.copy]]
to = "nas"
target = "backup/laptop"
frequency = "daily"

[[remote]]
name = "nas"
host = "nas.example"
user = "zfsbackup"
root = "backup/laptop"

[[maintenance]]
id = "scrub-rpool"
kind = "scrub"
pool = "rpool"
schedule = "monthly first sun 03:00"