]>
Commit | Line | Data |
---|---|---|
b6c89768 HH |
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 | == dracut Components | |
14 | ||
15 | dracut uses a modular system to build and extend the initramfs image. All | |
16 | modules are located in _/usr/lib/dracut/modules.d_ or in _<git-src>/modules.d_. | |
17 | The most basic dracut module is _99base_. In _99base_ the initial shell script | |
18 | init is defined, which gets run by the kernel after initramfs loading. Although | |
19 | you can replace init with your own version of _99base_, this is not encouraged. | |
20 | Instead you should use, if possible, the hooks of dracut. All hooks, and the | |
21 | point of time in which they are executed, are described in <<stages>>. | |
22 | ||
23 | The main script, which creates the initramfs is dracut itsself. It parses all | |
24 | arguments and sets up the directory, in which everything is installed. It then | |
25 | executes all check, install, installkernel scripts found in the modules, which | |
26 | are to be processed. After everything is installed, the install directory is | |
27 | archived and compressed to the final initramfs image. All helper functions used | |
28 | by check, install and installkernel are found in in the file _dracut-functions_. | |
29 | These shell functions are available to all module installer (install, | |
30 | installkernel) scripts, without the need to source _dracut-functions_. | |
31 | ||
32 | A module can check the preconditions for install and installkernel with the | |
33 | check script. Also dependencies can be expressed with check. If a module passed | |
34 | check, install and installkernel will be called to install all of the necessary | |
35 | files for the module. To split between kernel and non-kernel parts of the | |
36 | installation, all kernel module related parts have to be in installkernel. All | |
37 | other files found in a module directory are module specific and mostly are hook | |
38 | scripts and udev rules. | |
39 | ||
40 | ||
41 | [[stages]] | |
42 | == Boot Process Stages | |
43 | ||
44 | dracut modules can insert custom script at various points, to control the boot | |
45 | process. | |
46 | These hooks are plain directories containing shell scripts ending with ".sh", | |
47 | which are sourced by init. | |
48 | Common used functions are in _dracut-lib.sh_, which can be sourced by any script. | |
49 | ||
50 | === Hook: cmdline | |
51 | ||
52 | The _cmdline_ hook is a place to insert scripts to parse the kernel command line | |
53 | and prepare the later actions, like setting up udev rules and configuration | |
54 | files. | |
55 | ||
56 | In this hook the most important environment variable is defined: root. The | |
57 | second one is rootok, which indicates, that a module claimed to be able to parse | |
58 | the root defined. So for example, **root=**__iscsi:....__ will be claimed by the | |
59 | iscsi dracut module, which then sets rootok. | |
60 | ||
61 | === Hook: pre-udev | |
62 | ||
63 | This hook is executed right after the cmdline hook and a check if root and | |
64 | rootok were set. Here modules can take action with the final root, and before | |
65 | udev has been run. | |
66 | ||
67 | === Start Udev | |
68 | ||
69 | Now udev is started and the logging for udev is setup. | |
70 | ||
71 | === Hook: pre-trigger | |
72 | ||
73 | In this hook, you can set udev environment variables with **udevadm control | |
74 | --property=KEY=_value_** or control the further execution of udev with | |
75 | udevadm. | |
76 | ||
77 | === Trigger Udev | |
78 | ||
79 | udev is triggered by calling udevadm trigger, which sends add events for all | |
80 | devices and subsystems. | |
81 | ||
82 | === Main Loop | |
83 | ||
84 | In the main loop of dracut loops until udev has settled and | |
85 | all scripts in _initqueue/finished_ returned true. | |
86 | In this loop there are three hooks, where scripts can be inserted | |
87 | by calling /sbin/initqueue. | |
88 | ||
89 | ==== Initqueue | |
90 | ||
91 | This hook gets executed every time a script is inserted here, regardless of the | |
92 | udev state. | |
93 | ||
94 | ==== Initqueue settled | |
95 | ||
96 | This hooks (initqueue/settled) gets executed every time udev has settled. | |
97 | ||
98 | ==== Initqueue timeout | |
99 | ||
100 | This hooks (initqueue/timeout) gets executed, when the main loop counter becomes half of the | |
101 | rd.retry counter. | |
102 | ||
103 | ==== Initqueue finished | |
104 | ||
105 | This hook (initqueue/finished) is called after udev has settled and | |
106 | if all scripts herein return 0 the main loop will be ended. | |
107 | Abritary scripts can be added here, to loop in the | |
108 | initqueue until something happens, which a dracut module wants to wait for. | |
109 | ||
110 | === Hook: pre-mount | |
111 | ||
112 | Before the root device is mounted all scripts in the hook pre-mount are | |
113 | executed. In some cases (e.g. NFS) the real root device is already mounted, | |
114 | though. | |
115 | ||
116 | === Hook: mount | |
117 | ||
118 | This hook is mainly to mount the real root device. | |
119 | ||
120 | === Hook: pre-pivot | |
121 | ||
122 | This hook is called before cleanup hook, This is a good place for | |
123 | actions other than cleanups which need to be called before pivot. | |
124 | ||
125 | === Hook: cleanup | |
126 | ||
127 | This hook is the last hook and is called before init finally switches root to | |
128 | the real root device. This is a good place to clean up and kill processes not | |
129 | needed anymore. | |
130 | ||
131 | ||
132 | === Cleanup and switch_root | |
133 | ||
134 | Init (or systemd) kills all udev processes, cleans up the environment, | |
135 | sets up the arguments for the real init process and finally calls switch_root. | |
136 | switch_root removes the whole filesystem hierarchy of the initramfs, | |
137 | chroot()s to the real root device and calls /sbin/init with the specified 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 _pase-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 fullfilled | |
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 current | |
230 | machine setup. It should start with a space and should not print a newline. | |
231 | ||
232 | === module-setup.sh: install() | |
233 | ||
234 | The install() function is called to install everything non-kernel related. To install | |
235 | binaries, scripts, and other files, you can use the functions mentioned in <<creation>>. | |
236 | ||
237 | To address a file in the current module directory, use the variable "$moddir". | |
238 | ||
239 | === module-setup.sh: installkernel() | |
240 | ||
241 | In installkernel() all kernel related files should be installed. You can use all of the functions | |
242 | mentioned in <<creation>> to install files. | |
243 | ||
244 | === [[creation]]Creation Functions | |
245 | ||
246 | ==== inst_multiple [-o] <file> [ <file> ...] | |
247 | ||
248 | installs multiple binaries and files. If executables are specified without a path, dracut | |
249 | will search the path PATH=/usr/sbin:/sbin:/usr/bin:/bin for the binary. If the option "-o" | |
250 | is given as the first parameter, a missing file does not lead to an error. | |
251 | ||
252 | ==== inst <src> [<dst>] | |
253 | ||
254 | installs _one_ file <src> either to the same place in the initramfs or to an optional <dst>. | |
255 | ||
256 | ==== inst_hook <hookdir> <prio> <src> | |
257 | ||
258 | installs an executable/script <src> in the dracut hook <hookdir> with priority <prio>. | |
259 | ||
260 | ==== inst_rules <udevrule> [ <udevrule> ...] | |
261 | ||
262 | installs one ore more udev rules. Non-existant udev rules are reported, but do not let dracut fail. | |
263 | ||
264 | ==== instmods <kernelmodule> [ <kernelmodule> ... ] | |
265 | ||
266 | instmods should be used only in the installkernel() function. | |
267 | ||
268 | instmods installs one or more kernel modules in the initramfs. <kernelmodule> can also be a whole | |
269 | subsystem, if prefixed with a "=", like "=drivers/net/team". | |
270 | ||
271 | instmods will not install the kernel module, if $hostonly is set and the kernel module is not currently | |
272 | needed by any /sys/*...*/uevent MODALIAS. | |
273 | To install a kernel module regardless of the hostonly mode use the form: | |
274 | ---- | |
275 | hostonly='' instmods <kernelmodule> | |
276 | ---- | |
277 | ||
278 | === Initramfs Functions | |
279 | ||
280 | FIXME | |
281 | ||
282 | ||
283 | === Network Modules | |
284 | ||
285 | FIXME | |
286 | ||
287 | AUTHOR | |
288 | ------ | |
289 | Harald Hoyer | |
290 | ||
291 | SEE ALSO | |
292 | -------- | |
293 | *dracut*(8) |