SOME IMPORTANT NOTES ABOUT HOW DRACUT WORKS
===========================================
Will Woods <wwoods@redhat.com>
v1.0, August 2012
// vim: set syntax=asciidoc textwidth=78:
File locations / installation
-----------------------------
The files are installed into the initramfs according to the instructions in
`module-setup.sh`. So this line:
inst_hook cmdline 25 "$moddir/parse-anaconda-options.sh"
means that the file `parse-anaconda-options.sh` will be installed at priority
`25` in the `cmdline` hook. In practice, this means that it will be located at
/lib/dracut/hooks/cmdline/25-parse-anaconda-options.sh
inside the initramfs.
Hooks and script ordering
-------------------------
The hooks run in the following order:
cmdline::
This is where you parse (and _only_ parse) the boot commandline. Just
set up config files and do sanity checks; the real action is later.
pre-udev::
This is where you write out udev rules (before udev starts).
pre-trigger::
At this point udev is running but *kernel modules haven't been loaded*.
If you need to set udev environment variables, set them here.
initqueue::
This is the mainloop, where initramfs tries to find/fetch rootfs.
Scripts in this hook will run _repeatedly_ until finished or timeout (see
below). Runs at 0.5-second intervals.
initqueue/settled::
This part of the mainloop only runs once _udev is settled_, i.e. once all
devices have been found.
initqueue/online::
This hook runs _every time a network device goes online_.
initqueue/finished::
If all the scripts here return success dracut exits the mainloop, _even if
some initqueue scripts have not yet run_.
To put it another way, if you want dracut to wait for something to happen,
you need a script in `initqueue/finished` that returns non-zero _until_
the thing you're waiting for happens.
pre-mount::
Runs _once_ before trying to mount rootfs.
mount::
Each script in this hook runs in order, until one of them mounts rootfs at
`$NEWROOT`. May run multiple times.
pre-pivot::
This is where you (e.g.) copy files into `$NEWROOT` before switching over.
cleanup::
Clean up after your other hooks.
The scripts _within_ each hook run according to the numeric priority given in
the `inst_hook` lines in `module-setup.sh`.
Variables, scope, sharing data between scripts
----------------------------------------------
Each script in a hook gets sourced by the same `bash` interpreter. If you
define a function or variable in a script, each subsequent script _in the same
hook_ can see and use it, but *it won't be visible to other hooks.*
If you export a variable, it will be available to all subsequent scripts. You
can, of course, also share data by writing files to `/tmp`.
*NOTE:* You can break _other_ modules by accidentally overwriting their
variables. Avoid the following variable names in your own code.
Exported Variables
~~~~~~~~~~~~~~~~~~
==== Special dracut variables ====
$root:: The root device. Must be set by the end of the `cmdline` hook.
Might not actually be a device (e.g. "nfs").
$rflags:: Mount flags for the root device.
$fstype:: The fstype of the root filesystem. Usually `auto`.
$netroot:: The network root location. Syntax depends on type of network root.
==== Read-only dracut variables ====
$NEWROOT:: Mountpoint for the root filesystem. Usually `/sysroot`.
$hookdir:: Location of the dracut hooks. Usually `/lib/dracut/hooks`.
$RDRETRY:: Number of loops to try before giving up. Usually *60* (=30 seconds).
$main_loop:: Counter for the current mainloop iteration.
$DRACUT_QUIET:: Whether dracut should operate quietly; `yes` or `no`.
(Don't worry about this; just use `info()` or `warn()` instead)
$UDEVVERSION:: Self-explanatory.
==== Variables from other modules ====
$resume, $splash:: Used by `95resume`.
$CURL_HOME:: Exported by `45url-lib`.
==== Anaconda ====
$kickstart:: Anaconda-style URL for the kickstart.
$anac_updates:: Anaconda-style URL for `updates.img`.
$ksdevice:: Network device to use for fetching kickstart/stage2/etc.
Further Reading
---------------
Dracut documentation:
http://www.kernel.org/pub/linux/utils/boot/dracut/dracut.html
My other set of dracut notes:
http://wwoods.fedorapeople.org/doc/dracut-notes.html
