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