---
name: "zfs-mount-generator"
section: "8"
platform: "linux"
package: "zfsutils-linux"
version: "2.3.9-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/zfs-mount-generator"
---

# zfs-mount-generator(8)

generate systemd mount units for ZFS filesystems

## 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)](/systemd.generator/7.md) that generates native [systemd.mount(5)](/systemd.mount/5.md) 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)](/systemd-ask-password/1.md)

  - **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)](/zed/8.md)).

## ENVIRONMENT

If the **ZFS\_DEBUG** environment variable is nonzero (or unset and */proc/cmdline* contains "**debug**"), print summary accounting information at the end.

## 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.mount/5.md), [systemd.target(5)](/systemd.target/5.md), zfs(5), [systemd.generator(7)](/systemd.generator/7.md), [systemd.special(7)](/systemd.special/7.md), [zed(8)](/zed/8.md), [zpool-events(8)](/zpool-events/8.md)