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