Adding upstream version 060+5.upstream/060+5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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