]>
Commit | Line | Data |
---|---|---|
b6c89768 HH |
1 | To create a initramfs image, the most simple command is: |
2 | ---- | |
3 | # dracut | |
4 | ---- | |
5 | ||
6 | This will generate a general purpose initramfs image, with all possible | |
7 | functionality resulting of the combination of the installed dracut modules and | |
8 | system tools. The image is /boot/initramfs-_++<kernel version>++_.img and | |
9 | contains the kernel modules of the currently active kernel with version | |
10 | _++<kernel version>++_. | |
11 | ||
12 | If the initramfs image already exists, dracut will display an error message, and | |
13 | to overwrite the existing image, you have to use the --force option. | |
14 | ---- | |
15 | # dracut --force | |
16 | ---- | |
17 | ||
18 | If you want to specify another filename for the resulting image you would issue | |
19 | a command like: | |
20 | ---- | |
21 | # dracut foobar.img | |
22 | ---- | |
23 | ||
24 | To generate an image for a specific kernel version, the command would be: | |
25 | ---- | |
26 | # dracut foobar.img 2.6.40-1.rc5.f20 | |
27 | ---- | |
28 | ||
29 | A shortcut to generate the image at the default location for a specific kernel | |
30 | version is: | |
31 | ---- | |
32 | # dracut --kver 2.6.40-1.rc5.f20 | |
33 | ---- | |
34 | ||
35 | If you want to create lighter, smaller initramfs images, you may want to specify | |
36 | the --hostonly or -H option. Using this option, the resulting image will | |
37 | contain only those dracut modules, kernel modules and filesystems, which are | |
38 | needed to boot this specific machine. This has the drawback, that you can't put | |
39 | the disk on another controller or machine, and that you can't switch to another | |
40 | root filesystem, without recreating the initramfs image. The usage of the | |
41 | --hostonly option is only for experts and you will have to keep the broken | |
42 | pieces. At least keep a copy of a general purpose image (and corresponding | |
43 | kernel) as a fallback to rescue your system. | |
44 | ||
45 | === Inspecting the Contents | |
ef9ddb91 HH |
46 | To see the contents of the image created by dracut, you can use the lsinitrd |
47 | tool. | |
b6c89768 HH |
48 | ---- |
49 | # lsinitrd | less | |
50 | ---- | |
51 | ||
52 | To display the contents of a file in the initramfs also use the lsinitrd tool: | |
53 | ---- | |
54 | # lsinitrd -f /etc/ld.so.conf | |
55 | include ld.so.conf.d/*.conf | |
56 | ---- | |
57 | ||
58 | === Adding dracut Modules | |
59 | Some dracut modules are turned off by default and have to be activated manually. | |
60 | You can do this by adding the dracut modules to the configuration file | |
61 | _/etc/dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_. See *dracut.conf*(5). | |
62 | You can also add dracut modules on the command line | |
63 | by using the -a or --add option: | |
64 | ---- | |
65 | # dracut --add bootchart initramfs-bootchart.img | |
66 | ---- | |
67 | ||
68 | To see a list of available dracut modules, use the --list-modules option: | |
69 | ---- | |
70 | # dracut --list-modules | |
71 | ---- | |
72 | ||
73 | === Omitting dracut Modules | |
74 | Sometimes you don't want a dracut module to be included for reasons of speed, | |
75 | size or functionality. To do this, either specify the omit_dracutmodules | |
76 | variable in the _dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_ configuration | |
77 | file (see *dracut.conf*(5)), or use the -o or --omit option | |
78 | on the command line: | |
79 | ---- | |
80 | # dracut -o "multipath lvm" no-multipath-lvm.img | |
81 | ---- | |
82 | ||
83 | === Adding Kernel Modules | |
84 | If you need a special kernel module in the initramfs, which is not | |
85 | automatically picked up by dracut, you have the use the --add-drivers option | |
86 | on the command line or the drivers vaiable in the _/etc/dracut.conf_ | |
87 | or _/etc/dracut.conf.d/myconf.conf_ configuration file (see *dracut.conf*(5)): | |
88 | ---- | |
89 | # dracut --add-drivers mymod initramfs-with-mymod.img | |
90 | ---- | |
91 | ||
92 | === Boot parameters | |
93 | An initramfs generated without the "hostonly" mode, does not contain any system | |
94 | configuration files (except for some special exceptions), so the configuration | |
95 | has to be done on the kernel command line. With this flexibility, you can easily | |
96 | boot from a changed root partition, without the need to recompile the initramfs | |
97 | image. So, you could completly change your root partition (move it inside a md | |
98 | raid with encryption and LVM on top), as long as you specify the correct | |
99 | filesystem LABEL or UUID on the kernel command line for your root device, dracut | |
100 | will find it and boot from it. | |
101 | ||
b6c89768 HH |
102 | The kernel command line can also be provided by the dhcp server with the |
103 | root-path option. See <<NetworkBoot>>. | |
104 | ||
ef9ddb91 HH |
105 | For a full reference of all kernel command line parameters, |
106 | see *dracut.cmdline*(5). | |
b6c89768 | 107 | |
ef9ddb91 HH |
108 | To get a quick start for the suitable kernel command line on your system, |
109 | use the __--print-cmdline__ option: | |
b6c89768 HH |
110 | ---- |
111 | # dracut --print-cmdline | |
112 | root=UUID=8b8b6f91-95c7-4da2-831b-171e12179081 rootflags=rw,relatime,discard,data=ordered rootfstype=ext4 | |
113 | ---- | |
114 | ||
115 | ==== Specifying the root Device | |
116 | This is the only option dracut really needs to boot from your root partition. | |
117 | Because your root partition can live in various environments, there are a lot of | |
118 | formats for the root= option. The most basic one is root=_++<path to device | |
119 | node>++_: | |
120 | ---- | |
121 | root=/dev/sda2 | |
122 | ---- | |
123 | ||
124 | Because device node names can change, dependent on the drive ordering, you are | |
125 | encouraged to use the filesystem identifier (UUID) or filesystem label (LABEL) | |
126 | to specify your root partition: | |
127 | ---- | |
128 | root=UUID=19e9dda3-5a38-484d-a9b0-fa6b067d0331 | |
129 | ---- | |
130 | ||
131 | or | |
132 | ||
133 | ---- | |
134 | root=LABEL=myrootpartitionlabel | |
135 | ---- | |
136 | ||
137 | To see all UUIDs or LABELs on your system, do: | |
138 | ---- | |
139 | # ls -l /dev/disk/by-uuid | |
140 | ---- | |
141 | ||
142 | or | |
143 | ||
144 | ---- | |
145 | # ls -l /dev/disk/by-label | |
146 | ---- | |
147 | ||
148 | If your root partition is on the network see <<NetworkBoot>>. | |
149 | ||
150 | ==== Keyboard Settings | |
151 | If you have to input passwords for encrypted disk volumes, you might want to set | |
152 | the keyboard layout and specify a display font. | |
153 | ||
154 | A typical german kernel command would contain: | |
155 | ---- | |
156 | rd.vconsole.font=latarcyrheb-sun16 rd.vconsole.keymap=de-latin1-nodeadkeys rd.locale.LANG=de_DE.UTF-8 | |
157 | ---- | |
158 | ||
159 | Setting these options can override the setting stored on your system, if you use | |
160 | a modern init system, like systemd. | |
161 | ||
162 | ==== Blacklisting Kernel Modules | |
163 | Sometimes it is required to prevent the automatic kernel module loading of a | |
164 | specific kernel module. To do this, just add rd.blacklist=_++<kernel module | |
165 | name>++_, with _++<kernel module name>++_ not containing the _.ko_ | |
166 | suffix, to the kernel command line. For example: | |
167 | ---- | |
168 | rd.driver.blacklist=mptsas rd.driver.blacklist=nouveau | |
169 | ---- | |
170 | ||
171 | The option can be specified multiple times on the kernel command line. | |
172 | ||
173 | ==== Speeding up the Boot Process | |
174 | If you want to speed up the boot process, you can specify as much information | |
175 | for dracut on the kernel command as possible. For example, you can tell dracut, | |
176 | that you root partition is not on a LVM volume or not on a raid partition, or | |
177 | that it lives inside a specific crypto LUKS encrypted volume. By default, dracut | |
178 | searches everywhere. A typical dracut kernel command line for a plain primary or | |
179 | logical partition would contain: | |
180 | ---- | |
181 | rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 | |
182 | ---- | |
183 | ||
ef9ddb91 HH |
184 | This turns off every automatic assembly of LVM, MD raids, DM raids and |
185 | crypto LUKS. | |
b6c89768 HH |
186 | |
187 | Of course, you could also omit the dracut modules in the initramfs creation | |
188 | process, but then you would lose the posibility to turn it on on demand. | |
189 | ||
190 | ||
191 | [[Injecting]] | |
192 | === Injecting custom Files | |
193 | To add your own files to the initramfs image, you have several possibilities. | |
194 | ||
ef9ddb91 HH |
195 | The --include option let you specify a source path and a target path. |
196 | For example | |
b6c89768 HH |
197 | ---- |
198 | # dracut --include cmdline-preset /etc/cmdline.d/mycmdline.conf initramfs-cmdline-pre.img | |
199 | ---- | |
200 | will create an initramfs image, where the file cmdline-preset will be copied | |
ef9ddb91 HH |
201 | inside the initramfs to _/etc/cmdline.d/mycmdline.conf_. --include can only |
202 | be specified once. | |
b6c89768 HH |
203 | |
204 | ||
205 | ---- | |
206 | # mkdir -p rd.live.overlay/etc/cmdline.d | |
207 | # mkdir -p rd.live.overlay/etc/conf.d | |
e3250e20 | 208 | # echo "ip=dhcp" >> rd.live.overlay/etc/cmdline.d/mycmdline.conf |
b6c89768 HH |
209 | # echo export FOO=testtest >> rd.live.overlay/etc/conf.d/testvar.conf |
210 | # echo export BAR=testtest >> rd.live.overlay/etc/conf.d/testvar.conf | |
211 | # tree rd.live.overlay/ | |
212 | rd.live.overlay/ | |
213 | `-- etc | |
214 | |-- cmdline.d | |
215 | | `-- mycmdline.conf | |
216 | `-- conf.d | |
217 | `-- testvar.conf | |
218 | ||
219 | # dracut --include rd.live.overlay / initramfs-rd.live.overlay.img | |
220 | ---- | |
221 | ||
222 | This will put the contents of the rd.live.overlay directory into the root of the | |
223 | initramfs image. | |
224 | ||
225 | The --install option let you specify several files, which will get installed in | |
226 | the initramfs image at the same location, as they are present on initramfs | |
227 | creation time. | |
228 | ||
229 | ||
230 | ---- | |
231 | # dracut --install 'strace fsck.ext3 ssh' initramfs-dbg.img | |
232 | ---- | |
233 | ||
234 | This will create an initramfs with the strace, fsck.ext3 and ssh executables, | |
235 | together with the libraries needed to start those. The --install option can be | |
236 | specified multiple times. | |
237 | ||
238 | ||
239 | [[NetworkBoot]] | |
240 | === Network Boot | |
241 | ||
242 | If your root partition is on a network drive, you have to have the network | |
243 | dracut modules installed to create a network aware initramfs image. | |
244 | ||
e3250e20 | 245 | If you specify ip=dhcp on the kernel command line, then dracut asks a dhcp |
b6c89768 HH |
246 | server about the ip adress for the machine. The dhcp server can also serve an |
247 | additional root-path, which will set the root device for dracut. With this | |
248 | mechanism, you have static configuration on your client machine and a | |
249 | centralized boot configuration on your TFTP/DHCP server. If you can't pass a | |
ef9ddb91 HH |
250 | kernel command line, then you can inject _/etc/cmdline.d/mycmdline.conf_, with a |
251 | method described in <<Injecting>>. | |
b6c89768 HH |
252 | |
253 | ==== Reducing the Image Size | |
254 | ||
255 | To reduce the size of the initramfs, you should create it with by ommitting all | |
256 | dracut modules, which you know, you don't need to boot the machine. | |
257 | ||
258 | You can also specify the exact dracut and kernel modules to produce a very tiny | |
259 | initramfs image. | |
260 | ||
261 | For example for a NFS image, you would do: | |
262 | ||
263 | ||
264 | ---- | |
265 | # dracut -m "nfs network base" initramfs-nfs-only.img | |
266 | ---- | |
267 | ||
268 | Then you would boot from this image with your target machine and reduce the size | |
269 | once more by creating it on the target machine with the --host-only option: | |
270 | ||
271 | ||
272 | ---- | |
273 | # dracut -m "nfs network base" --host-only initramfs-nfs-host-only.img | |
274 | ---- | |
275 | ||
276 | This will reduce the size of the initramfs image significantly. | |
277 | ||
278 | ||
279 | == Troubleshooting | |
280 | ||
281 | If the boot process does not succeed, you have several options to debug the | |
282 | situation. Some of the basic operations are covered here. For more information | |
283 | you should also visit: | |
4d258921 | 284 | https://www.kernel.org/pub/linux/utils/boot/dracut/dracut.html |
b6c89768 HH |
285 | |
286 | ||
287 | [[identifying-your-problem-area]] | |
288 | === Identifying your problem area | |
289 | . Remove ''rhgb'' and ''quiet'' from the kernel command line | |
290 | . Add ''rd.shell'' to the kernel command line. This will present a shell should | |
291 | dracut be unable to locate your root device | |
292 | . Add ''rd.shell rd.debug log_buf_len=1M'' to the kernel command line so that | |
293 | dracut shell commands are printed as they are executed | |
294 | . The file /run/initramfs/rdsosreport.txt is generated, | |
ef9ddb91 HH |
295 | which contains all the logs and the output of all significant tools, which are |
296 | mentioned later. | |
b6c89768 | 297 | |
ef9ddb91 HH |
298 | If you want to save that output, simply mount /boot by hand or insert an USB |
299 | stick and mount that. Then you can store the output for later inspection. | |
b6c89768 HH |
300 | |
301 | [[information-to-include-in-your-report]] | |
302 | === Information to include in your report | |
303 | ||
304 | [[all-bug-reports]] | |
305 | ==== All bug reports | |
306 | In all cases, the following should be mentioned and attached to your bug report: | |
307 | ||
308 | * The exact kernel command-line used. Typically from the bootloader | |
20486a16 | 309 | configuration file (e.g. _/boot/grub2/grub.cfg_) or from _/proc/cmdline_. |
b6c89768 HH |
310 | * A copy of your disk partition information from _/etc/fstab_, which might be |
311 | obtained booting an old working initramfs or a rescue medium. | |
312 | * Turn on dracut debugging (see _the 'debugging dracut' section_), and attach | |
313 | the file /run/initramfs/rdsosreport.txt. | |
314 | * If you use a dracut configuration file, please include _/etc/dracut.conf_ and | |
315 | all files in _/etc/dracut.conf.d/*.conf_ | |
316 | ||
317 | [[network-root-device-related-problems]] | |
318 | ==== Network root device related problems | |
319 | This section details information to include when experiencing problems on a | |
320 | system whose root device is located on a network attached volume (e.g. iSCSI, | |
321 | NFS or NBD). As well as the information from <<all-bug-reports>>, include the | |
322 | following information: | |
323 | ||
324 | ||
325 | * Please include the output of | |
326 | + | |
327 | ---- | |
328 | # /sbin/ifup <interfacename> | |
329 | # ip addr show | |
330 | ---- | |
331 | ||
332 | [[debugging-dracut]] | |
333 | === Debugging dracut | |
334 | ||
335 | ||
336 | [[configure-a-serial-console]] | |
337 | ==== Configure a serial console | |
338 | ||
339 | Successfully debugging dracut will require some form of console | |
340 | logging during the system boot. This section documents configuring a | |
341 | serial console connection to record boot messages. | |
342 | ||
343 | . First, enable serial console output for both the kernel and the bootloader. | |
20486a16 | 344 | . Open the file _/boot/grub2/grub.cfg_ for editing. Below the line ''timeout=5'', add |
b6c89768 HH |
345 | the following: |
346 | + | |
347 | ---- | |
348 | serial --unit=0 --speed=9600 | |
349 | terminal --timeout=5 serial console | |
350 | ---- | |
351 | + | |
20486a16 | 352 | . Also in _/boot/grub2/grub.cfg_, add the following boot arguemnts to the ''kernel'' |
b6c89768 HH |
353 | line: |
354 | + | |
355 | ---- | |
356 | console=tty0 console=ttyS0,9600 | |
357 | ---- | |
358 | + | |
20486a16 | 359 | . When finished, the _/boot/grub2/grub.cfg_ file should look similar to the example |
b6c89768 HH |
360 | below. |
361 | + | |
362 | ---- | |
363 | default=0 | |
364 | timeout=5 | |
365 | serial --unit=0 --speed=9600 | |
366 | terminal --timeout=5 serial console | |
367 | title Fedora (2.6.29.5-191.fc11.x86_64) | |
368 | root (hd0,0) | |
369 | kernel /vmlinuz-2.6.29.5-191.fc11.x86_64 ro root=/dev/mapper/vg_uc1-lv_root console=tty0 console=ttyS0,9600 | |
370 | initrd /dracut-2.6.29.5-191.fc11.x86_64.img | |
371 | ---- | |
372 | + | |
373 | . More detailed information on how to configure the kernel for console output | |
374 | can be found at | |
375 | http://www.faqs.org/docs/Linux-HOWTO/Remote-Serial-Console-HOWTO.html#CONFIGURE-KERNEL. | |
376 | . Redirecting non-interactive output | |
377 | + | |
378 | -- | |
379 | NOTE: You can redirect all non-interactive output to _/dev/kmsg_ and the kernel | |
380 | will put it out on the console when it reaches the kernel buffer by doing | |
381 | ||
382 | ---- | |
383 | # exec >/dev/kmsg 2>&1 </dev/console | |
384 | ---- | |
385 | -- | |
386 | ||
387 | [[using-the-dracut-shell]] | |
388 | ==== Using the dracut shell | |
389 | ||
390 | dracut offers a shell for interactive debugging in the event dracut fails to | |
391 | locate your root filesystem. To enable the shell: | |
392 | ||
393 | . Add the boot parameter ''rd.shell'' to your bootloader configuration file | |
20486a16 | 394 | (e.g. _/boot/grub2/grub.cfg_) |
b6c89768 HH |
395 | . Remove the boot arguments ''rhgb'' and ''quiet'' |
396 | + | |
20486a16 | 397 | A sample _/boot/grub2/grub.cfg_ bootloader configuration file is listed below. |
b6c89768 HH |
398 | + |
399 | ---- | |
400 | default=0 | |
401 | timeout=5 | |
402 | serial --unit=0 --speed=9600 | |
403 | terminal --timeout=5 serial console | |
404 | title Fedora (2.6.29.5-191.fc11.x86_64) | |
405 | root (hd0,0) | |
406 | kernel /vmlinuz-2.6.29.5-191.fc11.x86_64 ro root=/dev/mapper/vg_uc1-lv_root console=tty0 rd.shell | |
407 | initrd /dracut-2.6.29.5-191.fc11.x86_64.img | |
408 | ---- | |
409 | + | |
ef9ddb91 HH |
410 | . If system boot fails, you will be dropped into a shell as seen in the example |
411 | below. | |
b6c89768 HH |
412 | + |
413 | ---- | |
414 | No root device found | |
415 | Dropping to debug shell. | |
416 | ||
417 | # | |
418 | ---- | |
419 | + | |
ef9ddb91 HH |
420 | . Use this shell prompt to gather the information requested above |
421 | (see <<all-bug-reports>>). | |
b6c89768 HH |
422 | |
423 | [[accessing-the-root-volume-from-the-dracut-shell]] | |
424 | ==== Accessing the root volume from the dracut shell | |
425 | From the dracut debug shell, you can manually perform the task of locating and | |
426 | preparing your root volume for boot. The required steps will depend on how your | |
427 | root volume is configured. Common scenarios include: | |
428 | ||
429 | * A block device (e.g. _/dev/sda7_) | |
430 | * A LVM logical volume (e.g. _/dev/VolGroup00/LogVol00_) | |
ef9ddb91 HH |
431 | * An encrypted device |
432 | (e.g. _/dev/mapper/luks-4d5972ea-901c-4584-bd75-1da802417d83_) | |
433 | * A network attached device | |
434 | (e.g. _netroot=iscsi:@192.168.0.4::3260::iqn.2009-02.org.example:for.all_) | |
b6c89768 HH |
435 | |
436 | The exact method for locating and preparing will vary. However, to continue with | |
437 | a successful boot, the objective is to locate your root volume and create a | |
438 | symlink _/dev/root_ which points to the file system. For example, the following | |
439 | example demonstrates accessing and booting a root volume that is an encrypted | |
440 | LVM Logical volume. | |
441 | ||
442 | . Inspect your partitions using parted | |
443 | + | |
444 | ---- | |
445 | # parted /dev/sda -s p | |
446 | Model: ATA HTS541060G9AT00 (scsi) | |
447 | Disk /dev/sda: 60.0GB | |
448 | Sector size (logical/physical): 512B/512B | |
449 | Partition Table: msdos | |
450 | Number Start End Size Type File system Flags | |
451 | 1 32.3kB 10.8GB 107MB primary ext4 boot | |
452 | 2 10.8GB 55.6GB 44.7GB logical lvm | |
453 | ---- | |
454 | + | |
455 | . You recall that your root volume was a LVM logical volume. Scan and activate | |
456 | any logical volumes. | |
457 | + | |
458 | ---- | |
459 | # lvm vgscan | |
460 | # lvm vgchange -ay | |
461 | ---- | |
462 | + | |
463 | . You should see any logical volumes now using the command blkid: | |
464 | + | |
465 | ---- | |
466 | # blkid | |
467 | /dev/sda1: UUID="3de247f3-5de4-4a44-afc5-1fe179750cf7" TYPE="ext4" | |
468 | /dev/sda2: UUID="Ek4dQw-cOtq-5MJu-OGRF-xz5k-O2l8-wdDj0I" TYPE="LVM2_member" | |
469 | /dev/mapper/linux-root: UUID="def0269e-424b-4752-acf3-1077bf96ad2c" TYPE="crypto_LUKS" | |
470 | /dev/mapper/linux-home: UUID="c69127c1-f153-4ea2-b58e-4cbfa9257c5e" TYPE="ext3" | |
471 | /dev/mapper/linux-swap: UUID="47b4d329-975c-4c08-b218-f9c9bf3635f1" TYPE="swap" | |
472 | ---- | |
473 | + | |
474 | . From the output above, you recall that your root volume exists on an encrypted | |
475 | block device. Following the guidance disk encryption guidance from the | |
476 | Installation Guide, you unlock your encrypted root volume. | |
477 | + | |
478 | ---- | |
479 | # UUID=$(cryptsetup luksUUID /dev/mapper/linux-root) | |
480 | # cryptsetup luksOpen /dev/mapper/linux-root luks-$UUID | |
481 | Enter passphrase for /dev/mapper/linux-root: | |
482 | Key slot 0 unlocked. | |
483 | ---- | |
484 | + | |
485 | . Next, make a symbolic link to the unlocked root volume | |
486 | + | |
487 | ---- | |
488 | # ln -s /dev/mapper/luks-$UUID /dev/root | |
489 | ---- | |
490 | + | |
491 | . With the root volume available, you may continue booting the system by exiting | |
492 | the dracut shell | |
493 | + | |
494 | ---- | |
495 | # exit | |
496 | ---- | |
497 | ||
498 | [[additional-dracut-boot-parameters]] | |
499 | ==== Additional dracut boot parameters | |
500 | For more debugging options, see *dracut.cmdline*(7). | |
501 | ||
502 | ||
503 | [[debugging-dracut-on-shutdown]] | |
504 | ==== Debugging dracut on shutdown | |
505 | ||
506 | To debug the shutdown sequence on systemd systems, you can _rd.break_ | |
507 | on _pre-shutdown_ or _shutdown_. | |
508 | ||
509 | To do this from an already booted system: | |
510 | ---- | |
511 | # mkdir -p /run/initramfs/etc/cmdline.d | |
e02a29e7 | 512 | # echo "rd.debug rd.break=pre-shutdown rd.break=shutdown" > /run/initramfs/etc/cmdline.d/debug.conf |
b6c89768 HH |
513 | # touch /run/initramfs/.need_shutdown |
514 | ---- | |
515 | ||
ef9ddb91 HH |
516 | This will give you a dracut shell after the system pivot'ed back in the |
517 | initramfs. | |
b6c89768 | 518 |