1.\" SPDX-License-Identifier: 0BSD 2.\" 3.Dd April 4, 2022 4.Dt DRACUT.ZFS 7 5.Os 6. 7.Sh NAME 8.Nm dracut.zfs 9.Nd overview of ZFS dracut hooks 10. 11.Sh SYNOPSIS 12.Bd -literal -compact 13 parse-zfs.sh \(-> dracut-cmdline.service 14 | \(da 15 | … 16 | \(da 17 \e\(em\(em\(em\(em\(em\(em\(em\(em\(-> dracut-initqueue.service 18 | zfs-import-opts.sh 19 zfs-load-module.service \(da | | 20 | | sysinit.target \(da | 21 \(da | | zfs-import-scan.service \(da 22zfs-import-scan.service \(da \(da | zfs-import-cache.service 23 | zfs-import-cache.service basic.target | | 24 \e__________________| | \(da \(da 25 \(da | zfs-load-key.sh 26 zfs-env-bootfs.service | | 27 \(da \(da \(da 28 zfs-import.target \(-> dracut-pre-mount.service 29 | \(ua | 30 | dracut-zfs-generator | 31 | ____________________/| 32 |/ \(da 33 | sysroot.mount \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em dracut-zfs-generator 34 | | \(da | 35 | \(da sysroot-{usr,etc,lib,&c.}.mount | 36 | initrd-root-fs.target \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em or \(da 37 | | zfs-nonroot-necessities.service 38 | \(da | 39 \(da dracut-mount.service | 40 zfs-snapshot-bootfs.service | | 41 | \(da | 42 \(da … | 43 zfs-rollback-bootfs.service | | 44 | \(da | 45 | sysroot-usr.mount \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em/ 46 | | 47 | \(da 48 | initrd-fs.target 49 \e______________________ | 50 \e| 51 \(da 52 export-zfs.sh initrd.target 53 | | 54 \(da \(da 55 dracut-shutdown.service … 56 | 57 \(da 58 zfs-needshutdown.sh \(-> initrd-cleanup.service 59.Ed 60.Pp 61Compare 62.Xr dracut.bootup 7 63for the full flowchart. 64. 65.Sh DESCRIPTION 66Under dracut, booting with 67.No ZFS-on- Ns Pa / 68is facilitated by a number of hooks in the 69.Nm 90zfs 70module. 71.Pp 72Booting into a ZFS dataset requires 73.Sy mountpoint Ns = Ns Pa / 74to be set on the dataset containing the root filesystem (henceforth "the boot dataset") and at the very least either the 75.Sy bootfs 76property to be set to that dataset, or the 77.Sy root= 78kernel cmdline (or dracut drop-in) argument to specify it. 79.Pp 80All children of the boot dataset with 81.Sy canmount Ns = Ns Sy on 82with 83.Sy mountpoint Ns s 84matching 85.Pa /etc , /bin , /lib , /lib?? , /libx32 , No and Pa /usr 86globs are deemed essential and will be mounted as well. 87.Pp 88.Xr zfs-mount-generator 8 89is recommended for proper functioning of the system afterward (correct mount properties, remounting, &c.). 90. 91.Sh CMDLINE 92.Ss Standard 93.Bl -tag -compact -width ".Sy root=zfs:AUTO , root=zfs: , root=zfs , Op Sy root=" 94.It Sy root=zfs:\& Ns Ar dataset , Sy root=ZFS= Ns Ar dataset 95Use 96.Ar dataset 97as the boot dataset. 98All pluses 99.Pq Sq + 100are replaced with spaces 101.Pq Sq \ . 102. 103.It Sy root=zfs:AUTO , root=zfs:\& , root=zfs , Op Sy root= 104After import, search for the first pool with the 105.Sy bootfs 106property set, use its value as-if specified as the 107.Ar dataset 108above. 109. 110.It Sy rootfstype=zfs root= Ns Ar dataset 111Equivalent to 112.Sy root=zfs:\& Ns Ar dataset . 113. 114.It Sy rootfstype=zfs Op Sy root= 115Equivalent to 116.Sy root=zfs:AUTO . 117. 118.It Sy rootflags= Ns Ar flags 119Mount the boot dataset with 120.Fl o Ar flags ; 121cf.\& 122.Sx Temporary Mount Point Properties 123in 124.Xr zfsprops 7 . 125These properties will not last, since all filesystems will be re-mounted from the real root. 126. 127.It Sy debug 128If specified, 129.Nm dracut-zfs-generator 130logs to the journal. 131.El 132.Pp 133Be careful about setting neither 134.Sy rootfstype=zfs 135nor 136.Sy root=zfs:\& Ns Ar dataset 137\(em other automatic boot selection methods, like 138.Nm systemd-gpt-auto-generator 139and 140.Nm systemd-fstab-generator 141might take precedent. 142. 143.Ss ZFS-specific 144.Bl -tag -compact -width ".Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name" 145.It Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name 146Execute 147.Nm zfs Cm snapshot Ar boot-dataset Ns Sy @ Ns Ar snapshot-name 148before pivoting to the real root. 149.Ar snapshot-name 150defaults to the current kernel release. 151. 152.It Sy bootfs.rollback Ns Op Sy = Ns Ar snapshot-name 153Execute 154.Nm zfs Cm snapshot Fl Rf Ar boot-dataset Ns Sy @ Ns Ar snapshot-name 155before pivoting to the real root. 156.Ar snapshot-name 157defaults to the current kernel release. 158. 159.It Sy spl_hostid= Ns Ar host-id 160Use 161.Xr zgenhostid 8 162to set the host ID to 163.Ar host-id ; 164otherwise, 165.Pa /etc/hostid 166inherited from the real root is used. 167. 168.It Sy zfs_force , zfs.force , zfsforce 169Appends 170.Fl f 171to all 172.Nm zpool Cm import 173invocations; primarily useful in conjunction with 174.Sy spl_hostid= , 175or if no host ID was inherited. 176.El 177. 178.Sh FILES 179.Bl -tag -width 0 180.It Pa parse-zfs.sh Pq Sy cmdline 181Processes 182.Sy spl_hostid= . 183If 184.Sy root= 185matches a known pattern, above, provides 186.Pa /dev/root 187and delays the initqueue until 188.Xr zfs 4 189is loaded, 190. 191.It Pa zfs-import-opts.sh Pq Nm systemd No environment generator 192Turns 193.Sy zfs_force , zfs.force , No or Sy zfsforce 194into 195.Ev ZPOOL_IMPORT_OPTS Ns = Ns Fl f 196for 197.Pa zfs-import-scan.service 198or 199.Pa zfs-import-cache.service . 200. 201.It Pa zfs-load-key.sh Pq Sy pre-mount 202Loads encryption keys for the boot dataset and its essential descendants. 203.Bl -tag -compact -offset 4n -width ".Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL" 204.It Sy keylocation Ns = Ns Sy prompt 205Is prompted for via 206.Nm systemd-ask-password 207thrice. 208. 209.It Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL 210.Pa network-online.target 211is started before loading. 212. 213.It Sy keylocation Ns = Ns Sy file:// Ns Ar path 214If 215.Ar path 216doesn't exist, 217.Nm udevadm No is Cm settle Ns d . 218If it still doesn't, it's waited for for up to 219.Sy 10 Ns s . 220.El 221. 222.It Pa zfs-env-bootfs.service Pq Nm systemd No service 223After pool import, sets 224.Ev BOOTFS Ns = 225in the systemd environment to the first non-null 226.Sy bootfs 227value in iteration order. 228. 229.It Pa dracut-zfs-generator Pq Nm systemd No generator 230Generates 231.Pa sysroot.mount Pq using Sy rootflags= , No if any . 232If an explicit boot dataset was specified, also generates essential mountpoints 233.Pq Pa sysroot-etc.mount , sysroot-bin.mount , No &c.\& , 234otherwise generates 235.Pa zfs-nonroot-necessities.service 236which mounts them explicitly after 237.Pa /sysroot 238using 239.Ev BOOTFS Ns = . 240. 241.It Pa zfs-snapshot-bootfs.service , zfs-rollback-bootfs.service Pq Nm systemd No services 242Consume 243.Sy bootfs.snapshot 244and 245.Sy bootfs.rollback 246as described in 247.Sx CMDLINE . 248Use 249.Ev BOOTFS Ns = 250if no explicit boot dataset was specified. 251. 252.It Pa zfs-needshutdown.sh Pq Sy cleanup 253If any pools were imported, signals that shutdown hooks are required. 254. 255.It Pa export-zfs.sh Pq Sy shutdown 256Forcibly exports all pools. 257. 258.It Pa /etc/hostid , /etc/zfs/zpool.cache , /etc/zfs/vdev_id.conf Pq regular files 259Included verbatim, hostonly. 260. 261.It Pa mount-zfs.sh Pq Sy mount 262Does nothing on 263.Nm systemd 264systems 265.Pq if Pa dracut-zfs-generator No succeeded . 266Otherwise, loads encryption key for the boot dataset from the console or via plymouth. 267It may not work at all! 268.El 269. 270.Sh SEE ALSO 271.Xr dracut.bootup 7 , 272.Xr zfsprops 7 , 273.Xr zpoolprops 7 , 274.Xr dracut-shutdown.service 8 , 275.Xr systemd-fstab-generator 8 , 276.Xr systemd-gpt-auto-generator 8 , 277.Xr zfs-mount-generator 8 , 278.Xr zgenhostid 8 279