]>
Commit | Line | Data |
---|---|---|
888d53f2 HH |
1 | dracut |
2 | ====== | |
3 | Harald Hoyer <harald@redhat.com> | |
4 | v2.0, March 2011 | |
5 | ||
6 | :language: bash | |
7 | ||
8 | = Introduction | |
9 | This section is a modified version of | |
10 | http://en.wikipedia.org/wiki/Initrd which is licensed under the | |
11 | Creative Commons Attribution/Share-Alike License. | |
12 | ||
13 | == Definition | |
14 | An _initial ramdisk_ is a temporary file system used in the boot process of the | |
15 | Linux kernel. _initrd_ and _initramfs_ refer to slightly different schemes for | |
16 | loading this file system into memory. Both are commonly used to make | |
17 | preparations before the real root file system can be mounted. | |
18 | ||
19 | == Rationale | |
20 | Many Linux distributions ship a single, generic kernel image that is intended to | |
21 | boot as wide a variety of hardware as possible. The device drivers for this | |
22 | generic kernel image are included as loadable modules, as it is not possible to | |
23 | statically compile them all into the one kernel without making it too large to | |
24 | boot from computers with limited memory or from lower-capacity media like floppy | |
25 | disks. | |
26 | ||
27 | This then raises the problem of detecting and loading the modules necessary to | |
28 | mount the root file system at boot time (or, for that matter, deducing where or | |
29 | what the root file system is). | |
30 | ||
31 | To further complicate matters, the root file system may be on a software RAID | |
32 | volume, LVM, NFS (on diskless workstations), or on an encrypted partition. All | |
33 | of these require special preparations to mount. | |
34 | ||
35 | Another complication is kernel support for hibernation, which suspends the | |
36 | computer to disk by dumping an image of the entire system to a swap partition or | |
37 | a regular file, then powering off. On next boot, this image has to be made | |
38 | accessible before it can be loaded back into memory. | |
39 | ||
40 | To avoid having to hardcode handling for so many special cases into the kernel, | |
41 | an initial boot stage with a temporary root file system | |
42 | —now dubbed early user space— is used. This root file system would contain | |
43 | user-space helpers that would do the hardware detection, module loading and | |
44 | device discovery necessary to get the real root file system mounted. | |
45 | ||
46 | == Implementation | |
47 | An image of this initial root file system (along with the kernel image) must be | |
48 | stored somewhere accessible by the Linux bootloader or the boot firmware of the | |
49 | computer. This can be: | |
50 | ||
51 | * The root file system itself | |
52 | * A boot image on an optical disc | |
53 | * A small ext2/ext3 or FAT-formatted partition on a local disk | |
54 | (a _boot partition_) | |
55 | * A TFTP server (on systems that can boot from Ethernet) | |
56 | ||
57 | The bootloader will load the kernel and initial root file system image into | |
58 | memory and then start the kernel, passing in the memory address of the image. | |
59 | ||
60 | Depending on which algorithms were compiled statically into it, the kernel can | |
61 | currently unpack initrd/initramfs images compressed with gzip, bzip2 and LZMA. | |
62 | ||
63 | == Mount preparations | |
64 | dracut can generate a customized initrams image which contains only whatever is | |
65 | necessary to boot some particular computer, such as ATA, SCSI and filesystem | |
66 | kernel modules (host-only mode). | |
67 | ||
68 | dracut can also generate a more generic initramfs image (default mode). | |
69 | ||
70 | dracut's initramfs starts only with the device name of the root file system (or | |
71 | its UUID) and must discover everything else at boot time. A complex cascade of | |
72 | tasks must be performed to get the root file system mounted: | |
73 | ||
74 | * Any hardware drivers that the boot process depends on must be loaded. All | |
75 | kernel modules for common storage devices are packed onto the initramfs and then | |
76 | udev pulls in modules matching the computer's detected hardware. | |
77 | ||
78 | * On systems which display a boot rd.splash screen, the video hardware must be | |
79 | initialized and a user-space helper started to paint animations onto the display | |
80 | in lockstep with the boot process. | |
81 | ||
1d22c670 | 82 | * If the root file system is on NFS, dracut does then: |
888d53f2 HH |
83 | ** Bring up the primary network interface. |
84 | ** Invoke a DHCP client, with which it can obtain a DHCP lease. | |
85 | ** Extract the name of the NFS share and the address of the NFS server from the | |
86 | lease. | |
87 | ** Mount the NFS share. | |
88 | ||
89 | * If the root file system appears to be on a software RAID device, there is no | |
90 | way of knowing which devices the RAID volume spans; the standard MD utilities | |
91 | must be invoked to scan all available block devices with a raid signature and | |
92 | bring the required ones online. | |
93 | ||
94 | * If the root file system appears to be on a logical volume, the LVM utilities | |
95 | must be invoked to scan for and activate the volume group containing it. | |
96 | ||
97 | * If the root file system is on an encrypted block device: | |
98 | ** Invoke a helper script to prompt the user to type in a passphrase and/or | |
99 | insert a hardware token (such as a smart card or a USB security dongle). | |
100 | ||
101 | * Create a decryption target with the device mapper. | |
102 | ||
103 | dracut uses udev, an event-driven hotplug agent, which invokes helper programs | |
104 | as hardware devices, disk partitions and storage volumes matching certain rules | |
105 | come online. This allows discovery to run in parallel, and to progressively | |
106 | cascade into arbitrary nestings of LVM, RAID or encryption to get at the root | |
107 | file system. | |
108 | ||
109 | When the root file system finally becomes visible: | |
110 | ||
111 | * Any maintenance tasks which cannot run on a mounted root file system | |
112 | are done. | |
113 | * The root file system is mounted read-only. | |
114 | * Any processes which must continue running (such as the rd.splash screen helper | |
115 | and its command FIFO) are hoisted into the newly-mounted root file system. | |
116 | ||
117 | The final root file system cannot simply be mounted over /, since that would | |
118 | make the scripts and tools on the initial root file system inaccessible for any | |
119 | final cleanup tasks. On an initramfs, the initial root file system cannot be | |
120 | rotated away. Instead, it is simply emptied and the final root file system | |
121 | mounted over the top. | |
122 | ||
a1ebd771 HH |
123 | If the systemd module is used in the initramfs, the ordering of the services |
124 | started looks like <<dracutbootup7>>. | |
125 | ||
1d22c670 HH |
126 | == Dracut on shutdown |
127 | ||
128 | On a systemd driven system, the dracut initramfs is also used for the shutdown procedure. | |
129 | ||
130 | The following steps are executed during a shutdown: | |
131 | ||
132 | * systemd switches to the shutdown.target | |
133 | * systemd starts /lib/systemd/system/shutdown.target.wants/dracut-shutdown.service | |
134 | * dracut-shutdown.service executes /usr/lib/dracut/dracut-initramfs-restore | |
135 | which unpacks the initramfs to /run/initramfs | |
136 | * systemd finishes shutdown.target | |
137 | * systemd kills all processes | |
138 | * systemd tries to unmount everything and mounts the remaining read-only | |
139 | * systemd checks, if there is a /run/initramfs/shutdown executable | |
140 | * if yes, it does a pivot_root to /run/initramfs and executes ./shutdown. | |
141 | The old root is then mounted on /oldroot. /usr/lib/dracut/modules.d/99shutdown/shutdown.sh is the shutdown executable. | |
142 | * shutdown will try to umount every /oldroot mount and calls the various shutdown hooks from the dracut modules | |
143 | ||
144 | This ensures, that all devices are disassembled and unmounted cleanly. | |
145 | ||
888d53f2 HH |
146 | = User Manual |
147 | ||
148 | == Creating an initramfs Image | |
149 | To create a initramfs image, the most simple command is: | |
150 | ---- | |
151 | # dracut | |
152 | ---- | |
153 | ||
154 | This will generate a general purpose initramfs image, with all possible | |
155 | functionality resulting of the combination of the installed dracut modules and | |
156 | system tools. The image is /boot/initramfs-_++<kernel version>++_.img and | |
157 | contains the kernel modules of the currently active kernel with version | |
158 | _++<kernel version>++_. | |
159 | ||
160 | If the initramfs image already exists, dracut will display an error message, and | |
161 | to overwrite the existing image, you have to use the --force option. | |
162 | ---- | |
163 | # dracut --force | |
164 | ---- | |
165 | ||
166 | If you want to specify another filename for the resulting image you would issue | |
167 | a command like: | |
168 | ---- | |
169 | # dracut foobar.img | |
170 | ---- | |
171 | ||
172 | To generate an image for a specific kernel version, the command would be: | |
173 | ---- | |
174 | # dracut foobar.img 2.6.40-1.rc5.f20 | |
175 | ---- | |
176 | ||
177 | A shortcut to generate the image at the default location for a specific kernel | |
178 | version is: | |
179 | ---- | |
e65caf36 | 180 | # dracut --kver 2.6.40-1.rc5.f20 |
888d53f2 HH |
181 | ---- |
182 | ||
183 | If you want to create lighter, smaller initramfs images, you may want to specify | |
184 | the --host-only or -H option. Using this option, the resulting image will | |
185 | contain only those dracut modules, kernel modules and filesystems, which are | |
186 | needed to boot this specific machine. This has the drawback, that you can't put | |
187 | the disk on another controller or machine, and that you can't switch to another | |
188 | root filesystem, without recreating the initramfs image. The usage of the | |
189 | --host-only option is only for experts and you will have to keep the broken | |
190 | pieces. At least keep a copy of a general purpose image (and corresponding | |
191 | kernel) as a fallback to rescue your system. | |
192 | ||
193 | === Inspecting the Contents | |
194 | To see the contents of the image created by dracut, you can use the lsinitrd tool. | |
195 | ---- | |
196 | # lsinitrd /boot/initramfs-$(uname -r).img | less | |
197 | ---- | |
198 | ||
199 | To display the contents of a file in the initramfs also use the lsinitrd tool: | |
200 | ---- | |
201 | # lsinitrd /boot/initramfs-$(uname -r).img /etc/ld.so.conf | |
202 | include ld.so.conf.d/*.conf | |
203 | ---- | |
204 | ||
205 | === Adding dracut Modules | |
206 | Some dracut modules are turned off by default and have to be activated manually. | |
207 | You can do this by adding the dracut modules to the configuration file | |
208 | _/etc/dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_. See <<dracutconf5>>. | |
209 | You can also add dracut modules on the command line | |
210 | by using the -a or --add option: | |
211 | ---- | |
212 | # dracut --add bootchart initramfs-bootchart.img | |
213 | ---- | |
214 | ||
215 | To see a list of available dracut modules, use the --list-modules option: | |
216 | ---- | |
217 | # dracut --list-modules | |
218 | ---- | |
219 | ||
220 | or, if you have a dracut version earlier than +008+, issue the command: | |
221 | ---- | |
222 | # for mod in /usr/lib/dracut/modules.d/*; do echo ${mod##*/??}; done | |
223 | ---- | |
224 | ||
225 | === Omitting dracut Modules | |
226 | Sometimes you don't want a dracut module to be included for reasons of speed, | |
227 | size or functionality. To do this, either specify the omit_dracutmodules | |
228 | variable in the _dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_ configuration | |
229 | file (see <<dracutconf5>>), or use the -o or --omit option | |
230 | on the command line: | |
231 | ---- | |
232 | # dracut -o "multipath lvm" no-multipath-lvm.img | |
233 | ---- | |
234 | ||
235 | === Adding Kernel Modules | |
236 | If you need a special kernel module in the initramfs, which is not | |
237 | automatically picked up by dracut, you have the use the --add-drivers option | |
238 | on the command line or the drivers vaiable in the _/etc/dracut.conf_ | |
239 | or _/etc/dracut.conf.d/myconf.conf_ configuration file (see <<dracutconf5>>): | |
240 | ---- | |
241 | # dracut --add-drivers mymod initramfs-with-mymod.img | |
242 | ---- | |
243 | ||
244 | == Boot parameters | |
245 | The generated initramfs.img file normally does not contain any system | |
246 | configuration files (except for some special exceptions), so the configuration | |
247 | has to be done on the kernel command line. With this flexibility, you can easily | |
248 | boot from a changed root partition, without the need to recompile the initramfs | |
249 | image. So, you could completly change your root partition (move it inside a md | |
250 | raid with encryption and LVM on top), as long as you specify the correct | |
251 | filesystem LABEL or UUID on the kernel command line for your root device, dracut | |
252 | will find it and boot from it. | |
253 | ||
254 | The kernel command line usually can be configured in _/boot/grub/grub.conf_, if | |
255 | grub is your bootloader and it also can be edited in the real boot process in | |
256 | the grub menu. | |
257 | ||
258 | The kernel command line can also be provided by the dhcp server with the | |
259 | root-path option. See <<NetworkBoot>>. | |
260 | ||
261 | For a full reference of all kernel command line parameters, see <<dracut8>>. | |
262 | ||
263 | === Specifying the root Device | |
264 | This is the only option dracut really needs to boot from your root partition. | |
265 | Because your root partition can live in various environments, there are a lot of | |
266 | formats for the root= option. The most basic one is root=_++<path to device | |
267 | node>++_: | |
268 | ---- | |
269 | root=/dev/sda2 | |
270 | ---- | |
271 | ||
272 | Because device node names can change, dependent on the drive ordering, you are | |
273 | encouraged to use the filesystem identifier (UUID) or filesystem label (LABEL) | |
274 | to specify your root partition: | |
275 | ---- | |
276 | root=UUID=19e9dda3-5a38-484d-a9b0-fa6b067d0331 | |
277 | ---- | |
278 | ||
279 | or | |
280 | ||
281 | ---- | |
282 | root=LABEL=myrootpartitionlabel | |
283 | ---- | |
284 | ||
285 | To see all UUIDs or LABELs on your system, do: | |
286 | ---- | |
287 | # ls -l /dev/disk/by-uuid | |
288 | ---- | |
289 | ||
290 | or | |
291 | ||
292 | ---- | |
293 | # ls -l /dev/disk/by-label | |
294 | ---- | |
295 | ||
296 | If your root partition is on the network see <<NetworkBoot>>. | |
297 | ||
298 | === Keyboard Settings | |
299 | If you have to input passwords for encrypted disk volumes, you might want to set | |
300 | the keyboard layout and specify a display font. | |
301 | ||
302 | A typical german kernel command would contain: | |
303 | ---- | |
304 | vconsole.font=latarcyrheb-sun16 vconsole.keymap=de-latin1-nodeadkeys locale.LANG=de_DE.UTF-8 | |
305 | ---- | |
306 | ||
307 | Setting these options can override the setting stored on your system, if you use | |
308 | a modern init system, like systemd. | |
309 | ||
310 | For dracut versions prior to version +008+ the line would look like: | |
311 | ---- | |
312 | LANG=de_DE.UTF-8 SYSFONT=latarcyrheb-sun16 KEYBOARDTYPE=pc KEYTABLE=de-latin1-nodeadkeys | |
313 | ---- | |
314 | ||
315 | === Blacklisting Kernel Modules | |
316 | Sometimes it is required to prevent the automatic kernel module loading of a | |
317 | specific kernel module. To do this, just add rd.blacklist=_++<kernel module | |
318 | name>++_, with _++<kernel module name>++_ not containing the _.ko_ | |
319 | suffix, to the kernel command line. For example: | |
320 | ---- | |
321 | rd.driver.blacklist=mptsas rd.driver.blacklist=nouveau | |
322 | ---- | |
323 | ||
324 | The option can be specified multiple times on the kernel command line. | |
325 | ||
326 | === Speeding up the Boot Process | |
327 | If you want to speed up the boot process, you can specify as much information | |
328 | for dracut on the kernel command as possible. For example, you can tell dracut, | |
329 | that you root partition is not on a LVM volume or not on a raid partition, or | |
330 | that it lives inside a specific crypto LUKS encrypted volume. By default, dracut | |
331 | searches everywhere. A typical dracut kernel command line for a plain primary or | |
332 | logical partition would contain: | |
333 | ---- | |
334 | rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 | |
335 | ---- | |
336 | ||
337 | On systems with dracut version prior to +008+ the line would look like: | |
338 | ---- | |
339 | rd_NO_LUKS rd_NO_LVM rd_NO_MD rd_NO_DM | |
340 | ---- | |
341 | ||
342 | This turns off every automatic assembly of LVM, MD raids, DM raids and crypto LUKS. | |
343 | ||
344 | Of course, you could also omit the dracut modules in the initramfs creation | |
345 | process, but then you would lose the posibility to turn it on on demand. | |
346 | ||
347 | ||
348 | [[Injecting]] | |
349 | === Injecting custom Files | |
350 | To add your own files to the initramfs image, you have several possibilities. | |
351 | ||
352 | The --include option let you specify a source path and a target path. For example | |
353 | ---- | |
3cff5fb5 | 354 | # dracut --include cmdline-preset /etc/cmdline.d/mycmdline.conf initramfs-cmdline-pre.img |
888d53f2 HH |
355 | ---- |
356 | will create an initramfs image, where the file cmdline-preset will be copied | |
3cff5fb5 | 357 | inside the initramfs to _/etc/cmdline.d/mycmdline.conf_. --include can only be specified once. |
888d53f2 HH |
358 | |
359 | ||
360 | ---- | |
361 | # mkdir rd.live.overlay | |
362 | # mkdir rd.live.overlay/etc | |
363 | # mkdir rd.live.overlay/etc/conf.d | |
3cff5fb5 HH |
364 | # mkdir rd.live.overlay/etc/cmdline.d |
365 | # echo "ip=auto" >> rd.live.overlay/etc/cmdline.d/mycmdline.conf | |
366 | # echo export FOO=testtest >> rd.live.overlay/etc/conf.d/testvar.conf | |
367 | # echo export BAR=testtest >> rd.live.overlay/etc/conf.d/testvar.conf | |
888d53f2 HH |
368 | # tree rd.live.overlay/ |
369 | rd.live.overlay/ | |
370 | └── etc | |
3cff5fb5 HH |
371 | ├── cmdline.d |
372 | │ └── mycmdline.conf | |
373 | └── conf.d | |
374 | └── testvar.conf | |
375 | ||
888d53f2 HH |
376 | # dracut --include rd.live.overlay / initramfs-rd.live.overlay.img |
377 | ---- | |
378 | ||
379 | This will put the contents of the rd.live.overlay directory into the root of the | |
380 | initramfs image. | |
381 | ||
382 | The --install option let you specify several files, which will get installed in | |
383 | the initramfs image at the same location, as they are present on initramfs | |
384 | creation time. | |
385 | ||
386 | ||
387 | ---- | |
388 | # dracut --install 'strace fsck.ext3 ssh' initramfs-dbg.img | |
389 | ---- | |
390 | ||
391 | This will create an initramfs with the strace, fsck.ext3 and ssh executables, | |
392 | together with the libraries needed to start those. The --install option can be | |
393 | specified multiple times. | |
394 | ||
395 | ||
396 | [[NetworkBoot]] | |
397 | == Network Boot | |
398 | ||
399 | If your root partition is on a network drive, you have to have the network | |
400 | dracut modules installed to create a network aware initramfs image. | |
401 | ||
402 | On a Red Hat Enterprise Linux or Fedora system, this means, you have to install | |
403 | the _dracut-network_ rpm package: | |
404 | ||
405 | ||
406 | ---- | |
407 | # yum install dracut-network | |
408 | ---- | |
409 | ||
410 | The resulting initramfs image can be served by a boot manager residing on your | |
411 | local hard drive or it can be served by a PXE/TFTP server. | |
412 | ||
413 | How to setup your PXE/TFTP server can be found in the | |
414 | http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/[Red | |
415 | Hat Enterprise Linux Storage Administration Guide]. | |
416 | ||
0ae480dc | 417 | If you specify ip=auto on the kernel command line, then dracut asks a dhcp |
888d53f2 HH |
418 | server about the ip adress for the machine. The dhcp server can also serve an |
419 | additional root-path, which will set the root device for dracut. With this | |
420 | mechanism, you have static configuration on your client machine and a | |
421 | centralized boot configuration on your TFTP/DHCP server. If you can't pass a | |
3cff5fb5 | 422 | kernel command line, then you can inject _/etc/cmdline.d/mycmdline.conf_, with a method described |
888d53f2 HH |
423 | in <<Injecting>>. |
424 | ||
425 | ||
426 | ||
427 | ||
428 | === Reducing the Image Size | |
429 | ||
430 | To reduce the size of the initramfs, you should create it with by ommitting all | |
431 | dracut modules, which you know, you don't need to boot the machine. | |
432 | ||
433 | You can also specify the exact dracut and kernel modules to produce a very tiny | |
434 | initramfs image. | |
435 | ||
436 | For example for a NFS image, you would do: | |
437 | ||
438 | ||
439 | ---- | |
440 | # dracut -m "nfs network base" initramfs-nfs-only.img | |
441 | ---- | |
442 | ||
443 | Then you would boot from this image with your target machine and reduce the size | |
444 | once more by creating it on the target machine with the --host-only option: | |
445 | ||
446 | ||
447 | ---- | |
448 | # dracut -m "nfs network base" --host-only initramfs-nfs-host-only.img | |
449 | ---- | |
450 | ||
451 | This will reduce the size of the initramfs image significantly. | |
452 | ||
453 | ||
454 | ||
455 | === NFS Root Device | |
456 | ||
457 | FIXME | |
458 | ||
459 | === iSCSI Root Device | |
460 | ||
461 | FIXME | |
462 | ||
463 | === FCoE Root Device | |
464 | ||
465 | FIXME | |
466 | ||
467 | == Troubleshooting | |
468 | ||
469 | If the boot process does not succeed, you have several options to debug the | |
470 | situation. Some of the basic operations are covered here. For more information | |
471 | you should also visit: | |
472 | http://fedoraproject.org/wiki/How_to_debug_Dracut_problems | |
473 | ||
474 | ||
475 | [[identifying-your-problem-area]] | |
476 | === Identifying your problem area | |
477 | . Remove ''rhgb'' and ''quiet'' from the kernel command line | |
478 | . Add ''rd.shell'' to the kernel command line. This will present a shell should | |
479 | dracut be unable to locate your root device | |
480 | . Add ''rd.shell rd.debug log_buf_len=1M'' to the kernel command line so that | |
481 | dracut shell commands are printed as they are executed | |
482 | . With dracut >= 002-11, you can inspect the rd.debug output with: | |
483 | + | |
484 | ---- | |
485 | # less /run/initramfs/init.log | |
486 | # dmesg | less | |
487 | ---- | |
a844fb15 HH |
488 | . With dracut >= 022 and systemd, you can inspect the rd.debug output with: |
489 | ---- | |
490 | # journalctl -ab | |
491 | ---- | |
c33488fe | 492 | . With dracut >= 025 the file /run/initramfs/rdsosreport.txt is generated, which contains all the logs and the output of all significant tools, which are mentioned later. |
a844fb15 HH |
493 | |
494 | If you want to save that output, simply mount /boot by hand or insert an USB stick and mount that. | |
495 | Then you can store the output for later inspection. | |
888d53f2 HH |
496 | |
497 | [[information-to-include-in-your-report]] | |
498 | === Information to include in your report | |
499 | ||
500 | [[all-bug-reports]] | |
501 | ==== All bug reports | |
502 | In all cases, the following should be mentioned and attached to your bug report: | |
503 | ||
504 | * The exact kernel command-line used. Typically from the bootloader | |
505 | configuration file (e.g. _/etc/grub.conf_) or from _/proc/cmdline_. | |
506 | * A copy of your disk partition information from _/etc/fstab_, which might be | |
507 | obtained booting an old working initramfs or a rescue medium. | |
508 | * A device listing from device-mapper. This can be obtained by running the | |
a844fb15 | 509 | command |
888d53f2 HH |
510 | + |
511 | ---- | |
512 | # dmsetup ls --tree | |
513 | ---- | |
514 | + | |
cce69be6 | 515 | * A list of block device attributes. This can be obtained by running the commands: |
888d53f2 HH |
516 | + |
517 | ---- | |
518 | # blkid -p | |
519 | # blkid -p -o udev | |
520 | ---- | |
521 | * Turn on dracut debugging (see _the 'debugging dracut' section_), and attach | |
522 | all relevant information from the boot log. This can be obtained by running the | |
523 | command | |
524 | + | |
525 | ---- | |
526 | # dmesg|grep dracut | |
527 | ---- | |
528 | + | |
529 | * If you use a dracut configuration file, please include _/etc/dracut.conf_ and | |
530 | all files in _/etc/dracut.conf.d/*.conf_ | |
531 | ||
532 | [[logical-volume-management-related-problems]] | |
533 | ==== Logical Volume Management related problems | |
534 | As well as the information from <<all-bug-reports>> include the following | |
535 | information: | |
536 | ||
a1ebd771 | 537 | * Include physical volume information by running the command: |
888d53f2 HH |
538 | + |
539 | ---- | |
540 | # lvm pvdisplay | |
541 | ---- | |
542 | + | |
a1ebd771 | 543 | * Include volume group information by running the command: |
888d53f2 HH |
544 | + |
545 | ---- | |
546 | # lvm vgdisplay | |
547 | ---- | |
548 | + | |
a1ebd771 | 549 | * Include logical volume information by running the command: |
888d53f2 HH |
550 | + |
551 | ---- | |
552 | # lvm lvdisplay | |
553 | ---- | |
554 | ||
555 | [[software-raid-related-problems]] | |
556 | ==== Software RAID related problems | |
557 | As well as the information from <<all-bug-reports>>, include the following | |
558 | information: | |
559 | ||
a1ebd771 | 560 | * If using software RAID disk partitions, please include the output of |
888d53f2 HH |
561 | + |
562 | ---- | |
563 | # cat /proc/mdstat | |
564 | ---- | |
565 | ||
566 | [[network-root-device-related-problems]] | |
567 | ==== Network root device related problems | |
568 | This section details information to include when experiencing problems on a | |
569 | system whose root device is located on a network attached volume (e.g. iSCSI, | |
570 | NFS or NBD). As well as the information from <<all-bug-reports>>, include the | |
571 | following information: | |
572 | ||
573 | ||
574 | * Please include the output of | |
575 | + | |
576 | ---- | |
577 | # /sbin/ifup <interfacename> | |
578 | # ip addr show | |
579 | ---- | |
580 | ||
581 | [[debugging-dracut]] | |
582 | === Debugging dracut | |
583 | ||
584 | ||
585 | [[configure-a-serial-console]] | |
586 | ==== Configure a serial console | |
587 | ||
588 | Successfully debugging dracut will require some form of console | |
589 | logging during the system boot. This section documents configuring a | |
590 | serial console connection to record boot messages. | |
591 | ||
592 | . First, enable serial console output for both the kernel and the bootloader. | |
593 | . Open the file _/etc/grub.conf_ for editing. Below the line ''timeout=5'', add | |
594 | the following: | |
595 | + | |
596 | ---- | |
597 | serial --unit=0 --speed=9600 | |
598 | terminal --timeout=5 serial console | |
599 | ---- | |
600 | + | |
601 | . Also in _/etc/grub.conf_, add the following boot arguemnts to the ''kernel'' | |
602 | line: | |
603 | + | |
604 | ---- | |
605 | console=tty0 console=ttyS0,9600 | |
606 | ---- | |
607 | + | |
608 | . When finished, the _/etc/grub.conf_ file should look similar to the example | |
609 | below. | |
610 | + | |
611 | ---- | |
612 | default=0 | |
613 | timeout=5 | |
614 | serial --unit=0 --speed=9600 | |
615 | terminal --timeout=5 serial console | |
616 | title Fedora (2.6.29.5-191.fc11.x86_64) | |
617 | root (hd0,0) | |
618 | kernel /vmlinuz-2.6.29.5-191.fc11.x86_64 ro root=/dev/mapper/vg_uc1-lv_root console=tty0 console=ttyS0,9600 | |
619 | initrd /dracut-2.6.29.5-191.fc11.x86_64.img | |
620 | ---- | |
621 | + | |
622 | . More detailed information on how to configure the kernel for console output | |
623 | can be found at | |
624 | http://www.faqs.org/docs/Linux-HOWTO/Remote-Serial-Console-HOWTO.html#CONFIGURE-KERNEL. | |
625 | . Redirecting non-interactive output | |
626 | + | |
627 | -- | |
628 | NOTE: You can redirect all non-interactive output to _/dev/kmsg_ and the kernel | |
629 | will put it out on the console when it reaches the kernel buffer by doing | |
630 | ||
631 | ---- | |
632 | # exec >/dev/kmsg 2>&1 </dev/console | |
633 | ---- | |
634 | -- | |
635 | ||
636 | [[using-the-dracut-shell]] | |
637 | ==== Using the dracut shell | |
638 | ||
600c8769 | 639 | dracut offers a shell for interactive debugging in the event dracut fails to |
888d53f2 HH |
640 | locate your root filesystem. To enable the shell: |
641 | ||
642 | . Add the boot parameter ''rd.shell'' to your bootloader configuration file | |
643 | (e.g. _/etc/grub.conf_) | |
644 | . Remove the boot arguments ''rhgb'' and ''quiet'' | |
645 | + | |
646 | A sample _/etc/grub.conf_ bootloader configuration file is listed below. | |
647 | + | |
648 | ---- | |
649 | default=0 | |
650 | timeout=5 | |
651 | serial --unit=0 --speed=9600 | |
652 | terminal --timeout=5 serial console | |
653 | title Fedora (2.6.29.5-191.fc11.x86_64) | |
654 | root (hd0,0) | |
655 | kernel /vmlinuz-2.6.29.5-191.fc11.x86_64 ro root=/dev/mapper/vg_uc1-lv_root console=tty0 rd.shell | |
656 | initrd /dracut-2.6.29.5-191.fc11.x86_64.img | |
657 | ---- | |
658 | + | |
659 | . If system boot fails, you will be dropped into a shell as seen in the example below. | |
660 | + | |
661 | ---- | |
662 | No root device found | |
663 | Dropping to debug shell. | |
664 | ||
a1ebd771 | 665 | # |
888d53f2 HH |
666 | ---- |
667 | + | |
668 | . Use this shell prompt to gather the information requested above (see <<all-bug-reports>>). | |
669 | ||
670 | [[accessing-the-root-volume-from-the-dracut-shell]] | |
671 | ==== Accessing the root volume from the dracut shell | |
672 | From the dracut debug shell, you can manually perform the task of locating and | |
673 | preparing your root volume for boot. The required steps will depend on how your | |
674 | root volume is configured. Common scenarios include: | |
675 | ||
676 | * A block device (e.g. _/dev/sda7_) | |
677 | * A LVM logical volume (e.g. _/dev/VolGroup00/LogVol00_) | |
678 | * An encrypted device (e.g. _/dev/mapper/luks-4d5972ea-901c-4584-bd75-1da802417d83_) | |
679 | * A network attached device (e.g. netroot=iscsi:@192.168.0.4::3260::iqn.2009-02.org.fedoraproject:for.all) | |
680 | ||
681 | The exact method for locating and preparing will vary. However, to continue with | |
682 | a successful boot, the objective is to locate your root volume and create a | |
683 | symlink _/dev/root_ which points to the file system. For example, the following | |
684 | example demonstrates accessing and booting a root volume that is an encrypted | |
a1ebd771 | 685 | LVM Logical volume. |
888d53f2 HH |
686 | |
687 | . Inspect your partitions using parted | |
688 | + | |
689 | ---- | |
690 | # parted /dev/sda -s p | |
691 | Model: ATA HTS541060G9AT00 (scsi) | |
692 | Disk /dev/sda: 60.0GB | |
693 | Sector size (logical/physical): 512B/512B | |
694 | Partition Table: msdos | |
695 | Number Start End Size Type File system Flags | |
696 | 1 32.3kB 10.8GB 107MB primary ext4 boot | |
697 | 2 10.8GB 55.6GB 44.7GB logical lvm | |
698 | ---- | |
699 | + | |
700 | . You recall that your root volume was a LVM logical volume. Scan and activate | |
a1ebd771 | 701 | any logical volumes. |
888d53f2 HH |
702 | + |
703 | ---- | |
704 | # lvm vgscan | |
705 | # lvm vgchange -ay | |
706 | ---- | |
707 | + | |
708 | . You should see any logical volumes now using the command blkid: | |
709 | + | |
710 | ---- | |
711 | # blkid | |
712 | /dev/sda1: UUID="3de247f3-5de4-4a44-afc5-1fe179750cf7" TYPE="ext4" | |
713 | /dev/sda2: UUID="Ek4dQw-cOtq-5MJu-OGRF-xz5k-O2l8-wdDj0I" TYPE="LVM2_member" | |
714 | /dev/mapper/linux-root: UUID="def0269e-424b-4752-acf3-1077bf96ad2c" TYPE="crypto_LUKS" | |
715 | /dev/mapper/linux-home: UUID="c69127c1-f153-4ea2-b58e-4cbfa9257c5e" TYPE="ext3" | |
716 | /dev/mapper/linux-swap: UUID="47b4d329-975c-4c08-b218-f9c9bf3635f1" TYPE="swap" | |
717 | ---- | |
718 | + | |
719 | . From the output above, you recall that your root volume exists on an encrypted | |
720 | block device. Following the guidance disk encryption guidance from the | |
721 | Installation Guide, you unlock your encrypted root volume. | |
722 | + | |
723 | ---- | |
724 | # UUID=$(cryptsetup luksUUID /dev/mapper/linux-root) | |
725 | # cryptsetup luksOpen /dev/mapper/linux-root luks-$UUID | |
726 | Enter passphrase for /dev/mapper/linux-root: | |
a1ebd771 | 727 | Key slot 0 unlocked. |
888d53f2 HH |
728 | ---- |
729 | + | |
730 | . Next, make a symbolic link to the unlocked root volume | |
731 | + | |
732 | ---- | |
733 | # ln -s /dev/mapper/luks-$UUID /dev/root | |
734 | ---- | |
735 | + | |
736 | . With the root volume available, you may continue booting the system by exiting | |
737 | the dracut shell | |
738 | + | |
739 | ---- | |
740 | # exit | |
741 | ---- | |
742 | ||
743 | [[additional-dracut-boot-parameters]] | |
744 | ==== Additional dracut boot parameters | |
745 | For more debugging options, see <<dracutkerneldebug>> in <<dracutcmdline7>>. | |
746 | ||
747 | = Developer Manual | |
748 | ||
749 | == dracut Components | |
750 | ||
751 | dracut uses a modular system to build and extend the initramfs image. All | |
752 | modules are located in _/usr/lib/dracut/modules.d_ or in _<git-src>/modules.d_. | |
753 | The most basic dracut module is _99base_. In _99base_ the initial shell script | |
754 | init is defined, which gets run by the kernel after initramfs loading. Although | |
755 | you can replace init with your own version of _99base_, this is not encouraged. | |
756 | Instead you should use, if possible, the hooks of dracut. All hooks, and the | |
757 | point of time in which they are executed, are described in <<stages>>. | |
758 | ||
759 | The main script, which creates the initramfs is dracut itsself. It parses all | |
760 | arguments and sets up the directory, in which everything is installed. It then | |
761 | executes all check, install, installkernel scripts found in the modules, which | |
762 | are to be processed. After everything is installed, the install directory is | |
763 | archived and compressed to the final initramfs image. All helper functions used | |
764 | by check, install and installkernel are found in in the file _dracut-functions_. | |
765 | These shell functions are available to all module installer (install, | |
766 | installkernel) scripts, without the need to source _dracut-functions_. | |
767 | ||
768 | A module can check the preconditions for install and installkernel with the | |
769 | check script. Also dependencies can be expressed with check. If a module passed | |
770 | check, install and installkernel will be called to install all of the necessary | |
771 | files for the module. To split between kernel and non-kernel parts of the | |
772 | installation, all kernel module related parts have to be in installkernel. All | |
773 | other files found in a module directory are module specific and mostly are hook | |
774 | scripts and udev rules. | |
775 | ||
776 | ||
777 | [[stages]] | |
778 | == Boot Process Stages | |
779 | ||
780 | The init script in _99base_ is the main script, which prepares the root file | |
781 | system for usage, runs udev, mounts the real root device, kills the remaining | |
782 | processes, and switches to the real root device for further booting. dracut | |
783 | modules can insert custom script at various points, to control the boot process. | |
784 | These hooks are plain directories containing shell scripts ending with ".sh", | |
785 | which are sourced by init. | |
a1ebd771 | 786 | Common used functions are in _dracut-lib.sh_, which can be sourced by any script. |
888d53f2 HH |
787 | |
788 | ||
789 | ||
790 | === Basic Setup | |
791 | ||
792 | The first thing init does, is to mount _/proc_ and _/sys_ and manually create | |
793 | the basic device nodes and symbolic links in _/dev_ needed to execute basic | |
794 | commands. Then logging is setup according to kernel command line arguments. | |
795 | _/dev/pts_ and _/dev/shm_ are mounted and the first hook is sourced. | |
796 | ||
797 | ||
798 | ||
799 | === Hook: cmdline | |
800 | ||
801 | The _cmdline_ hook is a place to insert scripts to parse the kernel command line | |
802 | and prepare the later actions, like setting up udev rules and configuration | |
803 | files. | |
804 | ||
805 | In this hook the most important environment variable is defined: root. The | |
806 | second one is rootok, which indicates, that a module claimed to be able to parse | |
807 | the root defined. So for example, **root=**__iscsi:....__ will be claimed by the | |
808 | iscsi dracut module, which then sets rootok. | |
809 | ||
810 | === Hook: pre-udev | |
811 | ||
812 | This hook is executed right after the cmdline hook and a check if root and | |
813 | rootok were set. Here modules can take action with the final root, and before | |
814 | udev has been run. | |
815 | ||
816 | ||
817 | ||
818 | === Start Udev | |
819 | ||
820 | Now udev is started and the logging for udev is setup. | |
821 | ||
822 | ||
823 | ||
824 | === Hook: pre-trigger | |
825 | ||
826 | In this hook, you can set udev environment variables with **udevadm control | |
827 | --property=KEY=_value_** or control the further execution of udev with | |
828 | udevadm. | |
829 | ||
830 | ||
831 | ||
832 | === Trigger Udev | |
833 | ||
834 | udev is triggered by calling udevadm trigger, which sends add events for all | |
a1ebd771 | 835 | devices and subsystems. |
888d53f2 HH |
836 | |
837 | ||
838 | ||
839 | === Main Loop | |
840 | ||
841 | Now the main loop of 99base/init begins. Here we loop until udev has settled and | |
842 | all scripts in _initqueue/finished_ returned true. In this loop there are three | |
843 | hooks, where scripts can be inserted by calling /sbin/initqueue. | |
844 | ||
845 | ||
846 | ||
847 | ==== Initqueue | |
848 | ||
849 | This hook gets executed every time a script is inserted here, regardless of the | |
850 | udev state. | |
851 | ||
852 | ||
853 | ||
854 | ==== Initqueue settled | |
855 | ||
856 | This hooks gets executed every time udev has settled. | |
857 | ||
858 | ||
859 | ||
860 | ==== Initqueue timeout | |
861 | ||
862 | This hooks gets executed, when the main loop counter becomes half of the | |
863 | rd.retry counter. | |
864 | ||
865 | ||
866 | ||
867 | ==== Initqueue finished | |
868 | ||
869 | This hook is called after udev has settled and if all scripts herein return 0 | |
870 | the main loop will be ended. | |
871 | ||
872 | ||
873 | ||
874 | === Hook: pre-mount | |
875 | ||
876 | Before the root device is mounted all scripts in the hook pre-mount are | |
877 | executed. In some cases (e.g. NFS) the real root device is already mounted, | |
878 | though. | |
879 | ||
880 | ||
881 | ||
882 | === Hook: mount | |
883 | ||
884 | This hook is mainly to mount the real root device. | |
885 | ||
886 | ||
887 | ||
888 | === Hook: pre-pivot | |
889 | ||
eef7649e | 890 | This hook is called before cleanup hook, This is a good place for |
2e7257a2 DY |
891 | actions other than cleanups which need to be called before pivot. |
892 | ||
893 | ||
eef7649e | 894 | === Hook: cleanup |
2e7257a2 | 895 | |
888d53f2 HH |
896 | This hook is the last hook and is called before init finally switches root to |
897 | the real root device. This is a good place to clean up and kill processes not | |
898 | needed anymore. | |
899 | ||
900 | ||
888d53f2 HH |
901 | === Cleanup and switch_root |
902 | ||
903 | Init kills all udev processes, cleans up the environment, sets up the arguments | |
904 | for the real init process and finally calls switch_root. switch_root removes the | |
905 | whole filesystem hierarchy of the initramfs, chroot()s to the real root device | |
906 | and calls /sbin/init with the specified arguments. | |
907 | ||
908 | To ensure all files in the initramfs hierarchy can be removed, all processes | |
909 | still running from the initramfs should not have any open file descriptors left. | |
910 | ||
911 | ||
912 | ||
913 | == Network Infrastructure | |
914 | ||
888d53f2 HH |
915 | FIXME |
916 | ||
917 | ||
918 | == Writing a Module | |
919 | ||
920 | A simple example module is _96insmodpost_, which modprobes a kernel module after | |
921 | udev has settled and the basic device drivers have been loaded. | |
922 | ||
923 | All module installation information is in the file module-setup.sh. | |
924 | ||
925 | First we create a check() function, which just exits with 0 indicating that this | |
926 | module should be included by default. | |
927 | ||
928 | check(): | |
929 | ||
930 | ||
931 | ---- | |
932 | return 0 | |
933 | ---- | |
934 | ||
935 | The we create the install() function, which installs a cmdline hook with | |
936 | priority number 20 called _parse-insmodpost.sh_. It also installs the | |
937 | _insmodpost.sh_ script in _/sbin_. | |
938 | ||
939 | install(): | |
940 | ||
941 | ||
942 | ---- | |
943 | inst_hook cmdline 20 "$moddir/parse-insmodpost.sh" | |
944 | inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh | |
945 | ---- | |
946 | ||
947 | The _pase-instmodpost.sh_ parses the kernel command line for a argument | |
948 | rd.driver.post, blacklists the module from being autoloaded and installs the | |
949 | hook _insmodpost.sh_ in the _initqueue/settled_. | |
950 | ||
951 | _parse-insmodpost.sh_: | |
952 | ||
953 | ||
954 | ---- | |
955 | for p in $(getargs rd.driver.post=); do | |
956 | echo "blacklist $p" >> /etc/modprobe.d/initramfsblacklist.conf | |
957 | _do_insmodpost=1 | |
958 | done | |
959 | ||
960 | [ -n "$_do_insmodpost" ] && /sbin/initqueue --settled --unique --onetime /sbin/insmodpost.sh | |
961 | unset _do_insmodpost | |
962 | ||
963 | ---- | |
964 | ||
965 | _insmodpost.sh_, which is called in the _initqueue/settled_ hook will just | |
966 | modprobe the kernel modules specified in all rd.driver.post kernel command line | |
967 | parameters. It runs after udev has settled and is only called once (--onetime). | |
968 | ||
969 | _insmodpost.sh_: | |
970 | ||
971 | ||
972 | ---- | |
973 | . /lib/dracut-lib.sh | |
974 | ||
975 | for p in $(getargs rd.driver.post=); do | |
976 | modprobe $p | |
977 | done | |
978 | ||
979 | ---- | |
980 | ||
981 | ||
982 | ||
983 | === check() | |
984 | ||
985 | _check()_ is called by dracut to evaluate the inclusion of a dracut module in | |
986 | the initramfs. | |
987 | ||
988 | $hostonly:: If the $hostonly variable is set, then the module check() function | |
989 | should be in "hostonly" mode, which means, that the check() should only return | |
990 | 0, if the module is really needed to boot this specific host. | |
991 | ||
992 | check() should return with: | |
993 | ||
994 | 0:: Include the dracut module in the initramfs. | |
995 | ||
996 | 1:: Do not include the dracut module. The requirements are not fullfilled | |
997 | (missing tools, etc.) | |
998 | ||
999 | 255:: Only include the dracut module, if another module requires it or if | |
1000 | explicitly specified in the config file or on the argument list. | |
1001 | ||
1002 | ||
1003 | ||
1004 | === depends() | |
1005 | ||
1006 | The function depends() should echo all other dracut module names the module | |
1007 | depends on. | |
1008 | ||
1009 | ||
1010 | ||
1011 | === install() | |
1012 | ||
1013 | dracut_install | |
1014 | ||
1015 | inst | |
1016 | ||
1017 | inst_hook | |
1018 | ||
1019 | inst_rules | |
1020 | ||
1021 | ||
1022 | ||
1023 | ||
1024 | ||
1025 | === installkernel() | |
1026 | ||
1027 | instmods | |
1028 | ||
1029 | ||
1030 | ||
1031 | === Creation Functions | |
1032 | ||
888d53f2 HH |
1033 | FIXME |
1034 | ||
1035 | ||
1036 | === Initramfs Functions | |
1037 | ||
888d53f2 HH |
1038 | FIXME |
1039 | ||
1040 | ||
1041 | === Network Modules | |
1042 | ||
1043 | FIXME | |
1044 | ||
a1ebd771 HH |
1045 | :leveloffset: 1 |
1046 | [[dracutbootup7]] | |
1047 | include::dracut.bootup.7.asc[] | |
3d3f32ae HH |
1048 | |
1049 | :leveloffset: 1 | |
888d53f2 HH |
1050 | [[dracut8]] |
1051 | include::dracut.8.asc[] | |
1052 | ||
1053 | [[dracutconf5]] | |
1054 | include::dracut.conf.5.asc[] | |
1055 | ||
1056 | [[dracutcmdline7]] | |
1057 | include::dracut.cmdline.7.asc[] | |
1058 | ||
e5efb6a7 HH |
1059 | [[lsinitrd1]] |
1060 | include::lsinitrd.1.asc[] | |
1061 | ||
1062 | [[mkinitrd8]] | |
1063 | include::mkinitrd.8.asc[] | |
1064 | ||
3d3f32ae | 1065 | :leveloffset: 0 |
888d53f2 HH |
1066 | [appendix] |
1067 | License | |
1068 | ------- | |
1069 | This work is licensed under the Creative Commons Attribution/Share-Alike | |
1070 | License. To view a copy of this license, visit | |
1071 | http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative | |
1072 | Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. | |
1073 |