contrib/initramfs/README.initramfs.markdown

   1 DESCRIPTION
   2   These scripts is intended to be used with initramfs-tools, which is a similar
   3   software product to "dracut" (which is more used in RedHat based distributions,
   4   and is mainly used by Debian GNU/Linux and derivates to create a initramfs so
   5   that the system can be booted of a ZFS filesystem. If you have no need or
   6   interest for this, then it can safely be ignored.
   7
   8   These script were written with the primary intention of being portable and
   9   usable on as many systems as possible.
  10
  11   This is, in practice, usually not possible. But the intention is there.
  12   And it is a good one.
  13
  14   They have been tested successfully on:
  15
  16     * Debian GNU/Linux Wheezy
  17     * Debian GNU/Linux Jessie
  18
  19   It uses some functionality common with the SYSV init scripts, primarily
  20   the "/etc/zfs/zfs-functions" script.
  21
  22 FUNCTIONALITY
  23   * Supports booting of a ZFS snapshot.
  24     Do this by cloning the snapshot into a dataset. If this, the resulting
  25     dataset, already exists, destroy it. Then mount it as the root filesystem.
  26     * If snapshot does not exist, use base dataset (the part before '@')
  27       as boot filesystem instead.
  28     * Clone with 'mountpoint=none' and 'canmount=noauto' - we mount manually
  29       and explicitly.
  30     * Allow rollback of snapshots instead of clone it and boot from the clone.
  31     * If no snapshot is specified on the 'root=' kernel command line, but
  32       there is an '@', then get a list of snapshots below that filesystem
  33       and ask the user which to use.
  34
  35   * Support all currently used kernel command line arguments
  36     * Core options:
  37       All the different distributions have their own standard on what to specify
  38       on the kernel command line to boot of a ZFS filesystem.
  39
  40       Supports the following kernel command line argument combinations
  41       (in this order - first match win):
  42       * rpool=<pool>                    (tries to finds bootfs automatically)
  43       * bootfs=<pool>/<dataset>         (uses this for rpool - first part)
  44       * rpool=<pool> bootfs=<pool>/<dataset>
  45       * -B zfs-bootfs=<pool>/<fs>       (uses this for rpool - first part)
  46       * rpool=rpool                     (default if none of the above is used)
  47       * root=<pool>/<dataset>           (uses this for rpool - first part)
  48       * root=ZFS=<pool>/<dataset>       (uses this for rpool - first part, without 'ZFS=')
  49       * root=zfs:AUTO                   (tries to detect both pool and rootfs
  50       * root=zfs:<pool>/<dataset>       (uses this for rpool - first part, without 'zfs:')
  51
  52       Option <dataset> could also be <snapshot>
  53     * Extra (control) options:
  54       * zfsdebug=(on,yes,1)   Show extra debugging information
  55       * zfsforce=(on,yes,1)   Force import the pool
  56       * rollback=(on,yes,1)   Rollback (instead of clone) the snapshot
  57
  58   * 'Smarter' way to import pools. Don't just try cache file or /dev.
  59     * Try to use /dev/disk/by-vdev (if /etc/zfs/vdev_id.conf exists),
  60     * Try /dev/mapper (to be able to use LUKS backed pools as well as
  61       multi-path devices).
  62     * /dev/disk/by-id and any other /dev/disk/by-* directory that may exist.
  63     * Use /dev as a last ditch attempt.
  64     * Fallback to using the cache file if that exist if nothing else worked.
  65     * Only try to import pool if it haven't already been imported
  66       * This will negate the need to force import a pool that have not been
  67         exported cleanly.
  68       * Support exclusion of pools to import by setting ZFS_POOL_EXCEPTIONS
  69          in /etc/default/zfs.
  70
  71     Controlling in which order devices is searched for is controlled by
  72     ZPOOL_IMPORT_PATH variable set in /etc/defaults/zfs.
  73
  74   * Support additional configuration variable ZFS_INITRD_ADDITIONAL_DATASETS
  75     to mount additional filesystems not located under your root dataset.
  76
  77     For example, if the root fs is specified as 'rpool/ROOT/rootfs', it will
  78     automatically and without specific configuration mount any filesystems
  79     below this on the mount point specified in the 'mountpoint' property.
  80     Such as 'rpool/root/rootfs/var', 'rpool/root/rootfs/usr' etc)
  81
  82     However, if one prefer to have separate filesystems, not located below
  83     the root fs (such as 'rpool/var', 'rpool/ROOT/opt' etc), special
  84     configuration needs to be done. This is what the variable, set in
  85     /etc/defaults/zfs file, needs to be configured. The 'mountpoint'
  86     property needs to be correct for this to work though.
  87
  88   * Allows mounting a rootfs with mountpoint=legacy set.
  89
  90   * Include /etc/modprobe.d/{zfs,spl}.conf in the initrd if it/they exist.
  91
  92   * Include the udev rule to use by-vdev for pool imports.
  93
  94   * Include the /etc/default/zfs file to the initrd.