initialized and a user-space helper started to paint animations onto the display
in lockstep with the boot process.
-* If the root file system is on NFS, dracut does then:
+* If the root file system is on NFS, dracut does then:
** Bring up the primary network interface.
** Invoke a DHCP client, with which it can obtain a DHCP lease.
** Extract the name of the NFS share and the address of the NFS server from the
rotated away. Instead, it is simply emptied and the final root file system
mounted over the top.
+If the systemd module is used in the initramfs, the ordering of the services
+started looks like <<dracutbootup7>>.
+
+== Dracut on shutdown
+
+On a systemd driven system, the dracut initramfs is also used for the shutdown procedure.
+
+The following steps are executed during a shutdown:
+
+* systemd switches to the shutdown.target
+* systemd starts /lib/systemd/system/shutdown.target.wants/dracut-shutdown.service
+* dracut-shutdown.service executes /usr/lib/dracut/dracut-initramfs-restore
+ which unpacks the initramfs to /run/initramfs
+* systemd finishes shutdown.target
+* systemd kills all processes
+* systemd tries to unmount everything and mounts the remaining read-only
+* systemd checks, if there is a /run/initramfs/shutdown executable
+* if yes, it does a pivot_root to /run/initramfs and executes ./shutdown.
+ The old root is then mounted on /oldroot. /usr/lib/dracut/modules.d/99shutdown/shutdown.sh is the shutdown executable.
+* shutdown will try to umount every /oldroot mount and calls the various shutdown hooks from the dracut modules
+
+This ensures, that all devices are disassembled and unmounted cleanly.
+
= User Manual
== Creating an initramfs Image
A shortcut to generate the image at the default location for a specific kernel
version is:
----
-# dracut '' 2.6.40-1.rc5.f20
+# dracut --kver 2.6.40-1.rc5.f20
----
If you want to create lighter, smaller initramfs images, you may want to specify
The --include option let you specify a source path and a target path. For example
----
-# dracut --include cmdline-preset /etc/cmdline initramfs-cmdline-pre.img
+# 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_. --include can only be specified once.
+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
-# echo "ip=auto" >> rd.live.overlay/etc/cmdline
-# echo export TESTVAR=testtest >> rd.live.overlay/etc/conf.d/testvar.conf
-# echo export TESTVAR=testtest >> rd.live.overlay/etc/conf.d/testvar.conf
+# 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
- └── conf.d
- └── testvar.conf
+ ├── cmdline.d
+ │ └── mycmdline.conf
+ └── conf.d
+ └── testvar.conf
+
# dracut --include rd.live.overlay / initramfs-rd.live.overlay.img
----
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 rd.ip=auto on the kernel command line, then dracut asks a dhcp
+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_, with a method described
+kernel command line, then you can inject _/etc/cmdline.d/mycmdline.conf_, with a method described
in <<Injecting>>.
# 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
* 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
+command
+
----
# dmsetup ls --tree
----
+
-* A list of block device attributes including vol_id compatible mode. This can
-be obtained by running the commands:
+* A list of block device attributes. This can be obtained by running the commands:
+
----
# blkid -p
As well as the information from <<all-bug-reports>> include the following
information:
-* Include physical volume information by running the command:
+* Include physical volume information by running the command:
+
----
# lvm pvdisplay
----
+
-* Include volume group information by running the command:
+* Include volume group information by running the command:
+
----
# lvm vgdisplay
----
+
-* Include logical volume information by running the command:
+* Include logical volume information by running the command:
+
----
# lvm lvdisplay
As well as the information from <<all-bug-reports>>, include the following
information:
-* If using software RAID disk partitions, please include the output of
+* If using software RAID disk partitions, please include the output of
+
----
# cat /proc/mdstat
[[using-the-dracut-shell]]
==== Using the dracut shell
-Dracut offers a shell for interactive debugging in the event dracut fails to
+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
No root device found
Dropping to debug shell.
-#
+#
----
+
. Use this shell prompt to gather the information requested above (see <<all-bug-reports>>).
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.
+LVM Logical volume.
. Inspect your partitions using parted
+
----
+
. You recall that your root volume was a LVM logical volume. Scan and activate
-any logical volumes.
+any logical volumes.
+
----
# lvm vgscan
# 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.
+Key slot 0 unlocked.
----
+
. Next, make a symbolic link to the unlocked root volume
[[stages]]
== Boot Process Stages
-The init script in _99base_ is the main script, which prepares the root file
-system for usage, runs udev, mounts the real root device, kills the remaining
-processes, and switches to the real root device for further booting. dracut
-modules can insert custom script at various points, to control the boot process.
+dracut modules can insert custom script at various points, to control the boot
+process.
These hooks are plain directories containing shell scripts ending with ".sh",
which are sourced by init.
-Common used functions are in _dracut-lib.sh_, which can be sourced by any script.
-
-
-
-=== Basic Setup
-
-The first thing init does, is to mount _/proc_ and _/sys_ and manually create
-the basic device nodes and symbolic links in _/dev_ needed to execute basic
-commands. Then logging is setup according to kernel command line arguments.
-_/dev/pts_ and _/dev/shm_ are mounted and the first hook is sourced.
-
-
+Common used functions are in _dracut-lib.sh_, which can be sourced by any script.
=== Hook: cmdline
rootok were set. Here modules can take action with the final root, and before
udev has been run.
-
-
=== Start Udev
Now udev is started and the logging for udev is setup.
-
-
=== Hook: pre-trigger
In this hook, you can set udev environment variables with **udevadm control
--property=KEY=_value_** or control the further execution of udev with
udevadm.
-
-
=== Trigger Udev
udev is triggered by calling udevadm trigger, which sends add events for all
-devices and subsystems.
-
-
+devices and subsystems.
=== Main Loop
-Now the main loop of 99base/init begins. Here we loop until udev has settled and
-all scripts in _initqueue/finished_ returned true. In this loop there are three
-hooks, where scripts can be inserted by calling /sbin/initqueue.
-
-
+In the main loop of dracut loops until udev has settled and
+all scripts in _initqueue/finished_ returned true.
+In this loop there are three hooks, where scripts can be inserted
+by calling /sbin/initqueue.
==== Initqueue
This hook gets executed every time a script is inserted here, regardless of the
udev state.
-
-
==== Initqueue settled
-This hooks gets executed every time udev has settled.
-
+This hooks (initqueue/settled) gets executed every time udev has settled.
==== Initqueue timeout
-This hooks gets executed, when the main loop counter becomes half of the
+This hooks (initqueue/timeout) gets executed, when the main loop counter becomes half of the
rd.retry counter.
-
-
==== Initqueue finished
-This hook is called after udev has settled and if all scripts herein return 0
-the main loop will be ended.
-
-
+This hook (initqueue/finished) is called after udev has settled and
+if all scripts herein return 0 the main loop will be ended.
+Abritary scripts can be added here, to loop in the
+initqueue until something happens, which a dracut module wants to wait for.
=== Hook: pre-mount
executed. In some cases (e.g. NFS) the real root device is already mounted,
though.
-
-
=== Hook: mount
This hook is mainly to mount the real root device.
+=== Hook: pre-pivot
+This hook is called before cleanup hook, This is a good place for
+actions other than cleanups which need to be called before pivot.
-=== Hook: pre-pivot
+=== Hook: cleanup
This hook is the last hook and is called before init finally switches root to
the real root device. This is a good place to clean up and kill processes not
needed anymore.
-
=== Cleanup and switch_root
-Init kills all udev processes, cleans up the environment, sets up the arguments
-for the real init process and finally calls switch_root. switch_root removes the
-whole filesystem hierarchy of the initramfs, chroot()s to the real root device
-and calls /sbin/init with the specified arguments.
+Init (or systemd) kills all udev processes, cleans up the environment,
+sets up the arguments for the real init process and finally calls switch_root.
+switch_root removes the whole filesystem hierarchy of the initramfs,
+chroot()s to the real root device and calls /sbin/init with the specified arguments.
To ensure all files in the initramfs hierarchy can be removed, all processes
still running from the initramfs should not have any open file descriptors left.
-
-
== Network Infrastructure
-
FIXME
-
== Writing a Module
A simple example module is _96insmodpost_, which modprobes a kernel module after
module should be included by default.
check():
-
-
----
return 0
----
_insmodpost.sh_ script in _/sbin_.
install():
-
-
----
inst_hook cmdline 20 "$moddir/parse-insmodpost.sh"
inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh
hook _insmodpost.sh_ in the _initqueue/settled_.
_parse-insmodpost.sh_:
-
-
----
for p in $(getargs rd.driver.post=); do
echo "blacklist $p" >> /etc/modprobe.d/initramfsblacklist.conf
parameters. It runs after udev has settled and is only called once (--onetime).
_insmodpost.sh_:
-
-
----
. /lib/dracut-lib.sh
=== install()
-dracut_install
+inst_multiple
inst
=== Creation Functions
-
FIXME
=== Initramfs Functions
-
FIXME
FIXME
+:leveloffset: 1
+[[dracutbootup7]]
+include::dracut.bootup.7.asc[]
+
+:leveloffset: 1
[[dracut8]]
include::dracut.8.asc[]
[[dracutcmdline7]]
include::dracut.cmdline.7.asc[]
+[[lsinitrd1]]
+include::lsinitrd.1.asc[]
+
+[[mkinitrd8]]
+include::mkinitrd.8.asc[]
+
+:leveloffset: 0
[appendix]
License
-------
projects / platform / upstream / dracut.git / blobdiff