Provided by: zfsutils-linux_2.0.6-1ubuntu2_amd64 bug

NAME

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

SYNOPSIS

       /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 Requires.  All mount  units  of  encrypted  datasets  add  the  key-load
       service  for  their  encryption  root  to  their Wants and After.  The service will not be
       Wanted or Required by local-fs.target directly, and so will only be started manually or as
       a dependency of a started mount unit.

   UNIT ORDERING AND DEPENDENCIES
       mount unit's Before -> key-load service (if any) -> mount unit -> mount unit's After

       It  is worth nothing that when a mount unit is activated, it activates all available mount
       units  for  parent  paths  to  its  mountpoint,  i.e.  activating  the  mount   unit   for
       /tmp/foo/1/2/3  automatically  activates  all  available  mount  units for /tmp, /tmp/foo,
       /tmp/foo/1, and /tmp/foo/1/2. This is true for any combination of  mount  units  from  any
       sources, not just ZFS.

   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 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

           /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)