man/man7/dracut.zfs.7

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