Next: , Previous: , Up: System Configuration   [Contents][Index]

6.2.11 Initial RAM Disk

For bootstrapping purposes, the Linux-Libre kernel is passed an initial RAM disk, or initrd. An initrd contains a temporary root file system as well as an initialization script. The latter is responsible for mounting the real root file system, and for loading any kernel modules that may be needed to achieve that.

The initrd field of an operating-system declaration allows you to specify which initrd you would like to use. The (gnu system linux-initrd) module provides three ways to build an initrd: the high-level base-initrd procedure and the low-level raw-initrd and expression->initrd procedures.

The base-initrd procedure is intended to cover most common uses. For example, if you want to add a bunch of kernel modules to be loaded at boot time, you can define the initrd field of the operating system declaration like this:

(initrd (lambda (file-systems . rest)
          ;; Create a standard initrd that has modules "foo.ko"
          ;; and "bar.ko", as well as their dependencies, in
          ;; addition to the modules available by default.
          (apply base-initrd file-systems
                 #:extra-modules '("foo" "bar")

The base-initrd procedure also handles common use cases that involves using the system as a QEMU guest, or as a “live” system with volatile root file system.

The base-initrd procedure is built from raw-initrd procedure. Unlike base-initrd, raw-initrd doesn’t do anything high-level, such as trying to guess which kernel modules and packages should be included to the initrd. An example use of raw-initrd is when a user has a custom Linux kernel configuration and default kernel modules included by base-initrd are not available.

The initial RAM disk produced by base-initrd or raw-initrd honors several options passed on the Linux kernel command line (that is, arguments passed via the linux command of GRUB, or the -append option of QEMU), notably:


Tell the initial RAM disk to load boot, a file containing a Scheme program, once it has mounted the root file system.

GuixSD uses this option to yield control to a boot program that runs the service activation programs and then spawns the GNU Shepherd, the initialization system.


Mount root as the root file system. root can be a device name like /dev/sda1, a partition label, or a partition UUID.


Have /run/booted-system and /run/current-system point to system.


Instruct the initial RAM disk as well as the modprobe command (from the kmod package) to refuse to load modules. modules must be a comma-separated list of module names—e.g., usbkbd,9pnet.


Start a read-eval-print loop (REPL) from the initial RAM disk before it tries to load kernel modules and to mount the root file system. Our marketing team calls it boot-to-Guile. The Schemer in you will love it. See Using Guile Interactively in GNU Guile Reference Manual, for more information on Guile’s REPL.

Now that you know all the features that initial RAM disks produced by base-initrd and raw-initrd provide, here is how to use it and customize it further.

Monadic Procedure: raw-initrd file-systems [#:linux-modules '()] [#:mapped-devices '()] [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]

Return a monadic derivation that builds a raw initrd. file-systems is a list of file systems to be mounted by the initrd, possibly in addition to the root file system specified on the kernel command line via --root. linux-modules is a list of kernel modules to be loaded at boot time. mapped-devices is a list of device mappings to realize before file-systems are mounted (see Mapped Devices). helper-packages is a list of packages to be copied in the initrd. It may include e2fsck/static or other packages needed by the initrd to check root partition.

When qemu-networking? is true, set up networking with the standard QEMU parameters. When virtio? is true, load additional modules so that the initrd can be used as a QEMU guest with para-virtualized I/O drivers.

When volatile-root? is true, the root file system is writable but any changes to it are lost.

Monadic Procedure: base-initrd file-systems [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f] [#:virtio? #t] [#:extra-modules '()]

Return a monadic derivation that builds a generic initrd. file-systems is a list of file systems to be mounted by the initrd like for raw-initrd. mapped-devices, qemu-networking? and volatile-root? also behaves as in raw-initrd.

When virtio? is true, load additional modules so that the initrd can be used as a QEMU guest with para-virtualized I/O drivers.

The initrd is automatically populated with all the kernel modules necessary for file-systems and for the given options. However, additional kernel modules can be listed in extra-modules. They will be added to the initrd, and loaded at boot time in the order in which they appear.

Needless to say, the initrds we produce and use embed a statically-linked Guile, and the initialization program is a Guile program. That gives a lot of flexibility. The expression->initrd procedure builds such an initrd, given the program to run in that initrd.

Monadic Procedure: expression->initrd exp [#:guile %guile-static-stripped] [#:name "guile-initrd"]

Return a derivation that builds a Linux initrd (a gzipped cpio archive) containing guile and that evaluates exp, a G-expression, upon booting. All the derivations referenced by exp are automatically copied to the initrd.

Next: , Previous: , Up: System Configuration   [Contents][Index]