--- name: "dracut.zfs" section: "7" platform: "linux" package: "zfs-dracut" version: "2.3.9-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/dracut.zfs" --- # dracut.zfs(7) overview of ZFS dracut hooks ## NAME **dracut.zfs** – overview of ZFS dracut hooks ## SYNOPSIS ``` parse-zfs.sh → dracut-cmdline.service | ↓ | … | ↓ \————————→ dracut-initqueue.service | zfs-import-opts.sh zfs-load-module.service ↓ | | | | sysinit.target ↓ | ↓ | | zfs-import-scan.service ↓ zfs-import-scan.service ↓ ↓ | zfs-import-cache.service | zfs-import-cache.service basic.target | | \__________________| | ↓ ↓ ↓ | zfs-load-key.sh zfs-env-bootfs.service | | ↓ ↓ ↓ zfs-import.target → dracut-pre-mount.service | ↑ | | dracut-zfs-generator | | _____________________/| |/ ↓ | sysroot.mount ←——— dracut-zfs-generator | | | ↓ | initrd-root-fs.target ←— zfs-nonroot-necessities.service | | | | ↓ | ↓ dracut-mount.service | zfs-snapshot-bootfs.service | | | ↓ | ↓ … | zfs-rollback-bootfs.service | | | ↓ | | /sysroot/{usr,etc,lib,&c.} ←———————————————————/ | | | ↓ | initrd-fs.target \______________________ | \| ↓ export-zfs.sh initrd.target | | ↓ ↓ dracut-shutdown.service … | ↓ zfs-needshutdown.sh → initrd-cleanup.service ``` Compare [dracut.bootup(7)](/dracut.bootup/7.md) for the full flowchart. ## DESCRIPTION Under dracut, booting with ZFS-on-*/* is facilitated by a number of hooks in the **90zfs** module. Booting into a ZFS dataset requires **mountpoint**=*/* to be set on the dataset containing the root filesystem (henceforth "the boot dataset") and at the very least either the **bootfs** property to be set to that dataset, or the **root=** kernel cmdline (or dracut drop-in) argument to specify it. All children of the boot dataset with **canmount**=**on** with **mountpoint**s matching */etc*, */bin*, */lib*, */lib??*, */libx32*, and */usr* globs are deemed essential and will be mounted as well. [zfs-mount-generator(8)](/zfs-mount-generator/8.md) is recommended for proper functioning of the system afterward (correct mount properties, remounting, &c.). ## CMDLINE ### Standard - **root=zfs:***dataset*, **root=ZFS=***dataset* Use *dataset* as the boot dataset. All pluses (‘+’) are replaced with spaces (‘ ’). - **root=zfs:AUTO**, **root=zfs:**, **root=zfs**, \[**root=**\] After import, search for the first pool with the **bootfs** property set, use its value as-if specified as the *dataset* above. - **rootfstype=zfs** **root=***dataset* Equivalent to **root=zfs:***dataset*. - **rootfstype=zfs** \[**root=**\] Equivalent to **root=zfs:AUTO**. - **rootflags=***flags* Mount the boot dataset with **-o** *flags*; cf. Temporary Mount Point Properties in [zfsprops(7)](/zfsprops/7.md). These properties will not last, since all filesystems will be re-mounted from the real root. - **debug** If specified, **dracut-zfs-generator** logs to the journal. Be careful about setting neither **rootfstype=zfs** nor **root=zfs:***dataset* — other automatic boot selection methods, like **systemd-gpt-auto-generator** and **systemd-fstab-generator** might take precedent. ### ZFS-specific - **bootfs.snapshot**\[**=***snapshot-name*\] Execute **zfs** **snapshot** *boot-dataset***@***snapshot-name* before pivoting to the real root. *snapshot-name* defaults to the current kernel release. - **bootfs.rollback**\[**=***snapshot-name*\] Execute **zfs** **rollback** **-Rf** *boot-dataset***@***snapshot-name* before pivoting to the real root. *snapshot-name* defaults to the current kernel release. - **spl\_hostid=***host-id* Use [zgenhostid(8)](/zgenhostid/8.md) to set the host ID to *host-id*; otherwise, */etc/hostid* inherited from the real root is used. - **zfs\_force**, **zfs.force**, **zfsforce** Appends **-f** to all **zpool** **import** invocations; primarily useful in conjunction with **spl\_hostid=**, or if no host ID was inherited. ## FILES - *parse-zfs.sh* (**cmdline**) Processes **spl\_hostid=**. If **root=** matches a known pattern, above, provides */dev/root* and delays the initqueue until [zfs(4)](/zfs/4.md) is loaded, - *zfs-import-opts.sh* (**systemd** environment generator) Turns **zfs\_force**, **zfs.force**, or **zfsforce** into ZPOOL\_IMPORT\_OPTS=**-f** for *zfs-import-scan.service* or *zfs-import-cache.service*. - *zfs-load-key.sh* (**pre-mount**) Loads encryption keys for the boot dataset and its essential descendants. - **keylocation**=**prompt** Is prompted for via **systemd-ask-password** thrice. - **keylocation**=**https://***URL*, **keylocation**=**http://***URL* *network-online.target* is started before loading. - **keylocation**=**file://***path* If *path* doesn't exist, **udevadm** is **settle**d. If it still doesn't, it's waited for for up to **10**s. - *zfs-env-bootfs.service* (**systemd** service) After pool import, sets BOOTFS= in the systemd environment to the first non-null **bootfs** value in iteration order. - *dracut-zfs-generator* (**systemd** generator) Generates *sysroot.mount* (using **rootflags=**, if any). If an explicit boot dataset was specified, also generates essential mountpoints (*sysroot-etc.mount*, *sysroot-bin.mount*, &c.), otherwise generates *zfs-nonroot-necessities.service* which mounts them explicitly after */sysroot* using BOOTFS=. - *zfs-snapshot-bootfs.service*, *zfs-rollback-bootfs.service* (**systemd** services) Consume **bootfs.snapshot** and **bootfs.rollback** as described in CMDLINE. Use BOOTFS= if no explicit boot dataset was specified. - *zfs-needshutdown.sh* (**cleanup**) If any pools were imported, signals that shutdown hooks are required. - *export-zfs.sh* (**shutdown**) Forcibly exports all pools. - */etc/hostid*, */etc/zfs/zpool.cache*, */etc/zfs/vdev\_id.conf* (regular files) Included verbatim, hostonly. - *mount-zfs.sh* (**mount**) Does nothing on **systemd** systems (if *dracut-zfs-generator* succeeded). Otherwise, loads encryption key for the boot dataset from the console or via plymouth. It may not work at all! ## SEE ALSO [dracut.bootup(7)](/dracut.bootup/7.md), [zfsprops(7)](/zfsprops/7.md), [zpoolprops(7)](/zpoolprops/7.md), [dracut-shutdown.service(8)](/dracut-shutdown.service/8.md), [systemd-fstab-generator(8)](/systemd-fstab-generator/8.md), [systemd-gpt-auto-generator(8)](/systemd-gpt-auto-generator/8.md), [zfs-mount-generator(8)](/zfs-mount-generator/8.md), [zgenhostid(8)](/zgenhostid/8.md)