From 180f7c26aa18b9af71f050534279abc5e520cdf5 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 13 Jan 2020 18:48:31 +0100 Subject: docs: import initrd interface documentation from fdo wiki Imported from https://www.freedesktop.org/wiki/Software/systemd/InitrdInterface/ --- docs/INITRD_INTERFACE.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/INITRD_INTERFACE.md (limited to 'docs') diff --git a/docs/INITRD_INTERFACE.md b/docs/INITRD_INTERFACE.md new file mode 100644 index 0000000000..04b189f89c --- /dev/null +++ b/docs/INITRD_INTERFACE.md @@ -0,0 +1,73 @@ +--- +title: Initrd Interface +category: Interfaces +layout: default +--- + + +# The initrd Interface of systemd + +The Linux initrd mechanism (short for "initial RAM disk") refers to a small +file system archive that is unpacked by the kernel and contains the first +userspace code that runs. It typically finds and transitions into the actual +root file system to use. systemd supports both initrd and initrd-less boots. If +an initrd is used it is a good idea to pass a few bits of runtime information +from the initrd to systemd in order to avoid duplicate work and to provide +performance data to the administrator. In this page we attempt to roughly +describe the interfaces that exist between the initrd and systemd. These +interfaces are currently used by dracut and the ArchLinux initrds. + +* The initrd should mount `/run/` as a tmpfs and pass it pre-mounted when + jumping into the main system when executing systemd. The mount options should + be `mode=755,nodev,nosuid,strictatime` + +* It's highly recommended that the initrd also mounts `/usr/` (if split off) as + appropriate and passes it pre-mounted to the main system, to avoid the + problems described in [Booting without /usr is + Broken](http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken). + +* If the executable `/run/initramfs/shutdown` exists systemd will use it to + jump back into the initrd on shutdown. `/run/initramfs/` should be a usable + initrd environment to which systemd will pivot back and the `shutdown` + executable in it should be able to detach all complex storage that for + example was needed to mount the root file system. It's the job of the initrd + to set up this directory and executable in the right way so that this works + correctly. The shutdown binary is invoked with the shutdown verb as `argv[1]`, + optionally followed (in `argv[2]`, `argv[3]`, … systemd's original command + line options, for example `--log-level=` and similar. + +* Storage daemons run from the initrd should follow the the guide on [systemd + and Storage Daemons for the Root File + System](https://systemd.io/ROOT_STORAGE_DAEMONS) to survive properly from the + boot initrd all the way to the point where systemd jumps back into the initrd + for shutdown. + +One last clarification: we use the term _initrd_ very generically here +describing any kind of early boot file system, regardless whether that might be +implemented as an actual ramdisk, ramfs or tmpfs. We recommend using _initrd_ +in this sense as a term that is unrelated to the actual backing technologies +used. + +Oh, and one last question before closing: instead of implementing these +features in your own distro's initrd, may I suggest just using Dracut instead? +It's all already implemented there! + +## Using systemd inside an initrd + +It is also possible and recommended to implement the initrd itself based on +systemd. Here are a few terse notes: + +* Provide `/etc/initrd-release` in the initrd image. The idea is that it follows + the same format as the usual `/etc/os-release` but describes the initial RAM + disk implementation rather than the OS. systemd uses the existence of this + file as a flag whether to run in initial RAM disk mode, or not. + +* When run in initrd mode, systemd and its components will read a couple of + additional command line arguments, which are generally prefixed with `rd.` + +* To transition into the main system image invoke `systemctl switch-root`. + +* The switch-root operation will result in a killing spree of all running + processes. Some processes might need to be excluded from that, see the guide + on [systemd and Storage Daemons for the Root File + System](https://systemd.io/ROOT_STORAGE_DAEMONS). -- cgit v1.2.3