]>
Commit | Line | Data |
---|---|---|
180f7c26 LP |
1 | --- |
2 | title: Initrd Interface | |
3 | category: Interfaces | |
4 | layout: default | |
0aff7b75 | 5 | SPDX-License-Identifier: LGPL-2.1-or-later |
180f7c26 LP |
6 | --- |
7 | ||
8 | ||
9 | # The initrd Interface of systemd | |
10 | ||
55c041b4 LP |
11 | The Linux initrd mechanism (short for "initial RAM disk", also known as |
12 | "initramfs") refers to a small file system archive that is unpacked by the | |
13 | kernel and contains the first userspace code that runs. It typically finds and | |
14 | transitions into the actual root file system to use. systemd supports both | |
15 | initrd and initrd-less boots. If an initrd is used, it is a good idea to pass a | |
16 | few bits of runtime information from the initrd to systemd in order to avoid | |
17 | duplicate work and to provide performance data to the administrator. In this | |
18 | page we attempt to roughly describe the interfaces that exist between the | |
98118c44 DDM |
19 | initrd and systemd. These interfaces are currently used by |
20 | [mkosi](https://github.com/systemd/mkosi)-generated initrds, dracut and the | |
21 | Arch Linux initrds. | |
180f7c26 LP |
22 | |
23 | * The initrd should mount `/run/` as a tmpfs and pass it pre-mounted when | |
24 | jumping into the main system when executing systemd. The mount options should | |
9f563f27 | 25 | be `mode=0755,nodev,nosuid,strictatime`. |
180f7c26 LP |
26 | |
27 | * It's highly recommended that the initrd also mounts `/usr/` (if split off) as | |
28 | appropriate and passes it pre-mounted to the main system, to avoid the | |
29 | problems described in [Booting without /usr is | |
a25d9395 | 30 | Broken](https://www.freedesktop.org/wiki/Software/systemd/separate-usr-is-broken). |
180f7c26 LP |
31 | |
32 | * If the executable `/run/initramfs/shutdown` exists systemd will use it to | |
33 | jump back into the initrd on shutdown. `/run/initramfs/` should be a usable | |
34 | initrd environment to which systemd will pivot back and the `shutdown` | |
35 | executable in it should be able to detach all complex storage that for | |
36 | example was needed to mount the root file system. It's the job of the initrd | |
37 | to set up this directory and executable in the right way so that this works | |
38 | correctly. The shutdown binary is invoked with the shutdown verb as `argv[1]`, | |
39 | optionally followed (in `argv[2]`, `argv[3]`, … systemd's original command | |
40 | line options, for example `--log-level=` and similar. | |
41 | ||
5c90c67a | 42 | * Storage daemons run from the initrd should follow the guide on |
1b4dc2ea | 43 | [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS) |
5c90c67a BF |
44 | to survive properly from the boot initrd all the way to the point where |
45 | systemd jumps back into the initrd for shutdown. | |
180f7c26 LP |
46 | |
47 | One last clarification: we use the term _initrd_ very generically here | |
48 | describing any kind of early boot file system, regardless whether that might be | |
49 | implemented as an actual ramdisk, ramfs or tmpfs. We recommend using _initrd_ | |
50 | in this sense as a term that is unrelated to the actual backing technologies | |
51 | used. | |
52 | ||
180f7c26 LP |
53 | ## Using systemd inside an initrd |
54 | ||
55 | It is also possible and recommended to implement the initrd itself based on | |
56 | systemd. Here are a few terse notes: | |
57 | ||
55c041b4 LP |
58 | * Provide `/etc/initrd-release` in the initrd image. The idea is that it |
59 | follows the same format as the usual `/etc/os-release` but describes the | |
60 | initrd implementation rather than the OS. systemd uses the existence of this | |
61 | file as a flag whether to run in initrd mode, or not. | |
180f7c26 LP |
62 | |
63 | * When run in initrd mode, systemd and its components will read a couple of | |
64 | additional command line arguments, which are generally prefixed with `rd.` | |
65 | ||
66 | * To transition into the main system image invoke `systemctl switch-root`. | |
67 | ||
68 | * The switch-root operation will result in a killing spree of all running | |
69 | processes. Some processes might need to be excluded from that, see the guide | |
1b4dc2ea | 70 | on [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS). |