diff options
Diffstat (limited to 'man/dracut.usage.asc')
| -rw-r--r-- | man/dracut.usage.asc | 519 |
1 files changed, 519 insertions, 0 deletions
diff --git a/man/dracut.usage.asc b/man/dracut.usage.asc new file mode 100644 index 0000000..b83abf6 --- /dev/null +++ b/man/dracut.usage.asc @@ -0,0 +1,519 @@ +To create a initramfs image, the most simple command is: +---- +# dracut +---- + +This will generate a general purpose initramfs image, with all possible +functionality resulting of the combination of the installed dracut modules and +system tools. The image, depending on bootloader specification, can be +_/efi/_++<machine-id>++_/_++<kernel-version>++_/initrd_, +_/boot/_++<machine-id>++_/_++<kernel-version>++_/initrd_, +_/boot/efi/_++<machine-id>++_/_++<kernel-version>++_/initrd_, +_/lib/modules/_++<kernel-version>++_/initrd_ or +_/boot/initramfs-_++<kernel-version>++_.img_ and contains the kernel modules of +the currently active kernel with version _++<kernel-version>++_. + +If the initramfs image already exists, dracut will display an error message, and +to overwrite the existing image, you have to use the --force option. +---- +# dracut --force +---- + +If you want to specify another filename for the resulting image you would issue +a command like: +---- +# dracut foobar.img +---- + +To generate an image for a specific kernel version, the command would be: +---- +# dracut foobar.img 2.6.40-1.rc5.f20 +---- + +A shortcut to generate the image at the default location for a specific kernel +version is: +---- +# dracut --kver 2.6.40-1.rc5.f20 +---- + +If you want to create lighter, smaller initramfs images, you may want to specify +the --hostonly or -H option. Using this option, the resulting image will +contain only those dracut modules, kernel modules and filesystems, which are +needed to boot this specific machine. This has the drawback, that you can't put +the disk on another controller or machine, and that you can't switch to another +root filesystem, without recreating the initramfs image. The usage of the +--hostonly option is only for experts and you will have to keep the broken +pieces. At least keep a copy of a general purpose image (and corresponding +kernel) as a fallback to rescue your system. + +=== Inspecting the Contents +To see the contents of the image created by dracut, you can use the lsinitrd +tool. +---- +# lsinitrd | less +---- + +To display the contents of a file in the initramfs also use the lsinitrd tool: +---- +# lsinitrd -f /etc/ld.so.conf +include ld.so.conf.d/*.conf +---- + +=== Adding dracut Modules +Some dracut modules are turned off by default and have to be activated manually. +You can do this by adding the dracut modules to the configuration file +_/etc/dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_. See *dracut.conf*(5). +You can also add dracut modules on the command line +by using the -a or --add option: +---- +# dracut --add module initramfs-module.img +---- + +To see a list of available dracut modules, use the --list-modules option: +---- +# dracut --list-modules +---- + +=== Omitting dracut Modules +Sometimes you don't want a dracut module to be included for reasons of speed, +size or functionality. To do this, either specify the omit_dracutmodules +variable in the _dracut.conf_ or _/etc/dracut.conf.d/myconf.conf_ configuration +file (see *dracut.conf*(5)), or use the -o or --omit option +on the command line: +---- +# dracut -o "multipath lvm" no-multipath-lvm.img +---- + +=== Adding Kernel Modules +If you need a special kernel module in the initramfs, which is not +automatically picked up by dracut, you have the use the --add-drivers option +on the command line or the drivers variable in the _/etc/dracut.conf_ +or _/etc/dracut.conf.d/myconf.conf_ configuration file (see *dracut.conf*(5)): +---- +# dracut --add-drivers mymod initramfs-with-mymod.img +---- + +=== Boot parameters +An initramfs generated without the "hostonly" mode, does not contain any system +configuration files (except for some special exceptions), so the configuration +has to be done on the kernel command line. With this flexibility, you can easily +boot from a changed root partition, without the need to recompile the initramfs +image. So, you could completely change your root partition (move it inside a md +raid with encryption and LVM on top), as long as you specify the correct +filesystem LABEL or UUID on the kernel command line for your root device, dracut +will find it and boot from it. + +The kernel command line can also be provided by the dhcp server with the +root-path option. See <<NetworkBoot>>. + +For a full reference of all kernel command line parameters, +see *dracut.cmdline*(7). + +To get a quick start for the suitable kernel command line on your system, +use the __--print-cmdline__ option: +---- +# dracut --print-cmdline + root=UUID=8b8b6f91-95c7-4da2-831b-171e12179081 rootflags=rw,relatime,discard,data=ordered rootfstype=ext4 +---- + +==== Specifying the root Device +This is the only option dracut really needs to boot from your root partition. +Because your root partition can live in various environments, there are a lot of +formats for the root= option. The most basic one is root=_++<path to device +node>++_: +---- +root=/dev/sda2 +---- + +Because device node names can change, dependent on the drive ordering, you are +encouraged to use the filesystem identifier (UUID) or filesystem label (LABEL) +to specify your root partition: +---- +root=UUID=19e9dda3-5a38-484d-a9b0-fa6b067d0331 +---- + +or + +---- +root=LABEL=myrootpartitionlabel +---- + +To see all UUIDs or LABELs on your system, do: +---- +# ls -l /dev/disk/by-uuid +---- + +or + +---- +# ls -l /dev/disk/by-label +---- + +If your root partition is on the network see <<NetworkBoot>>. + +==== Keyboard Settings +If you have to input passwords for encrypted disk volumes, you might want to set +the keyboard layout and specify a display font. + +A typical german kernel command line would contain: +---- +rd.vconsole.font=eurlatgr rd.vconsole.keymap=de-latin1-nodeadkeys rd.locale.LANG=de_DE.UTF-8 +---- + +Setting these options can override the setting stored on your system, if you use +a modern init system, like systemd. + +==== Blacklisting Kernel Modules +Sometimes it is required to prevent the automatic kernel module loading of a +specific kernel module. To do this, just add rd.driver.blacklist=_++<kernel +module name>++_, with _++<kernel module name>++_ not containing the _.ko_ +suffix, to the kernel command line. For example: +---- +rd.driver.blacklist=mptsas rd.driver.blacklist=nouveau +---- + +The option can be specified multiple times on the kernel command line. + +==== Speeding up the Boot Process +If you want to speed up the boot process, you can specify as much information +for dracut on the kernel command as possible. For example, you can tell dracut, +that you root partition is not on a LVM volume or not on a raid partition, or +that it lives inside a specific crypto LUKS encrypted volume. By default, dracut +searches everywhere. A typical dracut kernel command line for a plain primary or +logical partition would contain: +---- +rd.luks=0 rd.lvm=0 rd.md=0 rd.dm=0 +---- + +This turns off every automatic assembly of LVM, MD raids, DM raids and +crypto LUKS. + +Of course, you could also omit the dracut modules in the initramfs creation +process, but then you would lose the possibility to turn it on on demand. + + +[[Injecting]] +=== Injecting custom Files +To add your own files to the initramfs image, you have several possibilities. + +The --include option let you specify a source path and a target path. +For example +---- +# dracut --include cmdline-preset /etc/cmdline.d/mycmdline.conf initramfs-cmdline-pre.img +---- +will create an initramfs image, where the file cmdline-preset will be copied +inside the initramfs to _/etc/cmdline.d/mycmdline.conf_. --include can only +be specified once. + + +---- +# mkdir -p rd.live.overlay/etc/cmdline.d +# mkdir -p rd.live.overlay/etc/conf.d +# echo "ip=dhcp" >> rd.live.overlay/etc/cmdline.d/mycmdline.conf +# echo export FOO=testtest >> rd.live.overlay/etc/conf.d/testvar.conf +# echo export BAR=testtest >> rd.live.overlay/etc/conf.d/testvar.conf +# tree rd.live.overlay/ +rd.live.overlay/ +`-- etc + |-- cmdline.d + | `-- mycmdline.conf + `-- conf.d + `-- testvar.conf + +# dracut --include rd.live.overlay / initramfs-rd.live.overlay.img +---- + +This will put the contents of the rd.live.overlay directory into the root of the +initramfs image. + +The --install option let you specify several files, which will get installed in +the initramfs image at the same location, as they are present on initramfs +creation time. + + +---- +# dracut --install 'strace fsck.ext4 ssh' initramfs-dbg.img +---- + +This will create an initramfs with the strace, fsck.ext4 and ssh executables, +together with the libraries needed to start those. The --install option can be +specified multiple times. + + +[[NetworkBoot]] +=== Network Boot + +If your root partition is on a network drive, you have to have the network +dracut modules installed to create a network aware initramfs image. + +If you specify ip=dhcp on the kernel command line, then dracut asks a dhcp +server about the ip address for the machine. The dhcp server can also serve an +additional root-path, which will set the root device for dracut. With this +mechanism, you have static configuration on your client machine and a +centralized boot configuration on your TFTP/DHCP server. If you can't pass a +kernel command line, then you can inject _/etc/cmdline.d/mycmdline.conf_, with a +method described in <<Injecting>>. + +==== Reducing the Image Size + +To reduce the size of the initramfs, you should create it with by omitting all +dracut modules, which you know, you don't need to boot the machine. + +You can also specify the exact dracut and kernel modules to produce a very tiny +initramfs image. + +For example for a NFS image, you would do: + + +---- +# dracut -m "nfs network base" initramfs-nfs-only.img +---- + +Then you would boot from this image with your target machine and reduce the size +once more by creating it on the target machine with the --host-only option: + + +---- +# dracut -m "nfs network base" --host-only initramfs-nfs-host-only.img +---- + +This will reduce the size of the initramfs image significantly. + + +== Troubleshooting + +If the boot process does not succeed, you have several options to debug the +situation. + +[[identifying-your-problem-area]] +=== Identifying your problem area +. Remove ''rhgb'' and ''quiet'' from the kernel command line +. Add ''rd.shell'' to the kernel command line. This will present a shell should +dracut be unable to locate your root device +. Add ''rd.shell rd.debug log_buf_len=1M'' to the kernel command line so that +dracut shell commands are printed as they are executed +. The file /run/initramfs/rdsosreport.txt is generated, +which contains all the logs and the output of all significant tools, which are +mentioned later. + +If you want to save that output, simply mount /boot by hand or insert an USB +stick and mount that. Then you can store the output for later inspection. + +[[information-to-include-in-your-report]] +=== Information to include in your report + +[[all-bug-reports]] +==== All bug reports +In all cases, the following should be mentioned and attached to your bug report: + +* The exact kernel command-line used. Typically from the bootloader +configuration file (e.g. _/boot/grub2/grub.cfg_) or from _/proc/cmdline_. +* A copy of your disk partition information from _/etc/fstab_, which might be +obtained booting an old working initramfs or a rescue medium. +* Turn on dracut debugging (see _the 'debugging dracut' section_), and attach +the file /run/initramfs/rdsosreport.txt. +* If you use a dracut configuration file, please include _/etc/dracut.conf_ and +all files in _/etc/dracut.conf.d/*.conf_ + +[[network-root-device-related-problems]] +==== Network root device related problems +This section details information to include when experiencing problems on a +system whose root device is located on a network attached volume (e.g. iSCSI, +NFS or NBD). As well as the information from <<all-bug-reports>>, include the +following information: + + +* Please include the output of ++ +---- +# /sbin/ifup <interfacename> +# ip addr show +---- + +[[debugging-dracut]] +=== Debugging dracut + + +[[configure-a-serial-console]] +==== Configure a serial console + +Successfully debugging dracut will require some form of console +logging during the system boot. This section documents configuring a +serial console connection to record boot messages. + +. First, enable serial console output for both the kernel and the bootloader. +. Open the file _/boot/grub2/grub.cfg_ for editing. Below the line ''timeout=5'', add +the following: ++ +---- +serial --unit=0 --speed=9600 +terminal --timeout=5 serial console +---- ++ +. Also in _/boot/grub2/grub.cfg_, add the following boot arguments to the ''kernel'' +line: ++ +---- +console=tty0 console=ttyS0,9600 +---- ++ +. When finished, the _/boot/grub2/grub.cfg_ file should look similar to the example +below. ++ +---- +default=0 +timeout=5 +serial --unit=0 --speed=9600 +terminal --timeout=5 serial console +title Fedora (2.6.29.5-191.fc11.x86_64) + root (hd0,0) + kernel /vmlinuz-2.6.29.5-191.fc11.x86_64 ro root=/dev/mapper/vg_uc1-lv_root console=tty0 console=ttyS0,9600 + initrd /dracut-2.6.29.5-191.fc11.x86_64.img +---- ++ +. More detailed information on how to configure the kernel for console output +can be found at +http://www.faqs.org/docs/Linux-HOWTO/Remote-Serial-Console-HOWTO.html#CONFIGURE-KERNEL. +. Redirecting non-interactive output ++ +-- +NOTE: You can redirect all non-interactive output to _/dev/kmsg_ and the kernel +will put it out on the console when it reaches the kernel buffer by doing + +---- +# exec >/dev/kmsg 2>&1 </dev/console +---- +-- + +[[using-the-dracut-shell]] +==== Using the dracut shell + +dracut offers a shell for interactive debugging in the event dracut fails to +locate your root filesystem. To enable the shell: + +. Add the boot parameter ''rd.shell'' to your bootloader configuration file +(e.g. _/boot/grub2/grub.cfg_) +. Remove the boot arguments ''rhgb'' and ''quiet'' ++ +A sample _/boot/grub2/grub.cfg_ bootloader configuration file is listed below. ++ +---- +default=0 +timeout=5 +serial --unit=0 --speed=9600 +terminal --timeout=5 serial console +title Fedora (2.6.29.5-191.fc11.x86_64) + root (hd0,0) + kernel /vmlinuz-2.6.29.5-191.fc11.x86_64 ro root=/dev/mapper/vg_uc1-lv_root console=tty0 rd.shell + initrd /dracut-2.6.29.5-191.fc11.x86_64.img +---- ++ +. If system boot fails, you will be dropped into a shell as seen in the example +below. ++ +---- +No root device found +Dropping to debug shell. + +# +---- ++ +. Use this shell prompt to gather the information requested above +(see <<all-bug-reports>>). + +[[accessing-the-root-volume-from-the-dracut-shell]] +==== Accessing the root volume from the dracut shell +From the dracut debug shell, you can manually perform the task of locating and +preparing your root volume for boot. The required steps will depend on how your +root volume is configured. Common scenarios include: + +* A block device (e.g. _/dev/sda7_) +* A LVM logical volume (e.g. _/dev/VolGroup00/LogVol00_) +* An encrypted device + (e.g. _/dev/mapper/luks-4d5972ea-901c-4584-bd75-1da802417d83_) +* A network attached device + (e.g. _netroot=iscsi:@192.168.0.4::3260::iqn.2009-02.org.example:for.all_) + +The exact method for locating and preparing will vary. However, to continue with +a successful boot, the objective is to locate your root volume and create a +symlink _/dev/root_ which points to the file system. For example, the following +example demonstrates accessing and booting a root volume that is an encrypted +LVM Logical volume. + +. Inspect your partitions using parted ++ +---- +# parted /dev/sda -s p +Model: ATA HTS541060G9AT00 (scsi) +Disk /dev/sda: 60.0GB +Sector size (logical/physical): 512B/512B +Partition Table: msdos +Number Start End Size Type File system Flags +1 32.3kB 10.8GB 107MB primary ext4 boot +2 10.8GB 55.6GB 44.7GB logical lvm +---- ++ +. You recall that your root volume was a LVM logical volume. Scan and activate +any logical volumes. ++ +---- +# lvm vgscan +# lvm vgchange -ay +---- ++ +. You should see any logical volumes now using the command blkid: ++ +---- +# blkid +/dev/sda1: UUID="3de247f3-5de4-4a44-afc5-1fe179750cf7" TYPE="ext4" +/dev/sda2: UUID="Ek4dQw-cOtq-5MJu-OGRF-xz5k-O2l8-wdDj0I" TYPE="LVM2_member" +/dev/mapper/linux-root: UUID="def0269e-424b-4752-acf3-1077bf96ad2c" TYPE="crypto_LUKS" +/dev/mapper/linux-home: UUID="c69127c1-f153-4ea2-b58e-4cbfa9257c5e" TYPE="ext4" +/dev/mapper/linux-swap: UUID="47b4d329-975c-4c08-b218-f9c9bf3635f1" TYPE="swap" +---- ++ +. From the output above, you recall that your root volume exists on an encrypted +block device. Following the guidance disk encryption guidance from the +Installation Guide, you unlock your encrypted root volume. ++ +---- +# UUID=$(cryptsetup luksUUID /dev/mapper/linux-root) +# cryptsetup luksOpen /dev/mapper/linux-root luks-$UUID +Enter passphrase for /dev/mapper/linux-root: +Key slot 0 unlocked. +---- ++ +. Next, make a symbolic link to the unlocked root volume ++ +---- +# ln -s /dev/mapper/luks-$UUID /dev/root +---- ++ +. With the root volume available, you may continue booting the system by exiting +the dracut shell ++ +---- +# exit +---- + +[[additional-dracut-boot-parameters]] +==== Additional dracut boot parameters +For more debugging options, see *dracut.cmdline*(7). + + +[[debugging-dracut-on-shutdown]] +==== Debugging dracut on shutdown + +To debug the shutdown sequence on systemd systems, you can _rd.break_ +on _pre-shutdown_ or _shutdown_. + +To do this from an already booted system: +---- +# mkdir -p /run/initramfs/etc/cmdline.d +# echo "rd.debug rd.break=pre-shutdown rd.break=shutdown" > /run/initramfs/etc/cmdline.d/debug.conf +# touch /run/initramfs/.need_shutdown +---- + +This will give you a dracut shell after the system pivot'ed back in the +initramfs. + |