90d0023005
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Ref: https://github.com/openzfs/zfs/issues/11420#issuecomment-850338673 Closes #11663 Closes #12148 |
||
---|---|---|
.. | ||
conf-hooks.d | ||
conf.d | ||
hooks | ||
scripts | ||
Makefile.am | ||
README.initramfs.markdown | ||
zfsunlock |
README.initramfs.markdown
Description
These scripts are intended to be used with initramfs-tools
, which is a
similar software product to dracut
(which is used in Red Hat based
distributions), and is mainly used by Debian GNU/Linux and derivatives.
These scripts share some common functionality with the SysV init scripts,
primarily the /etc/zfs/zfs-functions
script.
Configuration
Root pool/filesystem
Different distributions have their own standard on what to specify on the kernel command line to boot off a ZFS filesystem.
This script supports the following kernel command line argument combinations (in this order - first match wins):
rpool=<pool>
bootfs=<pool>/<dataset>
rpool=<pool> bootfs=<pool>/<dataset>
-B zfs-bootfs=<pool>/<fs>
root=<pool>/<dataset>
root=ZFS=<pool>/<dataset>
root=zfs:AUTO
root=zfs:<pool>/<dataset>
rpool=rpool
If a pool is specified, it will be used. Otherwise, in AUTO
mode, all pools
will be searched. Pools may be excluded from the search by listing them in
ZFS_POOL_EXCEPTIONS
in /etc/default/zfs
.
Pools will be imported as follows:
- Try
/dev/disk/by-vdev
if it exists; see/etc/zfs/vdev_id.conf
. - Try
/dev/disk/by-id
and any other/dev/disk/by-*
directories. - Try
/dev
. - Use the cache file if nothing else worked.
This order may be modified by setting ZPOOL_IMPORT_PATH
in
/etc/default/zfs
.
If a dataset is specified, it will be used as the root filesystem. Otherwise, this script will attempt to find a root filesystem automatically (in the specified pool or all pools, as described above).
Filesystems below the root filesystem will be automatically mounted with no
additional configuration necessary. For example, if the root filesystem is
rpool/ROOT/rootfs
, rpool/root/rootfs/var
, rpool/root/rootfs/usr
, etc.
will be mounted (if they exist).
Snapshots
The <dataset>
can be a snapshot. In this case, the snapshot will be cloned
and the clone used as the root filesystem. Note:
- If the snapshot does not exist, the base dataset (the part before
@
) is used as the boot filesystem instead. - If the resulting clone dataset already exists, it is destroyed.
- The clone is created with
mountpoint=none
andcanmount=noauto
. The root filesystem is mounted manually by the initramfs script. - If no snapshot is specified on the
root=
kernel command line, but there is an@
, the user will be prompted to choose a snapshot to use.
Extra options
The following kernel command line arguments are supported:
zfsdebug=(on,yes,1)
: Show extra debugging informationzfsforce=(on,yes,1)
: Force import the poolrollback=(on,yes,1)
: Rollback to (instead of clone) the snapshot
Unlocking a ZFS encrypted root over SSH
To use this feature:
- Install the
dropbear-initramfs
package. You may wish to uninstall thecryptsetup-initramfs
package to avoid warnings. - Add your SSH key(s) to
/etc/dropbear-initramfs/authorized_keys
. Note that Dropbear does not support ed25519 keys; use RSA (2048-bit or more) instead. - Rebuild the initramfs with your keys:
update-initramfs -u
- During the system boot, login via SSH and run:
zfsunlock