From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- docs/INITRD_INTERFACE.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/INITRD_INTERFACE.md (limited to 'docs/INITRD_INTERFACE.md') diff --git a/docs/INITRD_INTERFACE.md b/docs/INITRD_INTERFACE.md new file mode 100644 index 0000000..6a54f9f --- /dev/null +++ b/docs/INITRD_INTERFACE.md @@ -0,0 +1,73 @@ +--- +title: Initrd Interface +category: Interfaces +layout: default +SPDX-License-Identifier: LGPL-2.1-or-later +--- + + +# The initrd Interface of systemd + +The Linux initrd mechanism (short for "initial RAM disk", also known as +"initramfs") 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](https://www.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 guide on + [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS.md) + 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 + initrd implementation rather than the OS. systemd uses the existence of this + file as a flag whether to run in initrd 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](ROOT_STORAGE_DAEMONS.md). -- cgit v1.2.3