]>
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 | |
19 | initrd and systemd. These interfaces are currently used by dracut and the | |
20 | ArchLinux initrds. | |
180f7c26 LP |
21 | |
22 | * The initrd should mount `/run/` as a tmpfs and pass it pre-mounted when | |
23 | jumping into the main system when executing systemd. The mount options should | |
744c49e1 | 24 | be `mode=755,nodev,nosuid,strictatime`. |
180f7c26 LP |
25 | |
26 | * It's highly recommended that the initrd also mounts `/usr/` (if split off) as | |
27 | appropriate and passes it pre-mounted to the main system, to avoid the | |
28 | problems described in [Booting without /usr is | |
a25d9395 | 29 | Broken](https://www.freedesktop.org/wiki/Software/systemd/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]`, | |
38 | optionally followed (in `argv[2]`, `argv[3]`, … systemd's original command | |
39 | line options, for example `--log-level=` and similar. | |
40 | ||
5c90c67a BF |
41 | * Storage daemons run from the initrd should follow the guide on |
42 | [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS.md) | |
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 | ||
52 | Oh, and one last question before closing: instead of implementing these | |
53 | features in your own distro's initrd, may I suggest just using Dracut instead? | |
54 | It's all already implemented there! | |
55 | ||
56 | ## Using systemd inside an initrd | |
57 | ||
58 | It is also possible and recommended to implement the initrd itself based on | |
59 | systemd. Here are a few terse notes: | |
60 | ||
55c041b4 LP |
61 | * Provide `/etc/initrd-release` in the initrd image. The idea is that it |
62 | follows the same format as the usual `/etc/os-release` but describes the | |
63 | initrd implementation rather than the OS. systemd uses the existence of this | |
64 | file as a flag whether to run in initrd mode, or not. | |
180f7c26 LP |
65 | |
66 | * When run in initrd mode, systemd and its components will read a couple of | |
67 | additional command line arguments, which are generally prefixed with `rd.` | |
68 | ||
69 | * To transition into the main system image invoke `systemctl switch-root`. | |
70 | ||
71 | * The switch-root operation will result in a killing spree of all running | |
72 | processes. Some processes might need to be excluded from that, see the guide | |
5c90c67a | 73 | on [systemd and Storage Daemons for the Root File System](ROOT_STORAGE_DAEMONS.md). |