| 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 is /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 bootchart initramfs-bootchart.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 vaiable 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 completly 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 usually can be configured in _/boot/grub/grub.conf_ or |
| _/boot/grub2/grub.cfg_, if grub is your bootloader and it also can be edited in |
| the real boot process in the grub menu. |
| |
| 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*(5). |
| |
| 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 would contain: |
| ---- |
| rd.vconsole.font=latarcyrheb-sun16 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.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 posibility 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.ext3 ssh' initramfs-dbg.img |
| ---- |
| |
| This will create an initramfs with the strace, fsck.ext3 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 adress 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 ommitting 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. Some of the basic operations are covered here. For more information |
| you should also visit: |
| https://www.kernel.org/pub/linux/utils/boot/dracut/dracut.html |
| |
| |
| [[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. _/etc/grub.conf_) 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 _/etc/grub.conf_ for editing. Below the line ''timeout=5'', add |
| the following: |
| + |
| ---- |
| serial --unit=0 --speed=9600 |
| terminal --timeout=5 serial console |
| ---- |
| + |
| . Also in _/etc/grub.conf_, add the following boot arguemnts to the ''kernel'' |
| line: |
| + |
| ---- |
| console=tty0 console=ttyS0,9600 |
| ---- |
| + |
| . When finished, the _/etc/grub.conf_ 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. _/etc/grub.conf_) |
| . Remove the boot arguments ''rhgb'' and ''quiet'' |
| + |
| A sample _/etc/grub.conf_ 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="ext3" |
| /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. |
| |