contrib/initramfs/README.md

   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.
  51 will be mounted (if they exist).
  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
  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
  81    that Dropbear does not support ed25519 keys before version 2020.79;
  82    in that case, use RSA (2048-bit or more) instead.
  83 3. Rebuild the initramfs with your keys: `update-initramfs -u`
  84 4. During the system boot, login via SSH and run: `zfsunlock`
  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 ```