Add canonical mount options zfs-mount-generator

lib/libzfs/libzfs_mount.c:zfs_add_options provides the canonical
mount options used by a `zfs mount` command. Because we cannot call
`zfs mount` directly from a systemd.mount unit, we mirror that logic
in zfs-mount-generator.

The zed script is updated to cache these properties as well.

Include a mini-tutorial in the manual page, properly substitute
configuration paths in zfs-mount-generator.8.in, and standardize the
Makefile.

Reviewed-by: Brian Behlendorf <[email protected]>
Reviewed-by: Richard Laager <[email protected]>
Signed-off-by: Antonio Russo <[email protected]>
Closes #7453 

1 files changed, 83 insertions, 0 deletions

diff --git a/man/man8/zfs-mount-generator.8.in b/man/man8/zfs-mount-generator.8.in
new file mode 100644
index 000000000..319ac8e57
--- /dev/null
+++ b/man/man8/zfs-mount-generator.8.in
@@ -0,0 +1,83 @@
+.TH "ZFS\-MOUNT\-GENERATOR" "8" "ZFS" "zfs-mount-generator" "\""
+.SH "NAME"
+zfs\-mount\-generator \- generates systemd mount units for ZFS
+.SH SYNOPSIS
+.B /lib/systemd/system-generators/zfs\-mount\-generator
+.sp
+.SH DESCRIPTION
+zfs\-mount\-generator implements the \fBGenerators Specification\fP
+of
+.BR systemd (1),
+and is called during early boot to generate
+.BR systemd.mount (5)
+units for automatically mounted datasets. Mount ordering and dependencies
+are created for all tracked pools (see below). If a dataset has
+.BR canmount=on
+and
+.BR mountpoint
+set, the
+.BR auto
+mount option will be set, and a dependency for
+.BR local-fs.target
+on the mount will be created.
+
+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
+.PP
+.RS 4
+zfs list -H -o name,mountpoint,canmount,atime,relatime,devices,exec,readonly,setuid,nbmand
+.RE
+.PP
+for datasets that should be mounted by systemd, should be kept
+separate from the pool, at
+.PP
+.RS 4
+.RI @sysconfdir@/zfs/zfs-list.cache/ POOLNAME
+.
+.RE
+.PP
+The cache file, if writeable, will be kept synchronized with the pool
+state by the ZEDLET
+.PP
+.RS 4
+history_event-zfs-list-cacher.sh .
+.RE
+.PP
+.sp
+.SH EXAMPLE
+To begin, enable tracking for the pool:
+.PP
+.RS 4
+touch
+.RI @sysconfdir@/zfs/zfs-list.cache/ POOLNAME
+.RE
+.PP
+Then, enable the tracking ZEDLET:
+.PP
+.RS 4
+ln -s "@libexecdir@/zfs/zed.d/history_event-zfs-list-cacher.sh" "@sysconfdir@/zfs/zed.d/"
+
+systemctl enable zed.service
+
+systemctl restart zed.service
+.RE
+.PP
+Force the running of the ZEDLET by setting canmount=on for at least one dataset in the pool:
+.PP
+.RS 4
+zfs set canmount=on
+.I DATASET
+.RE
+.PP
+This forces an update to the stale cache file.
+.sp
+.SH SEE ALSO
+.BR zfs (5)
+.BR zfs-events (5)
+.BR zed (8)
+.BR zpool (5)
+.BR systemd (1)
+.BR systemd.target (5)
+.BR systemd.special (7)
+.BR systemd.mount (7)