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 hooks (initqueue/settled) gets executed every time udev has
82           settled.
83
84       Initqueue timeout
85           This hooks (initqueue/timeout) gets executed, when the main loop
86           counter becomes half of the rd.retry counter.
87
88       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
94   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
99   Hook: mount
100       This hook is mainly to mount the real root device.
101
102   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
106   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
111   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
118       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

NETWORK INFRASTRUCTURE

123       FIXME
124

WRITING A MODULE

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
130       All module installation information is in the file module-setup.sh.
131
132       First we create a check() function, which just exits with 0 indicating
133       that this module should be included by default.
134
135       check():
136
137           return 0
138
139       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
143       install():
144
145           inst_hook cmdline 20 "$moddir/parse-insmodpost.sh"
146           inst_simple "$moddir/insmodpost.sh" /sbin/insmodpost.sh
147
148       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
152       parse-insmodpost.sh:
153
154           for p in $(getargs rd.driver.post=); do
155               echo "blacklist $p" >> /etc/modprobe.d/initramfsblacklist.conf
156               _do_insmodpost=1
157           done
158
159           [ -n "$_do_insmodpost" ] && /sbin/initqueue --settled --unique --onetime /sbin/insmodpost.sh
160           unset _do_insmodpost
161
162       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
167       insmodpost.sh:
168
169           . /lib/dracut-lib.sh
170
171           for p in $(getargs rd.driver.post=); do
172               modprobe $p
173           done
174
175   module-setup.sh: check()
176       check() is called by dracut to evaluate the inclusion of a dracut
177       module in the initramfs.
178
179       $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
185       check() should return with:
186
187       0
188           Include the dracut module in the initramfs.
189
190       1
191           Do not include the dracut module. The requirements are not
192           fulfilled (missing tools, etc.)
193
194       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
198   module-setup.sh: depends()
199       The function depends() should echo all other dracut module names the
200       module depends on.
201
202   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
207   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
212       To address a file in the current module directory, use the variable
213       "$moddir".
214
215   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
219   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
227       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
233       inst_hook <hookdir> <prio> <src>
234           installs an executable/script <src> in the dracut hook <hookdir>
235           with priority <prio>.
236
237       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
241       instmods <kernelmodule> [ <kernelmodule> ... ]
242           instmods should be used only in the installkernel() function.
243
244           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
248           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
253               hostonly='' instmods <kernelmodule>
254
255   Initramfs Functions
256       FIXME
257
258   Network Modules
259       FIXME
260

AUTHOR

262       Harald Hoyer
263

SEE ALSO

265       dracut(8)
266
267
268
269dracut                            07/24/2019                 DRACUT.MODULES(7)
Impressum