Provided by: zfs-dracut_2.1.5-1ubuntu6~22.04.4_amd64 bug

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
                             |                       |                                        ↓   |
                             |                       ↓            sysroot-{usr,etc,lib,&c.}.mount |
                             |             initrd-root-fs.target ←———————————— or                 ↓
                             |                       |              zfs-nonroot-necessities.service
                             |                       ↓                                 |
                             ↓             dracut-mount.service                        |
            zfs-snapshot-bootfs.service              |                                 |
                             |                       ↓                                 |
                             ↓                       …                                 |
            zfs-rollback-bootfs.service              |                                 |
                             |                       ↓                                 |
                             |               sysroot-usr.mount ←———————————————————————/
                             |                       |
                             |                       ↓
                             |                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 snapshot -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 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) 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
                                                            settled.  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

     dracut.bootup(7), zfsprops(7), zpoolprops(7), dracut-shutdown.service(8),
     systemd-fstab-generator(8), systemd-gpt-auto-generator(8), zfs-mount-generator(8),
     zgenhostid(8)