ZFS-MOUNT-GENERATOR(8)

NAME
zfs-mount-generator - generates systemd mount units for ZFS

SYNOPSIS
/usr/lib/systemd/system-generators/zfs-mount-generator

DESCRIPTION
zfs-mount-generator implements the Generators Specification of systemd(1), and is called during early boot to generate systemd.mount(5) units for automatically mounted datasets. Mount ordering and dependencies are created for all tracked pools (see below).

  ENCRYPTION KEYS
If the dataset is an encryption root, a service that loads the associated key (either from file or through a systemd-ask-password(1) prompt) will be created. This service RequiresMountsFor the path of the key (if file-based) and also copies the mount unit's After, Before and Additionally, unless the logical flag is set, the mount unit gains a reverse-dependency for of strength Because ZFS pools may not be available very early in the boot process, information on ZFS mountpoints must be stored separately. The output of the command

    zfs list -H -o name,mountpoint,canmount,atime,relatime,devices,exec,readonly,setuid,nbmand,encroot,keylocation,org.openzfs.systemd:requires,org.openzfs.systemd:requires-mounts-for,org.openzfs.systemd:before,org.openzfs.systemd:after,org.openzfs.systemd:wanted-by,org.openzfs.systemd:required-by,org.openzfs.systemd:nofail,org.openzfs.systemd:ignore

for datasets that should be mounted by systemd, should be kept separate from the pool, at

    /etc/zfs/zfs-list.cache/POOLNAME

The cache file, if writeable, will be kept synchronized with the pool state by the ZEDLET

    history_event-zfs-list-cacher.sh .

  PROPERTIES
The behavior of the generator script can be influenced by the following dataset properties:

canmount=on|off|noauto
    If a dataset has mountpoint set and canmount is not off, a mount unit will be generated. Additionally, if canmount is on, local-fs.target will gain a dependency on the mount unit.

    This behavior is equal to the auto and noauto legacy mount options, see systemd.mount(5).

    Encryption roots always generate a key-load service, even for canmount=off.

org.openzfs.systemd:requires-mounts-for=path...
    Space-separated list of mountpoints to require to be mounted for this mount unit

org.openzfs.systemd:before=unit...
    The mount unit and associated key-load service will be ordered before this space-separated list of units.

org.openzfs.systemd:after=unit...
    The mount unit and associated key-load service will be ordered after this space-separated list of units.

org.openzfs.systemd:wanted-by=unit...
    Space-separated list of units that will gain a Wants dependency on this mount unit. Setting this property implies noauto.

org.openzfs.systemd:required-by=unit...
    Space-separated list of units that will gain a Requires dependency on this mount unit. Setting this property implies noauto.

org.openzfs.systemd:nofail=unset|on|off
    Toggles between a Wants and Requires type of dependency between the mount unit and local-fs.target, if noauto isn't set or implied.

    on: Mount will be WantedBy local-fs.target

    off: Mount will be Before and RequiredBy local-fs.target

    unset: Mount will be Before and WantedBy local-fs.target

org.openzfs.systemd:ignore=on|off
    If set to on, do not generate a mount unit for this dataset.

    See also systemd.mount(5)

EXAMPLE
To begin, enable tracking for the pool:

    touch /etc/zfs/zfs-list.cache/POOLNAME

Then, enable the tracking ZEDLET:

    ln -s "/usr/lib/zfs-linux/zed.d/history_event-zfs-list-cacher.sh" "/etc/zfs/zed.d"

    systemctl enable zfs-zed.service

    systemctl restart zfs-zed.service

Force the running of the ZEDLET by setting a monitored property, e.g. canmount, for at least one dataset in the pool:

    zfs set canmount=on DATASET

This forces an update to the stale cache file.

To test the generator output, run

    /usr/lib/systemd/system-generators/zfs-mount-generator /tmp/zfs-mount-generator . .

This will generate units and dependencies in /tmp/zfs-mount-generator for you to inspect them. The second and third argument are ignored.

If you're satisfied with the generated units, instruct systemd to re-run all generators:

    systemctl daemon-reload

SEE ALSO
zfs(5) zfs-events(5) zed(8) zpool(5) systemd(1) systemd.target(5) systemd.special(7) systemd.mount(7)