guix.texi

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 @samp{guix package --delete-generations}
(@pxref{Invoking guix package, @option{--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 @option{--share} and @option{--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 @option{--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 @option{--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}.

The @code{disk-image} command can produce various image types.  The
image type can be selected using the @command{--image-type} option.  It
defaults to @code{raw}. When its value is @code{iso9660}, the
@option{--label} option can be used to specify a volume ID with
@code{disk-image}.

When using the @code{raw} image type, 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 status=progress
@end example

The @code{--list-image-types} command lists all the available image
types.

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{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}.

Last, the @option{--network} option applies to @command{guix system
docker-image}: it produces an image where network is supposedly shared
with the host, and thus without services like nscd or NetworkManager.

@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 --image-type=@var{type}
@itemx -t @var{type}
For the @code{disk-image} action, create an image with given @var{type}.

When this option is omitted, @command{guix system} uses the @code{raw}
image type.

@cindex ISO-9660 format
@cindex CD image format
@cindex DVD image format
@option{--image-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.

@item --allow-downgrades
Instruct @command{guix system reconfigure} to allow system downgrades.

By default, @command{reconfigure} prevents you from downgrading your
system.  It achieves that by comparing the provenance info of your
system (shown by @command{guix system describe}) with that of your
@command{guix} command (shown by @command{guix describe}).  If the
commits for @command{guix} are not descendants of those used for your
system, @command{guix system reconfigure} errors out.  Passing
@option{--allow-downgrades} allows you to bypass these checks.

@quotation Note
Make sure you understand its security implications before using
@option{--allow-downgrades}.
@end quotation

@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} | xdot -
@end example

shows 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 @code{%system}.
@code{environment} and @code{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}), though this step is automatic on Guix
System:

@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
be accomplished with the following operating system configuration snippet:

@lisp
(use-modules ...
             (gnu system))               ;for %sudoers-specification

(define %user "username")

(operating-system
  ...
  (sudoers-file
     (plain-file "sudoers"
                 (string-append (plain-file-content %sudoers-specification)
                                (format #f "~a ALL = NOPASSWD: ALL~%"
                                        %user)))))

@end lisp

For more information regarding the format of the @file{sudoers} file,
consult @command{man sudoers}.

@deftp {Data Type} machine
This is the data type representing a single machine in a heterogeneous Guix
deployment.

@table @asis
@item @code{operating-system}
The object of the operating system configuration to deploy.

@item @code{environment}
An @code{environment-type} describing how the machine should be provisioned.

@item @code{configuration} (default: @code{#f})
An object describing the configuration for the machine's @code{environment}.
If the @code{environment} has a default configuration, @code{#f} may be used.
If @code{#f} is used for an environment with no default configuration,
however, an error will be thrown.
@end table
@end deftp

@deftp {Data Type} machine-ssh-configuration
This is the data type representing the SSH client parameters for a machine
with an @code{environment} of @code{managed-host-environment-type}.

@table @asis
@item @code{host-name}
@item @code{build-locally?} (default: @code{#t})
If false, system derivations will be built on the machine being deployed to.
@item @code{system}
The system type describing the architecture of the machine being deployed
to---e.g., @code{"x86_64-linux"}.
@item @code{authorize?} (default: @code{#t})
If true, the coordinator's signing key will be added to the remote's ACL
keyring.
@item @code{port} (default: @code{22})
@item @code{user} (default: @code{"root"})
@item @code{identity} (default: @code{#f})
If specified, the path to the SSH private key to use to authenticate with the
remote host.

@item @code{host-key} (default: @code{#f})
This should be the SSH host key of the machine, which looks like this:

@example
ssh-ed25519 AAAAC3Nz@dots{} root@@example.org
@end example

When @code{host-key} is @code{#f}, the server is authenticated against
the @file{~/.ssh/known_hosts} file, just like the OpenSSH @command{ssh}
client does.

@item @code{allow-downgrades?} (default: @code{#f})
Whether to allow potential downgrades.

Like @command{guix system reconfigure}, @command{guix deploy} compares
the channel commits currently deployed on the remote host (as returned
by @command{guix system describe}) to those currently in use (as
returned by @command{guix describe}) to determine whether commits
currently in use are descendants of those deployed.  When this is not
the case and @code{allow-downgrades?} is false, it raises an error.
This ensures you do not accidentally downgrade remote machines.
@end table
@end deftp

@deftp {Data Type} digital-ocean-configuration
This is the data type describing the Droplet that should be created for a
machine with an @code{environment} of @code{digital-ocean-environment-type}.

@table @asis
@item @code{ssh-key}
The path to the SSH private key to use to authenticate with the remote
host. In the future, this field may not exist.
@item @code{tags}
A list of string ``tags'' that uniquely identify the machine. Must be given
such that no two machines in the deployment have the same set of tags.
@item @code{region}
A Digital Ocean region slug, such as @code{"nyc3"}.
@item @code{size}
A Digital Ocean size slug, such as @code{"s-1vcpu-1gb"}
@item @code{enable-ipv6?}
Whether or not the droplet should be created with IPv6 networking.
@end table
@end deftp

@node Running Guix in a VM
@section Running Guix in a Virtual Machine

@cindex virtual machine
To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image
distributed at
@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.xz}.
This image is a compressed image in QCOW format.  You will first need to
decompress with @command{xz -d}, and then you can pass it to an emulator such
as QEMU (see below for details).

This image boots the Xfce graphical environment and it contains some
commonly-used tools.  You can install more software in the image by running
@command{guix package} in a terminal (@pxref{Invoking guix package}).  You can
also reconfigure the system based on its initial configuration file available
as @file{/run/current-system/configuration.scm} (@pxref{Using the
Configuration System}).

Instead of using this pre-built image, one can also build their own virtual
machine image using @command{guix system vm-image} (@pxref{Invoking guix
system}).  The returned image is in qcow2 format, which the
@uref{https://qemu.org/, QEMU emulator} can efficiently use.

@cindex QEMU
If you built your own image, you must copy it out of the store
(@pxref{The Store}) and give yourself permission to write to the copy
before you can use it.  When invoking QEMU, you must choose a system
emulator that is suitable for your hardware platform.  Here is a minimal
QEMU invocation that will boot the result of @command{guix system
vm-image} on x86_64 hardware:

@example
$ qemu-system-x86_64 \
   -nic user,model=virtio-net-pci \
   -enable-kvm -m 1024 \
   -device virtio-blk,drive=myhd \
   -drive if=none,file=/tmp/qemu-image,id=myhd
@end example

Here is what each of these options means:

@table @code
@item qemu-system-x86_64
This specifies the hardware platform to emulate.  This should match the
host.

@item -nic user,model=virtio-net-pci
Enable the unprivileged user-mode network stack.  The guest OS can
access the host but not vice versa.  This is the simplest way to get the
guest OS online.  @code{model} specifies which network device to emulate:
@code{virtio-net-pci} is a special device made for virtualized operating
systems and recommended for most uses.  Assuming your hardware platform is
x86_64, you can get a list of available NIC models by running
@command{qemu-system-x86_64 -nic model=help}.

@item -enable-kvm
If your system has hardware virtualization extensions, enabling the
virtual machine support (KVM) of the Linux kernel will make things run
faster.

@c To run Xfce + 'guix pull', we need at least 1G of RAM.
@item -m 1024
RAM available to the guest OS, in mebibytes.  Defaults to 128@tie{}MiB,
which may be insufficient for some operations.

@item -device virtio-blk,drive=myhd
Create a @code{virtio-blk} drive called ``myhd''.  @code{virtio-blk} is a
``paravirtualization'' mechanism for block devices that allows QEMU to achieve
better performance than if it were emulating a complete disk drive.  See the
QEMU and KVM documentation for more info.

@item -drive if=none,file=/tmp/qemu-image,id=myhd
Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing store the
the ``myhd'' drive.
@end table

The default @command{run-vm.sh} script that is returned by an invocation of
@command{guix system vm} does not add a @command{-nic user} flag by default.
To get network access from within the vm add the @code{(dhcp-client-service)}
to your system definition and start the VM using
@command{`guix system vm config.scm` -nic user}.  An important caveat of using
@command{-nic user} for networking is that @command{ping} will not work, because
it uses the ICMP protocol.  You'll have to use a different command to check for
network connectivity, for example @command{guix download}.

@subsection Connecting Through SSH

@cindex SSH
@cindex SSH server
To enable SSH inside a VM you need to add an SSH server like
@code{openssh-service-type} to your VM (@pxref{Networking Services,
@code{openssh-service-type}}).  In addition you need to forward the SSH port,
22 by default, to the host.  You can do this with

@example
`guix system vm config.scm` -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
@end example

To connect to the VM you can run

@example
ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022
@end example

The @command{-p} tells @command{ssh} the port you want to connect to.
@command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from complaining
every time you modify your @command{config.scm} file and the
@command{-o StrictHostKeyChecking=no} prevents you from having to allow a
connection to an unknown host every time you connect.

@subsection Using @command{virt-viewer} with Spice

As an alternative to the default @command{qemu} graphical client you can
use the @command{remote-viewer} from the @command{virt-viewer} package.  To
connect pass the @command{-spice port=5930,disable-ticketing} flag to
@command{qemu}.  See previous section for further information on how to do this.

Spice also allows you to do some nice stuff like share your clipboard with your
VM.  To enable that you'll also have to pass the following flags to @command{qemu}:

@example
-device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
-chardev spicevmc,name=vdagent,id=vdagent
-device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,
name=com.redhat.spice.0
@end example

You'll also need to add the @code{(spice-vdagent-service)} to your
system definition (@pxref{Miscellaneous Services, Spice service}).

@node Defining Services
@section Defining Services

The previous sections show the available services and how one can combine
them in an @code{operating-system} declaration.  But how do we define
them in the first place?  And what is a service anyway?

@menu
* Service Composition::         The model for composing services.
* Service Types and Services::  Types and services.
* Service Reference::           API reference.
* Shepherd Services::           A particular type of service.
@end menu

@node Service Composition
@subsection Service Composition

@cindex services
@cindex daemons
Here we define a @dfn{service} as, broadly, something that extends the
functionality of the operating system.  Often a service is a process---a
@dfn{daemon}---started when the system boots: a secure shell server, a
Web server, the Guix build daemon, etc.  Sometimes a service is a daemon
whose execution can be triggered by another daemon---e.g., an FTP server
started by @command{inetd} or a D-Bus service activated by
@command{dbus-daemon}.  Occasionally, a service does not map to a
daemon.  For instance, the ``account'' service collects user accounts
and makes sure they exist when the system runs; the ``udev'' service
collects device management rules and makes them available to the eudev
daemon; the @file{/etc} service populates the @file{/etc} directory
of the system.

@cindex service extensions
Guix system services are connected by @dfn{extensions}.  For instance, the
secure shell service @emph{extends} the Shepherd---the
initialization system, running as PID@tie{}1---by giving it the command
lines to start and stop the secure shell daemon (@pxref{Networking
Services, @code{openssh-service-type}}); the UPower service extends the D-Bus
service by passing it its @file{.service} specification, and extends the
udev service by passing it device management rules (@pxref{Desktop
Services, @code{upower-service}}); the Guix daemon service extends the
Shepherd by passing it the command lines to start and stop the daemon,
and extends the account service by passing it a list of required build
user accounts (@pxref{Base Services}).

All in all, services and their ``extends'' relations form a directed
acyclic graph (DAG).  If we represent services as boxes and extensions
as arrows, a typical system might provide something like this:

@image{images/service-graph,,5in,Typical service extension graph.}

@cindex system service
At the bottom, we see the @dfn{system service}, which produces the
directory containing everything to run and boot the system, as returned
by the @command{guix system build} command.  @xref{Service Reference},
to learn about the other service types shown here.
@xref{system-extension-graph, the @command{guix system extension-graph}
command}, for information on how to generate this representation for a
particular operating system definition.

@cindex service types
Technically, developers can define @dfn{service types} to express these
relations.  There can be any number of services of a given type on the
system---for instance, a system running two instances of the GNU secure
shell server (lsh) has two instances of @code{lsh-service-type}, with
different parameters.

The following section describes the programming interface for service
types and services.

@node Service Types and Services
@subsection Service Types and Services

A @dfn{service type} is a node in the DAG described above.  Let us start
with a simple example, the service type for the Guix build daemon
(@pxref{Invoking guix-daemon}):

@lisp
(define guix-service-type
  (service-type
   (name 'guix)
   (extensions
    (list (service-extension shepherd-root-service-type guix-shepherd-service)
          (service-extension account-service-type guix-accounts)
          (service-extension activation-service-type guix-activation)))
   (default-value (guix-configuration))))
@end lisp

@noindent
It defines three things:

@enumerate
@item
A name, whose sole purpose is to make inspection and debugging easier.

@item
A list of @dfn{service extensions}, where each extension designates the
target service type and a procedure that, given the parameters of the
service, returns a list of objects to extend the service of that type.

Every service type has at least one service extension.  The only
exception is the @dfn{boot service type}, which is the ultimate service.

@item
Optionally, a default value for instances of this type.
@end enumerate

In this example, @code{guix-service-type} extends three services:

@table @code
@item shepherd-root-service-type
The @code{guix-shepherd-service} procedure defines how the Shepherd
service is extended.  Namely, it returns a @code{<shepherd-service>}
object that defines how @command{guix-daemon} is started and stopped
(@pxref{Shepherd Services}).

@item account-service-type
This extension for this service is computed by @code{guix-accounts},
which returns a list of @code{user-group} and @code{user-account}
objects representing the build user accounts (@pxref{Invoking
guix-daemon}).

@item activation-service-type
Here @code{guix-activation} is a procedure that returns a gexp, which is
a code snippet to run at ``activation time''---e.g., when the service is
booted.
@end table

A service of this type is instantiated like this:

@lisp
(service guix-service-type
         (guix-configuration
           (build-accounts 5)
           (extra-options '("--gc-keep-derivations"))))
@end lisp

The second argument to the @code{service} form is a value representing
the parameters of this specific service instance.
@xref{guix-configuration-type, @code{guix-configuration}}, for
information about the @code{guix-configuration} data type.  When the
value is omitted, the default value specified by
@code{guix-service-type} is used:

@lisp
(service guix-service-type)
@end lisp

@code{guix-service-type} is quite simple because it extends other
services but is not extensible itself.

@c @subsubsubsection Extensible Service Types

The service type for an @emph{extensible} service looks like this:

@lisp
(define udev-service-type
  (service-type (name 'udev)
                (extensions
                 (list (service-extension shepherd-root-service-type
                                          udev-shepherd-service)))

                (compose concatenate)       ;concatenate the list of rules
                (extend (lambda (config rules)
                          (match config
                            (($ <udev-configuration> udev initial-rules)
                             (udev-configuration
                              (udev udev)   ;the udev package to use
                              (rules (append initial-rules rules)))))))))
@end lisp

This is the service type for the
@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
management daemon}.  Compared to the previous example, in addition to an
extension of @code{shepherd-root-service-type}, we see two new fields:

@table @code
@item compose
This is the procedure to @dfn{compose} the list of extensions to
services of this type.

Services can extend the udev service by passing it lists of rules; we
compose those extensions simply by concatenating them.

@item extend
This procedure defines how the value of the service is @dfn{extended} with
the composition of the extensions.

Udev extensions are composed into a list of rules, but the udev service
value is itself a @code{<udev-configuration>} record.  So here, we
extend that record by appending the list of rules it contains to the
list of contributed rules.

@item description
This is a string giving an overview of the service type.  The string can
contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}).  The
@command{guix system search} command searches these strings and displays
them (@pxref{Invoking guix system}).
@end table

There can be only one instance of an extensible service type such as
@code{udev-service-type}.  If there were more, the
@code{service-extension} specifications would be ambiguous.

Still here?  The next section provides a reference of the programming
interface for services.

@node Service Reference
@subsection Service Reference

We have seen an overview of service types (@pxref{Service Types and
Services}).  This section provides a reference on how to manipulate
services and service types.  This interface is provided by the
@code{(gnu services)} module.

@deffn {Scheme Procedure} service @var{type} [@var{value}]
Return a new service of @var{type}, a @code{<service-type>} object (see
below).  @var{value} can be any object; it represents the parameters of
this particular service instance.

When @var{value} is omitted, the default value specified by @var{type}
is used; if @var{type} does not specify a default value, an error is
raised.

For instance, this:

@lisp
(service openssh-service-type)
@end lisp

@noindent
is equivalent to this:

@lisp
(service openssh-service-type
         (openssh-configuration))
@end lisp

In both cases the result is an instance of @code{openssh-service-type}
with the default configuration.
@end deffn

@deffn {Scheme Procedure} service? @var{obj}
Return true if @var{obj} is a service.
@end deffn

@deffn {Scheme Procedure} service-kind @var{service}
Return the type of @var{service}---i.e., a @code{<service-type>} object.
@end deffn

@deffn {Scheme Procedure} service-value @var{service}
Return the value associated with @var{service}.  It represents its
parameters.
@end deffn

Here is an example of how a service is created and manipulated:

@lisp
(define s
  (service nginx-service-type
           (nginx-configuration
            (nginx nginx)
            (log-directory log-directory)
            (run-directory run-directory)
            (file config-file))))

(service? s)
@result{} #t