]>
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 | |
2cc48348 | 29 | problems described in [Booting without /usr is Broken](SEPARATE_USR_IS_BROKEN). |
180f7c26 LP |
30 | |
31 | * If the executable `/run/initramfs/shutdown` exists systemd will use it to | |
32 | jump back into the initrd on shutdown. `/run/initramfs/` should be a usable | |
33 | initrd environment to which systemd will pivot back and the `shutdown` | |
34 | executable in it should be able to detach all complex storage that for | |
35 | example was needed to mount the root file system. It's the job of the initrd | |
36 | to set up this directory and executable in the right way so that this works | |
37 | correctly. The shutdown binary is invoked with the shutdown verb as `argv[1]`, | |
2cc48348 | 38 | optionally followed (in `argv[2]`, `argv[3]`, …) systemd's original command |
180f7c26 LP |
39 | line options, for example `--log-level=` and similar. |
40 | ||
5c90c67a | 41 | * Storage daemons run from the initrd should follow the guide on |
1b4dc2ea | 42 | [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS) |
5c90c67a BF |
43 | to survive properly from the boot initrd all the way to the point where |
44 | systemd jumps back into the initrd for shutdown. | |
180f7c26 LP |
45 | |
46 | One last clarification: we use the term _initrd_ very generically here | |
47 | describing any kind of early boot file system, regardless whether that might be | |
48 | implemented as an actual ramdisk, ramfs or tmpfs. We recommend using _initrd_ | |
49 | in this sense as a term that is unrelated to the actual backing technologies | |
50 | used. | |
51 | ||
180f7c26 LP |
52 | ## Using systemd inside an initrd |
53 | ||
54 | It is also possible and recommended to implement the initrd itself based on | |
55 | systemd. Here are a few terse notes: | |
56 | ||
55c041b4 LP |
57 | * Provide `/etc/initrd-release` in the initrd image. The idea is that it |
58 | follows the same format as the usual `/etc/os-release` but describes the | |
59 | initrd implementation rather than the OS. systemd uses the existence of this | |
60 | file as a flag whether to run in initrd mode, or not. | |
180f7c26 LP |
61 | |
62 | * When run in initrd mode, systemd and its components will read a couple of | |
63 | additional command line arguments, which are generally prefixed with `rd.` | |
64 | ||
65 | * To transition into the main system image invoke `systemctl switch-root`. | |
66 | ||
67 | * The switch-root operation will result in a killing spree of all running | |
68 | processes. Some processes might need to be excluded from that, see the guide | |
1b4dc2ea | 69 | on [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS). |