contrib/dracut/README.md

   1 ## Basic setup
   2 1. Install `zfs-dracut`
   3 2. Set `mountpoint=/` for your root dataset (for compatibility, `legacy` also works, but is not recommended for new installations):
   4     ```sh
   5     zfs set mountpoint=/ pool/dataset
   6     ```
   7 3. Either (a) set `bootfs=` on the pool to the dataset:
   8     ```sh
   9     zpool set bootfs=pool/dataset pool
  10     ```
  11 4. Or (b) append `root=zfs:pool/dataset` to your kernel cmdline.
  12 5. Re-generate your initrd and update it in your boot bundle
  13
  14 Encrypted datasets have keys loaded automatically or prompted for.
  15
  16 If the root dataset contains children with `mountpoint=`s of `/etc`, `/bin`, `/lib*`, or `/usr`, they're mounted too.
  17
  18 For complete documentation, see `dracut.zfs(7)`.
  19
  20 ## cmdline
  21 1. `root=`                    | Root dataset is…                                         |
  22    ---------------------------|----------------------------------------------------------|
  23    *(empty)*                  | the first `bootfs=` after `zpool import -aN`             |
  24    `zfs:AUTO`, `zfs:`, `zfs`  | *(as above, but overriding other autoselection methods)* |
  25    `ZFS=pool/dataset`         | `pool/dataset`                                           |
  26    `zfs:pool/dataset`         | *(as above)*                                             |
  27
  28    All `+`es are replaced with spaces (i.e. to boot from `root pool/data set`, pass `root=zfs:root+pool/data+set`).
  29
  30    The dataset can be at any depth, including being the pool's root dataset (i.e. `root=zfs:pool`).
  31
  32    `rootfstype=zfs` is equivalent to `root=zfs:AUTO`, `rootfstype=zfs root=pool/dataset` is equivalent to `root=zfs:pool/dataset`.
  33
  34 2. `spl_hostid`: passed to `zgenhostid -f`, useful to override the `/etc/hostid` file baked into the initrd.
  35
  36 3. `bootfs.snapshot`, `bootfs.snapshot=snapshot-name`: enables `zfs-snapshot-bootfs.service`,
  37    which creates a snapshot `$root_dataset@$(uname -r)` (or, in the second form, `$root_dataset@snapshot-name`)
  38    after pool import but before the rootfs is mounted.
  39    Failure to create the snapshot is noted, but booting continues.
  40
  41 4. `bootfs.rollback`, `bootfs.rollback=snapshot-name`: enables `zfs-rollback-bootfs.service`,
  42    which `-Rf` rolls back to `$root_dataset@$(uname -r)` (or, in the second form, `$root_dataset@snapshot-name`)
  43    after pool import but before the rootfs is mounted.
  44    Failure to roll back will fall down to the rescue shell.
  45    This has obvious potential for data loss: make sure your persistent data is not below the rootfs and you don't care about any intermediate snapshots.
  46
  47 5. If both `bootfs.snapshot` and `bootfs.rollback` are set, `bootfs.rollback` is ordered *after* `bootfs.snapshot`.
  48
  49 6. `zfs_force`, `zfs.force`, `zfsforce`: add `-f` to all `zpool import` invocations.
  50    May be useful. Use with caution.