docs/INITRD_INTERFACE.md

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