| .\" SPDX-License-Identifier: 0BSD |
| .\" |
| .Dd March 28, 2023 |
| .Dt DRACUT.ZFS 7 |
| .Os |
| . |
| .Sh NAME |
| .Nm dracut.zfs |
| .Nd overview of ZFS dracut hooks |
| . |
| .Sh SYNOPSIS |
| .Bd -literal -compact |
| parse-zfs.sh \(-> dracut-cmdline.service |
| | \(da |
| | … |
| | \(da |
| \e\(em\(em\(em\(em\(em\(em\(em\(em\(-> dracut-initqueue.service |
| | zfs-import-opts.sh |
| zfs-load-module.service \(da | | |
| | | sysinit.target \(da | |
| \(da | | zfs-import-scan.service \(da |
| zfs-import-scan.service \(da \(da | zfs-import-cache.service |
| | zfs-import-cache.service basic.target | | |
| \e__________________| | \(da \(da |
| \(da | zfs-load-key.sh |
| zfs-env-bootfs.service | | |
| \(da \(da \(da |
| zfs-import.target \(-> dracut-pre-mount.service |
| | \(ua | |
| | dracut-zfs-generator | |
| | _____________________/| |
| |/ \(da |
| | sysroot.mount \(<-\(em\(em\(em dracut-zfs-generator |
| | | |
| | \(da |
| | initrd-root-fs.target \(<-\(em zfs-nonroot-necessities.service |
| | | | |
| | \(da | |
| \(da dracut-mount.service | |
| zfs-snapshot-bootfs.service | | |
| | \(da | |
| \(da … | |
| zfs-rollback-bootfs.service | | |
| | \(da | |
| | /sysroot/{usr,etc,lib,&c.} \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em/ |
| | | |
| | \(da |
| | initrd-fs.target |
| \e______________________ | |
| \e| |
| \(da |
| export-zfs.sh initrd.target |
| | | |
| \(da \(da |
| dracut-shutdown.service … |
| | |
| \(da |
| zfs-needshutdown.sh \(-> initrd-cleanup.service |
| .Ed |
| .Pp |
| Compare |
| .Xr dracut.bootup 7 |
| for the full flowchart. |
| . |
| .Sh DESCRIPTION |
| Under dracut, booting with |
| .No ZFS-on- Ns Pa / |
| is facilitated by a number of hooks in the |
| .Nm 90zfs |
| module. |
| .Pp |
| Booting into a ZFS dataset requires |
| .Sy mountpoint Ns = Ns Pa / |
| to be set on the dataset containing the root filesystem (henceforth "the boot dataset") and at the very least either the |
| .Sy bootfs |
| property to be set to that dataset, or the |
| .Sy root= |
| kernel cmdline (or dracut drop-in) argument to specify it. |
| .Pp |
| All children of the boot dataset with |
| .Sy canmount Ns = Ns Sy on |
| with |
| .Sy mountpoint Ns s |
| matching |
| .Pa /etc , /bin , /lib , /lib?? , /libx32 , No and Pa /usr |
| globs are deemed essential and will be mounted as well. |
| .Pp |
| .Xr zfs-mount-generator 8 |
| is recommended for proper functioning of the system afterward (correct mount properties, remounting, &c.). |
| . |
| .Sh CMDLINE |
| .Ss Standard |
| .Bl -tag -compact -width ".Sy root=zfs:AUTO , root=zfs: , root=zfs , Op Sy root=" |
| .It Sy root=zfs:\& Ns Ar dataset , Sy root=ZFS= Ns Ar dataset |
| Use |
| .Ar dataset |
| as the boot dataset. |
| All pluses |
| .Pq Sq + |
| are replaced with spaces |
| .Pq Sq \ . |
| . |
| .It Sy root=zfs:AUTO , root=zfs:\& , root=zfs , Op Sy root= |
| After import, search for the first pool with the |
| .Sy bootfs |
| property set, use its value as-if specified as the |
| .Ar dataset |
| above. |
| . |
| .It Sy rootfstype=zfs root= Ns Ar dataset |
| Equivalent to |
| .Sy root=zfs:\& Ns Ar dataset . |
| . |
| .It Sy rootfstype=zfs Op Sy root= |
| Equivalent to |
| .Sy root=zfs:AUTO . |
| . |
| .It Sy rootflags= Ns Ar flags |
| Mount the boot dataset with |
| .Fl o Ar flags ; |
| cf.\& |
| .Sx Temporary Mount Point Properties |
| in |
| .Xr zfsprops 7 . |
| These properties will not last, since all filesystems will be re-mounted from the real root. |
| . |
| .It Sy debug |
| If specified, |
| .Nm dracut-zfs-generator |
| logs to the journal. |
| .El |
| .Pp |
| Be careful about setting neither |
| .Sy rootfstype=zfs |
| nor |
| .Sy root=zfs:\& Ns Ar dataset |
| \(em other automatic boot selection methods, like |
| .Nm systemd-gpt-auto-generator |
| and |
| .Nm systemd-fstab-generator |
| might take precedent. |
| . |
| .Ss ZFS-specific |
| .Bl -tag -compact -width ".Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name" |
| .It Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name |
| Execute |
| .Nm zfs Cm snapshot Ar boot-dataset Ns Sy @ Ns Ar snapshot-name |
| before pivoting to the real root. |
| .Ar snapshot-name |
| defaults to the current kernel release. |
| . |
| .It Sy bootfs.rollback Ns Op Sy = Ns Ar snapshot-name |
| Execute |
| .Nm zfs Cm snapshot Fl Rf Ar boot-dataset Ns Sy @ Ns Ar snapshot-name |
| before pivoting to the real root. |
| .Ar snapshot-name |
| defaults to the current kernel release. |
| . |
| .It Sy spl_hostid= Ns Ar host-id |
| Use |
| .Xr zgenhostid 8 |
| to set the host ID to |
| .Ar host-id ; |
| otherwise, |
| .Pa /etc/hostid |
| inherited from the real root is used. |
| . |
| .It Sy zfs_force , zfs.force , zfsforce |
| Appends |
| .Fl f |
| to all |
| .Nm zpool Cm import |
| invocations; primarily useful in conjunction with |
| .Sy spl_hostid= , |
| or if no host ID was inherited. |
| .El |
| . |
| .Sh FILES |
| .Bl -tag -width 0 |
| .It Pa parse-zfs.sh Pq Sy cmdline |
| Processes |
| .Sy spl_hostid= . |
| If |
| .Sy root= |
| matches a known pattern, above, provides |
| .Pa /dev/root |
| and delays the initqueue until |
| .Xr zfs 4 |
| is loaded, |
| . |
| .It Pa zfs-import-opts.sh Pq Nm systemd No environment generator |
| Turns |
| .Sy zfs_force , zfs.force , No or Sy zfsforce |
| into |
| .Ev ZPOOL_IMPORT_OPTS Ns = Ns Fl f |
| for |
| .Pa zfs-import-scan.service |
| or |
| .Pa zfs-import-cache.service . |
| . |
| .It Pa zfs-load-key.sh Pq Sy pre-mount |
| Loads encryption keys for the boot dataset and its essential descendants. |
| .Bl -tag -compact -offset 4n -width ".Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL" |
| .It Sy keylocation Ns = Ns Sy prompt |
| Is prompted for via |
| .Nm systemd-ask-password |
| thrice. |
| . |
| .It Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL |
| .Pa network-online.target |
| is started before loading. |
| . |
| .It Sy keylocation Ns = Ns Sy file:// Ns Ar path |
| If |
| .Ar path |
| doesn't exist, |
| .Nm udevadm No is Cm settle Ns d . |
| If it still doesn't, it's waited for for up to |
| .Sy 10 Ns s . |
| .El |
| . |
| .It Pa zfs-env-bootfs.service Pq Nm systemd No service |
| After pool import, sets |
| .Ev BOOTFS Ns = |
| in the systemd environment to the first non-null |
| .Sy bootfs |
| value in iteration order. |
| . |
| .It Pa dracut-zfs-generator Pq Nm systemd No generator |
| Generates |
| .Pa sysroot.mount Pq using Sy rootflags= , No if any . |
| If an explicit boot dataset was specified, also generates essential mountpoints |
| .Pq Pa sysroot-etc.mount , sysroot-bin.mount , No &c.\& , |
| otherwise generates |
| .Pa zfs-nonroot-necessities.service |
| which mounts them explicitly after |
| .Pa /sysroot |
| using |
| .Ev BOOTFS Ns = . |
| . |
| .It Pa zfs-snapshot-bootfs.service , zfs-rollback-bootfs.service Pq Nm systemd No services |
| Consume |
| .Sy bootfs.snapshot |
| and |
| .Sy bootfs.rollback |
| as described in |
| .Sx CMDLINE . |
| Use |
| .Ev BOOTFS Ns = |
| if no explicit boot dataset was specified. |
| . |
| .It Pa zfs-needshutdown.sh Pq Sy cleanup |
| If any pools were imported, signals that shutdown hooks are required. |
| . |
| .It Pa export-zfs.sh Pq Sy shutdown |
| Forcibly exports all pools. |
| . |
| .It Pa /etc/hostid , /etc/zfs/zpool.cache , /etc/zfs/vdev_id.conf Pq regular files |
| Included verbatim, hostonly. |
| . |
| .It Pa mount-zfs.sh Pq Sy mount |
| Does nothing on |
| .Nm systemd |
| systems |
| .Pq if Pa dracut-zfs-generator No succeeded . |
| Otherwise, loads encryption key for the boot dataset from the console or via plymouth. |
| It may not work at all! |
| .El |
| . |
| .Sh SEE ALSO |
| .Xr dracut.bootup 7 , |
| .Xr zfsprops 7 , |
| .Xr zpoolprops 7 , |
| .Xr dracut-shutdown.service 8 , |
| .Xr systemd-fstab-generator 8 , |
| .Xr systemd-gpt-auto-generator 8 , |
| .Xr zfs-mount-generator 8 , |
| .Xr zgenhostid 8 |
