NAME

     zfs-mount-generator — generate systemd mount units for ZFS filesystems

SYNOPSIS

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

DESCRIPTION

     zfs-mount-generator is a systemd.generator(7) that generates native systemd.mount(5) units
     for configured ZFS datasets.

   Properties
     mountpoint=                                   Skipped if legacy or none.
     canmount=                                     Skipped if off.  Skipped if only noauto
                                                   datasets exist for a given mountpoint and
                                                   there's more than one.  Datasets with yes take
                                                   precedence over ones with noauto for the same
                                                   mountpoint.  Sets logical noauto flag if
                                                   noauto.  Encryption roots always generate
                                                   zfs-load-key@root.service, even if off.
     atime=, relatime=, devices=, exec=, readonly=, setuid=, nbmand=
                                                   Used to generate mount options equivalent to
                                                   zfs mount.
     encroot=, keylocation=                        If the dataset is an encryption root, its
                                                   mount unit will bind to
                                                   zfs-load-key@root.service, with additional
                                                   dependencies as follows:
                                                         keylocation=prompt                None,
                                                                                           uses
                                                                                           systemd-ask-password(1)
                                                         keylocation=https://URL (et al.)  Wants=,
                                                                                           After=:
                                                                                           network-online.target
                                                         keylocation=file://<path>         RequiresMountsFor=path
                                                   The service also uses the same Wants=, After=,
                                                   Requires=, and RequiresMountsFor=, as the
                                                   mount unit.
     org.openzfs.systemd:requires=path[ path]…     Sets Requires= for the mount- and key-loading
                                                   unit.
     org.openzfs.systemd:requires-mounts-for=path[ path]…
                                                   Sets RequiresMountsFor= for the mount- and
                                                   key-loading unit.
     org.openzfs.systemd:before=unit[ unit]…       Sets Before= for the mount unit.
     org.openzfs.systemd:after=unit[ unit]…        Sets After= for the mount unit.
     org.openzfs.systemd:wanted-by=unit[ unit]…    Sets logical noauto flag (see below).  If not
                                                   none, sets WantedBy= for the mount unit.
     org.openzfs.systemd:required-by=unit[ unit]…  Sets logical noauto flag (see below).  If not
                                                   none, sets RequiredBy= for the mount unit.
     org.openzfs.systemd:nofail=(unset)|on|off     Waxes or wanes strength of default reverse
                                                   dependencies of the mount unit, see below.
     org.openzfs.systemd:ignore=on|off             Skip if on.  Defaults to off.

   Unit Ordering And Dependencies
     Additionally, unless the pool the dataset resides on is imported at generation time, both
     units gain Wants=zfs-import.target and After=zfs-import.target.

     Additionally, unless the logical noauto flag is set, the mount unit gains a reverse-
     dependency for local-fs.target of strength
           (unset)  WantedBy= + Before=
           on       WantedBy=
           off      RequiredBy= + Before=

   Cache File
     Because ZFS pools may not be available very early in the boot process, information on ZFS
     mountpoints must be stored separately.  The output of
           zfs list -Ho name,⟨every property above in order⟩
     for datasets that should be mounted by systemd should be kept at
     /etc/zfs/zfs-list.cache/poolname, and, if writeable, will be kept synchronized for the
     entire pool by the history_event-zfs-list-cacher.sh ZEDLET, if enabled (see zed(8)).

ENVIRONMENT

     The ZFS_DEBUG environment variable can either be 0 (default), 1 (print summary accounting
     information at the end), or at least 2 (print accounting information for each subprocess as
     it finishes).  If not present, /proc/cmdline is additionally checked for "debug", in which
     case the debug level is set to 2.

EXAMPLES

     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

     If no history event is in the queue, inject one to ensure the ZEDLET runs to refresh the
     cache file by setting a monitored property somewhere on the pool:
           # zfs set relatime=off poolname/dset
           # zfs inherit relatime poolname/dset

     To test the generator output:
           $ mkdir /tmp/zfs-mount-generator
           $ /usr/lib/systemd/system-generators/zfs-mount-generator /tmp/zfs-mount-generator
     If the generated units are satisfactory, instruct systemd to re-run all generators:
           # systemctl daemon-reload

SEE ALSO

     systemd.mount(5), systemd.target(5), zfs(5), systemd.generator(7), systemd.special(7),
     zed(8), zpool-events(8)