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