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