dracut/README.dracut.markdown

   1 How to setup a zfs root filesystem using dracut
   2 -----------------------------------------------
   3
   4 1) Install the zfs-dracut package.  This package adds a zfs dracut module
   5 to the /usr/share/dracut/modules.d/ directory which allows dracut to
   6 create an initramfs which is zfs aware.
   7
   8 2) Set the bootfs property for the bootable dataset in the pool.  Then set
   9 the dataset mountpoint property to '/'.
  10
  11     $ zpool set bootfs=pool/dataset pool
  12     $ zfs set mountpoint=/ pool/dataset
  13
  14 Alternately, legacy mountpoints can be used by setting the 'root=' option
  15 on the kernel line of your grub.conf/menu.lst configuration file.  Then
  16 set the dataset mountpoint property to 'legacy'.
  17
  18     $ grub.conf/menu.lst: kernel ... root=ZFS=pool/dataset
  19     $ zfs set mountpoint=legacy pool/dataset
  20
  21 3) To set zfs module options put them in /etc/modprobe.d/zfs.conf file.
  22 The complete list of zfs module options is available by running the
  23 _modinfo zfs_ command.  Commonly set options include: zfs_arc_min,
  24 zfs_arc_max, zfs_prefetch_disable, and zfs_vdev_max_pending.
  25
  26 4) Finally, create your new initramfs by running dracut.
  27
  28     $ dracut --force /path/to/initramfs kernel_version
  29
  30 Kernel Command Line
  31 -------------------
  32
  33 The initramfs' behavior is influenced by the following kernel command line
  34 parameters passed in from the boot loader:
  35
  36 * `root=...`: If not set, importable pools are searched for a bootfs attribute.
  37 If an explicitly set root is desired, you may use `root=ZFS:pool/dataset`
  38
  39 * `zfs_force=0`: If set to 1, the initramfs will run `zpool import -f` when
  40 attempting to import pools if the required pool isn't automatically imported
  41 by the zfs module.  This can save you a trip to a bootcd if hostid has changed,
  42 but is dangerous and can lead to zpool corruption, particularly in cases where
  43 storage is on a shared fabric such as iSCSI where multiple hosts can access
  44 storage devices concurrently.  _Please understand the implications of
  45 force-importing a pool before enabling this option!_
  46
  47 * `spl_hostid`: By default, the hostid used by the SPL module is read from
  48 /etc/hostid inside the initramfs.  This file is placed there from the host
  49 system when the initramfs is built which effectively ties the ramdisk to the
  50 host which builds it.  If a different hostid is desired, one may be set in
  51 this attribute and will override any file present in the ramdisk.  The
  52 format should be hex exactly as found in the `/etc/hostid` file, IE
  53 `spl_hostid=0x00bab10c`.
  54
  55 Note that changing the hostid between boots will most likely lead to an
  56 un-importable pool since the last importing hostid won't match.  In order
  57 to recover from this, you may use the `zfs_force` option or boot from a
  58 different filesystem and `zpool import -f` then `zpool export` the pool
  59 before rebooting with the new hostid.
  60
  61 How it Works
  62 ============
  63
  64 The Dracut module consists of the following files (less Makefile's):
  65
  66 * `module-setup.sh`: Script run by the initramfs builder to create the
  67 ramdisk.  Contains instructions on which files are required by the modules
  68 and z* programs.  Also triggers inclusion of `/etc/hostid` and the zpool
  69 cache.  This file is not included in the initramfs.
  70
  71 * `90-zfs.rules`: udev rules which trigger loading of the ZFS modules at boot.
  72
  73 * `parse-zfs.sh`: Run early in the initramfs boot process to parse kernel
  74 command line and determine if ZFS is the active root filesystem.
  75
  76 * `mount-zfs.sh`: Run later in initramfs boot process after udev has settled
  77 to mount the root dataset.
  78
  79 `module-setup.sh`
  80 ---------------
  81
  82 This file is run by the Dracut script within the live system, not at boot
  83 time.  It's not included in the final initramfs.  Functions in this script
  84 describe which files are needed by ZFS at boot time.
  85
  86 Currently all the various z* and spl modules are included, a dependency is
  87 asserted on udev-rules, and the various zfs, zpool, etc. helpers are included.
  88 Dracut provides library functions which automatically gather the shared libs
  89 necessary to run each of these binaries, so statically built binaries are
  90 not required.
  91
  92 The zpool and zvol udev rules files are copied from where they are
  93 installed by the ZFS build.  __PACKAGERS TAKE NOTE__: If you move
  94 `/etc/udev/rules/60-z*.rules`, you'll need to update this file to match.
  95
  96 Currently this file also includes `/etc/hostid` and `/etc/zfs/zpool.cache`
  97 which means the generated ramdisk is specific to the host system which built
  98 it.  If a generic initramfs is required, it may be preferable to omit these
  99 files and specify the `spl_hostid` from the boot loader instead.
 100
 101 `parse-zfs.sh`
 102 ------------
 103
 104 Run during the cmdline phase of the initramfs boot process, this script
 105 performs some basic sanity checks on kernel command line parameters to
 106 determine if booting from ZFS is likely to be what is desired.  Dracut
 107 requires this script to adjust the `root` variable if required and to set
 108 `rootok=1` if a mountable root filesystem is available.  Unfortunately this
 109 script must run before udev is settled and kernel modules are known to be
 110 loaded, so accessing the zpool and zfs commands is unsafe.
 111
 112 If the root=ZFS... parameter is set on the command line, then it's at least
 113 certain that ZFS is what is desired, though this script is unable to
 114 determine if ZFS is in fact available.  This script will alter the `root`
 115 parameter to replace several historical forms of specifying the pool and
 116 dataset name with the canonical form of `zfs:pool/dataset`.
 117
 118 If no root= parameter is set, the best this script can do is guess that
 119 ZFS is desired.  At present, no other known filesystems will work with no
 120 root= parameter, though this might possibly interfere with using the
 121 compiled-in default root in the kernel image.  It's considered unlikely
 122 that would ever be the case when an initramfs is in use, so this script
 123 sets `root=zfs:AUTO` and hopes for the best.
 124
 125 Once the root=... (or lack thereof) parameter is parsed, a dummy symlink
 126 is created from `/dev/root` -> `/dev/null` to satisfy parts of the Dracut
 127 process which check for presence of a single root device node.
 128
 129 Finally, an initqueue/finished hook is registered which causes the initqueue
 130 phase of Dracut to wait for `/dev/zfs` to become available before attempting
 131 to mount anything.
 132
 133 `mount-zfs.sh`
 134 ------------
 135
 136 This script is run after udev has settled and all tasks in the initqueue
 137 have succeeded.  This ensures that `/dev/zfs` is available and that the
 138 various ZFS modules are successfully loaded.  As it is now safe to call
 139 zpool and friends, we can proceed to find the bootfs attribute if necessary.
 140
 141 If the root parameter was explicitly set on the command line, no parsing is
 142 necessary.  The list of imported pools is checked to see if the desired pool
 143 is already imported.  If it's not, and attempt is made to import the pool
 144 explicitly, though no force is attempted.  Finally the specified dataset
 145 is mounted on `$NEWROOT`, first using the `-o zfsutil` option to handle
 146 non-legacy mounts, then if that fails, without zfsutil to handle legacy
 147 mount points.
 148
 149 If no root parameter was specified, this script attempts to find a pool with
 150 its bootfs attribute set.  First, already-imported pools are scanned and if
 151 an appropriate pool is found, no additional pools are imported.  If no pool
 152 with bootfs is found, any additional pools in the system are imported with
 153 `zpool import -N -a`, and the scan for bootfs is tried again.  If no bootfs
 154 is found with all pools imported, all pools are re-exported, and boot fails.
 155 Assuming a bootfs is found, an attempt is made to mount it to `$NEWROOT`,
 156 first with, then without the zfsutil option as above.
 157
 158 Ordinarily pools are imported _without_ the force option which may cause
 159 boot to fail if the hostid has changed or a pool has been physically moved
 160 between servers.  The `zfs_force` kernel parameter is provided which when
 161 set to `1` causes `zpool import` to be run with the `-f` flag.  Forcing pool
 162 import can lead to serious data corruption and loss of pools, so this option
 163 should be used with extreme caution.  Note that even with this flag set, if
 164 the required zpool was auto-imported by the kernel module, no additional
 165 `zpool import` commands are run, so nothing is forced.