ZFS-MOUNT-GENERATOR(8)

✨ NAME ✨

zfs-mount-generator — she generates systemd mount units for ZFS 💅

(also hiii, this one lives in section 8 of the System Manager's Manual, aka the admin-commands girlies 🫶)

---

🌸 SYNOPSIS 🌸

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

---

🦋 DESCRIPTION 🦋

okay so zfs-mount-generator implements the Generators Specification of systemd(1), and she gets called during early boot to generate systemd.mount(5) units for datasets that get automatically mounted. Mount ordering and dependencies get created for all tracked pools (see below, bestie, keep scrolling 👇).

🔑 ENCRYPTION KEYS 🔑

• If the dataset is an encryption root, a service that loads the associated key gets created — either from a file, or through a systemd-ask-password(1) prompt. 🗝️
• That service RequiresMountsFor the path of the key (if it's file-based).
• It also copies the mount unit's After, Before and … and ngl, the original text literally stops mid-sentence right there 😭

fr fr, the raw manpage says: "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" — I am not inventing anything to fill that gap, so there it is in all its unhinged glory 💀

Because ZFS pools may not be available very early in the boot process, information on ZFS mountpoints has to 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, bestie:

• canmount=on|off|noauto — if a dataset has mountpoint set and canmount is not off, a mount unit gets generated. And additionally, if canmount is on, then local-fs.target gains a dependency on that 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. periodt.

• org.openzfs.systemd:requires-mounts-for=path... — space-separated list of mountpoints that have to be mounted for this mount unit.
• org.openzfs.systemd:before=unit... — the mount unit and its associated key-load service will be ordered before this space-separated list of units.
• org.openzfs.systemd:after=unit... — the mount unit and its 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 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 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. slay. ✨

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)

---

and that's the whole page, bestie 🫶 this icon was brought to you by OpenZFS, dated Aug 24, 2020 — go forth and mount responsibly 💖✨🎀🦋