guix.texi

@item hybrid-sleep-state
@code{("disk")}
@item hybrid-sleep-mode
@code{("suspend" "platform" "shutdown")}
@end table
@end deffn

@deffn {Scheme Procedure} polkit-service @
                         [#:polkit @var{polkit}]
Return a service that runs the
@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
management service}, which allows system administrators to grant access to
privileged operations in a structured way.  By querying the Polkit service, a
privileged system component can know when it should grant additional
capabilities to ordinary users.  For example, an ordinary user can be granted
the capability to suspend the system if the user is logged in locally.
@end deffn

@deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @
                         [#:watts-up-pro? #f] @
                         [#:poll-batteries? #t] @
                         [#:ignore-lid? #f] @
                         [#:use-percentage-for-policy? #f] @
                         [#:percentage-low 10] @
                         [#:percentage-critical 3] @
                         [#:percentage-action 2] @
                         [#:time-low 1200] @
                         [#:time-critical 300] @
                         [#:time-action 120] @
                         [#:critical-power-action 'hybrid-sleep]
Return a service that runs @uref{http://upower.freedesktop.org/,
@command{upowerd}}, a system-wide monitor for power consumption and battery
levels, with the given configuration settings.  It implements the
@code{org.freedesktop.UPower} D-Bus interface, and is notably used by
GNOME.
@end deffn

@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
Return a service for @uref{http://udisks.freedesktop.org/docs/latest/,
UDisks}, a @dfn{disk management} daemon that provides user interfaces with
notifications and ways to mount/unmount disks.  Programs that talk to UDisks
include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
@end deffn

@deffn {Scheme Procedure} colord-service [#:colord @var{colord}]
Return a service that runs @command{colord}, a system service with a D-Bus
interface to manage the color profiles of input and output devices such as
screens and scanners.  It is notably used by the GNOME Color Manager graphical
tool.  See @uref{http://www.freedesktop.org/software/colord/, the colord web
site} for more information.
@end deffn

@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
Return an configuration allowing an application to access GeoClue
location data.  @var{name} is the Desktop ID of the application, without
the @code{.desktop} part.  If @var{allowed?} is true, the application
will have access to location information by default.  The boolean
@var{system?}  value indicates that an application is a system component
or not.  Finally @var{users} is a list of UIDs of all users for which
this application is allowed location info access.  An empty users list
means that all users are allowed.
@end deffn

@defvr {Scheme Variable} %standard-geoclue-applications
The standard list of well-known GeoClue application configurations,
granting authority to GNOME's date-and-time utility to ask for the
current location in order to set the time zone, and allowing the Firefox
(IceCat) and Epiphany web browsers to request location information.
Firefox and Epiphany both query the user before allowing a web page to
know the user's location.
@end defvr

@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
                         [#:whitelist '()] @
                         [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
                         [#:submit-data? #f]
                         [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
                         [#:submission-nick "geoclue"] @
                         [#:applications %standard-geoclue-applications]
Return a service that runs the GeoClue location service.  This service
provides a D-Bus interface to allow applications to request access to a
user's physical location, and optionally to add information to online
location databases.  See
@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
web site} for more information.
@end deffn

@node Database Services
@subsubsection Database Services

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

@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
       [#:config-file] [#:data-directory ``/var/lib/postgresql/data'']
Return a service that runs @var{postgresql}, the PostgreSQL database
server.

The PostgreSQL daemon loads its runtime configuration from
@var{config-file} and stores the database cluster in
@var{data-directory}.
@end deffn

@node Web Services
@subsubsection Web Services

The @code{(gnu services web)} module provides the following service:

@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
       [#:log-directory ``/var/log/nginx''] @
       [#:run-directory ``/var/run/nginx''] @
       [#:config-file]

Return a service that runs @var{nginx}, the nginx web server.

The nginx daemon loads its runtime configuration from @var{config-file}.
Log files are written to @var{log-directory} and temporary runtime data
files are written to @var{run-directory}.  For proper operation, these
arguments should match what is in @var{config-file} to ensure that the
directories are created when the service is activated.

@end deffn

@node Various Services
@subsubsection Various Services

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


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


@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 libc's @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

Don't worry: the @code{%mdns-host-lookup-nss} variable (see below)
contains this configuration, so you won't 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 C library's configuration file format, so
please refer to the C library manual for more information (@pxref{NSS
Configuration File,,, libc, The GNU C Library Reference Manual}).
Compared to libc's NSS configuration file format, it has the advantage
not only of adding this warm parenthetic feel that we like, but also
static checks: you'll 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 initial RAM disk (initrd)
@cindex initrd (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 whose
root file system is volatile.

@deffn {Monadic Procedure} base-initrd @var{file-systems} @
       [#:qemu-networking? #f] [#:virtio? #f] [#: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 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"] @
       [#:modules '()]
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.

@var{modules} is a list of Guile module names to be embedded in 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 @code{grub-configuration} declarations.  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 current
system's entry.

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

@end deftp

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:

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

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

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

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.

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

@item build
Build the operating system's derivation, 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 contain the operating system declared in
@var{file}, and return a script to run that virtual machine (VM).
Arguments given to the script are passed as is 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 the host's @file{$HOME/tmp}:

@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
host's store 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
image's size.

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

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 on 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 provided by
@command{guix build} (@pxref{Invoking guix build}).  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's 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
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 program's
state.  @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
a list of available debugging commands.
@end table
@end table

Note that all the actions above, except @code{build} and @code{init},
rely on KVM support in the Linux-Libre kernel.  Specifically, the
machine should have 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 daemon's
build users.

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

@table @code

@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 up to 10-day 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-dmd-graph}
@item dmd-graph
Emit in Dot/Graphviz format to standard output the @dfn{dependency
graph} of dmd services of the operating system defined in @var{file}.
@xref{dmd Services}, for more information and for an example graph.

@end table


@node Defining Services
@subsection 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.
* dmd Services::                A particular type of service.
@end menu

@node Service Composition
@subsubsection Service Composition

@cindex services
@cindex daemons
Here we define a @dfn{service} as, broadly, something that extends the
operating system's functionality.  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 system's @file{/etc}
directory.

@cindex service extensions
GuixSD services are connected by @dfn{extensions}.  For instance, the
secure shell service @emph{extends} dmd---GuixSD's 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{lsh-service}}); 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 dmd 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 @var{lsh-service-type}, with
different parameters.

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

@node Service Types and Services
@subsubsection 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}):

@example
(define guix-service-type
  (service-type
   (name 'guix)
   (extensions
    (list (service-extension dmd-root-service-type guix-dmd-service)
          (service-extension account-service-type guix-accounts)
          (service-extension activation-service-type guix-activation)))))
@end example

@noindent
It defines a two 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 service's
parameters, returns a list of object 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.
@end enumerate

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

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

@item account-service-type
This extension for this service is computed by @var{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 @var{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:

@example
(service guix-service-type
         (guix-configuration
           (build-accounts 5)
           (use-substitutes? #f)))
@end example

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.

@var{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:

@example
(define udev-service-type
  (service-type (name 'udev)
                (extensions
                 (list (service-extension dmd-root-service-type
                                          udev-dmd-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 example

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 @var{dmd-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 service's value 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 is contains to the
list of contributed rules.
@end table

There can be only one instance of an extensible service type such as
@var{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
@subsubsection 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.
@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-parameters @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:

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

(eq? (service-kind s) nginx-service-type)
@result{} #t
@end example

The @code{modify-services} form provides a handy way to change the
parameters of some of the services of a list such as
@var{%base-services} (@pxref{Base Services, @code{%base-services}}).  Of
course, you could always use standard list combinators such as