`zfs-assistant-helper(8)`

The privileged service of ZFS Assistant

NAME

zfs-assistant-helper - the privileged service of ZFS Assistant

SYNOPSIS

zfs-assistant-helper daemon
zfs-assistant-helper job ID

DESCRIPTION

zfs-assistant-helper does everything in ZFS Assistant that needs root. It serves org.zfsassistant.Helper1 on the system D-Bus to zfs-assistant(1), zfs-assistant-tray(1) and zfsa(1), which run as the user. Every caller and every argument is treated as hostile: the helper validates its input, identifies pools and datasets by name and GUID, and never takes a command or an arbitrary path from a client.

You don't start it by hand. D-Bus starts it when a client first calls it, and it exits again after it has been idle for helper_idle_exit (see zfs-assistant.toml(5)). It is installed outside the PATH because it is not meant to be run directly.

COMMANDS

daemon: Serve org.zfsassistant.Helper1 until the service has been idle long enough. On Linux with systemd it runs as zfs-assistant-helper.service, which D-Bus activation starts. On FreeBSD and Linux without systemd, D-Bus starts it directly. FreeBSD also has an rc.d script, zfs_assistant_helper, for administrators who want it running from boot.
job ID: Run one scheduled job and exit. The scheduler starts it: on systemd through zfs-assistant-job@ID.service and zfs-assistant-snapshot.timer, otherwise from cron lines that the helper writes. The job snapshot takes and prunes the snapshots of every policy and runs the backups. Scrub and trim jobs are named after their kind and pool, such as scrub-tank. A job that is already running is skipped. zfsa schedule apply rewrites the timers or cron lines from the configuration.

AUTHORIZATION

Clients ask for a grant through polkit. The helper keeps grants by the caller's unique bus name, never by process ID, so a grant ends when the client disconnects. A management grant also ends after grant_idle_timeout without use. There are two actions:

org.zfsassistant.view: Read pools, datasets, snapshots and status. Allowed without a password for the user of an active local session.
org.zfsassistant.manage: Change anything, and read private information such as job logs, pool history and the files with errors. Needs an administrator's password.

Administrators can relax or tighten these with polkit rules files; see polkit(8). The helper never sends signals that anyone on the bus could read.

As root, zfsa --local runs the same service in its own process, without the bus, with the same validation, locks and audit records. Jobs, backup sync and cancel, remote restore and scheduler management need the daemon.

LOGGING

The helper logs to the journal when the system runs systemd, and to syslog otherwise. Every change a client asks for is recorded in an audit record with the caller; in syslog these go to the authpriv facility. Names that come from users or ZFS are logged as escaped fields, so they can't forge a log line. Passphrases are never logged.

EXIT STATUS

daemon exits 0 when it stops after being idle, and 1 when it can't start: a wrong command line, a configuration file or directory that is not trusted, or a bus name that is taken.

job exits 0 when the job ran, was skipped because it was running already, or was cancelled, and 1 when it failed, so the systemd unit of a failed job shows as failed.

FILES

/etc/zfs-assistant/zfs-assistant.toml: The configuration on Linux; /usr/local/etc/zfs-assistant/zfs-assistant.toml on FreeBSD. See zfs-assistant.toml(5).
/usr/share/dbus-1/system.d/org.zfsassistant.Helper1.conf: The D-Bus policy: who may own the name and send to it. It authorizes nothing.
/usr/share/polkit-1/actions/org.zfsassistant.policy: The polkit actions. On FreeBSD these are below /usr/local/share.