dracut.zfs.7
DRACUT.ZFS(7) | Miscellaneous Information Manual | DRACUT.ZFS(7) |
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) 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 mountpoints matching /etc, /bin, /lib, /lib??, /libx32, and /usr globs are deemed essential and will be mounted as well.
zfs-mount-generator(8) 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). 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) 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 allzpool
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) 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
issettle
d. If it still doesn't, it's waited for for up to 10s.
- 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
zfsprops(7), zpoolprops(7), dracut-shutdown.service(8), systemd-fstab-generator(8), systemd-gpt-auto-generator(8), zfs-mount-generator(8), zgenhostid(8)
March 28, 2023 | Debian |