DRACUT.ZFS(7) Miscellaneous Information Manual DRACUT.ZFS(7) # [NAME](#NAME) `dracut.zfs` — overview of ZFS dracut hooks # [SYNOPSIS](#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)](/man/os/zfs/dracut.bootup.7) for the full flowchart. # [DESCRIPTION](#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**](#canmount)=[**on**](#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)](/man/os/zfs/zfs-mount-generator.8) is recommended for proper functioning of the system afterward (correct mount properties, remounting, &c.). # [CMDLINE](#CMDLINE) ## [Standard](#Standard) [**root=zfs:**](#root=zfs:)`dataset`, [**root=ZFS=**](#root=ZFS=)`dataset` Use `dataset` as the boot dataset. All pluses (‘+’) are replaced with spaces (‘ ’). [**root=zfs:AUTO**](#root=zfs:AUTO), **root=zfs:**, [**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**](#rootfstype=zfs) \[**root=**] Equivalent to **root=zfs:AUTO**. [**rootflags=**](#rootflags=)`flags` Mount the boot dataset with `-o` `flags`; cf. [Temporary Mount Point Properties](#Temporary_Mount_Point_Properties) in [zfsprops(7)](/man/os/zfs/zfsprops.7). These properties will not last, since all filesystems will be re-mounted from the real root. [**debug**](#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](#ZFS-specific) [**bootfs.snapshot**](#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**](#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=**](#spl_hostid=)`host-id` Use [zgenhostid(8)](/man/os/zfs/zgenhostid.8) to set the host ID to `host-id`; otherwise, /etc/hostid inherited from the real root is used. [**zfs\_force**](#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](#FILES) parse-zfs.sh ([**cmdline**](#cmdline)) Processes **spl\_hostid=**. If **root=** matches a known pattern, above, provides /dev/root and delays the initqueue until [zfs(4)](/man/os/zfs/zfs.4) 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**](#pre-mount)) Loads encryption keys for the boot dataset and its essential descendants. [**keylocation**](#keylocation)=[**prompt**](#prompt) Is prompted for via `systemd-ask-password` thrice. [**keylocation**](#keylocation~2)=[**https://**](#https://)`URL`, **keylocation**=[**http://**](#http://)`URL` network-online.target is started before loading. [**keylocation**](#keylocation~3)=[**file://**](#file://)`path` If `path` doesn't exist, `udevadm` is `settle`d. If it still doesn't, it's waited for for up to [**10**](#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](#CMDLINE). Use `BOOTFS`= if no explicit boot dataset was specified. zfs-needshutdown.sh ([**cleanup**](#cleanup)) If any pools were imported, signals that shutdown hooks are required. export-zfs.sh ([**shutdown**](#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**](#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](#SEE_ALSO) [dracut.bootup(7)](/man/os/zfs/dracut.bootup.7), [zfsprops(7)](/man/os/zfs/zfsprops.7), [zpoolprops(7)](/man/os/zfs/zpoolprops.7), [dracut-shutdown.service(8)](/man/os/zfs/dracut-shutdown.service.8), [systemd-fstab-generator(8)](/man/os/zfs/systemd-fstab-generator.8), [systemd-gpt-auto-generator(8)](/man/os/zfs/systemd-gpt-auto-generator.8), [zfs-mount-generator(8)](/man/os/zfs/zfs-mount-generator.8), [zgenhostid(8)](/man/os/zfs/zgenhostid.8) July 13, 2024 OpenZFS --- Document: dracut.zfs(7) from zfs 2.4.4-r3 (Chainguard OS) Source: https://github.com/openzfs/zfs