guix.texi

(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

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

The @code{modify-services} form provides a handy way to change the
parameters of some of the services of a list such as
@code{%base-services} (@pxref{Base Services, @code{%base-services}}).  It
evaluates to a list of services.  Of course, you could always use
standard list combinators such as @code{map} and @code{fold} to do that
(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
@code{modify-services} simply provides a more concise form for this
common pattern.

@deffn {Scheme Syntax} modify-services @var{services} @
  (@var{type} @var{variable} => @var{body}) @dots{}

Modify the services listed in @var{services} according to the given
clauses.  Each clause has the form:

@example
(@var{type} @var{variable} => @var{body})
@end example

where @var{type} is a service type---e.g.,
@code{guix-service-type}---and @var{variable} is an identifier that is
bound within the @var{body} to the service parameters---e.g., a
@code{guix-configuration} instance---of the original service of that
@var{type}.

The @var{body} should evaluate to the new service parameters, which will
be used to configure the new service.  This new service will replace the
original in the resulting list.  Because a service's service parameters
are created using @code{define-record-type*}, you can write a succinct
@var{body} that evaluates to the new service parameters by using the
@code{inherit} feature that @code{define-record-type*} provides.

@xref{Using the Configuration System}, for example usage.

@end deffn

Next comes the programming interface for service types.  This is
something you want to know when writing new service definitions, but not
necessarily when simply looking for ways to customize your
@code{operating-system} declaration.

@deftp {Data Type} service-type
@cindex service type
This is the representation of a @dfn{service type} (@pxref{Service Types
and Services}).

@table @asis
@item @code{name}
This is a symbol, used only to simplify inspection and debugging.

@item @code{extensions}
A non-empty list of @code{<service-extension>} objects (see below).

@item @code{compose} (default: @code{#f})
If this is @code{#f}, then the service type denotes services that cannot
be extended---i.e., services that do not receive ``values'' from other
services.

Otherwise, it must be a one-argument procedure.  The procedure is called
by @code{fold-services} and is passed a list of values collected from
extensions.  It may return any single value.

@item @code{extend} (default: @code{#f})
If this is @code{#f}, services of this type cannot be extended.

Otherwise, it must be a two-argument procedure: @code{fold-services}
calls it, passing it the initial value of the service as the first
argument and the result of applying @code{compose} to the extension
values as the second argument.  It must return a value that is a valid
parameter value for the service instance.

@item @code{description}
This is a string, possibly using Texinfo markup, describing in a couple
of sentences what the service is about.  This string allows users to
find about the service through @command{guix system search}
(@pxref{Invoking guix system}).

@item @code{default-value} (default: @code{&no-default-value})
The default value associated for instances of this service type.  This
allows users to use the @code{service} form without its second argument:

@lisp
(service @var{type})
@end lisp

The returned service in this case has the default value specified by
@var{type}.
@end table

@xref{Service Types and Services}, for examples.
@end deftp

@deffn {Scheme Procedure} service-extension @var{target-type} @
                              @var{compute}
Return a new extension for services of type @var{target-type}.
@var{compute} must be a one-argument procedure: @code{fold-services}
calls it, passing it the value associated with the service that provides
the extension; it must return a valid value for the target service.
@end deffn

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

Occasionally, you might want to simply extend an existing service.  This
involves creating a new service type and specifying the extension of
interest, which can be verbose; the @code{simple-service} procedure
provides a shorthand for this.

@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
Return a service that extends @var{target} with @var{value}.  This works
by creating a singleton service type @var{name}, of which the returned
service is an instance.

For example, this extends mcron (@pxref{Scheduled Job Execution}) with
an additional job:

@lisp
(simple-service 'my-mcron-job mcron-service-type
                #~(job '(next-hour (3)) "guix gc -F 2G"))
@end lisp
@end deffn

At the core of the service abstraction lies the @code{fold-services}
procedure, which is responsible for ``compiling'' a list of services
down to a single directory that contains everything needed to boot and
run the system---the directory shown by the @command{guix system build}
command (@pxref{Invoking guix system}).  In essence, it propagates
service extensions down the service graph, updating each node parameters
on the way, until it reaches the root node.

@deffn {Scheme Procedure} fold-services @var{services} @
                            [#:target-type @var{system-service-type}]
Fold @var{services} by propagating their extensions down to the root of
type @var{target-type}; return the root service adjusted accordingly.
@end deffn

Lastly, the @code{(gnu services)} module also defines several essential
service types, some of which are listed below.

@defvr {Scheme Variable} system-service-type
This is the root of the service graph.  It produces the system directory
as returned by the @command{guix system build} command.
@end defvr

@defvr {Scheme Variable} boot-service-type
The type of the ``boot service'', which produces the @dfn{boot script}.
The boot script is what the initial RAM disk runs when booting.
@end defvr

@defvr {Scheme Variable} etc-service-type
The type of the @file{/etc} service.  This service is used to create
files under @file{/etc} and can be extended by
passing it name/file tuples such as:

@lisp
(list `("issue" ,(plain-file "issue" "Welcome!\n")))
@end lisp

In this example, the effect would be to add an @file{/etc/issue} file
pointing to the given file.
@end defvr

@defvr {Scheme Variable} setuid-program-service-type
Type for the ``setuid-program service''.  This service collects lists of
executable file names, passed as gexps, and adds them to the set of
setuid-root programs on the system (@pxref{Setuid Programs}).
@end defvr

@defvr {Scheme Variable} profile-service-type
Type of the service that populates the @dfn{system profile}---i.e., the
programs under @file{/run/current-system/profile}.  Other services can
extend it by passing it lists of packages to add to the system profile.
@end defvr

@cindex provenance tracking, of the operating system
@anchor{provenance-service-type}
@defvr {Scheme Variable} provenance-service-type
This is the type of the service that records @dfn{provenance meta-data}
in the system itself.  It creates several files under
@file{/run/current-system}:

@table @file
@item channels.scm
This is a ``channel file'' that can be passed to @command{guix pull -C}
or @command{guix time-machine -C}, and which describes the channels used
to build the system, if that information was available
(@pxref{Channels}).

@item configuration.scm
This is the file that was passed as the value for this
@code{provenance-service-type} service.  By default, @command{guix
system reconfigure} automatically passes the OS configuration file it
received on the command line.

@item provenance
This contains the same information as the two other files but in a
format that is more readily processable.
@end table

In general, these two pieces of information (channels and configuration
file) are enough to reproduce the operating system ``from source''.

@quotation Caveats
This information is necessary to rebuild your operating system, but it
is not always sufficient.  In particular, @file{configuration.scm}
itself is insufficient if it is not self-contained---if it refers to
external Guile modules or to extra files.  If you want
@file{configuration.scm} to be self-contained, we recommend that modules
or files it refers to be part of a channel.

Besides, provenance meta-data is ``silent'' in the sense that it does
not change the bits contained in your system, @emph{except for the
meta-data bits themselves}.  Two different OS configurations or sets of
channels can lead to the same system, bit-for-bit; when
@code{provenance-service-type} is used, these two systems will have
different meta-data and thus different store file names, which makes
comparison less trivial.
@end quotation

This service is automatically added to your operating system
configuration when you use @command{guix system reconfigure},
@command{guix system init}, or @command{guix deploy}.
@end defvr

@node Shepherd Services
@subsection Shepherd Services

@cindex shepherd services
@cindex PID 1
@cindex init system
The @code{(gnu services shepherd)} module provides a way to define
services managed by the GNU@tie{}Shepherd, which is the
initialization system---the first process that is started when the
system boots, also known as PID@tie{}1
(@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}).

Services in the Shepherd can depend on each other.  For instance, the
SSH daemon may need to be started after the syslog daemon has been
started, which in turn can only happen once all the file systems have
been mounted.  The simple operating system defined earlier (@pxref{Using
the Configuration System}) results in a service graph like this:

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

You can actually generate such a graph for any operating system
definition using the @command{guix system shepherd-graph} command
(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).

The @code{%shepherd-root-service} is a service object representing
PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended
by passing it lists of @code{<shepherd-service>} objects.

@deftp {Data Type} shepherd-service
The data type representing a service managed by the Shepherd.

@table @asis
@item @code{provision}
This is a list of symbols denoting what the service provides.

These are the names that may be passed to @command{herd start},
@command{herd status}, and similar commands (@pxref{Invoking herd,,,
shepherd, The GNU Shepherd Manual}).  @xref{Slots of services, the
@code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.

@item @code{requirement} (default: @code{'()})
List of symbols denoting the Shepherd services this one depends on.

@cindex one-shot services, for the Shepherd
@item @code{one-shot?} (default: @code{#f})
Whether this service is @dfn{one-shot}.  One-shot services stop immediately
after their @code{start} action has completed.  @xref{Slots of services,,,
shepherd, The GNU Shepherd Manual}, for more info.

@item @code{respawn?} (default: @code{#t})
Whether to restart the service when it stops, for instance when the
underlying process dies.

@item @code{start}
@itemx @code{stop} (default: @code{#~(const #f)})
The @code{start} and @code{stop} fields refer to the Shepherd's
facilities to start and stop processes (@pxref{Service De- and
Constructors,,, shepherd, The GNU Shepherd Manual}).  They are given as
G-expressions that get expanded in the Shepherd configuration file
(@pxref{G-Expressions}).

@item @code{actions} (default: @code{'()})
@cindex actions, of Shepherd services
This is a list of @code{shepherd-action} objects (see below) defining
@dfn{actions} supported by the service, in addition to the standard
@code{start} and @code{stop} actions.  Actions listed here become available as
@command{herd} sub-commands:

@example
herd @var{action} @var{service} [@var{arguments}@dots{}]
@end example

@item @code{auto-start?} (default: @code{#t})
Whether this service should be started automatically by the Shepherd.  If it
is @code{#f} the service has to be started manually with @code{herd start}.

@item @code{documentation}
A documentation string, as shown when running:

@example
herd doc @var{service-name}
@end example

where @var{service-name} is one of the symbols in @code{provision}
(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).

@item @code{modules} (default: @code{%default-modules})
This is the list of modules that must be in scope when @code{start} and
@code{stop} are evaluated.

@end table
@end deftp

@deftp {Data Type} shepherd-action
This is the data type that defines additional actions implemented by a
Shepherd service (see above).

@table @code
@item name
Symbol naming the action.

@item documentation
This is a documentation string for the action.  It can be viewed by running:

@example
herd doc @var{service} action @var{action}
@end example

@item procedure
This should be a gexp that evaluates to a procedure of at least one argument,
which is the ``running value'' of the service (@pxref{Slots of services,,,
shepherd, The GNU Shepherd Manual}).
@end table

The following example defines an action called @code{say-hello} that kindly
greets the user:

@lisp
(shepherd-action
  (name 'say-hello)
  (documentation "Say hi!")
  (procedure #~(lambda (running . args)
                 (format #t "Hello, friend! arguments: ~s\n"
                         args)
                 #t)))
@end lisp

Assuming this action is added to the @code{example} service, then you can do:

@example
# herd say-hello example
Hello, friend! arguments: ()
# herd say-hello example a b c
Hello, friend! arguments: ("a" "b" "c")
@end example

This, as you can see, is a fairly sophisticated way to say hello.
@xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more
info on actions.
@end deftp

@defvr {Scheme Variable} shepherd-root-service-type
The service type for the Shepherd ``root service''---i.e., PID@tie{}1.

This is the service type that extensions target when they want to create
shepherd services (@pxref{Service Types and Services}, for an example).
Each extension must pass a list of @code{<shepherd-service>}.
@end defvr

@defvr {Scheme Variable} %shepherd-root-service
This service represents PID@tie{}1.
@end defvr


@node Documentation
@chapter Documentation

@cindex documentation, searching for
@cindex searching for documentation
@cindex Info, documentation format
@cindex man pages
@cindex manual pages
In most cases packages installed with Guix come with documentation.
There are two main documentation formats: ``Info'', a browseable
hypertext format used for GNU software, and ``manual pages'' (or ``man
pages''), the linear documentation format traditionally found on Unix.
Info manuals are accessed with the @command{info} command or with Emacs,
and man pages are accessed using @command{man}.

You can look for documentation of software installed on your system by
keyword.  For example, the following command searches for information
about ``TLS'' in Info manuals:

@example
$ info -k TLS
"(emacs)Network Security" -- STARTTLS
"(emacs)Network Security" -- TLS
"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
@dots{}
@end example

@noindent
The command below searches for the same keyword in man pages:

@example
$ man -k TLS
SSL (7)              - OpenSSL SSL/TLS library
certtool (1)         - GnuTLS certificate tool
@dots {}
@end example

These searches are purely local to your computer so you have the
guarantee that documentation you find corresponds to what you have
actually installed, you can access it off-line, and your privacy is
respected.

Once you have these results, you can view the relevant documentation by
running, say: