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