guix.texi

Before exchanging RPC requests an RPC client must establish a security
context.  Typically this is done using the Kerberos command @command{kinit}
or automatically at login time using PAM services (@pxref{Kerberos Services}).

@defvr {Scheme Variable} gss-service-type
A service type for the Global Security System (GSS) daemon.
@end defvr

@deftp {Data Type} gss-configuration
Data type representing the configuration of the GSS daemon service.
This type has the following parameters:
@table @asis
@item @code{nfs-utils} (default: @code{nfs-utils})
The package in which the @command{rpc.gssd} command is to be found.

@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory where the pipefs file system is mounted.

@end table
@end deftp


@subsubheading IDMAP Daemon Service
@cindex idmapd
@cindex name mapper

The idmap daemon service provides mapping between user IDs and user names.
Typically it is required in order to access file systems mounted via NFSv4.

@defvr {Scheme Variable} idmap-service-type
A service type for the Identity Mapper (IDMAP) daemon.
@end defvr

@deftp {Data Type} idmap-configuration
Data type representing the configuration of the IDMAP daemon service.
This type has the following parameters:
@table @asis
@item @code{nfs-utils} (default: @code{nfs-utils})
The package in which the @command{rpc.idmapd} command is to be found.

@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory where the pipefs file system is mounted.

