]>
Commit | Line | Data |
---|---|---|
746d22ee RL |
1 | ## Description |
2 | ||
3 | These scripts are intended to be used with `initramfs-tools`, which is a | |
4 | similar software product to `dracut` (which is used in Red Hat based | |
5 | distributions), and is mainly used by Debian GNU/Linux and derivatives. | |
6 | ||
7 | These scripts share some common functionality with the SysV init scripts, | |
8 | primarily the `/etc/zfs/zfs-functions` script. | |
9 | ||
10 | ## Configuration | |
11 | ||
12 | ### Root pool/filesystem | |
13 | ||
14 | Different distributions have their own standard on what to specify on the | |
15 | kernel command line to boot off a ZFS filesystem. | |
16 | ||
17 | This 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 | ||
30 | If a pool is specified, it will be used. Otherwise, in `AUTO` mode, all pools | |
31 | will be searched. Pools may be excluded from the search by listing them in | |
32 | `ZFS_POOL_EXCEPTIONS` in `/etc/default/zfs`. | |
33 | ||
34 | Pools 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 | ||
41 | This order may be modified by setting `ZPOOL_IMPORT_PATH` in | |
42 | `/etc/default/zfs`. | |
43 | ||
44 | If a dataset is specified, it will be used as the root filesystem. Otherwise, | |
45 | this script will attempt to find a root filesystem automatically (in the | |
46 | specified pool or all pools, as described above). | |
47 | ||
48 | Filesystems below the root filesystem will be automatically mounted with no | |
49 | additional configuration necessary. For example, if the root filesystem is | |
50 | `rpool/ROOT/rootfs`, `rpool/root/rootfs/var`, `rpool/root/rootfs/usr`, etc. | |
a5b1b60e | 51 | will be mounted (if they exist). |
746d22ee RL |
52 | |
53 | ### Snapshots | |
54 | ||
55 | The `<dataset>` can be a snapshot. In this case, the snapshot will be cloned | |
56 | and 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 | ||
68 | The 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 | |
1cc635a2 AP |
73 | |
74 | ### Unlocking a ZFS encrypted root over SSH | |
75 | ||
76 | To use this feature: | |
77 | ||
78 | 1. Install the `dropbear-initramfs` package. You may wish to uninstall the | |
79 | `cryptsetup-initramfs` package to avoid warnings. | |
80 | 2. Add your SSH key(s) to `/etc/dropbear-initramfs/authorized_keys`. Note | |
6e015933 | 81 | that Dropbear does not support ed25519 keys before version 2020.79; |
4b87c198 | 82 | in that case, use RSA (2048-bit or more) instead. |
1cc635a2 AP |
83 | 3. Rebuild the initramfs with your keys: `update-initramfs -u` |
84 | 4. During the system boot, login via SSH and run: `zfsunlock` | |
6e015933 AZ |
85 | |
86 | ### Unlocking a ZFS encrypted root via alternate means | |
87 | ||
88 | If present, a shell program at `/etc/zfs/initramfs-tools-load-key` | |
89 | and files matching `/etc/zfs/initramfs-tools-load-key.d/*` | |
90 | will be copied to the initramfs during generation | |
91 | and sourced to load the key, if required. | |
92 | ||
93 | The `$ENCRYPTIONROOT` to load the key for and `$KEYLOCATION` variables are set, | |
94 | and all initramfs-tools functions are available; | |
95 | use unquoted `$ZPOOL` and `$ZFS` to run `zpool` and `zfs`. | |
96 | ||
97 | A successful return (and loaded key) stops the search. | |
98 | A failure return is non-fatal, | |
99 | and loading keys proceeds as normal if no hook succeeds. | |
100 | ||
101 | A trivial example of a key-loading drop-in that uses the BLAKE2 checksum | |
102 | of the file at the `keylocation` as the key follows. | |
103 | ||
104 | ```sh | |
105 | key="$(b2sum "${KEYLOCATION#file://}")" || return | |
106 | printf '%s\n' "${key%% *}" | $ZFS load-key -L prompt "$ENCRYPTIONROOT" | |
107 | ``` |