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 hooks (initqueue/settled) gets executed every time udev has
82 settled.
83 Initqueue timeout
85 This hooks (initqueue/timeout) gets executed, when the main loop
86 counter becomes half of the rd.retry counter.
87 Initqueue finished
89 This hook (initqueue/finished) is called after udev has settled and
90 if all scripts herein return 0 the main loop will be ended.
91 Abritary scripts can be added here, to loop in the initqueue until
92 something happens, which a dracut module wants to wait for.
93 Hook: pre-mount
95 Before the root device is mounted all scripts in the hook pre-mount are
96 executed. In some cases (e.g. NFS) the real root device is already
97 mounted, though.
98 Hook: mount
100 This hook is mainly to mount the real root device.
101 Hook: pre-pivot
103 This hook is called before cleanup hook, This is a good place for
104 actions other than cleanups which need to be called before pivot.
105 Hook: cleanup
107 This hook is the last hook and is called before init finally switches
108 root to the real root device. This is a good place to clean up and kill
109 processes not needed anymore.
110 Cleanup and switch_root
112 Init (or systemd) kills all udev processes, cleans up the environment,
113 sets up the arguments for the real init process and finally calls
114 switch_root. switch_root removes the whole filesystem hierarchy of the
115 initramfs, chroot()s to the real root device and calls /sbin/init with
116 the specified arguments.
117 To ensure all files in the initramfs hierarchy can be removed, all
119 processes still running from the initramfs should not have any open
120 file descriptors left.
121
123 FIXME
124
126 A simple example module is 96insmodpost, which modprobes a kernel
127 module after udev has settled and the basic device drivers have been
128 loaded.
129 All module installation information is in the file module-setup.sh.
131 First we create a check() function, which just exits with 0 indicating
133 that this module should be included by default.
134 check():
136 return 0
138 The we create the install() function, which installs a cmdline hook
140 with priority number 20 called parse-insmodpost.sh. It also installs
141 the insmodpost.sh script in /sbin.
142 install():
144 inst_hook cmdline 20 "$moddir/parse-insmodpost.sh"
146 inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh
147 The parse-instmodpost.sh parses the kernel command line for a argument
149 rd.driver.post, blacklists the module from being autoloaded and
150 installs the hook insmodpost.sh in the initqueue/settled.
151 parse-insmodpost.sh:
153 for p in $(getargs rd.driver.post=); do
155 echo "blacklist $p" >> /etc/modprobe.d/initramfsblacklist.conf
156 _do_insmodpost=1
157 done
158 [ -n "$_do_insmodpost" ] && /sbin/initqueue --settled --unique --onetime /sbin/insmodpost.sh
160 unset _do_insmodpost
161 insmodpost.sh, which is called in the initqueue/settled hook will just
163 modprobe the kernel modules specified in all rd.driver.post kernel
164 command line parameters. It runs after udev has settled and is only
165 called once (--onetime).
166 insmodpost.sh:
168 . /lib/dracut-lib.sh
170 for p in $(getargs rd.driver.post=); do
172 modprobe $p
173 done
174 module-setup.sh: check()
176 check() is called by dracut to evaluate the inclusion of a dracut
177 module in the initramfs.
178 $hostonly
180 If the $hostonly variable is set, then the module check() function
181 should be in "hostonly" mode, which means, that the check() should
182 only return 0, if the module is really needed to boot this specific
183 host.
184 check() should return with:
186 0
188 Include the dracut module in the initramfs.
189 1
191 Do not include the dracut module. The requirements are not
192 fulfilled (missing tools, etc.)
193 255
195 Only include the dracut module, if another module requires it or if
196 explicitly specified in the config file or on the argument list.
197 module-setup.sh: depends()
199 The function depends() should echo all other dracut module names the
200 module depends on.
201 module-setup.sh: cmdline()
203 This function should print the kernel command line options needed to
204 boot the current machine setup. It should start with a space and should
205 not print a newline.
206 module-setup.sh: install()
208 The install() function is called to install everything non-kernel
209 related. To install binaries, scripts, and other files, you can use the
210 functions mentioned in [creation].
211 To address a file in the current module directory, use the variable
213 "$moddir".
214 module-setup.sh: installkernel()
216 In installkernel() all kernel related files should be installed. You
217 can use all of the functions mentioned in [creation] to install files.
218 Creation Functions
220 inst_multiple [-o] <file> [ <file> ...]
221 installs multiple binaries and files. If executables are specified
222 without a path, dracut will search the path
223 PATH=/usr/sbin:/sbin:/usr/bin:/bin for the binary. If the option
224 "-o" is given as the first parameter, a missing file does not lead
225 to an error.
226 inst <src> [<dst>]
228 installs one file <src> either to the same place in the initramfs
229 or to an optional <dst>. inst with more than two arguments is
230 treated the same as inst_multiple, all arguments are treated as
231 files to install and none as install destinations.
232 inst_hook <hookdir> <prio> <src>
234 installs an executable/script <src> in the dracut hook <hookdir>
235 with priority <prio>.
236 inst_rules <udevrule> [ <udevrule> ...]
238 installs one or more udev rules. Non-existant udev rules are
239 reported, but do not let dracut fail.
240 instmods <kernelmodule> [ <kernelmodule> ... ]
242 instmods should be used only in the installkernel() function.
243 instmods installs one or more kernel modules in the initramfs.
245 <kernelmodule> can also be a whole subsystem, if prefixed with a
246 "=", like "=drivers/net/team".
247 instmods will not install the kernel module, if $hostonly is set
249 and the kernel module is not currently needed by any
250 /sys/.../uevent MODALIAS. To install a kernel module regardless of
251 the hostonly mode use the form:
252 hostonly='' instmods <kernelmodule>
254 Initramfs Functions
256 FIXME
257 Network Modules
259 FIXME
260
262 Harald Hoyer
263
265 dracut(8)
266dracut 07/24/2019 DRACUT.MODULES(7)