From 84fe197facb96947638c518639c0913ecad1599b Mon Sep 17 00:00:00 2001

From: Harald Hoyer <harald@redhat.com>

Date: Tue, 8 Oct 2013 14:59:47 +0200

Subject: [PATCH] Doc: cleanup, extend and split and reuse

---

 Makefile             |   8 +-

 dracut.8.asc         |  61 +--

 dracut.asc           | 888 +------------------------------------------

 dracut.cmdline.7.asc | 414 +++++++++++---------

 dracut.css           | 434 +--------------------

 dracut.modules.7.asc | 293 ++++++++++++++

 dracut.spec          |   1 +

 dracut.usage.asc     | 526 +++++++++++++++++++++++++

 8 files changed, 1084 insertions(+), 1541 deletions(-)

 create mode 100644 dracut.modules.7.asc

 create mode 100644 dracut.usage.asc

diff --git a/Makefile b/Makefile

index 124a41b1..e7da9484 100644

--- a/Makefile

+++ b/Makefile

@@ -21,7 +21,8 @@ man1pages = lsinitrd.1

 man5pages = dracut.conf.5

 man7pages = dracut.cmdline.7 \

-            dracut.bootup.7

+            dracut.bootup.7 \

+            dracut.modules.7

 man8pages = dracut.8 \

             dracut-catimages.8 \

@@ -37,7 +38,6 @@ man8pages = dracut.8 \

 manpages = $(man1pages) $(man5pages) $(man7pages) $(man8pages)

-

 .PHONY: install clean archive rpm testimage test all check AUTHORS doc dracut-version.sh

 all: dracut-version.sh dracut-install

@@ -76,7 +76,9 @@ endif

 %.xml: %.asc

 	asciidoc -d manpage -b docbook -o $@ $<

-dracut.html: dracut.asc $(manpages) dracut.css

+dracut.8: dracut.usage.asc dracut.8.asc

+

+dracut.html: dracut.asc $(manpages) dracut.css dracut.usage.asc

 	asciidoc -a numbered -d book -b docbook -o dracut.xml dracut.asc

 	xsltproc -o dracut.html --xinclude -nonet \

 		--stringparam custom.css.source dracut.css \

diff --git a/dracut.8.asc b/dracut.8.asc

index 76fc75c4..584514c0 100644

--- a/dracut.8.asc

+++ b/dracut.8.asc

@@ -10,7 +10,7 @@ dracut - low-level tool for generating an initramfs image

 SYNOPSIS

 --------

-*dracut* ['OPTION...'] [<image> [_<kernel version>_]]

+*dracut* [__OPTION...__] [__<image>__ [__<kernel version>__]]

 DESCRIPTION

 -----------

@@ -37,53 +37,10 @@ Additional debugging info can be produced by adding **rd.debug** to the kernel c

 _/run/initramfs/rdsosreport.txt_ contains all logs and the output of some tools.

 It should be attached to any report about dracut problems.

-EXAMPLE

--------

-

-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.

+USAGE

+-----

+include::dracut.usage.asc[]

 OPTIONS

 -------

@@ -337,7 +294,7 @@ provide a valid _/etc/fstab_.

 **-N, --no-hostonly**::

     Disable Host-Only mode

-**--persistent-policy** _<policy>_::

+**--persistent-policy** _<policy>_::

     Use _<policy>_ to address disks and partitions.

     _<policy>_ can be any directory name found in /dev/disk.

     E.g. "by-uuid", "by-label"

@@ -345,7 +302,7 @@ provide a valid _/etc/fstab_.

 **--fstab**::

     Use _/etc/fstab_ instead of _/proc/self/mountinfo_.

-**--add-fstab** _<filename>_ ::

+**--add-fstab** _<filename>_::

     Add entries of _<filename>_ to the initramfs /etc/fstab.

 **--mount** "_<device>_ _<mountpoint>_ _<filesystem type>_ _<filesystem options>_"::

@@ -358,13 +315,13 @@ provide a valid _/etc/fstab_.

     LVM or an encrypted partition.

     [NB --device can be used for compatibility with earlier releases]

-**-i, --include** _<SOURCE>_ _<TARGET>_::

+**-i, --include** _<SOURCE>_ _<TARGET>_::

     include the files in the SOURCE directory into the

     TARGET directory in the final initramfs. If SOURCE is a file, it will be

     installed to TARGET in the final initramfs. This parameter can be specified

     multiple times.

-**-I, --install** _<file list>_::

+**-I, --install** _<file list>_::

     install the space separated list of files into the initramfs.

 +

 [NOTE]

