Add dracut.zfs.7
Thorough documentation with a dracut.bootup(7)-style flowchart,
dracut.cmdline(7)-style cmdline listing,
and per-file docs like the old README
Upstream-commit: e3fc330d6c
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #13291
This commit is contained in:
наб
Brian Behlendorf
parent
0947096044
commit
1781ee703b
|
|
@ -15,6 +15,8 @@ Encrypted datasets have keys loaded automatically or prompted for.
|
||||||
|
|
||||||
If the root dataset contains children with `mountpoint=`s of `/etc`, `/bin`, `/lib*`, or `/usr`, they're mounted too.
|
If the root dataset contains children with `mountpoint=`s of `/etc`, `/bin`, `/lib*`, or `/usr`, they're mounted too.
|
||||||
|
|
||||||
|
For complete documentation, see `dracut.zfs(7)`.
|
||||||
|
|
||||||
## cmdline
|
## cmdline
|
||||||
1. `root=` | Root dataset is… |
|
1. `root=` | Root dataset is… |
|
||||||
---------------------------|----------------------------------------------------------|
|
---------------------------|----------------------------------------------------------|
|
||||||
|
|
|
||||||
|
|
@ -15,6 +15,7 @@ dist_man_MANS = \
|
||||||
man4/spl.4 \
|
man4/spl.4 \
|
||||||
man4/zfs.4 \
|
man4/zfs.4 \
|
||||||
\
|
\
|
||||||
|
man7/dracut.zfs.7 \
|
||||||
man7/zpool-features.7 \
|
man7/zpool-features.7 \
|
||||||
man7/zfsconcepts.7 \
|
man7/zfsconcepts.7 \
|
||||||
man7/zfsprops.7 \
|
man7/zfsprops.7 \
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,278 @@
|
||||||
|
.\" SPDX-License-Identifier: 0BSD
|
||||||
|
.\"
|
||||||
|
.Dd April 4, 2022
|
||||||
|
.Dt DRACUT.ZFS 7
|
||||||
|
.Os
|
||||||
|
.
|
||||||
|
.Sh NAME
|
||||||
|
.Nm dracut.zfs
|
||||||
|
.Nd overview of ZFS dracut hooks
|
||||||
|
.
|
||||||
|
.Sh SYNOPSIS
|
||||||
|
.Bd -literal -compact
|
||||||
|
parse-zfs.sh \(-> dracut-cmdline.service
|
||||||
|
| \(da
|
||||||
|
| …
|
||||||
|
| \(da
|
||||||
|
\e\(em\(em\(em\(em\(em\(em\(em\(em\(-> dracut-initqueue.service
|
||||||
|
| zfs-import-opts.sh
|
||||||
|
zfs-load-module.service \(da | |
|
||||||
|
| | sysinit.target \(da |
|
||||||
|
\(da | | zfs-import-scan.service \(da
|
||||||
|
zfs-import-scan.service \(da \(da | zfs-import-cache.service
|
||||||
|
| zfs-import-cache.service basic.target | |
|
||||||
|
\e__________________| | \(da \(da
|
||||||
|
\(da | zfs-load-key.sh
|
||||||
|
zfs-env-bootfs.service | |
|
||||||
|
\(da \(da \(da
|
||||||
|
zfs-import.target \(-> dracut-pre-mount.service
|
||||||
|
| \(ua |
|
||||||
|
| dracut-zfs-generator |
|
||||||
|
| ____________________/|
|
||||||
|
|/ \(da
|
||||||
|
| sysroot.mount \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em dracut-zfs-generator
|
||||||
|
| | \(da |
|
||||||
|
| \(da sysroot-{usr,etc,lib,&c.}.mount |
|
||||||
|
| initrd-root-fs.target \(<-\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em\(em or \(da
|
||||||
|
| | zfs-nonroot-necessities.service
|
||||||
|
| \(da |
|
||||||
|
\(da dracut-mount.service |
|
||||||
|
zfs-snapshot-bootfs.service | |
|
||||||
|
| \(da |
|
||||||
|
\(da … |
|
||||||
|
zfs-rollback-bootfs.service | |
|
||||||
|
| \(da |
|
||||||
|
| 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/
|
||||||
|
| |
|
||||||
|
| \(da
|
||||||
|
| initrd-fs.target
|
||||||
|
\e______________________ |
|
||||||
|
\e|
|
||||||
|
\(da
|
||||||
|
export-zfs.sh initrd.target
|
||||||
|
| |
|
||||||
|
\(da \(da
|
||||||
|
dracut-shutdown.service …
|
||||||
|
|
|
||||||
|
\(da
|
||||||
|
zfs-needshutdown.sh \(-> initrd-cleanup.service
|
||||||
|
.Ed
|
||||||
|
.Pp
|
||||||
|
Compare
|
||||||
|
.Xr dracut.bootup 7
|
||||||
|
for the full flowchart.
|
||||||
|
.
|
||||||
|
.Sh DESCRIPTION
|
||||||
|
Under dracut, booting with
|
||||||
|
.No ZFS-on- Ns Pa /
|
||||||
|
is facilitated by a number of hooks in the
|
||||||
|
.Nm 90zfs
|
||||||
|
module.
|
||||||
|
.Pp
|
||||||
|
Booting into a ZFS dataset requires
|
||||||
|
.Sy mountpoint Ns = Ns Pa /
|
||||||
|
to be set on the dataset containing the root filesystem (henceforth "the boot dataset") and at the very least either the
|
||||||
|
.Sy bootfs
|
||||||
|
property to be set to that dataset, or the
|
||||||
|
.Sy root=
|
||||||
|
kernel cmdline (or dracut drop-in) argument to specify it.
|
||||||
|
.Pp
|
||||||
|
All children of the boot dataset with
|
||||||
|
.Sy canmount Ns = Ns Sy on
|
||||||
|
with
|
||||||
|
.Sy mountpoint Ns s
|
||||||
|
matching
|
||||||
|
.Pa /etc , /bin , /lib , /lib?? , /libx32 , No and Pa /usr
|
||||||
|
globs are deemed essential and will be mounted as well.
|
||||||
|
.Pp
|
||||||
|
.Xr zfs-mount-generator 8
|
||||||
|
is recommended for proper functioning of the system afterward (correct mount properties, remounting, &c.).
|
||||||
|
.
|
||||||
|
.Sh CMDLINE
|
||||||
|
.Ss Standard
|
||||||
|
.Bl -tag -compact -width ".Sy root=zfs:AUTO , root=zfs: , root=zfs , Op Sy root="
|
||||||
|
.It Sy root=zfs:\& Ns Ar dataset , Sy root=ZFS= Ns Ar dataset
|
||||||
|
Use
|
||||||
|
.Ar dataset
|
||||||
|
as the boot dataset.
|
||||||
|
All pluses
|
||||||
|
.Pq Sq +
|
||||||
|
are replaced with spaces
|
||||||
|
.Pq Sq \ .
|
||||||
|
.
|
||||||
|
.It Sy root=zfs:AUTO , root=zfs:\& , root=zfs , Op Sy root=
|
||||||
|
After import, search for the first pool with the
|
||||||
|
.Sy bootfs
|
||||||
|
property set, use its value as-if specified as the
|
||||||
|
.Ar dataset
|
||||||
|
above.
|
||||||
|
.
|
||||||
|
.It Sy rootfstype=zfs root= Ns Ar dataset
|
||||||
|
Equivalent to
|
||||||
|
.Sy root=zfs:\& Ns Ar dataset .
|
||||||
|
.
|
||||||
|
.It Sy rootfstype=zfs Op Sy root=
|
||||||
|
Equivalent to
|
||||||
|
.Sy root=zfs:AUTO .
|
||||||
|
.
|
||||||
|
.It Sy rootflags= Ns Ar flags
|
||||||
|
Mount the boot dataset with
|
||||||
|
.Fl o Ar flags ;
|
||||||
|
cf.\&
|
||||||
|
.Sx Temporary Mount Point Properties
|
||||||
|
in
|
||||||
|
.Xr zfsprops 7 .
|
||||||
|
These properties will not last, since all filesystems will be re-mounted from the real root.
|
||||||
|
.
|
||||||
|
.It Sy debug
|
||||||
|
If specified,
|
||||||
|
.Nm dracut-zfs-generator
|
||||||
|
logs to the journal.
|
||||||
|
.El
|
||||||
|
.Pp
|
||||||
|
Be careful about setting neither
|
||||||
|
.Sy rootfstype=zfs
|
||||||
|
nor
|
||||||
|
.Sy root=zfs:\& Ns Ar dataset
|
||||||
|
\(em other automatic boot selection methods, like
|
||||||
|
.Nm systemd-gpt-auto-generator
|
||||||
|
and
|
||||||
|
.Nm systemd-fstab-generator
|
||||||
|
might take precedent.
|
||||||
|
.
|
||||||
|
.Ss ZFS-specific
|
||||||
|
.Bl -tag -compact -width ".Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name"
|
||||||
|
.It Sy bootfs.snapshot Ns Op Sy = Ns Ar snapshot-name
|
||||||
|
Execute
|
||||||
|
.Nm zfs Cm snapshot Ar boot-dataset Ns Sy @ Ns Ar snapshot-name
|
||||||
|
before pivoting to the real root.
|
||||||
|
.Ar snapshot-name
|
||||||
|
defaults to the current kernel release.
|
||||||
|
.
|
||||||
|
.It Sy bootfs.rollback Ns Op Sy = Ns Ar snapshot-name
|
||||||
|
Execute
|
||||||
|
.Nm zfs Cm snapshot Fl Rf Ar boot-dataset Ns Sy @ Ns Ar snapshot-name
|
||||||
|
before pivoting to the real root.
|
||||||
|
.Ar snapshot-name
|
||||||
|
defaults to the current kernel release.
|
||||||
|
.
|
||||||
|
.It Sy spl_hostid= Ns Ar host-id
|
||||||
|
Use
|
||||||
|
.Xr zgenhostid 8
|
||||||
|
to set the host ID to
|
||||||
|
.Ar host-id ;
|
||||||
|
otherwise,
|
||||||
|
.Pa /etc/hostid
|
||||||
|
inherited from the real root is used.
|
||||||
|
.
|
||||||
|
.It Sy zfs_force , zfs.force , zfsforce
|
||||||
|
Appends
|
||||||
|
.Fl f
|
||||||
|
to all
|
||||||
|
.Nm zpool Cm import
|
||||||
|
invocations; primarily useful in conjunction with
|
||||||
|
.Sy spl_hostid= ,
|
||||||
|
or if no host ID was inherited.
|
||||||
|
.El
|
||||||
|
.
|
||||||
|
.Sh FILES
|
||||||
|
.Bl -tag -width 0
|
||||||
|
.It Pa parse-zfs.sh Pq Sy cmdline
|
||||||
|
Processes
|
||||||
|
.Sy spl_hostid= .
|
||||||
|
If
|
||||||
|
.Sy root=
|
||||||
|
matches a known pattern, above, provides
|
||||||
|
.Pa /dev/root
|
||||||
|
and delays the initqueue until
|
||||||
|
.Xr zfs 4
|
||||||
|
is loaded,
|
||||||
|
.
|
||||||
|
.It Pa zfs-import-opts.sh Pq Nm systemd No environment generator
|
||||||
|
Turns
|
||||||
|
.Sy zfs_force , zfs.force , No or Sy zfsforce
|
||||||
|
into
|
||||||
|
.Ev ZPOOL_IMPORT_OPTS Ns = Ns Fl f
|
||||||
|
for
|
||||||
|
.Pa zfs-import-scan.service
|
||||||
|
or
|
||||||
|
.Pa zfs-import-cache.service .
|
||||||
|
.
|
||||||
|
.It Pa zfs-load-key.sh Pq Sy pre-mount
|
||||||
|
Loads encryption keys for the boot dataset and its essential descendants.
|
||||||
|
.Bl -tag -compact -offset 4n -width ".Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL"
|
||||||
|
.It Sy keylocation Ns = Ns Sy prompt
|
||||||
|
Is prompted for via
|
||||||
|
.Nm systemd-ask-password
|
||||||
|
thrice.
|
||||||
|
.
|
||||||
|
.It Sy keylocation Ns = Ns Sy https:// Ns Ar URL , Sy keylocation Ns = Ns Sy http:// Ns Ar URL
|
||||||
|
.Pa network-online.target
|
||||||
|
is started before loading.
|
||||||
|
.
|
||||||
|
.It Sy keylocation Ns = Ns Sy file:// Ns Ar path
|
||||||
|
If
|
||||||
|
.Ar path
|
||||||
|
doesn't exist,
|
||||||
|
.Nm udevadm No is Cm settle Ns d .
|
||||||
|
If it still doesn't, it's waited for for up to
|
||||||
|
.Sy 10 Ns s .
|
||||||
|
.El
|
||||||
|
.
|
||||||
|
.It Pa zfs-env-bootfs.service Pq Nm systemd No service
|
||||||
|
After pool import, sets
|
||||||
|
.Ev BOOTFS Ns =
|
||||||
|
in the systemd environment to the first non-null
|
||||||
|
.Sy bootfs
|
||||||
|
value in iteration order.
|
||||||
|
.
|
||||||
|
.It Pa dracut-zfs-generator Pq Nm systemd No generator
|
||||||
|
Generates
|
||||||
|
.Pa sysroot.mount Pq using Sy rootflags= , No if any .
|
||||||
|
If an explicit boot dataset was specified, also generates essential mountpoints
|
||||||
|
.Pq Pa sysroot-etc.mount , sysroot-bin.mount , No &c.\& ,
|
||||||
|
otherwise generates
|
||||||
|
.Pa zfs-nonroot-necessities.service
|
||||||
|
which mounts them explicitly after
|
||||||
|
.Pa /sysroot
|
||||||
|
using
|
||||||
|
.Ev BOOTFS Ns = .
|
||||||
|
.
|
||||||
|
.It Pa zfs-snapshot-bootfs.service , zfs-rollback-bootfs.service Pq Nm systemd No services
|
||||||
|
Consume
|
||||||
|
.Sy bootfs.snapshot
|
||||||
|
and
|
||||||
|
.Sy bootfs.rollback
|
||||||
|
as described in
|
||||||
|
.Sx CMDLINE .
|
||||||
|
Use
|
||||||
|
.Ev BOOTFS Ns =
|
||||||
|
if no explicit boot dataset was specified.
|
||||||
|
.
|
||||||
|
.It Pa zfs-needshutdown.sh Pq Sy cleanup
|
||||||
|
If any pools were imported, signals that shutdown hooks are required.
|
||||||
|
.
|
||||||
|
.It Pa export-zfs.sh Pq Sy shutdown
|
||||||
|
Forcibly exports all pools.
|
||||||
|
.
|
||||||
|
.It Pa /etc/hostid , /etc/zfs/zpool.cache , /etc/zfs/vdev_id.conf Pq regular files
|
||||||
|
Included verbatim, hostonly.
|
||||||
|
.
|
||||||
|
.It Pa mount-zfs.sh Pq Sy mount
|
||||||
|
Does nothing on
|
||||||
|
.Nm systemd
|
||||||
|
systems
|
||||||
|
.Pq if Pa dracut-zfs-generator No succeeded .
|
||||||
|
Otherwise, loads encryption key for the boot dataset from the console or via plymouth.
|
||||||
|
It may not work at all!
|
||||||
|
.El
|
||||||
|
.
|
||||||
|
.Sh SEE ALSO
|
||||||
|
.Xr dracut.bootup 7 ,
|
||||||
|
.Xr zfsprops 7 ,
|
||||||
|
.Xr zpoolprops 7 ,
|
||||||
|
.Xr dracut-shutdown.service 8 ,
|
||||||
|
.Xr systemd-fstab-generator 8 ,
|
||||||
|
.Xr systemd-gpt-auto-generator 8 ,
|
||||||
|
.Xr zfs-mount-generator 8 ,
|
||||||
|
.Xr zgenhostid 8
|
||||||
Loading…
Reference in New Issue