1## Description
2
3These scripts are intended to be used with `initramfs-tools`, which is a
4similar software product to `dracut` (which is used in Red Hat based
5distributions), and is mainly used by Debian GNU/Linux and derivatives.
6
7These scripts share some common functionality with the SysV init scripts,
8primarily the `/etc/zfs/zfs-functions` script.
9
10## Configuration
11
12### Root pool/filesystem
13
14Different distributions have their own standard on what to specify on the
15kernel command line to boot off a ZFS filesystem.
16
17This script supports the following kernel command line argument combinations
18(in this order - first match wins):
19
20* `rpool=<pool>`
21* `bootfs=<pool>/<dataset>`
22* `rpool=<pool> bootfs=<pool>/<dataset>`
23* `-B zfs-bootfs=<pool>/<fs>`
24* `root=<pool>/<dataset>`
25* `root=ZFS=<pool>/<dataset>`
26* `root=zfs:AUTO`
27* `root=zfs:<pool>/<dataset>`
28* `rpool=rpool`
29
30If a pool is specified, it will be used.  Otherwise, in `AUTO` mode, all pools
31will be searched.  Pools may be excluded from the search by listing them in
32`ZFS_POOL_EXCEPTIONS` in `/etc/default/zfs`.
33
34Pools will be imported as follows:
35
36* Try `/dev/disk/by-vdev` if it exists; see `/etc/zfs/vdev_id.conf`.
37* Try `/dev/disk/by-id` and any other `/dev/disk/by-*` directories.
38* Try `/dev`.
39* Use the cache file if nothing else worked.
40
41This order may be modified by setting `ZPOOL_IMPORT_PATH` in
42`/etc/default/zfs`.
43
44If a dataset is specified, it will be used as the root filesystem.  Otherwise,
45this script will attempt to find a root filesystem automatically (in the
46specified pool or all pools, as described above).
47
48Filesystems below the root filesystem will be automatically mounted with no
49additional configuration necessary.  For example, if the root filesystem is
50`rpool/ROOT/rootfs`, `rpool/root/rootfs/var`, `rpool/root/rootfs/usr`, etc.
51will be mounted (if they exist).
52
53### Snapshots
54
55The `<dataset>` can be a snapshot.  In this case, the snapshot will be cloned
56and the clone used as the root filesystem.  Note:
57
58* If the snapshot does not exist, the base dataset (the part before `@`) is
59  used as the boot filesystem instead.
60* If the resulting clone dataset already exists, it is destroyed.
61* The clone is created with `mountpoint=none` and `canmount=noauto`.  The root
62  filesystem is mounted manually by the initramfs script.
63* If no snapshot is specified on the `root=` kernel command line, but
64  there is an `@`, the user will be prompted to choose a snapshot to use.
65
66### Extra options
67
68The following kernel command line arguments are supported:
69
70* `zfsdebug=(on,yes,1)`: Show extra debugging information
71* `zfsforce=(on,yes,1)`: Force import the pool
72* `rollback=(on,yes,1)`: Rollback to (instead of clone) the snapshot
73
74### Unlocking a ZFS encrypted root over SSH
75
76To use this feature:
77
781. Install the `dropbear-initramfs` package.  You may wish to uninstall the
79   `cryptsetup-initramfs` package to avoid warnings.
802. Add your SSH key(s) to `/etc/dropbear-initramfs/authorized_keys`.  Note
81   that Dropbear does not support ed25519 keys before version 2020.79;
82   in that case, use RSA (2048-bit or more) instead.
833. Rebuild the initramfs with your keys: `update-initramfs -u`
844. During the system boot, login via SSH and run: `zfsunlock`
85
86### Unlocking a ZFS encrypted root via alternate means
87
88If present, a shell program at `/etc/zfs/initramfs-tools-load-key`
89and files matching `/etc/zfs/initramfs-tools-load-key.d/*`
90will be copied to the initramfs during generation
91and sourced to load the key, if required.
92
93The `$ENCRYPTIONROOT` to load the key for and `$KEYLOCATION` variables are set,
94and all initramfs-tools functions are available;
95use unquoted `$ZPOOL` and `$ZFS` to run `zpool` and `zfs`.
96
97A successful return (and loaded key) stops the search.
98A failure return is non-fatal,
99and loading keys proceeds as normal if no hook succeeds.
100
101A trivial example of a key-loading drop-in that uses the BLAKE2 checksum
102of the file at the `keylocation` as the key follows.
103
104```sh
105key="$(b2sum "${KEYLOCATION#file://}")" || return
106printf '%s\n' "${key%% *}" | $ZFS load-key -L prompt "$ENCRYPTIONROOT"
107```
108