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