systemd zfs-import.target and documentation

zfs-import-{cache,scan}.service must complete before any mounting of
filesystems can occur. To simplify this dependency, create a target
that is reached After (in the systemd sense) the pool is imported.

Additionally, recommend that legacy zfs mounts use the option

x-systemd.requires=zfs-import.target

to codify this requirement.

Reviewed-by: Fabian Grünbichler <[email protected]>
Reviewed-by: Brian Behlendorf <[email protected]>
Reviewed-by: Giuseppe Di Natale <[email protected]>
Signed-off-by: Antonio Russo <[email protected]>
Closes openzfs#6764

etc/systemd/system/Makefile.am

@@ -7,6 +7,7 @@ systemdunit_DATA = \
 	zfs-import-scan.service \
 	zfs-mount.service \
 	zfs-share.service \
+	zfs-import.target \
 	zfs.target
 
 EXTRA_DIST = \
@@ -15,6 +16,7 @@ EXTRA_DIST = \
 	$(top_srcdir)/etc/systemd/system/zfs-import-scan.service.in \
 	$(top_srcdir)/etc/systemd/system/zfs-mount.service.in \
 	$(top_srcdir)/etc/systemd/system/zfs-share.service.in \
+	$(top_srcdir)/etc/systemd/system/zfs-import.target.in \
 	$(top_srcdir)/etc/systemd/system/zfs.target.in \
 	$(top_srcdir)/etc/systemd/system/50-zfs.preset.in
 

etc/systemd/system/zfs-import-cache.service.in

@@ -7,6 +7,7 @@ After=systemd-udev-settle.service
 After=cryptsetup.target
 After=systemd-remount-fs.service
 Before=dracut-mount.service
+Before=zfs-import.target
 ConditionPathExists=@sysconfdir@/zfs/zpool.cache
 
 [Service]
@@ -16,5 +17,4 @@ ExecStartPre=/sbin/modprobe zfs
 ExecStart=@sbindir@/zpool import -c @sysconfdir@/zfs/zpool.cache -aN
 
 [Install]
-WantedBy=zfs-mount.service
-WantedBy=zfs.target
+WantedBy=zfs-import.target

etc/systemd/system/zfs-import-scan.service.in

@@ -6,6 +6,7 @@ Requires=systemd-udev-settle.service
 After=systemd-udev-settle.service
 After=cryptsetup.target
 Before=dracut-mount.service
+Before=zfs-import.target
 ConditionPathExists=!@sysconfdir@/zfs/zpool.cache
 
 [Service]
@@ -15,5 +16,4 @@ ExecStartPre=/sbin/modprobe zfs
 ExecStart=@sbindir@/zpool import -aN -o cachefile=none
 
 [Install]
-WantedBy=zfs-mount.service
-WantedBy=zfs.target
+WantedBy=zfs-import.target

etc/systemd/system/zfs-import.target.in

@@ -0,0 +1,6 @@
+[Unit]
+Description=ZFS pool import target
+
+[Install]
+WantedBy=zfs-mount.service
+WantedBy=zfs.target

etc/systemd/system/zfs-mount.service.in

@@ -3,8 +3,7 @@ Description=Mount ZFS filesystems
 Documentation=man:zfs(8)
 DefaultDependencies=no
 After=systemd-udev-settle.service
-After=zfs-import-cache.service
-After=zfs-import-scan.service
+After=zfs-import.target
 After=systemd-remount-fs.service
 Before=local-fs.target
 

man/man8/zfs.8

@@ -461,7 +461,16 @@ If needed, ZFS file systems can also be managed with traditional tools
 If a file system's mount point is set to
 .Sy legacy ,
 ZFS makes no attempt to manage the file system, and the administrator is
-responsible for mounting and unmounting the file system.
+responsible for mounting and unmounting the file system. Because pools must
+be imported before a legacy mount can succeed, administrators should ensure
+that legacy mounts are only attempted after the zpool import process
+finishes at boot time. For example, on machines using systemd, the mount
+option
+.Pp
+.Nm x-systemd.requires=zfs-import.target
+.Pp
+will ensure that the zfs-import completes before systemd attempts mounting
+the filesystem. See systemd.mount(5) for details.
 .Ss Deduplication
 Deduplication is the process for removing redundant data at the block level,
 reducing the total amount of data stored. If a file system has the