| blob | f31543c3cf6b80d673100b3ebae6fd7c2f140bcf |
1 How to setup a zfs root filesystem using dracut
2 -----------------------------------------------
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.
8 2) Set the bootfs property for the bootable dataset in the pool. Then set
9 the dataset mountpoint property to '/'.
11 $ zpool set bootfs=pool/dataset pool
12 $ zfs set mountpoint=/ pool/dataset
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'.
18 $ grub.conf/menu.lst: kernel ... root=ZFS=pool/dataset
19 $ zfs set mountpoint=legacy pool/dataset
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.
26 4) Finally, create your new initramfs by running dracut.
28 $ dracut --force /path/to/initramfs kernel_version
30 Kernel Command Line
31 -------------------
33 The initramfs' behavior is influenced by the following kernel command line
34 parameters passed in from the boot loader:
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`
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!_
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`.
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.
62 * `bootfs.snapshot`: If listed, enables the zfs-snapshot-bootfs service on a Dracut system. The zfs-snapshot-bootfs service simply runs `zfs snapshot $BOOTFS@%v` after the pool has been imported but before the bootfs is mounted. `$BOOTFS` is substituted with the value of the bootfs setting on the pool. `%v` is substituted with the version string of the kernel currently being booted (e.g. 5.6.6-200.fc31.x86\_64). Failure to create the snapshot (e.g. because one with the same name already exists) will be logged, but will not otherwise interrupt the boot process.
64 It is safe to leave the bootfs.snapshot flag set persistently on your kernel command line so that a new snapshot of your bootfs will be created on every kernel update. If you leave bootfs.snapshot set persistently on your kernel command line, you may find the below script helpful for automatically removing old snapshots of the bootfs along with their associated kernel.
66 #!/usr/bin/sh
68 if [[ "$1" == "remove" ]] && grep -q "\bbootfs.snapshot\b" /proc/cmdline; then
69 zfs destroy $(findmnt -n -o source /)@$2 &> /dev/null
70 fi
72 exit 0
74 To use the above script place it in a plain text file named /etc/kernel/install.d/99-zfs-cleanup.install and mark it executable with the following command:
76 $ chmod +x /etc/kernel/install.d/99-zfs-cleanup.install
78 On Red Hat based systems, you can change the value of `installonly_limit` in /etc/dnf/dnf.conf to adjust the number of kernels and their associated snapshots that are kept.
80 * `bootfs.snapshot=<snapname>`: Is identical to the bootfs.snapshot parameter explained above except that the value substituted for \<snapname\> will be used when creating the snapshot instead of the version string of the kernel currently being booted.
82 * `bootfs.rollback`: If listed, enables the zfs-rollback-bootfs service on a Dracut system. The zfs-rollback-bootfs service simply runs `zfs rollback -Rf $BOOTFS@%v` after the pool has been imported but before the bootfs is mounted. If the rollback operation fails, the boot process will be interrupted with a Dracut rescue shell. __Use this parameter with caution. Intermediate snapshots of the bootfs will be destroyed!__ TIP: Keep your user data (e.g. /home) on separate file systems (it can be in the same pool though).
84 * `bootfs.rollback=<snapname>`: Is identical to the bootfs.rollback parameter explained above except that the value substituted for \<snapname\> will be used when rolling back the bootfs instead of the version string of the kernel currently being booted. If you use this form, choose a snapshot that is new enough to contain the needed kernel modules under /lib/modules or use a kernel that has all the needed modules built-in.
86 How it Works
87 ============
89 The Dracut module consists of the following files (less Makefile's):
91 * `module-setup.sh`: Script run by the initramfs builder to create the
92 ramdisk. Contains instructions on which files are required by the modules
93 and z* programs. Also triggers inclusion of `/etc/hostid` and the zpool
94 cache. This file is not included in the initramfs.
96 * `90-zfs.rules`: udev rules which trigger loading of the ZFS modules at boot.
98 * `zfs-lib.sh`: Utility functions used by the other files.
100 * `parse-zfs.sh`: Run early in the initramfs boot process to parse kernel
101 command line and determine if ZFS is the active root filesystem.
103 * `mount-zfs.sh`: Run later in initramfs boot process after udev has settled
104 to mount the root dataset.
106 * `export-zfs.sh`: Run on shutdown after dracut has restored the initramfs
107 and pivoted to it, allowing for a clean unmount and export of the ZFS root.
109 `zfs-lib.sh`
110 ------------
112 This file provides a few handy functions for working with ZFS. Those
113 functions are used by the `mount-zfs.sh` and `export-zfs.sh` files.
114 However, they could be used by any other file as well, as long as the file
115 sources `/lib/dracut-zfs-lib.sh`.
117 `module-setup.sh`
118 -----------------
120 This file is run by the Dracut script within the live system, not at boot
121 time. It's not included in the final initramfs. Functions in this script
122 describe which files are needed by ZFS at boot time.
124 Currently all the various z* and spl modules are included, a dependency is
125 asserted on udev-rules, and the various zfs, zpool, etc. helpers are included.
126 Dracut provides library functions which automatically gather the shared libs
127 necessary to run each of these binaries, so statically built binaries are
128 not required.
130 The zpool and zvol udev rules files are copied from where they are
131 installed by the ZFS build. __PACKAGERS TAKE NOTE__: If you move
132 `/etc/udev/rules/60-z*.rules`, you'll need to update this file to match.
134 Currently this file also includes `/etc/hostid` and `/etc/zfs/zpool.cache`
135 which means the generated ramdisk is specific to the host system which built
136 it. If a generic initramfs is required, it may be preferable to omit these
137 files and specify the `spl_hostid` from the boot loader instead.
139 `parse-zfs.sh`
140 --------------
142 Run during the cmdline phase of the initramfs boot process, this script
143 performs some basic sanity checks on kernel command line parameters to
144 determine if booting from ZFS is likely to be what is desired. Dracut
145 requires this script to adjust the `root` variable if required and to set
146 `rootok=1` if a mountable root filesystem is available. Unfortunately this
147 script must run before udev is settled and kernel modules are known to be
148 loaded, so accessing the zpool and zfs commands is unsafe.
150 If the root=ZFS... parameter is set on the command line, then it's at least
151 certain that ZFS is what is desired, though this script is unable to
152 determine if ZFS is in fact available. This script will alter the `root`
153 parameter to replace several historical forms of specifying the pool and
154 dataset name with the canonical form of `zfs:pool/dataset`.
156 If no root= parameter is set, the best this script can do is guess that
157 ZFS is desired. At present, no other known filesystems will work with no
158 root= parameter, though this might possibly interfere with using the
159 compiled-in default root in the kernel image. It's considered unlikely
160 that would ever be the case when an initramfs is in use, so this script
161 sets `root=zfs:AUTO` and hopes for the best.
163 Once the root=... (or lack thereof) parameter is parsed, a dummy symlink
164 is created from `/dev/root` -> `/dev/null` to satisfy parts of the Dracut
165 process which check for presence of a single root device node.
167 Finally, an initqueue/finished hook is registered which causes the initqueue
168 phase of Dracut to wait for `/dev/zfs` to become available before attempting
169 to mount anything.
171 `mount-zfs.sh`
172 --------------
174 This script is run after udev has settled and all tasks in the initqueue
175 have succeeded. This ensures that `/dev/zfs` is available and that the
176 various ZFS modules are successfully loaded. As it is now safe to call
177 zpool and friends, we can proceed to find the bootfs attribute if necessary.
179 If the root parameter was explicitly set on the command line, no parsing is
180 necessary. The list of imported pools is checked to see if the desired pool
181 is already imported. If it's not, and attempt is made to import the pool
182 explicitly, though no force is attempted. Finally the specified dataset
183 is mounted on `$NEWROOT`, first using the `-o zfsutil` option to handle
184 non-legacy mounts, then if that fails, without zfsutil to handle legacy
185 mount points.
187 If no root parameter was specified, this script attempts to find a pool with
188 its bootfs attribute set. First, already-imported pools are scanned and if
189 an appropriate pool is found, no additional pools are imported. If no pool
190 with bootfs is found, any additional pools in the system are imported with
191 `zpool import -N -a`, and the scan for bootfs is tried again. If no bootfs
192 is found with all pools imported, all pools are re-exported, and boot fails.
193 Assuming a bootfs is found, an attempt is made to mount it to `$NEWROOT`,
194 first with, then without the zfsutil option as above.
196 Ordinarily pools are imported _without_ the force option which may cause
197 boot to fail if the hostid has changed or a pool has been physically moved
198 between servers. The `zfs_force` kernel parameter is provided which when
199 set to `1` causes `zpool import` to be run with the `-f` flag. Forcing pool
200 import can lead to serious data corruption and loss of pools, so this option
201 should be used with extreme caution. Note that even with this flag set, if
202 the required zpool was auto-imported by the kernel module, no additional
203 `zpool import` commands are run, so nothing is forced.
205 `export-zfs.sh`
206 ---------------
208 Normally the zpool containing the root dataset cannot be exported on
209 shutdown as it is still in use by the init process. To work around this,
210 Dracut is able to restore the initramfs on shutdown and pivot to it.
211 All remaining process are then running from a ramdisk, allowing for a
212 clean unmount and export of the ZFS root. The theory of operation is
213 described in detail in the [Dracut manual](https://www.kernel.org/pub/linux/utils/boot/dracut/dracut.html#_dracut_on_shutdown).
215 This script will try to export all remaining zpools after Dracut has
216 pivoted to the initramfs. If an initial regular export is not successful,
217 Dracut will call this script once more with the `final` option,
218 in which case a forceful export is attempted.
220 Other Dracut modules include similar shutdown scripts and Dracut
221 invokes these scripts round-robin until they succeed. In particular,
222 the `90dm` module installs a script which tries to close and remove
223 all device mapper targets. Thus, if there are ZVOLs containing
224 dm-crypt volumes or if the zpool itself is backed by a dm-crypt
225 volume, the shutdown scripts will try to untangle this.