2020-05-02 23:16:46 +00:00
|
|
|
## 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.
|
2020-08-22 18:04:49 +00:00
|
|
|
will be mounted (if they exist).
|
2020-05-02 23:16:46 +00:00
|
|
|
|
|
|
|
|
### 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` and `canmount=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 information
|
|
|
|
|
* `zfsforce=(on,yes,1)`: Force import the pool
|
|
|
|
|
* `rollback=(on,yes,1)`: Rollback to (instead of clone) the snapshot
|
2020-05-03 05:43:42 +00:00
|
|
|
|
|
|
|
|
### Unlocking a ZFS encrypted root over SSH
|
|
|
|
|
|
|
|
|
|
To use this feature:
|
|
|
|
|
|
|
|
|
|
1. Install the `dropbear-initramfs` package. You may wish to uninstall the
|
|
|
|
|
`cryptsetup-initramfs` package to avoid warnings.
|
|
|
|
|
2. 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.
|
|
|
|
|
3. Rebuild the initramfs with your keys: `update-initramfs -u`
|
|
|
|
|
4. During the system boot, login via SSH and run: `zfsunlock`
|
