1 files changed, 84 insertions, 0 deletions
diff --git a/contrib/initramfs/README.initramfs.markdown b/contrib/initramfs/README.initramfs.markdown
new file mode 100644
index 0000000000000..be3ec71ef7856
--- /dev/null
+++ b/contrib/initramfs/README.initramfs.markdown
@@ -0,0 +1,84 @@
+## 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` 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
+
+### 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`