guix.texi

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.

@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 @code{--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 @code{--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-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

@defvr {Scheme Variable} %default-theme
This is the default GRUB theme used by the operating system if no
@code{theme} field is specified in @code{bootloader-configuration}
record.

It comes with a fancy background image displaying the GNU and Guix
logos.
@end defvr

For example, to override the default resolution, you may use something
like

@lisp
(bootloader
 (grub-configuration
 ;; @dots{}
 (theme (grub-theme
         (inherit %default-theme)
         (gfxmode '("1024x786x32" "auto"))))))
@end lisp

@node Invoking guix system
@section 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 search
Display available service type definitions that match the given regular
expressions, sorted by relevance:

@cindex HDPI
@cindex HiDPI
@cindex resolution
@example
$ guix system search console
name: console-fonts
location: gnu/services/base.scm:806:2
extends: shepherd-root
description: Install the given fonts on the specified ttys (fonts are per
+ virtual console on GNU/Linux).  The value of this service is a list of
+ tty/font pairs.  The font can be the name of a font provided by the `kbd'
+ package or any valid argument to `setfont', as in this example:
+
+      '(("tty1" . "LatGrkCyr-8x16")
+        ("tty2" . (file-append
+                      font-tamzen
+                      "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
+        ("tty3" . (file-append
+                      font-terminus
+                      "/share/consolefonts/ter-132n"))) ; for HDPI
relevance: 9

name: mingetty
location: gnu/services/base.scm:1190:2
extends: shepherd-root
description: Provide console login using the `mingetty' program.
relevance: 2

name: login
location: gnu/services/base.scm:860:2
extends: pam
description: Provide a console log-in service as specified by its
+ configuration value, a `login-configuration' object.
relevance: 2

@dots{}
@end example

As for @command{guix package --search}, the result is written in
@code{recutils} format, which makes it easy to filter the output
(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).

@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 Guix System.}.

@quotation Note
@c The paragraph below refers to the problem discussed at
@c <https://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

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 this command will
arrange for it to be upgraded the next time it is stopped (e.g.@: by
@code{herd stop X} or @code{herd restart X}).

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 bootloader menu entry for the new OS configuration,
---unless @option{--no-bootloader} is passed.  For GRUB, it moves
entries for older configurations to a submenu, allowing you to choose
an older system generation at boot time should you need it.

@cindex provenance tracking, of the operating system
Upon completion, the new system is deployed under
@file{/run/current-system}.  This directory contains @dfn{provenance
meta-data}: the list of channels in use (@pxref{Channels}) and
@var{file} itself, when available.  This information is useful should
you later want to inspect how this particular generation was built.

In fact, assuming @var{file} is self-contained, you can later rebuild
generation @var{n} of your operating system with:

@example
guix time-machine \
  -C /var/guix/profiles/system-@var{n}-link/channels.scm -- \
  system reconfigure \
  /var/guix/profiles/system-@var{n}-link/configuration.scm
@end example

You can think of it as some sort of built-in version control!  Your
system is not just a binary artifact: @emph{it carries its own source}.
@xref{Service Reference, @code{provenance-service-type}}, for more
information on provenance tracking.

@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 bootloader 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, if
supported by the bootloader being used.  The next time the system
boots, it will use the specified system generation.

The bootloader itself is not being reinstalled when using this
command.  Thus, the installed bootloader is used with an updated
configuration file.

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
bootloader 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 delete-generations
@cindex deleting system generations
@cindex saving space
Delete system generations, making them candidates for garbage collection
(@pxref{Invoking guix gc}, for information on how to run the ``garbage
collector'').

This works in the same way as @command{guix package --delete-generations}
(@pxref{Invoking guix package, @code{--delete-generations}}).  With no
arguments, all system generations but the current one are deleted:

@example
guix system delete-generations
@end example

You can also select the generations you want to delete.  The example below
deletes all the system generations that are more than two month old:

@example
guix system delete-generations 2m
@end example

Running this command automatically reinstalls the bootloader with an updated
list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no
longer lists the generations that have been deleted.

@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 Guix System.  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 bootloader on the target specified in
@file{my-os-config}, unless the @option{--no-bootloader} 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).

@quotation Note
The @code{vm} action and others below
can use KVM support in the Linux-libre kernel.  Specifically, if the
machine has hardware virtualization support, the corresponding
KVM kernel module should be loaded, and the @file{/dev/kvm} device node
must exist and be readable and writable by the user and by the
build users of the daemon (@pxref{Build Environment Setup}).
@end quotation

Arguments given to the script are passed to QEMU as in the example
below, which enables networking and requests 1@tie{}GiB of RAM for the
emulated machine:

@example
$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -net user,model=virtio-net-pci
@end example

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.

@cindex System images, creation in various formats
@cindex Creating system images in various formats
@item vm-image
@itemx disk-image
@itemx docker-image
Return a virtual machine, disk image, or Docker image of the operating
system declared in @var{file} that stands alone.  By default,
@command{guix system} estimates the size of the image needed to store
the system, but you can use the @option{--image-size} option to specify
a value.  Docker images are built to contain exactly what they need, so
the @option{--image-size} option is ignored in the case of
@code{docker-image}.

You can specify the root file system type by using the
@option{--file-system-type} option.  It defaults to @code{ext4}.

When using @code{vm-image}, the returned image is in qcow2 format, which
the QEMU emulator can efficiently use. @xref{Running Guix 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

When using @code{docker-image}, a Docker image is produced.  Guix builds
the image from scratch, not from a pre-existing Docker base image.  As a
result, it contains @emph{exactly} what you define in the operating
system configuration file.  You can then load the image and launch a
Docker container using commands like the following:

@example
image_id="`docker load < guix-system-docker-image.tar.gz`"
container_id="`docker create $image_id`"
docker start $container_id
@end example

This command starts a new Docker container from the specified image.  It
will boot the Guix system in the usual manner, which means it will
start any services you have defined in the operating system
configuration.  You can get an interactive shell running in the container
using @command{docker exec}:

@example
docker exec -ti $container_id /run/current-system/profile/bin/bash --login
@end example

Depending on what you run in the Docker container, it
may be necessary to give the container additional permissions.  For
example, if you intend to build software using Guix inside of the Docker
container, you may need to pass the @option{--privileged} option to
@code{docker create}.

@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 --expression=@var{expr}
@itemx -e @var{expr}
Consider the operating-system @var{expr} evaluates to.
This is an alternative to specifying a file which evaluates to an
operating system.
This is used to generate the Guix system installer @pxref{Building the
Installation Image}).

@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.

@cindex provenance tracking, of the operating system
@item --save-provenance
As discussed above, @command{guix system init} and @command{guix system
reconfigure} always save provenance information @i{via} a dedicated
service (@pxref{Service Reference, @code{provenance-service-type}}).
However, other commands don't do that by default.  If you wish to, say,
create a virtual machine image that contains provenance information, you
can run:

@example
guix system vm-image --save-provenance config.scm
@end example

That way, the resulting image will effectively ``embed its own source''
in the form of meta-data in @file{/run/current-system}.  With that
information, one can rebuild the image to make sure it really contains
what it pretends to contain; or they could use that to derive a variant
of the image.

@item --file-system-type=@var{type}
@itemx -t @var{type}
For the @code{disk-image} action, create a file system of the given
@var{type} on the image.

When this option is omitted, @command{guix system} uses @code{ext4}.

@cindex ISO-9660 format
@cindex CD image format
@cindex DVD image format
@code{--file-system-type=iso9660} produces an ISO-9660 image, suitable
for burning on CDs and DVDs.

@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}).

When this option is omitted, @command{guix system} computes an estimate
of the image size as a function of the size of the system declared in
@var{file}.

@item --network
@itemx -N
For the @code{container} action, allow containers to access the host network,
that is, do not create a network namespace.

@item --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
collector root.

@item --skip-checks
Skip pre-installation safety checks.

By default, @command{guix system init} and @command{guix system
reconfigure} perform safety checks: they make sure the file systems that
appear in the @code{operating-system} declaration actually exist
(@pxref{File Systems}), and that any Linux kernel modules that may be
needed at boot time are listed in @code{initrd-modules} (@pxref{Initial
RAM Disk}).  Passing this option skips these tests altogether.

@cindex on-error
@cindex on-error strategy
@cindex error strategy
@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
Report the error and enter Guile's debugger.  From there, you can run
commands such as @code{,bt} to get a backtrace, @code{,locals} to
display local variable values, and more generally inspect the state of the
program.  @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
a list of available debugging commands.
@end table
@end table

Once you have built, configured, re-configured, and re-re-configured
your Guix installation, you may find it useful to list the operating
system generations available on disk---and that you can choose from the
bootloader boot menu:

@table @code

@item describe
Describe the current system generation: its file name, the kernel and
bootloader used, etc., as well as provenance information when available.

@item list-generations
List a summary of each generation of the operating system available on
disk, in a human-readable way.  This is similar to the
@option{--list-generations} option of @command{guix package}
(@pxref{Invoking guix package}).

Optionally, one can specify a pattern, with the same syntax that is used
in @command{guix package --list-generations}, to restrict the list of
generations displayed.  For instance, the following command displays
generations that are up to 10 days old:

@example
$ guix system list-generations 10d
@end example

@end table

The @command{guix system} command has even more to offer!  The following
sub-commands allow you to visualize how your system services relate to
each other:

@anchor{system-extension-graph}
@table @code

@item extension-graph
Emit in Dot/Graphviz format to standard output the @dfn{service
extension graph} of the operating system defined in @var{file}
(@pxref{Service Composition}, for more information on service
extensions.)

The command:

@example
$ guix system extension-graph @var{file} | dot -Tpdf > services.pdf
@end example

produces a PDF file showing the extension relations among services.

@anchor{system-shepherd-graph}
@item shepherd-graph
Emit in Dot/Graphviz format to standard output the @dfn{dependency
graph} of shepherd services of the operating system defined in
@var{file}.  @xref{Shepherd Services}, for more information and for an
example graph.

@end table

@node Invoking guix deploy
@section Invoking @code{guix deploy}

We've already seen @code{operating-system} declarations used to manage a
machine's configuration locally.  Suppose you need to configure multiple
machines, though---perhaps you're managing a service on the web that's
comprised of several servers.  @command{guix deploy} enables you to use those
same @code{operating-system} declarations to manage multiple remote hosts at
once as a logical ``deployment''.

@quotation Note
The functionality described in this section is still under development
and is subject to change.  Get in touch with us on
@email{guix-devel@@gnu.org}!
@end quotation

@example
guix deploy @var{file}
@end example

Such an invocation will deploy the machines that the code within @var{file}
evaluates to.  As an example, @var{file} might contain a definition like this:

@lisp
;; This is a Guix deployment of a "bare bones" setup, with
;; no X11 display server, to a machine with an SSH daemon
;; listening on localhost:2222. A configuration such as this
;; may be appropriate for virtual machine with ports
;; forwarded to the host's loopback interface.

(use-service-modules networking ssh)
(use-package-modules bootloaders)

(define %system
  (operating-system
   (host-name "gnu-deployed")
   (timezone "Etc/UTC")
   (bootloader (bootloader-configuration
                (bootloader grub-bootloader)
                (target "/dev/vda")
                (terminal-outputs '(console))))
   (file-systems (cons (file-system
                        (mount-point "/")
                        (device "/dev/vda1")
                        (type "ext4"))
                       %base-file-systems))
   (services
    (append (list (service dhcp-client-service-type)
                  (service openssh-service-type
                           (openssh-configuration
                            (permit-root-login #t)
                            (allow-empty-passwords? #t))))
            %base-services))))

(list (machine
       (operating-system %system)
       (environment managed-host-environment-type)
       (configuration (machine-ssh-configuration
                       (host-name "localhost")
                       (system "x86_64-linux")
                       (user "alice")
                       (identity "./id_rsa")
                       (port 2222)))))
@end lisp

The file should evaluate to a list of @var{machine} objects.  This example,
upon being deployed, will create a new generation on the remote system
realizing the @code{operating-system} declaration @var{%system}.
@var{environment} and @var{configuration} specify how the machine should be
provisioned---that is, how the computing resources should be created and
managed.  The above example does not create any resources, as a
@code{'managed-host} is a machine that is already running the Guix system and
available over the network.  This is a particularly simple case; a more
complex deployment may involve, for example, starting virtual machines through
a Virtual Private Server (VPS) provider.  In such a case, a different
@var{environment} type would be used.

Do note that you first need to generate a key pair on the coordinator machine
to allow the daemon to export signed archives of files from the store
(@pxref{Invoking guix archive}).

@example
# guix archive --generate-key
@end example

@noindent
Each target machine must authorize the key of the master machine so that it
accepts store items it receives from the coordinator:

@example
# guix archive --authorize < coordinator-public-key.txt
@end example

@code{user}, in this example, specifies the name of the user account to log in
as to perform the deployment.  Its default value is @code{root}, but root
login over SSH may be forbidden in some cases.  To work around this,
@command{guix deploy} can log in as an unprivileged user and employ
@code{sudo} to escalate privileges.  This will only work if @code{sudo} is
currently installed on the remote and can be invoked non-interactively as
@code{user}.  That is, the line in @code{sudoers} granting @code{user} the
ability to use @code{sudo} must contain the @code{NOPASSWD} tag.  This can