@@ -481,7 +438,7 @@ _/etc/conf.d/_::

 _/etc/cmdline_::

     Can contain additional command line options. Deprecated, better use /etc/cmdline.d/*.conf.

-_/etc/cmdline.d/*.conf::

+_/etc/cmdline.d/*.conf_::

     Can contain additional command line options.

 AVAILABILITY

diff --git a/dracut.asc b/dracut.asc

index c0116581..031b2014 100644

--- a/dracut.asc

+++ b/dracut.asc

@@ -1,7 +1,7 @@

 dracut

 ======

 Harald Hoyer <harald@redhat.com>

-v2.0, March 2011

+v3.0, October 2013

 :language: bash

@@ -145,885 +145,10 @@ This ensures, that all devices are disassembled and unmounted cleanly.

 = User Manual

-== Creating an initramfs Image

-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 --host-only 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

---host-only 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 /boot/initramfs-$(uname -r).img | less

-----

-

-To display the contents of a file in the initramfs also use the lsinitrd tool:

-----

-# lsinitrd /boot/initramfs-$(uname -r).img  /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 <<dracutconf5>>.

-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

-----

-

-or, if you have a dracut version earlier than +008+, issue the command:

-----

-# for mod in /usr/lib/dracut/modules.d/*; do echo ${mod##*/??}; done

-----

-

-=== 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 <<dracutconf5>>), 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 <<dracutconf5>>):

-----

-# dracut --add-drivers mymod initramfs-with-mymod.img

-----

-

-== Boot parameters

-The generated initramfs.img file normally 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_, 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 <<dracut8>>.

-

-=== 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=_++

-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:

-----

-vconsole.font=latarcyrheb-sun16 vconsole.keymap=de-latin1-nodeadkeys 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.

-

-For dracut versions prior to version +008+ the line would look like:

-----

-LANG=de_DE.UTF-8 SYSFONT=latarcyrheb-sun16 KEYBOARDTYPE=pc KEYTABLE=de-latin1-nodeadkeys

-----

-

-=== 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=_++

-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

-----

-

-On systems with dracut version prior to +008+ the line would look like:

-----

-rd_NO_LUKS rd_NO_LVM rd_NO_MD rd_NO_DM

-----

-

-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 rd.live.overlay

-# mkdir rd.live.overlay/etc

-# mkdir rd.live.overlay/etc/conf.d

-# mkdir rd.live.overlay/etc/cmdline.d

-# echo "ip=auto" >> 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.

-

-On a Red Hat Enterprise Linux or Fedora system, this means, you have to install

-the _dracut-network_ rpm package:

-

-

-----

-# yum install dracut-network

-----

-

-The resulting initramfs image can be served by a boot manager residing on your

-local hard drive or it can be served by a PXE/TFTP server.

-

-How to setup your PXE/TFTP server can be found in the

-http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/[Red

-Hat Enterprise Linux Storage Administration Guide].

-

-If you specify ip=auto 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.

-

-

-

-=== NFS Root Device

-

-FIXME

-

-=== iSCSI Root Device

-

-FIXME 

-

-=== FCoE Root Device

-

-FIXME

-

-== 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:

-http://fedoraproject.org/wiki/How_to_debug_Dracut_problems

-

-

-[[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

-. With dracut >= 002-11, you can inspect the rd.debug output with:

-+

-----

-# less /run/initramfs/init.log

-# dmesg | less

-----

-. With dracut >= 022 and systemd, you can inspect the rd.debug output with:

-----

-# journalctl -ab

-----

-. 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.

-

-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.

-* A device listing from device-mapper. This can be obtained by running the

-command

-+

-----

-# dmsetup ls --tree

-----

-+

-* A list of block device attributes. This can be obtained by running the commands: 

-+

-----

-# blkid -p

-# blkid -p -o udev

-----

-* Turn on dracut debugging (see _the 'debugging dracut' section_), and attach

-all relevant information from the boot log. This can be obtained by running the

-command 

-+

-----

-# dmesg|grep dracut

-----

-+

-* If you use a dracut configuration file, please include _/etc/dracut.conf_ and

-all files in _/etc/dracut.conf.d/*.conf_

-

-[[logical-volume-management-related-problems]]

-==== Logical Volume Management related problems

-As well as the information from <<all-bug-reports>> include the following

-information:

-

-* Include physical volume information by running the command:

-+

-----

-# lvm pvdisplay

-----

-+

-* Include volume group information by running the command:

-+

-----

-# lvm vgdisplay

-----

-+

-* Include logical volume information by running the command:

-+

-----

-# lvm lvdisplay

-----

-

-[[software-raid-related-problems]]

-==== Software RAID related problems

-As well as the information from <<all-bug-reports>>, include the following

-information:

-

-* If using software RAID disk partitions, please include the output of

-+

-----

-# cat /proc/mdstat

-----

-

-[[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 

-----

---

-

-[[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.fedoraproject: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.