]>
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 | ||
11 | The Linux initrd mechanism (short for "initial RAM disk") refers to a small | |
12 | file system archive that is unpacked by the kernel and contains the first | |
13 | userspace code that runs. It typically finds and transitions into the actual | |
14 | root file system to use. systemd supports both initrd and initrd-less boots. If | |
15 | an initrd is used it is a good idea to pass a few bits of runtime information | |
16 | from the initrd to systemd in order to avoid duplicate work and to provide | |
17 | performance data to the administrator. In this page we attempt to roughly | |
18 | describe the interfaces that exist between the initrd and systemd. These | |
19 | interfaces are currently used by dracut and the ArchLinux initrds. | |
20 | ||
21 | * The initrd should mount `/run/` as a tmpfs and pass it pre-mounted when | |
22 | jumping into the main system when executing systemd. The mount options should | |
744c49e1 | 23 | be `mode=755,nodev,nosuid,strictatime`. |
180f7c26 LP |
24 | |
25 | * It's highly recommended that the initrd also mounts `/usr/` (if split off) as | |
26 | appropriate and passes it pre-mounted to the main system, to avoid the | |
27 | problems described in [Booting without /usr is | |
28 | Broken](http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken). | |
29 | ||
30 | * If the executable `/run/initramfs/shutdown` exists systemd will use it to | |
31 | jump back into the initrd on shutdown. `/run/initramfs/` should be a usable | |
32 | initrd environment to which systemd will pivot back and the `shutdown` | |
33 | executable in it should be able to detach all complex storage that for | |
34 | example was needed to mount the root file system. It's the job of the initrd | |
35 | to set up this directory and executable in the right way so that this works | |
36 | correctly. The shutdown binary is invoked with the shutdown verb as `argv[1]`, | |
37 | optionally followed (in `argv[2]`, `argv[3]`, … systemd's original command | |
38 | line options, for example `--log-level=` and similar. | |
39 | ||
37b22b3b | 40 | * Storage daemons run from the initrd should follow the guide on [systemd |
180f7c26 LP |
41 | and Storage Daemons for the Root File |
42 | System](https://systemd.io/ROOT_STORAGE_DAEMONS) to survive properly from the | |
43 | boot initrd all the way to the point where systemd jumps back into the initrd | |
44 | for shutdown. | |
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 | ||
61 | * Provide `/etc/initrd-release` in the initrd image. The idea is that it follows | |
62 | the same format as the usual `/etc/os-release` but describes the initial RAM | |
63 | disk implementation rather than the OS. systemd uses the existence of this | |
64 | file as a flag whether to run in initial RAM disk mode, or not. | |
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 | |
73 | on [systemd and Storage Daemons for the Root File | |
74 | System](https://systemd.io/ROOT_STORAGE_DAEMONS). |