guix.texi

                                           ,ddcci-config)))
                   %base-services))
  (kernel-loadable-modules (list ddcci-driver-linux)))
@end lisp
@end deffn

@node Miscellaneous Services
@subsection Miscellaneous Services

@cindex fingerprint
@subsubheading Fingerprint Service

The @code{(gnu services authentication)} module provides a DBus service to
read and identify fingerprints via a fingerprint sensor.

@defvr {Scheme Variable} fprintd-service-type
The service type for @command{fprintd}, which provides the fingerprint
reading capability.

@lisp
(service fprintd-service-type)
@end lisp
@end defvr

@cindex sysctl
@subsubheading System Control Service

The @code{(gnu services sysctl)} provides a service to configure kernel
parameters at boot.

@defvr {Scheme Variable} sysctl-service-type
The service type for @command{sysctl}, which modifies kernel parameters
under @file{/proc/sys/}.  To enable IPv4 forwarding, it can be
instantiated as:

@lisp
(service sysctl-service-type
         (sysctl-configuration
           (settings '(("net.ipv4.ip_forward" . "1")))))
@end lisp
@end defvr

@deftp {Data Type} sysctl-configuration
The data type representing the configuration of @command{sysctl}.

@table @asis
@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
The @command{sysctl} executable to use.

@item @code{settings} (default: @code{'()})
An association list specifies kernel parameters and their values.
@end table
@end deftp

@cindex pcscd
@subsubheading PC/SC Smart Card Daemon Service

The @code{(gnu services security-token)} module provides the following service
to run @command{pcscd}, the PC/SC Smart Card Daemon.  @command{pcscd} is the
daemon program for pcsc-lite and the MuscleCard framework. It is a resource
manager that coordinates communications with smart card readers, smart cards
and cryptographic tokens that are connected to the system.

@defvr {Scheme Variable} pcscd-service-type
Service type for the @command{pcscd} service.  Its value must be a
@code{pcscd-configuration} object.  To run pcscd in the default
configuration, instantiate it as:

@lisp
(service pcscd-service-type)
@end lisp
@end defvr

@deftp {Data Type} pcscd-configuration
The data type representing the configuration of @command{pcscd}.

@table @asis
@item @code{pcsc-lite} (default: @code{pcsc-lite})
The pcsc-lite package that provides pcscd.
@item @code{usb-drivers} (default: @code{(list ccid)})
List of packages that provide USB drivers to pcscd. Drivers are expected to be
under @file{pcsc/drivers} in the store directory of the package.
@end table
@end deftp

@cindex lirc
@subsubheading Lirc Service

The @code{(gnu services lirc)} module provides the following service.

@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
       [#:device #f] [#:driver #f] [#:config-file #f] @
       [#:extra-options '()]
Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
decodes infrared signals from remote controls.

Optionally, @var{device}, @var{driver} and @var{config-file}
(configuration file name) may be specified.  See @command{lircd} manual
for details.

Finally, @var{extra-options} is a list of additional command-line options
passed to @command{lircd}.
@end deffn

@cindex spice
@subsubheading Spice Service

The @code{(gnu services spice)} module provides the following service.

@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon
that enables sharing the clipboard with a vm and setting the guest display
resolution when the graphical console window resizes.
@end deffn

@cindex inputattach
@subsubheading inputattach Service

@cindex tablet input, for Xorg
@cindex touchscreen input, for Xorg
The @uref{https://linuxwacom.github.io/, inputattach} service allows you to
use input devices such as Wacom tablets, touchscreens, or joysticks with the
Xorg display server.

@deffn {Scheme Variable} inputattach-service-type
Type of a service that runs @command{inputattach} on a device and
dispatches events from it.
@end deffn

@deftp {Data Type} inputattach-configuration
@table @asis
@item @code{device-type} (default: @code{"wacom"})
The type of device to connect to.  Run @command{inputattach --help}, from the
@code{inputattach} package, to see the list of supported device types.

@item @code{device} (default: @code{"/dev/ttyS0"})
The device file to connect to the device.

@item @code{baud-rate} (default: @code{#f})
Baud rate to use for the serial connection.
Should be a number or @code{#f}.

@item @code{log-file} (default: @code{#f})
If true, this must be the name of a file to log messages to.
@end table
@end deftp

@subsubheading Dictionary Service
@cindex dictionary
The @code{(gnu services dict)} module provides the following service:

@defvr {Scheme Variable} dicod-service-type
This is the type of the service that runs the @command{dicod} daemon, an
implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
@end defvr

@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
Return a service that runs the @command{dicod} daemon, an implementation
of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).

The optional @var{config} argument specifies the configuration for
@command{dicod}, which should be a @code{<dicod-configuration>} object, by
default it serves the GNU Collaborative International Dictionary of English.

You can add @command{open localhost} to your @file{~/.dico} file to make
@code{localhost} the default server for @command{dico} client
(@pxref{Initialization File,,, dico, GNU Dico Manual}).
@end deffn

@deftp {Data Type} dicod-configuration
Data type representing the configuration of dicod.

@table @asis
@item @code{dico} (default: @var{dico})
Package object of the GNU Dico dictionary server.

@item @code{interfaces} (default: @var{'("localhost")})
This is the list of IP addresses and ports and possibly socket file
names to listen to (@pxref{Server Settings, @code{listen} directive,,
dico, GNU Dico Manual}).

@item @code{handlers} (default: @var{'()})
List of @code{<dicod-handler>} objects denoting handlers (module instances).

@item @code{databases} (default: @var{(list %dicod-database:gcide)})
List of @code{<dicod-database>} objects denoting dictionaries to be served.
@end table
@end deftp

@deftp {Data Type} dicod-handler
Data type representing a dictionary handler (module instance).

@table @asis
@item @code{name}
Name of the handler (module instance).

@item @code{module} (default: @var{#f})
Name of the dicod module of the handler (instance).  If it is @code{#f},
the module has the same name as the handler.
(@pxref{Modules,,, dico, GNU Dico Manual}).

@item @code{options}
List of strings or gexps representing the arguments for the module handler
@end table
@end deftp

@deftp {Data Type} dicod-database
Data type representing a dictionary database.

@table @asis
@item @code{name}
Name of the database, will be used in DICT commands.

@item @code{handler}
Name of the dicod handler (module instance) used by this database
(@pxref{Handlers,,, dico, GNU Dico Manual}).

@item @code{complex?} (default: @var{#f})
Whether the database configuration complex.  The complex configuration
will need a corresponding @code{<dicod-handler>} object, otherwise not.

@item @code{options}
List of strings or gexps representing the arguments for the database
(@pxref{Databases,,, dico, GNU Dico Manual}).
@end table
@end deftp

@defvr {Scheme Variable} %dicod-database:gcide
A @code{<dicod-database>} object serving the GNU Collaborative International
Dictionary of English using the @code{gcide} package.
@end defvr

The following is an example @code{dicod-service} configuration.

@lisp
(dicod-service #:config
  (dicod-configuration
   (handlers (list (dicod-handler
                    (name "wordnet")
                    (module "dictorg")
                    (options
                     (list #~(string-append "dbdir=" #$wordnet))))))
   (databases (list (dicod-database
                     (name "wordnet")
                     (complex? #t)
                     (handler "wordnet")
                     (options '("database=wn")))
                    %dicod-database:gcide))))
@end lisp

@cindex Docker
@subsubheading Docker Service

The @code{(gnu services docker)} module provides the following services.

@defvr {Scheme Variable} docker-service-type

This is the type of the service that runs @url{https://www.docker.com,Docker},
a daemon that can execute application bundles (sometimes referred to as
``containers'') in isolated environments.

@end defvr

@deftp {Data Type} docker-configuration
This is the data type representing the configuration of Docker and Containerd.

@table @asis

@item @code{package} (default: @code{docker})
The Docker package to use.

@item @code{containerd} (default: @var{containerd})
The Containerd package to use.

@end table
@end deftp

@cindex Audit
@subsubheading Auditd Service

The @code{(gnu services auditd)} module provides the following service.

@defvr {Scheme Variable} auditd-service-type

This is the type of the service that runs
@url{https://people.redhat.com/sgrubb/audit/,auditd},
a daemon that tracks security-relevant information on your system.

Examples of things that can be tracked:

@enumerate
@item
File accesses
@item
System calls
@item
Invoked commands
@item
Failed login attempts
@item
Firewall filtering
@item
Network access
@end enumerate

@command{auditctl} from the @code{audit} package can be used in order
to add or remove events to be tracked (until the next reboot).
In order to permanently track events, put the command line arguments
of auditctl into @file{/etc/audit/audit.rules}.
@command{aureport} from the @code{audit} package can be used in order
to view a report of all recorded events.
The audit daemon usually logs into the directory @file{/var/log/audit}.

@end defvr

@deftp {Data Type} auditd-configuration
This is the data type representing the configuration of auditd.

@table @asis

@item @code{audit} (default: @code{audit})
The audit package to use.

@end table
@end deftp

@defvr {Scheme Variable} singularity-service-type
This is the type of the service that allows you to run
@url{https://www.sylabs.io/singularity/, Singularity}, a Docker-style tool to
create and run application bundles (aka. ``containers'').  The value for this
service is the Singularity package to use.

The service does not install a daemon; instead, it installs helper programs as
setuid-root (@pxref{Setuid Programs}) such that unprivileged users can invoke
@command{singularity run} and similar commands.
@end defvr

@cindex Nix
@subsubheading Nix service

The @code{(gnu services nix)} module provides the following service.

@defvr {Scheme Variable} nix-service-type

This is the type of the service that runs build daemon of the
@url{https://nixos.org/nix/, Nix} package manager.  Here is an example showing
how to use it:

@lisp
(use-modules (gnu))
(use-service-modules nix)
(use-package-modules package-management)

(operating-system
  ;; @dots{}
  (packages (append (list nix)
                    %base-packages))

  (services (append (list (service nix-service-type))
                    %base-services)))
@end lisp

After @command{guix system reconfigure} configure Nix for your user:

@itemize
@item Add a Nix channel and update it.  See
@url{https://nixos.org/nix/manual/, Nix Package Manager Guide}.

@item Create a symlink to your profile and activate Nix profile:
@end itemize

@example
$ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile
$ source /run/current-system/profile/etc/profile.d/nix.sh
@end example

@end defvr

@node Setuid Programs
@section Setuid Programs

@cindex setuid programs
Some programs need to run with ``root'' privileges, even when they are
launched by unprivileged users.  A notorious example is the
@command{passwd} program, which users can run to change their
password, and which needs to access the @file{/etc/passwd} and
@file{/etc/shadow} files---something normally restricted to root, for
obvious security reasons.  To address that, these executables are
@dfn{setuid-root}, meaning that they always run with root privileges
(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
for more info about the setuid mechanism.)

The store itself @emph{cannot} contain setuid programs: that would be a
security issue since any user on the system can write derivations that
populate the store (@pxref{The Store}).  Thus, a different mechanism is
used: instead of changing the setuid bit directly on files that are in
the store, we let the system administrator @emph{declare} which programs
should be setuid root.

The @code{setuid-programs} field of an @code{operating-system}
declaration contains a list of G-expressions denoting the names of
programs to be setuid-root (@pxref{Using the Configuration System}).
For instance, the @command{passwd} program, which is part of the Shadow
package, can be designated by this G-expression (@pxref{G-Expressions}):

@example
#~(string-append #$shadow "/bin/passwd")
@end example

A default set of setuid programs is defined by the
@code{%setuid-programs} variable of the @code{(gnu system)} module.

@defvr {Scheme Variable} %setuid-programs
A list of G-expressions denoting common programs that are setuid-root.

The list includes commands such as @command{passwd}, @command{ping},
@command{su}, and @command{sudo}.
@end defvr

Under the hood, the actual setuid programs are created in the
@file{/run/setuid-programs} directory at system activation time.  The
files in this directory refer to the ``real'' binaries, which are in the
store.

@node X.509 Certificates
@section X.509 Certificates

@cindex HTTPS, certificates
@cindex X.509 certificates
@cindex TLS
Web servers available over HTTPS (that is, HTTP over the transport-layer
security mechanism, TLS) send client programs an @dfn{X.509 certificate}
that the client can then use to @emph{authenticate} the server.  To do
that, clients verify that the server's certificate is signed by a
so-called @dfn{certificate authority} (CA).  But to verify the CA's
signature, clients must have first acquired the CA's certificate.

Web browsers such as GNU@tie{}IceCat include their own set of CA
certificates, such that they are able to verify CA signatures
out-of-the-box.

However, most other programs that can talk HTTPS---@command{wget},
@command{git}, @command{w3m}, etc.---need to be told where CA
certificates can be found.

@cindex @code{nss-certs}
In Guix, this is done by adding a package that provides certificates
to the @code{packages} field of the @code{operating-system} declaration
(@pxref{operating-system Reference}).  Guix includes one such package,
@code{nss-certs}, which is a set of CA certificates provided as part of
Mozilla's Network Security Services.

Note that it is @emph{not} part of @code{%base-packages}, so you need to
explicitly add it.  The @file{/etc/ssl/certs} directory, which is where
most applications and libraries look for certificates by default, points
to the certificates installed globally.

Unprivileged users, including users of Guix on a foreign distro,
can also install their own certificate package in
their profile.  A number of environment variables need to be defined so
that applications and libraries know where to find them.  Namely, the
OpenSSL library honors the @env{SSL_CERT_DIR} and @env{SSL_CERT_FILE}
variables.  Some applications add their own environment variables; for
instance, the Git version control system honors the certificate bundle
pointed to by the @env{GIT_SSL_CAINFO} environment variable.  Thus, you
would typically run something like:

@example
guix install nss-certs
export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
export GIT_SSL_CAINFO="$SSL_CERT_FILE"
@end example

As another example, R requires the @env{CURL_CA_BUNDLE} environment
variable to point to a certificate bundle, so you would have to run
something like this:

@example
guix install nss-certs
export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
@end example

For other applications you may want to look up the required environment
variable in the relevant documentation.


@node Name Service Switch
@section Name Service Switch

@cindex name service switch
@cindex NSS
The @code{(gnu system nss)} module provides bindings to the
configuration file of the libc @dfn{name service switch} or @dfn{NSS}
(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
Manual}).  In a nutshell, the NSS is a mechanism that allows libc to be
extended with new ``name'' lookup methods for system databases, which
includes host names, service names, user accounts, and more (@pxref{Name
Service Switch, System Databases and Name Service Switch,, libc, The GNU
C Library Reference Manual}).

The NSS configuration specifies, for each system database, which lookup
method is to be used, and how the various methods are chained
together---for instance, under which circumstances NSS should try the
next method in the list.  The NSS configuration is given in the
@code{name-service-switch} field of @code{operating-system} declarations
(@pxref{operating-system Reference, @code{name-service-switch}}).

@cindex nss-mdns
@cindex .local, host name lookup
As an example, the declaration below configures the NSS to use the
@uref{https://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
back-end}, which supports host name lookups over multicast DNS (mDNS)
for host names ending in @code{.local}:

@lisp
(name-service-switch
   (hosts (list %files    ;first, check /etc/hosts

                ;; If the above did not succeed, try
                ;; with 'mdns_minimal'.
                (name-service
                  (name "mdns_minimal")

                  ;; 'mdns_minimal' is authoritative for
                  ;; '.local'.  When it returns "not found",
                  ;; no need to try the next methods.
                  (reaction (lookup-specification
                             (not-found => return))))

                ;; Then fall back to DNS.
                (name-service
                  (name "dns"))

                ;; Finally, try with the "full" 'mdns'.
                (name-service
                  (name "mdns")))))
@end lisp

Do not worry: the @code{%mdns-host-lookup-nss} variable (see below)
contains this configuration, so you will not have to type it if all you
want is to have @code{.local} host lookup working.

Note that, in this case, in addition to setting the
@code{name-service-switch} of the @code{operating-system} declaration,
you also need to use @code{avahi-service-type} (@pxref{Networking Services,
@code{avahi-service-type}}), or @code{%desktop-services}, which includes it
(@pxref{Desktop Services}).  Doing this makes @code{nss-mdns} accessible
to the name service cache daemon (@pxref{Base Services,
@code{nscd-service}}).

For convenience, the following variables provide typical NSS
configurations.

@defvr {Scheme Variable} %default-nss
This is the default name service switch configuration, a
@code{name-service-switch} object.
@end defvr

@defvr {Scheme Variable} %mdns-host-lookup-nss
This is the name service switch configuration with support for host name
lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
@end defvr

The reference for name service switch configuration is given below.  It
is a direct mapping of the configuration file format of the C library , so
please refer to the C library manual for more information (@pxref{NSS
Configuration File,,, libc, The GNU C Library Reference Manual}).
Compared to the configuration file format of libc NSS, it has the advantage
not only of adding this warm parenthetic feel that we like, but also
static checks: you will know about syntax errors and typos as soon as you
run @command{guix system}.

@deftp {Data Type} name-service-switch

This is the data type representation the configuration of libc's name
service switch (NSS).  Each field below represents one of the supported
system databases.

@table @code
@item aliases
@itemx ethers
@itemx group
@itemx gshadow
@itemx hosts
@itemx initgroups
@itemx netgroup
@itemx networks
@itemx password
@itemx public-key
@itemx rpc
@itemx services
@itemx shadow
The system databases handled by the NSS.  Each of these fields must be a
list of @code{<name-service>} objects (see below).
@end table
@end deftp

@deftp {Data Type} name-service

This is the data type representing an actual name service and the
associated lookup action.

@table @code
@item name
A string denoting the name service (@pxref{Services in the NSS
configuration,,, libc, The GNU C Library Reference Manual}).

Note that name services listed here must be visible to nscd.  This is
achieved by passing the @code{#:name-services} argument to
@code{nscd-service} the list of packages providing the needed name
services (@pxref{Base Services, @code{nscd-service}}).

@item reaction
An action specified using the @code{lookup-specification} macro
(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
Reference Manual}).  For example:

@lisp
(lookup-specification (unavailable => continue)
                      (success => return))
@end lisp
@end table
@end deftp

@node Initial RAM Disk
@section Initial RAM Disk

@cindex initrd
@cindex initial RAM disk
For bootstrapping purposes, the Linux-Libre kernel is passed an
@dfn{initial RAM disk}, or @dfn{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 @code{initrd-modules} field of an @code{operating-system}
declaration allows you to specify Linux-libre kernel modules that must
be available in the initrd.  In particular, this is where you would list
modules needed to actually drive the hard disk where your root partition
is---although the default value of @code{initrd-modules} should cover
most use cases.  For example, assuming you need the @code{megaraid_sas}
module in addition to the default modules to be able to access your root
file system, you would write:

@lisp
(operating-system
  ;; @dots{}
  (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
@end lisp

@defvr {Scheme Variable} %base-initrd-modules
This is the list of kernel modules included in the initrd by default.
@end defvr

Furthermore, if you need lower-level customization, the @code{initrd}
field of an @code{operating-system} declaration allows
you to specify which initrd you would like to use.  The @code{(gnu
system linux-initrd)} module provides three ways to build an initrd: the
high-level @code{base-initrd} procedure and the low-level
@code{raw-initrd} and @code{expression->initrd} procedures.

The @code{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 @code{initrd} field of the operating
system declaration like this:

@lisp
(initrd (lambda (file-systems . rest)
          ;; Create a standard initrd but set up networking
          ;; with the parameters QEMU expects by default.
          (apply base-initrd file-systems
                 #:qemu-networking? #t
                 rest)))
@end lisp

The @code{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 @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
Unlike @code{base-initrd}, @code{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 @code{raw-initrd} is when a user has
a custom Linux kernel configuration and default kernel modules included by
@code{base-initrd} are not available.

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

@table @code
@item --load=@var{boot}
Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
program, once it has mounted the root file system.

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

@item --root=@var{root}
Mount @var{root} as the root file system.  @var{root} can be a device
name like @code{/dev/sda1}, a file system label, or a file system UUID.
When unspecified, the device name from the root file system of the
operating system declaration is used.

@item --system=@var{system}
Have @file{/run/booted-system} and @file{/run/current-system} point to
@var{system}.

@item modprobe.blacklist=@var{modules}@dots{}
@cindex module, black-listing
@cindex black list, of kernel modules
Instruct the initial RAM disk as well as the @command{modprobe} command
(from the kmod package) to refuse to load @var{modules}.  @var{modules}
must be a comma-separated list of module names---e.g.,
@code{usbkbd,9pnet}.

@item --repl
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 @dfn{boot-to-Guile}.  The Schemer in you will
love it.  @xref{Using Guile Interactively,,, guile, GNU Guile Reference
Manual}, for more information on Guile's REPL.

@end table

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

@cindex initrd
@cindex initial RAM disk
@deffn {Scheme Procedure} raw-initrd @var{file-systems} @
       [#:linux-modules '()] [#:mapped-devices '()] @
       [#:keyboard-layout #f] @
       [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]
Return a derivation that builds a raw initrd.  @var{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 @option{--root}.
@var{linux-modules} is a list of kernel modules to be loaded at boot time.
@var{mapped-devices} is a list of device mappings to realize before
@var{file-systems} are mounted (@pxref{Mapped Devices}).
@var{helper-packages} is a list of packages to be copied in the initrd. It may
include @code{e2fsck/static} or other packages needed by the initrd to check
the root file system.

When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
the desired console keyboard layout.  This is done before @var{mapped-devices}
are set up and before @var{file-systems} are mounted such that, should the
user need to enter a passphrase or use the REPL, this happens using the
intended keyboard layout.

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

When @var{volatile-root?} is true, the root file system is writable but any changes
to it are lost.
@end deffn

@deffn {Scheme Procedure} base-initrd @var{file-systems} @
       [#:mapped-devices '()] [#:keyboard-layout #f] @
       [#:qemu-networking? #f] [#:volatile-root? #f] @
       [#:linux-modules '()]
Return as a file-like object a generic initrd, with kernel
modules taken from @var{linux}.  @var{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 @option{--root}.  @var{mapped-devices} is a list of device
mappings to realize before @var{file-systems} are mounted.

When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
the desired console keyboard layout.  This is done before @var{mapped-devices}
are set up and before @var{file-systems} are mounted such that, should the
user need to enter a passphrase or use the REPL, this happens using the
intended keyboard layout.

@var{qemu-networking?} and @var{volatile-root?} behaves as in @code{raw-initrd}.

The initrd is automatically populated with all the kernel modules necessary
for @var{file-systems} and for the given options.  Additional kernel
modules can be listed in @var{linux-modules}.  They will be added to the initrd, and
loaded at boot time in the order in which they appear.
@end deffn

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
@code{expression->initrd} procedure builds such an initrd, given the
program to run in that initrd.

@deffn {Scheme Procedure} expression->initrd @var{exp} @
       [#:guile %guile-3.0-static-stripped] [#:name "guile-initrd"]
Return as a file-like object a Linux initrd (a gzipped cpio archive)
containing @var{guile} and that evaluates @var{exp}, a G-expression,
upon booting.  All the derivations referenced by @var{exp} are
automatically copied to the initrd.
@end deffn

@node Bootloader Configuration
@section Bootloader Configuration

@cindex bootloader
@cindex boot loader

The operating system supports multiple bootloaders.  The bootloader is
configured using @code{bootloader-configuration} declaration.  All the
fields of this structure are bootloader agnostic except for one field,
@code{bootloader} that indicates the bootloader to be configured and
installed.

Some of the bootloaders do not honor every field of
@code{bootloader-configuration}.  For instance, the extlinux
bootloader does not support themes and thus ignores the @code{theme}
field.

@deftp {Data Type} bootloader-configuration
The type of a bootloader configuration declaration.

@table @asis

@item @code{bootloader}
@cindex EFI, bootloader
@cindex UEFI, bootloader
@cindex BIOS, bootloader
The bootloader to use, as a @code{bootloader} object. For now
@code{grub-bootloader}, @code{grub-efi-bootloader},
@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported.

@vindex grub-efi-bootloader
@code{grub-efi-bootloader} allows to boot on modern systems using the
@dfn{Unified Extensible Firmware Interface} (UEFI).  This is what you should
use if the installation image contains a @file{/sys/firmware/efi} directory
when you boot it on your system.

@vindex grub-bootloader
@code{grub-bootloader} allows you to boot in particular Intel-based machines
in ``legacy'' BIOS mode.

@cindex ARM, bootloaders
@cindex AArch64, bootloaders
Available bootloaders are described in @code{(gnu bootloader @dots{})}
modules.  In particular, @code{(gnu bootloader u-boot)} contains definitions
of bootloaders for a wide range of ARM and AArch64 systems, using the
@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.

@item @code{target}
This is a string denoting the target onto which to install the
bootloader.

The interpretation depends on the bootloader in question.  For
@code{grub-bootloader}, for example, it should be a device name understood by
the bootloader @command{installer} command, such as @code{/dev/sda} or
@code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}).  For
@code{grub-efi-bootloader}, it should be the mount point of the EFI file
system, usually @file{/boot/efi}.

@item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
entries to appear in the bootloader menu, in addition to the current
system entry and the entry pointing to previous system generations.

@item @code{default-entry} (default: @code{0})
The index of the default boot menu entry.  Index 0 is for the entry of the
current system.

@item @code{timeout} (default: @code{5})
The number of seconds to wait for keyboard input before booting.  Set to
0 to boot immediately, and to -1 to wait indefinitely.

@cindex keyboard layout, for the bootloader
@item @code{keyboard-layout} (default: @code{#f})
If this is @code{#f}, the bootloader's menu (if any) uses the default keyboard
layout, usually US@tie{}English (``qwerty'').

Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard
Layout}).

@quotation Note
This option is currently ignored by bootloaders other than @code{grub} and
@code{grub-efi}.
@end quotation

@item @code{theme} (default: @var{#f})
The bootloader theme object describing the theme to use.  If no theme
is provided, some bootloaders might use a default theme, that's true
for GRUB.

@item @code{terminal-outputs} (default: @code{'(gfxterm)})
The output terminals used for the bootloader boot menu, as a list of
symbols.  GRUB accepts the values: @code{console}, @code{serial},
@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
@code{mda_text}, @code{morse}, and @code{pkmodem}.  This field
corresponds to the GRUB variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple
configuration,,, grub,GNU GRUB manual}).

@item @code{terminal-inputs} (default: @code{'()})
The input terminals used for the bootloader boot menu, as a list of
symbols.  For GRUB, the default is the native platform terminal as
determined at run-time.  GRUB accepts the values: @code{console},
@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
@code{usb_keyboard}.  This field corresponds to the GRUB variable
@code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB
manual}).

@item @code{serial-unit} (default: @code{#f})
The serial unit used by the bootloader, as an integer from 0 to 3.
For GRUB, it is chosen at run-time; currently GRUB chooses 0, which
corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).

@item @code{serial-speed} (default: @code{#f})
The speed of the serial interface, as an integer.  For GRUB, the
default value is chosen at run-time; currently GRUB chooses
9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
@end table

@end deftp

@cindex dual boot
@cindex boot menu
Should you want to list additional boot menu entries @i{via} the
@code{menu-entries} field above, you will need to create them with the
@code{menu-entry} form.  For example, imagine you want to be able to
boot another distro (hard to imagine!), you can define a menu entry
along these lines:

@lisp
(menu-entry
  (label "The Other Distro")
  (linux "/boot/old/vmlinux-2.6.32")
  (linux-arguments '("root=/dev/sda2"))
  (initrd "/boot/old/initrd"))
@end lisp

Details below.

@deftp {Data Type} menu-entry
The type of an entry in the bootloader menu.

@table @asis

@item @code{label}
The label to show in the menu---e.g., @code{"GNU"}.

@item @code{linux}
The Linux kernel image to boot, for example:

@lisp
(file-append linux-libre "/bzImage")
@end lisp

For GRUB, it is also possible to specify a device explicitly in the
file path using GRUB's device naming convention (@pxref{Naming
convention,,, grub, GNU GRUB manual}), for example:

@example
"(hd0,msdos1)/boot/vmlinuz"
@end example

If the device is specified explicitly as above, then the @code{device}
field is ignored entirely.

@item @code{linux-arguments} (default: @code{()})
The list of extra Linux kernel command-line arguments---e.g.,
@code{("console=ttyS0")}.

@item @code{initrd}
A G-Expression or string denoting the file name of the initial RAM disk
to use (@pxref{G-Expressions}).
@item @code{device} (default: @code{#f})
The device where the kernel and initrd are to be found---i.e., for GRUB,
@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).

This may be a file system label (a string), a file system UUID (a
bytevector, @pxref{File Systems}), or @code{#f}, in which case
the bootloader will search the device containing the file specified by
the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}).  It
must @emph{not} be an OS device name such as @file{/dev/sda1}.

@end table
@end deftp

@cindex HDPI
@cindex HiDPI
@cindex resolution
@c FIXME: Write documentation once it's stable.
For now only GRUB has theme support.  GRUB themes are created using
the @code{grub-theme} form, which is not fully documented yet.

@deftp {Data Type} grub-theme
Data type representing the configuration of the GRUB theme.

@table @asis
@item @code{gfxmode} (default: @code{'("auto")})
The GRUB @code{gfxmode} to set (a list of screen resolution strings, see
@pxref{gfxmode,,, grub, GNU GRUB manual}).
@end table
@end deftp