@item @code{domain} (default: @code{#f})
The local NFSv4 domain name.
This must be a string or @code{#f}.
If it is @code{#f} then the daemon will use the host's fully qualified domain name.

@end table
@end deftp

@node Continuous Integration
@subsubsection Continuous Integration

@cindex continuous integration
@uref{https://notabug.org/mthl/cuirass, Cuirass} is a continuous
integration tool for Guix.  It can be used both for development and for
providing substitutes to others (@pxref{Substitutes}).

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

@defvr {Scheme Procedure} cuirass-service-type
The type of the Cuirass service.  Its value must be a
@code{cuirass-configuration} object, as described below.
@end defvr

To add build jobs, you have to set the @code{specifications} field of
the configuration.  Here is an example of a service defining a build job
based on a specification that can be found in Cuirass source tree.  This
service polls the Guix repository and builds a subset of the Guix
packages, as prescribed in the @file{gnu-system.scm} example spec:

@example
(let ((spec #~((#:name . "guix")
               (#:url . "git://git.savannah.gnu.org/guix.git")
               (#:load-path . ".")

               ;; Here we must provide an absolute file name.
               ;; We take jobs from one of the examples provided
               ;; by Cuirass.
               (#:file . #$(file-append
                            cuirass
                            "/tests/gnu-system.scm"))

               (#:proc . hydra-jobs)
               (#:arguments (subset . "hello"))
               (#:branch . "master"))))
  (service cuirass-service-type
           (cuirass-configuration
            (specifications #~(list #$spec)))))
@end example

While information related to build jobs is located directly in the
specifications, global settings for the @command{cuirass} process are
accessible in other @code{cuirass-configuration} fields.

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

@table @asis
@item @code{log-file} (default: @code{"/var/log/cuirass.log"})
Location of the log file.

@item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
Location of the repository cache.

@item @code{user} (default: @code{"cuirass"})
Owner of the @code{cuirass} process.

@item @code{group} (default: @code{"cuirass"})
Owner's group of the @code{cuirass} process.

@item @code{interval} (default: @code{60})
Number of seconds between the poll of the repositories followed by the
Cuirass jobs.

@item @code{database} (default: @code{"/var/run/cuirass/cuirass.db"})
Location of sqlite database which contains the build results and previously
added specifications.

@item @code{specifications} (default: @code{#~'()})
A gexp (@pxref{G-Expressions}) that evaluates to a list of specifications,
where a specification is an association list
(@pxref{Associations Lists,,, guile, GNU Guile Reference Manual}) whose
keys are keywords (@code{#:keyword-example}) as shown in the example
above.

@item @code{use-substitutes?} (default: @code{#f})
This allows using substitutes to avoid building every dependencies of a job
from source.

@item @code{one-shot?} (default: @code{#f})
Only evaluate specifications and build derivations once.

@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.
@end table
@end deftp

@node Miscellaneous Services
@subsubsection Miscellaneous Services


@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{http://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

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

@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 Dictonary 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{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-database
Data type representing a dictionary database.

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

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

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

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

@subsubsection Version Control

The @code{(gnu services version-control)} module provides the following services:

@subsubheading Git daemon service

@deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)]

Return a service that runs @command{git daemon}, a simple TCP server to
expose repositiories over the Git protocol for annoymous access.

The optional @var{config} argument should be a
@code{<git-daemon-configuration>} object, by default it allows read-only
access to exported@footnote{By creating the magic file
"git-daemon-export-ok" in the repository directory.} repositories under
@file{/srv/git}.

@end deffn

@deftp {Data Type} git-daemon-configuration
Data type representing the configuration for @code{git-daemon-service}.

@table @asis
@item @code{package} (default: @var{git})
Package object of the Git distributed version control system.

@item @code{export-all?} (default: @var{#f})
Whether to allow access for all Git repositories, even if they do not
have the @file{git-daemon-export-ok} file.

@item @code{base-path} (default: @file{/srv/git})
Whether to remap all the path requests as relative to the given path.
If you run git daemon with @var{(base-path "/srv/git")} on example.com,
then if you later try to pull @code{git://example.com/hello.git}, git
daemon will interpret the path as @code{/srv/git/hello.git}.

@item @code{user-path} (default: @var{#f})
Whether to allow @code{~user} notation to be used in requests.  When
specified with empty string, requests to @code{git://host/~alice/foo} is
taken as a request to access @code{foo} repository in the home directory
of user @code{alice}.  If @var{(user-path "path")} is specified, the
same request is taken as a request to access @code{path/foo} repository
in the home directory of user @code{alice}.

@item @code{listen} (default: @var{'()})
Whether to listen on specific IP addresses or hostnames, defaults to
all.

@item @code{port} (default: @var{#f})
Whether to listen on an alternative port, which defaults to 9418.

@item @code{whitelist} (default: @var{'()})
If not empty, only allow access to this list of directories.

@item @code{extra-options} (default: @var{'()})
Extra options will be passed to @code{git daemon}, please run
@command{man git-daemon} for more information.

@end table
@end deftp

@node Setuid Programs
@subsection 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
@subsection 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 GuixSD, 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}).  GuixSD 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 @var{%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 @code{SSL_CERT_DIR} and @code{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 @code{GIT_SSL_CAINFO} environment variable.  Thus, you
would typically run something like:

@example
$ guix package -i 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

@node Name Service Switch
@subsection 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{http://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}:

@example
(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 example

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} (@pxref{Networking Services,
@code{avahi-service}}), or @var{%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:

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

@node Initial RAM Disk
@subsection 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} 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 two ways to build an initrd: the
high-level @code{base-initrd} procedure, and the low-level
@code{expression->initrd} procedure.

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:

@example
(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")
                 rest)))
@end example

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 initial RAM disk produced by @code{base-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.

GuixSD 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 partition label, or a partition
UUID.

@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} provide, here is how to use it and customize it
further.

@cindex initrd
@cindex initial RAM disk
@deffn {Monadic Procedure} base-initrd @var{file-systems} @
       [#:qemu-networking? #f] [#:virtio? #t] [#:volatile-root? #f] @
       [#:extra-modules '()] [#:mapped-devices '()]
Return a monadic derivation that builds a generic 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 @code{--root}.
@var{mapped-devices} is a list of device mappings to realize before
@var{file-systems} are mounted (@pxref{Mapped Devices}).

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.

The initrd is automatically populated with all the kernel modules necessary
for @var{file-systems} and for the given options.  However, additional kernel
modules can be listed in @var{extra-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 {Monadic Procedure} expression->initrd @var{exp} @
       [#:guile %guile-static-stripped] [#:name "guile-initrd"]
Return a derivation that builds 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 GRUB Configuration
@subsection GRUB Configuration

@cindex GRUB
@cindex boot loader

The operating system uses GNU@tie{}GRUB as its boot loader
(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}).  It is
configured using a @code{grub-configuration} declaration.  This data type
is exported by the @code{(gnu system grub)} module and described below.

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

@table @asis

@item @code{device}
This is a string denoting the boot device.  It must be a device name
understood by the @command{grub-install} command, such as
@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
GNU GRUB Manual}).

@item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
entries to appear in the GRUB boot 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.

@item @code{theme} (default: @var{%default-theme})
The @code{grub-theme} object describing the theme to use.

@item @code{grub} (default: @code{grub})
The GRUB package to use.
@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:

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

Details below.

@deftp {Data Type} menu-entry
The type of an entry in the GRUB boot 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:

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

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., the 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 GRUB 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}.

@item @code{device-mount-point} (default: @code{"/"})
The mount point of the above device on the system.  You probably do not
need to change the default value.  GuixSD uses it to strip the prefix of
store file names for systems where @file{/gnu} or @file{/gnu/store} is
on a separate partition.

@end table
@end deftp

@c FIXME: Write documentation once it's stable.
Themes are created using the @code{grub-theme} form, which is not
documented yet.

@defvr {Scheme Variable} %default-theme
This is the default GRUB theme used by the operating system, with a
fancy background image displaying the GNU and Guix logos.
@end defvr


@node Invoking guix system
@subsection Invoking @code{guix system}

Once you have written an operating system declaration as seen in the
previous section, it can be @dfn{instantiated} using the @command{guix
system} command.  The synopsis is:

@example
guix system @var{options}@dots{} @var{action} @var{file}
@end example

@var{file} must be the name of a file containing an
@code{operating-system} declaration.  @var{action} specifies how the
operating system is instantiated.  Currently the following values are
supported:

@table @code
@item reconfigure
Build the operating system described in @var{file}, activate it, and
switch to it@footnote{This action (and the related actions
@code{switch-generation} and @code{roll-back}) are usable only on
systems already running GuixSD.}.

This effects all the configuration specified in @var{file}: user
accounts, system services, global package list, setuid programs, etc.
The command starts system services specified in @var{file} that are not
currently running; if a service is currently running, it does not
attempt to upgrade it since this would not be possible without stopping it
first.

This command creates a new generation whose number is one greater than
the current generation (as reported by @command{guix system
list-generations}).  If that generation already exists, it will be
overwritten.  This behavior mirrors that of @command{guix package}
(@pxref{Invoking guix package}).

It also adds a GRUB menu entry for the new OS configuration, and moves
entries for older configurations to a submenu---unless
@option{--no-grub} is passed.

@quotation Note
@c The paragraph below refers to the problem discussed at
@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
It is highly recommended to run @command{guix pull} once before you run
@command{guix system reconfigure} for the first time (@pxref{Invoking
guix pull}).  Failing to do that you would see an older version of Guix
once @command{reconfigure} has completed.
@end quotation

@item switch-generation
@cindex generations
Switch to an existing system generation.  This action atomically
switches the system profile to the specified system generation.  It also
rearranges the system's existing GRUB menu entries.  It makes the menu
entry for the specified system generation the default, and it moves the
entries for the other generations to a submenu.  The next time the
system boots, it will use the specified system generation.

The target generation can be specified explicitly by its generation
number.  For example, the following invocation would switch to system
generation 7:

@example
guix system switch-generation 7
@end example

The target generation can also be specified relative to the current
generation with the form @code{+N} or @code{-N}, where @code{+3} means
``3 generations ahead of the current generation,'' and @code{-1} means
``1 generation prior to the current generation.''  When specifying a
negative value such as @code{-1}, you must precede it with @code{--} to
prevent it from being parsed as an option.  For example:

@example
guix system switch-generation -- -1
@end example

Currently, the effect of invoking this action is @emph{only} to switch
the system profile to an existing generation and rearrange the GRUB menu
entries.  To actually start using the target system generation, you must
reboot after running this action.  In the future, it will be updated to
do the same things as @command{reconfigure}, like activating and
deactivating services.

This action will fail if the specified generation does not exist.

@item roll-back
@cindex rolling back
Switch to the preceding system generation.  The next time the system
boots, it will use the preceding system generation.  This is the inverse
of @command{reconfigure}, and it is exactly the same as invoking
@command{switch-generation} with an argument of @code{-1}.

Currently, as with @command{switch-generation}, you must reboot after
running this action to actually start using the preceding system
generation.

@item build
Build the derivation of the operating system, which includes all the
configuration files and programs needed to boot and run the system.
This action does not actually install anything.

@item init
Populate the given directory with all the files necessary to run the
operating system specified in @var{file}.  This is useful for first-time
installations of GuixSD.  For instance:

@example
guix system init my-os-config.scm /mnt
@end example

copies to @file{/mnt} all the store items required by the configuration
specified in @file{my-os-config.scm}.  This includes configuration
files, packages, and so on.  It also creates other essential files
needed for the system to operate correctly---e.g., the @file{/etc},
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.

This command also installs GRUB on the device specified in
@file{my-os-config}, unless the @option{--no-grub} option was passed.

@item vm
@cindex virtual machine
@cindex VM
@anchor{guix system vm}
Build a virtual machine that contains the operating system declared in
@var{file}, and return a script to run that virtual machine (VM).
Arguments given to the script are passed to QEMU.

The VM shares its store with the host system.

Additional file systems can be shared between the host and the VM using
the @code{--share} and @code{--expose} command-line options: the former
specifies a directory to be shared with write access, while the latter
provides read-only access to the shared directory.

The example below creates a VM in which the user's home directory is
accessible read-only, and where the @file{/exchange} directory is a
read-write mapping of @file{$HOME/tmp} on the host:

@example
guix system vm my-config.scm \
   --expose=$HOME --share=$HOME/tmp=/exchange
@end example

On GNU/Linux, the default is to boot directly to the kernel; this has
the advantage of requiring only a very tiny root disk image since the
store of the host can then be mounted.

The @code{--full-boot} option forces a complete boot sequence, starting
with the bootloader.  This requires more disk space since a root image
containing at least the kernel, initrd, and bootloader data files must
be created.  The @code{--image-size} option can be used to specify the
size of the image.

@item vm-image
@itemx disk-image
Return a virtual machine or disk image of the operating system declared
in @var{file} that stands alone.  Use the @option{--image-size} option
to specify the size of the image.

When using @code{vm-image}, the returned image is in qcow2 format, which
the QEMU emulator can efficiently use. @xref{Running GuixSD in a VM},
for more information on how to run the image in a virtual machine.

When using @code{disk-image}, a raw disk image is produced; it can be
copied as is to a USB stick, for instance.  Assuming @code{/dev/sdc} is
the device corresponding to a USB stick, one can copy the image to it
using the following command:

@example
# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
@end example

@item container
Return a script to run the operating system declared in @var{file}
within a container.  Containers are a set of lightweight isolation
mechanisms provided by the kernel Linux-libre.  Containers are
substantially less resource-demanding than full virtual machines since
the kernel, shared objects, and other resources can be shared with the
host system; this also means they provide thinner isolation.

Currently, the script must be run as root in order to support more than
a single user and group.  The container shares its store with the host
system.

As with the @code{vm} action (@pxref{guix system vm}), additional file
systems to be shared between the host and container can be specified
using the @option{--share} and @option{--expose} options:

@example
guix system container my-config.scm \
   --expose=$HOME --share=$HOME/tmp=/exchange
@end example

@quotation Note
This option requires Linux-libre 3.19 or newer.
@end quotation

@end table

@var{options} can contain any of the common build options (@pxref{Common
Build Options}).  In addition, @var{options} can contain one of the
following:

@table @option
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system} instead of the host system type.
This works as per @command{guix build} (@pxref{Invoking guix build}).

@item --derivation
@itemx -d
Return the derivation file name of the given operating system without
building anything.

@item --image-size=@var{size}
For the @code{vm-image} and @code{disk-image} actions, create an image
of the given @var{size}.  @var{size} may be a number of bytes, or it may
include a unit as a suffix (@pxref{Block size, size specifications,,
coreutils, GNU Coreutils}).

@item --on-error=@var{strategy}
Apply @var{strategy} when an error occurs when reading @var{file}.
@var{strategy} may be one of the following:

@table @code
@item nothing-special
Report the error concisely and exit.  This is the default strategy.

@item backtrace
Likewise, but also display a backtrace.

@item debug