| DRACUT.MODULES(7) |
| ================= |
| :doctype: manpage |
| :man source: dracut |
| :man manual: dracut |
| :man version: {version} |
| |
| NAME |
| ---- |
| dracut.modules - dracut modules |
| |
| DESCRIPTION |
| ----------- |
| |
| dracut uses a modular system to build and extend the initramfs image. All |
| modules are located in _/usr/lib/dracut/modules.d_ or in _<git-src>/modules.d_. |
| The most basic dracut module is _99base_. In _99base_ the initial shell script |
| init is defined, which gets run by the kernel after initramfs loading. Although |
| you can replace init with your own version of _99base_, this is not encouraged. |
| Instead you should use, if possible, the hooks of dracut. All hooks, and the |
| point of time in which they are executed, are described in <<stages>>. |
| |
| The main script, which creates the initramfs is dracut itself. It parses all |
| arguments and sets up the directory, in which everything is installed. It then |
| executes all check, install, installkernel scripts found in the modules, which |
| are to be processed. After everything is installed, the install directory is |
| archived and compressed to the final initramfs image. All helper functions used |
| by check, install and installkernel are found in in the file _dracut-functions_. |
| These shell functions are available to all module installer (install, |
| installkernel) scripts, without the need to source _dracut-functions_. |
| |
| A module can check the preconditions for install and installkernel with the |
| check script. Also dependencies can be expressed with check. If a module passed |
| check, install and installkernel will be called to install all of the necessary |
| files for the module. To split between kernel and non-kernel parts of the |
| installation, all kernel module related parts have to be in installkernel. All |
| other files found in a module directory are module specific and mostly are hook |
| scripts and udev rules. |
| |
| |
| [[stages]] |
| == Boot Process Stages |
| |
| 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. |
| |
| === Hook: cmdline |
| |
| The _cmdline_ hook is a place to insert scripts to parse the kernel command line |
| and prepare the later actions, like setting up udev rules and configuration |
| files. |
| |
| In this hook the most important environment variable is defined: root. The |
| second one is rootok, which indicates, that a module claimed to be able to parse |
| the root defined. So for example, **root=**__iscsi:....__ will be claimed by the |
| iscsi dracut module, which then sets rootok. |
| |
| === Hook: pre-udev |
| |
| This hook is executed right after the cmdline hook and a check if root and |
| 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. |
| |
| === Main Loop |
| |
| 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 hook (initqueue/settled) gets executed every time udev has settled. |
| |
| ==== Initqueue timeout |
| |
| This hook (initqueue/timeout) gets executed, when the main loop counter becomes |
| half of the rd.retry counter. |
| |
| ==== Initqueue online |
| |
| This hook (initqueue/online) gets executed whenever a network interface comes online |
| (that is, once it is up and configured by the configured network module). |
| |
| ==== Initqueue finished |
| |
| This hook (initqueue/finished) is called after udev has settled and |
| if all scripts herein return 0 the main loop will be ended. |
| Arbitrary scripts can be added here, to loop in the |
| initqueue until something happens, which a dracut module wants to wait for. |
| |
| === Hook: pre-mount |
| |
| Before the root device is mounted all scripts in the hook pre-mount are |
| 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: 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 (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 _90kernel-modules_, which modprobes a kernel module |
| after udev has settled and the basic device drivers have been loaded. |
| |
| All module installation information is in the file module-setup.sh. |
| |
| First we create a check() function, which just exits with 0 indicating that this |
| module should be included by default. |
| |
| check(): |
| ---- |
| return 0 |
| ---- |
| |
| Then we create the install() function, which installs a cmdline hook with |
| priority number 20 called _parse-insmodpost.sh_. It also installs the |
| _insmodpost.sh_ script in _/sbin_. |
| |
| install(): |
| ---- |
| inst_hook cmdline 20 "$moddir/parse-insmodpost.sh" |
| inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh |
| ---- |
| |
| The _parse-instmodpost.sh_ parses the kernel command line for a argument |
| rd.driver.post, blacklists the module from being autoloaded and installs the |
| 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 |
| _do_insmodpost=1 |
| done |
| |
| [ -n "$_do_insmodpost" ] && /sbin/initqueue --settled --unique --onetime /sbin/insmodpost.sh |
| unset _do_insmodpost |
| |
| ---- |
| |
| _insmodpost.sh_, which is called in the _initqueue/settled_ hook will just |
| modprobe the kernel modules specified in all rd.driver.post kernel command line |
| parameters. It runs after udev has settled and is only called once (--onetime). |
| |
| _insmodpost.sh_: |
| ---- |
| . /lib/dracut-lib.sh |
| |
| for p in $(getargs rd.driver.post=); do |
| modprobe $p |
| done |
| |
| ---- |
| |
| |
| === module-setup.sh: check() |
| |
| _check()_ is called by dracut to evaluate the inclusion of a dracut module in |
| the initramfs. |
| |
| $hostonly:: If the $hostonly variable is set, then the module check() function |
| should be in "hostonly" mode, which means, that the check() should only return |
| 0, if the module is really needed to boot this specific host. |
| |
| check() should return with: |
| |
| 0:: Include the dracut module in the initramfs. |
| |
| 1:: Do not include the dracut module. The requirements are not fulfilled |
| (missing tools, etc.) |
| |
| 255:: Only include the dracut module, if another module requires it or if |
| explicitly specified in the config file or on the argument list. |
| |
| |
| === module-setup.sh: depends() |
| |
| The function depends() should echo all other dracut module names the module |
| depends on. |
| |
| === module-setup.sh: cmdline() |
| |
| This function should print the kernel command line options needed to boot the |
| current machine setup. It should start with a space and should not print a |
| newline. |
| |
| === module-setup.sh: install() |
| |
| The install() function is called to install everything non-kernel related. |
| To install binaries, scripts, and other files, you can use the functions |
| mentioned in <<creation>>. |
| |
| To address a file in the current module directory, use the variable "$moddir". |
| |
| === module-setup.sh: installkernel() |
| |
| In installkernel() all kernel related files should be installed. You can use all |
| of the functions mentioned in <<creation>> to install files. |
| |
| === [[creation]]Creation Functions |
| |
| ==== inst_multiple [-o] <file> [ <file> ...] |
| |
| installs multiple binaries and files. If executables are specified without a |
| path, dracut will search the path PATH=/usr/sbin:/sbin:/usr/bin:/bin for the |
| binary. If the option "-o" is given as the first parameter, a missing file does |
| not lead to an error. |
| |
| ==== inst <src> [<dst>] |
| |
| installs _one_ file <src> either to the same place in the initramfs or to an |
| optional <dst>. inst with more than two arguments is treated the same as |
| inst_multiple, all arguments are treated as files to install and none as |
| install destinations. |
| |
| ==== inst_hook <hookdir> <prio> <src> |
| |
| installs an executable/script <src> in the dracut hook <hookdir> with priority |
| <prio>. |
| |
| ==== inst_rules <udevrule> [ <udevrule> ...] |
| |
| installs one or more udev rules. Non-existant udev rules are reported, but do |
| not let dracut fail. |
| |
| ==== instmods <kernelmodule> [ <kernelmodule> ... ] |
| |
| instmods should be used only in the installkernel() function. |
| |
| instmods installs one or more kernel modules in the initramfs. <kernelmodule> |
| can also be a whole subsystem, if prefixed with a "=", like "=drivers/net/team". |
| |
| instmods will not install the kernel module, if $hostonly is set and the kernel |
| module is not currently needed by any /sys/*...*/uevent MODALIAS. |
| To install a kernel module regardless of the hostonly mode use the form: |
| ---- |
| hostonly='' instmods <kernelmodule> |
| ---- |
| |
| === Initramfs Functions |
| |
| FIXME |
| |
| |
| === Network Modules |
| |
| FIXME |
| |
| AUTHOR |
| ------ |
| Harald Hoyer |
| |
| SEE ALSO |
| -------- |
| *dracut*(8) |