1DRACUT.MODULES(7)                   dracut                   DRACUT.MODULES(7)
2
3
4

NAME

6       dracut.modules - dracut modules
7

DESCRIPTION

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
19       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
29       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

BOOT PROCESS STAGES

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
44   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
49       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
54   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
59   Start Udev
60       Now udev is started and the logging for udev is setup.
61
62   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
67   Trigger Udev
68       udev is triggered by calling udevadm trigger, which sends add events
69       for all devices and subsystems.
70
71   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
76       Initqueue
77           This hook gets executed every time a script is inserted here,
78           regardless of the udev state.
79
80       Initqueue settled
81           This hook (initqueue/settled) gets executed every time udev has
82           settled.
83
84       Initqueue timeout
85           This hook (initqueue/timeout) gets executed, when the main loop
86           counter becomes half of the rd.retry counter.
87
88       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
93       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
99   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
104   Hook: mount
105       This hook is mainly to mount the real root device.
106
107   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
111   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
116   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
123       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

NETWORK INFRASTRUCTURE

128       FIXME
129

WRITING A MODULE

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
135       All module installation information is in the file module-setup.sh.
136
137       First we create a check() function, which just exits with 0 indicating
138       that this module should be included by default.
139
140       check():
141
142           return 0
143
144       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
148       install():
149
150           inst_hook cmdline 20 "$moddir/parse-insmodpost.sh"
151           inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh
152
153       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
157       parse-insmodpost.sh:
158
159           for p in $(getargs rd.driver.post=); do
160               echo "blacklist $p" >> /etc/modprobe.d/initramfsblacklist.conf
161               _do_insmodpost=1
162           done
163
164           [ -n "$_do_insmodpost" ] && /sbin/initqueue --settled --unique --onetime /sbin/insmodpost.sh
165           unset _do_insmodpost
166
167       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
172       insmodpost.sh:
173
174           . /lib/dracut-lib.sh
175
176           for p in $(getargs rd.driver.post=); do
177               modprobe $p
178           done
179
180   module-setup.sh: check()
181       check() is called by dracut to evaluate the inclusion of a dracut
182       module in the initramfs.
183
184       $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
190       check() should return with:
191
192       0
193           Include the dracut module in the initramfs.
194
195       1
196           Do not include the dracut module. The requirements are not
197           fulfilled (missing tools, etc.)
198
199       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
203   module-setup.sh: depends()
204       The function depends() should echo all other dracut module names the
205       module depends on.
206
207   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
212   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
217       To address a file in the current module directory, use the variable
218       "$moddir".
219
220   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
224   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
232       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
238       inst_hook <hookdir> <prio> <src>
239           installs an executable/script <src> in the dracut hook <hookdir>
240           with priority <prio>.
241
242       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
246       instmods <kernelmodule> [ <kernelmodule> ... ]
247           instmods should be used only in the installkernel() function.
248
249           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
253           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
258               hostonly='' instmods <kernelmodule>
259
260   Initramfs Functions
261       FIXME
262
263   Network Modules
264       FIXME
265

AUTHOR

267       Harald Hoyer
268

SEE ALSO

270       dracut(8)
271
272
273
274dracut 054-2-gb9b6f0ee            05/17/2021                 DRACUT.MODULES(7)
Impressum