dracut.modules.7.asc

   1 DRACUT.MODULES(7)
   2 =================
   3 :doctype: manpage
   4 :man source:   dracut
   5 :man manual:   dracut
   6
   7 NAME
   8 ----
   9 dracut.modules - dracut modules
  10
  11 DESCRIPTION
  12 -----------
  13
  14 dracut uses a modular system to build and extend the initramfs image. All
  15 modules are located in _/usr/lib/dracut/modules.d_ or in _<git-src>/modules.d_.
  16 The most basic dracut module is _99base_. In _99base_ the initial shell script
  17 init is defined, which gets run by the kernel after initramfs loading. Although
  18 you can replace init with your own version of _99base_, this is not encouraged.
  19 Instead you should use, if possible, the hooks of dracut. All hooks, and the
  20 point of time in which they are executed, are described in <<stages>>.
  21
  22 The main script, which creates the initramfs is dracut itself. It parses all
  23 arguments and sets up the directory, in which everything is installed. It then
  24 executes all check, install, installkernel scripts found in the modules, which
  25 are to be processed. After everything is installed, the install directory is
  26 archived and compressed to the final initramfs image. All helper functions used
  27 by check, install and installkernel are found in in the file _dracut-functions_.
  28 These shell functions are available to all module installer (install,
  29 installkernel) scripts, without the need to source _dracut-functions_.
  30
  31 A module can check the preconditions for install and installkernel with the
  32 check script. Also dependencies can be expressed with check. If a module passed
  33 check, install and installkernel will be called to install all of the necessary
  34 files for the module. To split between kernel and non-kernel parts of the
  35 installation, all kernel module related parts have to be in installkernel. All
  36 other files found in a module directory are module specific and mostly are hook
  37 scripts and udev rules.
  38
  39
  40 [[stages]]
  41 == Boot Process Stages
  42
  43 dracut modules can insert custom script at various points, to control the boot
  44 process.
  45 These hooks are plain directories containing shell scripts ending with ".sh",
  46 which are sourced by init.
  47 Common used functions are in _dracut-lib.sh_, which can be sourced by any script.
  48
  49 === Hook: cmdline
  50
  51 The _cmdline_ hook is a place to insert scripts to parse the kernel command line
  52 and prepare the later actions, like setting up udev rules and configuration
  53 files.
  54
  55 In this hook the most important environment variable is defined: root. The
  56 second one is rootok, which indicates, that a module claimed to be able to parse
  57 the root defined. So for example, **root=**__iscsi:....__ will be claimed by the
  58 iscsi dracut module, which then sets rootok.
  59
  60 === Hook: pre-udev
  61
  62 This hook is executed right after the cmdline hook and a check if root and
  63 rootok were set. Here modules can take action with the final root, and before
  64 udev has been run.
  65
  66 === Start Udev
  67
  68 Now udev is started and the logging for udev is setup.
  69
  70 === Hook: pre-trigger
  71
  72 In this hook, you can set udev environment variables with **udevadm control
  73 --property=KEY=_value_** or control the further execution of udev with
  74 udevadm.
  75
  76 === Trigger Udev
  77
  78 udev is triggered by calling udevadm trigger, which sends add events for all
  79 devices and subsystems.
  80
  81 === Main Loop
  82
  83 In the main loop of dracut loops until udev has settled and
  84 all scripts in _initqueue/finished_ returned true.
  85 In this loop there are three hooks, where scripts can be inserted
  86 by calling /sbin/initqueue.
  87
  88 ==== Initqueue
  89
  90 This hook gets executed every time a script is inserted here, regardless of the
  91 udev state.
  92
  93 ==== Initqueue settled
  94
  95 This hooks (initqueue/settled) gets executed every time udev has settled.
  96
  97 ==== Initqueue timeout
  98
  99 This hooks (initqueue/timeout) gets executed, when the main loop counter becomes
 100 half of the rd.retry counter.
 101
 102 ==== Initqueue finished
 103
 104 This hook (initqueue/finished) is called after udev has settled and
 105 if all scripts herein return 0 the main loop will be ended.
 106 Abritary scripts can be added here, to loop in the
 107 initqueue until something happens, which a dracut module wants to wait for.
 108
 109 === Hook: pre-mount
 110
 111 Before the root device is mounted all scripts in the hook pre-mount are
 112 executed. In some cases (e.g. NFS) the real root device is already mounted,
 113 though.
 114
 115 === Hook: mount
 116
 117 This hook is mainly to mount the real root device.
 118
 119 === Hook: pre-pivot
 120
 121 This hook is called before cleanup hook, This is a good place for
 122 actions other than cleanups which need to be called before pivot.
 123
 124 === Hook: cleanup
 125
 126 This hook is the last hook and is called before init finally switches root to
 127 the real root device. This is a good place to clean up and kill processes not
 128 needed anymore.
 129
 130
 131 === Cleanup and switch_root
 132
 133 Init (or systemd) kills all udev processes, cleans up the environment,
 134 sets up the arguments for the real init process and finally calls switch_root.
 135 switch_root removes the whole filesystem hierarchy of the initramfs,
 136 chroot()s to the real root device and calls /sbin/init with the specified
 137 arguments.
 138
 139 To ensure all files in the initramfs hierarchy can be removed, all processes
 140 still running from the initramfs should not have any open file descriptors left.
 141
 142 == Network Infrastructure
 143
 144 FIXME
 145
 146 == Writing a Module
 147
 148 A simple example module is _96insmodpost_, which modprobes a kernel module after
 149 udev has settled and the basic device drivers have been loaded.
 150
 151 All module installation information is in the file module-setup.sh.
 152
 153 First we create a check() function, which just exits with 0 indicating that this
 154 module should be included by default.
 155
 156 check():
 157 ----
 158 return 0
 159 ----
 160
 161 The we create the install() function, which installs a cmdline hook with
 162 priority number 20 called _parse-insmodpost.sh_. It also installs the
 163 _insmodpost.sh_ script in _/sbin_.
 164
 165 install():
 166 ----
 167 inst_hook cmdline 20 "$moddir/parse-insmodpost.sh"
 168 inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh
 169 ----
 170
 171 The _parse-instmodpost.sh_ parses the kernel command line for a argument
 172 rd.driver.post, blacklists the module from being autoloaded and installs the
 173 hook _insmodpost.sh_ in the _initqueue/settled_.
 174
 175 _parse-insmodpost.sh_:
 176 ----
 177 for p in $(getargs rd.driver.post=); do
 178     echo "blacklist $p" >> /etc/modprobe.d/initramfsblacklist.conf
 179     _do_insmodpost=1
 180 done
 181
 182 [ -n "$_do_insmodpost" ] && /sbin/initqueue --settled --unique --onetime /sbin/insmodpost.sh
 183 unset _do_insmodpost
 184
 185 ----
 186
 187 _insmodpost.sh_, which is called in the _initqueue/settled_ hook will just
 188 modprobe the kernel modules specified in all rd.driver.post kernel command line
 189 parameters. It runs after udev has settled and is only called once (--onetime).
 190
 191 _insmodpost.sh_:
 192 ----
 193 . /lib/dracut-lib.sh
 194
 195 for p in $(getargs rd.driver.post=); do
 196     modprobe $p
 197 done
 198
 199 ----
 200
 201
 202 === module-setup.sh: check()
 203
 204 _check()_ is called by dracut to evaluate the inclusion of a dracut module in
 205 the initramfs.
 206
 207 $hostonly:: If the $hostonly variable is set, then the module check() function
 208 should be in "hostonly" mode, which means, that the check() should only return
 209 0, if the module is really needed to boot this specific host.
 210
 211 check() should return with:
 212
 213 0:: Include the dracut module in the initramfs.
 214
 215 1:: Do not include the dracut module. The requirements are not fulfilled
 216 (missing tools, etc.)
 217
 218 255:: Only include the dracut module, if another module requires it or if
 219 explicitly specified in the config file or on the argument list.
 220
 221
 222 === module-setup.sh: depends()
 223
 224 The function depends() should echo all other dracut module names the module
 225 depends on.
 226
 227 === module-setup.sh: cmdline()
 228
 229 This function should print the kernel command line options needed to boot the
 230 current machine setup. It should start with a space and should not print a
 231 newline.
 232
 233 === module-setup.sh: install()
 234
 235 The install() function is called to install everything non-kernel related.
 236 To install binaries, scripts, and other files, you can use the functions
 237 mentioned in <<creation>>.
 238
 239 To address a file in the current module directory, use the variable "$moddir".
 240
 241 === module-setup.sh: installkernel()
 242
 243 In installkernel() all kernel related files should be installed. You can use all
 244 of the functions mentioned in <<creation>> to install files.
 245
 246 === [[creation]]Creation Functions
 247
 248 ==== inst_multiple [-o] <file> [ <file> ...]
 249
 250 installs multiple binaries and files. If executables are specified without a
 251 path, dracut will search the path PATH=/usr/sbin:/sbin:/usr/bin:/bin for the
 252 binary. If the option "-o" is given as the first parameter, a missing file does
 253 not lead to an error.
 254
 255 ==== inst <src> [<dst>]
 256
 257 installs _one_ file <src> either to the same place in the initramfs or to an
 258 optional <dst>. inst with more than two arguments is treated the same as
 259 inst_multiple, all arguments are treated as files to install and none as
 260 install destinations.
 261
 262 ==== inst_hook <hookdir> <prio> <src>
 263
 264 installs an executable/script <src> in the dracut hook <hookdir> with priority
 265 <prio>.
 266
 267 ==== inst_rules <udevrule> [ <udevrule> ...]
 268
 269 installs one or more udev rules. Non-existant udev rules are reported, but do
 270 not let dracut fail.
 271
 272 ==== instmods <kernelmodule> [ <kernelmodule> ... ]
 273
 274 instmods should be used only in the installkernel() function.
 275
 276 instmods installs one or more kernel modules in the initramfs. <kernelmodule>
 277 can also be a whole subsystem, if prefixed with a "=", like "=drivers/net/team".
 278
 279 instmods will not install the kernel module, if $hostonly is set and the kernel
 280 module is not currently needed by any /sys/*...*/uevent MODALIAS.
 281 To install a kernel module regardless of the hostonly mode use the form:
 282 ----
 283 hostonly='' instmods <kernelmodule>
 284 ----
 285
 286 === Initramfs Functions
 287
 288 FIXME
 289
 290
 291 === Network Modules
 292
 293 FIXME
 294
 295 AUTHOR
 296 ------
 297 Harald Hoyer
 298
 299 SEE ALSO
 300 --------
 301 *dracut*(8)