guix.texi

@item @code{dependencies} (default: @code{'()})
This is a list of @code{<file-system>} objects representing file systems
that must be mounted before (and unmounted after) this one.

As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
a dependency of @file{/sys/fs/cgroup/cpu} and
@file{/sys/fs/cgroup/memory}.

@end table
@end deftp

The @code{(gnu system file-systems)} exports the following useful
variables.

@defvr {Scheme Variable} %base-file-systems
These are essential file systems that are required on normal systems,
such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see
below.)  Operating system declarations should always contain at least
these.
@end defvr

@defvr {Scheme Variable} %pseudo-terminal-file-system
This is the file system to be mounted as @file{/dev/pts}.  It supports
@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
Manual}).  Pseudo-terminals are used by terminal emulators such as
@command{xterm}.
@end defvr

@defvr {Scheme Variable} %shared-memory-file-system
This file system is mounted as @file{/dev/shm} and is used to support
memory sharing across processes (@pxref{Memory-mapped I/O,
@code{shm_open},, libc, The GNU C Library Reference Manual}).
@end defvr

@defvr {Scheme Variable} %immutable-store
This file system performs a read-only ``bind mount'' of
@file{/gnu/store}, making it read-only for all the users including
@code{root}.  This prevents against accidental modification by software
running as @code{root} or by system administrators.

The daemon itself is still able to write to the store: it remounts it
read-write in its own ``name space.''
@end defvr

@defvr {Scheme Variable} %binary-format-file-system
The @code{binfmt_misc} file system, which allows handling of arbitrary
executable file types to be delegated to user space.  This requires the
@code{binfmt.ko} kernel module to be loaded.
@end defvr

@defvr {Scheme Variable} %fuse-control-file-system
The @code{fusectl} file system, which allows unprivileged users to mount
and unmount user-space FUSE file systems.  This requires the
@code{fuse.ko} kernel module to be loaded.
@end defvr

@node Mapped Devices
@subsection Mapped Devices

@cindex device mapping
@cindex mapped devices
The Linux kernel has a notion of @dfn{device mapping}: a block device,
such as a hard disk partition, can be @dfn{mapped} into another device,
usually in @code{/dev/mapper/},
with additional processing over the data that flows through
it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
concept of a ``mapped device'' and that of a file system: both boil down
to @emph{translating} input/output operations made on a file to
operations on its backing store.  Thus, the Hurd implements mapped
devices, like file systems, using the generic @dfn{translator} mechanism
(@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}.  A
typical example is encryption device mapping: all writes to the mapped
device are encrypted, and all reads are deciphered, transparently.
Guix extends this notion by considering any device or set of devices that
are @dfn{transformed} in some way to create a new device; for instance,
RAID devices are obtained by @dfn{assembling} several other devices, such
as hard disks or partitions, into a new one that behaves as one partition.
Other examples, not yet implemented, are LVM logical volumes.

Mapped devices are declared using the @code{mapped-device} form,
defined as follows; for examples, see below.

@deftp {Data Type} mapped-device
Objects of this type represent device mappings that will be made when
the system boots up.

@table @code
@item source
This is either a string specifying the name of the block device to be mapped,
such as @code{"/dev/sda3"}, or a list of such strings when several devices
need to be assembled for creating a new one.

@item target
This string specifies the name of the resulting mapped device.  For
kernel mappers such as encrypted devices of type @code{luks-device-mapping},
specifying @code{"my-partition"} leads to the creation of
the @code{"/dev/mapper/my-partition"} device.
For RAID devices of type @code{raid-device-mapping}, the full device name
such as @code{"/dev/md0"} needs to be given.

@item type
This must be a @code{mapped-device-kind} object, which specifies how
@var{source} is mapped to @var{target}.
@end table
@end deftp

@defvr {Scheme Variable} luks-device-mapping
This defines LUKS block device encryption using the @command{cryptsetup}
command from the package with the same name.  It relies on the
@code{dm-crypt} Linux kernel module.
@end defvr

@defvr {Scheme Variable} raid-device-mapping
This defines a RAID device, which is assembled using the @code{mdadm}
command from the package with the same name.  It requires a Linux kernel
module for the appropriate RAID level to be loaded, such as @code{raid456}
for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
@end defvr

@cindex disk encryption
@cindex LUKS
The following example specifies a mapping from @file{/dev/sda3} to
@file{/dev/mapper/home} using LUKS---the
@url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
standard mechanism for disk encryption.
The @file{/dev/mapper/home}
device can then be used as the @code{device} of a @code{file-system}
declaration (@pxref{File Systems}).

@example
(mapped-device
  (source "/dev/sda3")
  (target "home")
  (type luks-device-mapping))
@end example

Alternatively, to become independent of device numbering, one may obtain
the LUKS UUID (@dfn{unique identifier}) of the source device by a
command like:

@example
cryptsetup luksUUID /dev/sda3
@end example

and use it as follows:

@example
(mapped-device
  (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
  (target "home")
  (type luks-device-mapping))
@end example

A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
may be declared as follows:

@example
(mapped-device
  (source (list "/dev/sda1" "/dev/sdb1"))
  (target "/dev/md0")
  (type raid-device-mapping))
@end example

The @file{/dev/md0} device can then be used as the @code{device} of a
@code{file-system} declaration (@pxref{File Systems}).
Note that the RAID level need not be given; it is chosen during the
initial creation and formatting of the RAID device and is determined
automatically later.


@node User Accounts
@subsection User Accounts

User accounts and groups are entirely managed through the
@code{operating-system} declaration.  They are specified with the
@code{user-account} and @code{user-group} forms:

@example
(user-account
  (name "alice")
  (group "users")
  (supplementary-groups '("wheel"   ;allow use of sudo, etc.
                          "audio"   ;sound card
                          "video"   ;video devices such as webcams
                          "cdrom")) ;the good ol' CD-ROM
  (comment "Bob's sister")
  (home-directory "/home/alice"))
@end example

When booting or upon completion of @command{guix system reconfigure},
the system ensures that only the user accounts and groups specified in
the @code{operating-system} declaration exist, and with the specified
properties.  Thus, account or group creations or modifications made by
directly invoking commands such as @command{useradd} are lost upon
reconfiguration or reboot.  This ensures that the system remains exactly
as declared.

@deftp {Data Type} user-account
Objects of this type represent user accounts.  The following members may
be specified:

@table @asis
@item @code{name}
The name of the user account.

@item @code{group}
This is the name (a string) or identifier (a number) of the user group
this account belongs to.

@item @code{supplementary-groups} (default: @code{'()})
Optionally, this can be defined as a list of group names that this
account belongs to.

@item @code{uid} (default: @code{#f})
This is the user ID for this account (a number), or @code{#f}.  In the
latter case, a number is automatically chosen by the system when the
account is created.

@item @code{comment} (default: @code{""})
A comment about the account, such as the account owner's full name.

@item @code{home-directory}
This is the name of the home directory for the account.

@item @code{shell} (default: Bash)
This is a G-expression denoting the file name of a program to be used as
the shell (@pxref{G-Expressions}).

@item @code{system?} (default: @code{#f})
This Boolean value indicates whether the account is a ``system''
account.  System accounts are sometimes treated specially; for instance,
graphical login managers do not list them.

@anchor{user-account-password}
@item @code{password} (default: @code{#f})
You would normally leave this field to @code{#f}, initialize user
passwords as @code{root} with the @command{passwd} command, and then let
users change it with @command{passwd}.  Passwords set with
@command{passwd} are of course preserved across reboot and
reconfiguration.

If you @emph{do} want to have a preset password for an account, then
this field must contain the encrypted password, as a string.
@xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
Manual}, for information on Guile's @code{crypt} procedure.

@end table
@end deftp

User group declarations are even simpler:

@example
(user-group (name "students"))
@end example

@deftp {Data Type} user-group
This type is for, well, user groups.  There are just a few fields:

@table @asis
@item @code{name}
The name of the group.

@item @code{id} (default: @code{#f})
The group identifier (a number).  If @code{#f}, a new number is
automatically allocated when the group is created.

@item @code{system?} (default: @code{#f})
This Boolean value indicates whether the group is a ``system'' group.
System groups have low numerical IDs.

@item @code{password} (default: @code{#f})
What, user groups can have a password?  Well, apparently yes.  Unless
@code{#f}, this field specifies the password of the group.

@end table
@end deftp

For convenience, a variable lists all the basic user groups one may
expect:

@defvr {Scheme Variable} %base-groups
This is the list of basic user groups that users and/or packages expect
to be present on the system.  This includes groups such as ``root'',
``wheel'', and ``users'', as well as groups used to control access to
specific devices such as ``audio'', ``disk'', and ``cdrom''.
@end defvr

@defvr {Scheme Variable} %base-user-accounts
This is the list of basic system accounts that programs may expect to
find on a GNU/Linux system, such as the ``nobody'' account.

Note that the ``root'' account is not included here.  It is a
special-case and is automatically added whether or not it is specified.
@end defvr

@node Locales
@subsection Locales

@cindex locale
A @dfn{locale} defines cultural conventions for a particular language
and region of the world (@pxref{Locales,,, libc, The GNU C Library
Reference Manual}).  Each locale has a name that typically has the form
@code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
@code{fr_LU.utf8} designates the locale for the French language, with
cultural conventions from Luxembourg, and using the UTF-8 encoding.

@cindex locale definition
Usually, you will want to specify the default locale for the machine
using the @code{locale} field of the @code{operating-system} declaration
(@pxref{operating-system Reference, @code{locale}}).

The selected locale is automatically added to the @dfn{locale
definitions} known to the system if needed, with its codeset inferred
from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
@code{UTF-8} codeset.  Additional locale definitions can be specified in
the @code{locale-definitions} slot of @code{operating-system}---this is
useful, for instance, if the codeset could not be inferred from the
locale name.  The default set of locale definitions includes some widely
used locales, but not all the available locales, in order to save space.

For instance, to add the North Frisian locale for Germany, the value of
that field may be:

@example
(cons (locale-definition
        (name "fy_DE.utf8") (source "fy_DE"))
      %default-locale-definitions)
@end example

Likewise, to save space, one might want @code{locale-definitions} to
list only the locales that are actually used, as in:

@example
(list (locale-definition
        (name "ja_JP.eucjp") (source "ja_JP")
        (charset "EUC-JP")))
@end example

@vindex LOCPATH
The compiled locale definitions are available at
@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
version, which is the default location where the GNU@tie{}libc provided
by Guix looks for locale data.  This can be overridden using the
@code{LOCPATH} environment variable (@pxref{locales-and-locpath,
@code{LOCPATH} and locale packages}).

The @code{locale-definition} form is provided by the @code{(gnu system
locale)} module.  Details are given below.

@deftp {Data Type} locale-definition
This is the data type of a locale definition.

@table @asis

@item @code{name}
The name of the locale.  @xref{Locale Names,,, libc, The GNU C Library
Reference Manual}, for more information on locale names.

@item @code{source}
The name of the source for that locale.  This is typically the
@code{@var{language}_@var{territory}} part of the locale name.

@item @code{charset} (default: @code{"UTF-8"})
The ``character set'' or ``code set'' for that locale,
@uref{http://www.iana.org/assignments/character-sets, as defined by
IANA}.

@end table
@end deftp

@defvr {Scheme Variable} %default-locale-definitions
A list of commonly used UTF-8 locales, used as the default
value of the @code{locale-definitions} field of @code{operating-system}
declarations.

@cindex locale name
@cindex normalized codeset in locale names
These locale definitions use the @dfn{normalized codeset} for the part
that follows the dot in the name (@pxref{Using gettextized software,
normalized codeset,, libc, The GNU C Library Reference Manual}).  So for
instance it has @code{uk_UA.utf8} but @emph{not}, say,
@code{uk_UA.UTF-8}.
@end defvr

@subsubsection Locale Data Compatibility Considerations

@cindex incompatibility, of locale data
@code{operating-system} declarations provide a @code{locale-libcs} field
to specify the GNU@tie{}libc packages that are used to compile locale
declarations (@pxref{operating-system Reference}).  ``Why would I
care?'', you may ask.  Well, it turns out that the binary format of
locale data is occasionally incompatible from one libc version to
another.

@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
For instance, a program linked against libc version 2.21 is unable to
read locale data produced with libc 2.22; worse, that program
@emph{aborts} instead of simply ignoring the incompatible locale
data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
the incompatible locale data, which is already an improvement.}.
Similarly, a program linked against libc 2.22 can read most, but not
all, the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
data is incompatible); thus calls to @code{setlocale} may fail, but
programs will not abort.

The ``problem'' in GuixSD is that users have a lot of freedom: They can
choose whether and when to upgrade software in their profiles, and might
be using a libc version different from the one the system administrator
used to build the system-wide locale data.

Fortunately, unprivileged users can also install their own locale data
and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
@code{GUIX_LOCPATH} and locale packages}).

Still, it is best if the system-wide locale data at
@file{/run/current-system/locale} is built for all the libc versions
actually in use on the system, so that all the programs can access
it---this is especially crucial on a multi-user system.  To do that, the
administrator can specify several libc packages in the
@code{locale-libcs} field of @code{operating-system}:

@example
(use-package-modules base)

(operating-system
  ;; @dots{}
  (locale-libcs (list glibc-2.21 (canonical-package glibc))))
@end example

This example would lead to a system containing locale definitions for
both libc 2.21 and the current version of libc in
@file{/run/current-system/locale}.


@node Services
@subsection Services

@cindex system services
An important part of preparing an @code{operating-system} declaration is
listing @dfn{system services} and their configuration (@pxref{Using the
Configuration System}).  System services are typically daemons launched
when the system boots, or other actions needed at that time---e.g.,
configuring network access.

Services are managed by the GNU@tie{}Shepherd (@pxref{Introduction,,,
shepherd, The GNU Shepherd Manual}).  On a running system, the
@command{herd} command allows you to list the available services, show
their status, start and stop them, or do other specific operations
(@pxref{Jump Start,,, shepherd, The GNU Shepherd Manual}).  For example:

@example
# herd status
@end example

The above command, run as @code{root}, lists the currently defined
services.  The @command{herd doc} command shows a synopsis of the given
service:

@example
# herd doc nscd
Run libc's name service cache daemon (nscd).
@end example

The @command{start}, @command{stop}, and @command{restart} sub-commands
have the effect you would expect.  For instance, the commands below stop
the nscd service and restart the Xorg display server:

@example
# herd stop nscd
Service nscd has been stopped.
# herd restart xorg-server
Service xorg-server has been stopped.
Service xorg-server has been started.
@end example

The following sections document the available services, starting with
the core services, that may be used in an @code{operating-system}
declaration.

@menu
* Base Services::               Essential system services.
* Scheduled Job Execution::     The mcron service.
* Networking Services::         Network setup, SSH daemon, etc.
* X Window::                    Graphical display.
* Desktop Services::            D-Bus and desktop services.
* Database Services::           SQL databases.
* Mail Services::               IMAP, POP3, SMTP, and all that.
* Web Services::                Web servers.
* Various Services::            Other services.
@end menu

@node Base Services
@subsubsection Base Services

The @code{(gnu services base)} module provides definitions for the basic
services that one expects from the system.  The services exported by
this module are listed below.

@defvr {Scheme Variable} %base-services
This variable contains a list of basic services (@pxref{Service Types
and Services}, for more information on service objects) one would
expect from the system: a login service (mingetty) on each tty, syslogd,
the libc name service cache daemon (nscd), the udev device manager, and
more.

This is the default value of the @code{services} field of
@code{operating-system} declarations.  Usually, when customizing a
system, you will want to append services to @var{%base-services}, like
this:

@example
(cons* (avahi-service) (lsh-service) %base-services)
@end example
@end defvr

@deffn {Scheme Procedure} host-name-service @var{name}
Return a service that sets the host name to @var{name}.
@end deffn

@deffn {Scheme Procedure} mingetty-service @var{config}
Return a service to run mingetty according to @var{config}, a
@code{<mingetty-configuration>} object, which specifies the tty to run, among
other things.
@end deffn

@deftp {Data Type} mingetty-configuration
This is the data type representing the configuration of Mingetty, which
implements console log-in.

@table @asis

@item @code{tty}
The name of the console this Mingetty runs on---e.g., @code{"tty1"}.

@item @code{motd}
A file-like object containing the ``message of the day''.

@item @code{auto-login} (default: @code{#f})
When true, this field must be a string denoting the user name under
which the system automatically logs in.  When it is @code{#f}, a
user name and password must be entered to log in.

@item @code{login-program} (default: @code{#f})
This must be either @code{#f}, in which case the default log-in program
is used (@command{login} from the Shadow tool suite), or a gexp denoting
the name of the log-in program.

@item @code{login-pause?} (default: @code{#f})
When set to @code{#t} in conjunction with @var{auto-login}, the user
will have to press a key before the log-in shell is launched.

@item @code{mingetty} (default: @var{mingetty})
The Mingetty package to use.

@end table
@end deftp

@cindex name service cache daemon
@cindex nscd
@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
                [#:name-services '()]
Return a service that runs the libc name service cache daemon (nscd) with the
given @var{config}---an @code{<nscd-configuration>} object.  @xref{Name
Service Switch}, for an example.
@end deffn

@defvr {Scheme Variable} %nscd-default-configuration
This is the default @code{<nscd-configuration>} value (see below) used
by @code{nscd-service}.  It uses the caches defined by
@var{%nscd-default-caches}; see below.
@end defvr

@deftp {Data Type} nscd-configuration
This is the data type representing the name service cache daemon (nscd)
configuration.

@table @asis

@item @code{name-services} (default: @code{'()})
List of packages denoting @dfn{name services} that must be visible to
the nscd---e.g., @code{(list @var{nss-mdns})}.

@item @code{glibc} (default: @var{glibc})
Package object denoting the GNU C Library providing the @command{nscd}
command.

@item @code{log-file} (default: @code{"/var/log/nscd.log"})
Name of the nscd log file.  This is where debugging output goes when
@code{debug-level} is strictly positive.

@item @code{debug-level} (default: @code{0})
Integer denoting the debugging levels.  Higher numbers mean that more
debugging output is logged.

@item @code{caches} (default: @var{%nscd-default-caches})
List of @code{<nscd-cache>} objects denoting things to be cached; see
below.

@end table
@end deftp

@deftp {Data Type} nscd-cache
Data type representing a cache database of nscd and its parameters.

@table @asis

@item @code{database}
This is a symbol representing the name of the database to be cached.
Valid values are @code{passwd}, @code{group}, @code{hosts}, and
@code{services}, which designate the corresponding NSS database
(@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).

@item @code{positive-time-to-live}
@itemx @code{negative-time-to-live} (default: @code{20})
A number representing the number of seconds during which a positive or
negative lookup result remains in cache.

@item @code{check-files?} (default: @code{#t})
Whether to check for updates of the files corresponding to
@var{database}.

For instance, when @var{database} is @code{hosts}, setting this flag
instructs nscd to check for updates in @file{/etc/hosts} and to take
them into account.

@item @code{persistent?} (default: @code{#t})
Whether the cache should be stored persistently on disk.

@item @code{shared?} (default: @code{#t})
Whether the cache should be shared among users.

@item @code{max-database-size} (default: 32@tie{}MiB)
Maximum size in bytes of the database cache.

@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
@c settings, so leave them out.

@end table
@end deftp

@defvr {Scheme Variable} %nscd-default-caches
List of @code{<nscd-cache>} objects used by default by
@code{nscd-configuration} (see above).

It enables persistent and aggressive caching of service and host name
lookups.  The latter provides better host name lookup performance,
resilience in the face of unreliable name servers, and also better
privacy---often the result of host name lookups is in local cache, so
external name servers do not even need to be queried.
@end defvr


@deffn {Scheme Procedure} syslog-service @
             [#:config-file @var{%default-syslog.conf}]
Return a service that runs @command{syslogd}.  If the configuration file
name @var{config-file} is not specified, use some reasonable default
settings.

@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
information on the configuration file syntax.
@end deffn

@anchor{guix-configuration-type}
@deftp {Data Type} guix-configuration
This data type represents the configuration of the Guix build daemon.
@xref{Invoking guix-daemon}, for more information.

@table @asis
@item @code{guix} (default: @var{guix})
The Guix package to use.

@item @code{build-group} (default: @code{"guixbuild"})
Name of the group for build user accounts.

@item @code{build-accounts} (default: @code{10})
Number of build user accounts to create.

@item @code{authorize-key?} (default: @code{#t})
Whether to authorize the substitute key for @code{hydra.gnu.org}
(@pxref{Substitutes}).

@item @code{use-substitutes?} (default: @code{#t})
Whether to use substitutes.

@item @code{substitute-urls} (default: @var{%default-substitute-urls})
The list of URLs where to look for substitutes by default.

@item @code{extra-options} (default: @code{'()})
List of extra command-line options for @command{guix-daemon}.

@item @code{lsof} (default: @var{lsof})
@itemx @code{lsh} (default: @var{lsh})
The lsof and lsh packages to use.

@end table
@end deftp

@deffn {Scheme Procedure} guix-service @var{config}
Return a service that runs the Guix build daemon according to
@var{config}.
@end deffn

@deffn {Scheme Procedure} udev-service [#:udev udev]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
@end deffn

@deffn {Scheme Procedure} urandom-seed-service @var{#f}
Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
when rebooting.
@end deffn

@defvr {Scheme Variable} %random-seed-file
This is the name of the file where some random bytes are saved by
@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting.
It defaults to @file{/var/lib/random-seed}.
@end defvr

@deffn {Scheme Procedure} console-keymap-service @var{files} ...
@cindex keyboard layout
Return a service to load console keymaps from @var{files} using
@command{loadkeys} command.  Most likely, you want to load some default
keymap, which can be done like this:

@example
(console-keymap-service "dvorak")
@end example

Or, for example, for a Swedish keyboard, you may need to combine
the following keymaps:
@example
(console-keymap-service "se-lat6" "se-fi-lat6")
@end example

Also you can specify a full file name (or file names) of your keymap(s).
See @code{man loadkeys} for details.

@end deffn

@deffn {Scheme Procedure} gpm-service [#:gpm @var{gpm}] @
          [#:options]
Run @var{gpm}, the general-purpose mouse daemon, with the given
command-line @var{options}.  GPM allows users to use the mouse in the console,
notably to select, copy, and paste text.  The default value of @var{options}
uses the @code{ps2} protocol, which works for both USB and PS/2 mice.

This service is not part of @var{%base-services}.
@end deffn

@anchor{guix-publish-service}
@deffn {Scheme Procedure} guix-publish-service [#:guix @var{guix}] @
           [#:port 80] [#:host "localhost"]
Return a service that runs @command{guix publish} listening on @var{host}
and @var{port} (@pxref{Invoking guix publish}).

This assumes that @file{/etc/guix} already contains a signing key pair as
created by @command{guix archive --generate-key} (@pxref{Invoking guix
archive}).  If that is not the case, the service will fail to start.
@end deffn

@anchor{rngd-service}
@deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
            [#:device "/dev/hwrng"]
Return a service that runs the @command{rngd} program from @var{rng-tools}
to add @var{device} to the kernel's entropy pool.  The service will fail if
@var{device} does not exist.
@end deffn

@anchor{pam-limits-service}
@cindex session limits
@cindex ulimit
@cindex priority
@deffn {Scheme Procedure} pam-limits-service [#:limits @var{limits}]

Return a service that installs a configuration file for the
@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
@code{pam_limits} module}.  The procedure optionally takes a list of
@code{pam-limits-entry} values, which can be used to specify
@code{ulimit} limits and nice priority limits to user sessions.

The following limits definition sets two hard and soft limits for all
login sessions of users in the @code{realtime} group:

@example
(pam-limits-service
 (list
  (pam-limits-entry "@@realtime" 'both 'rtprio 99)
  (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
@end example

The first entry increases the maximum realtime priority for
non-privileged processes; the second entry lifts any restriction of the
maximum address space that can be locked in memory.  These settings are
commonly used for real-time audio systems.
@end deffn

@node Scheduled Job Execution
@subsubsection Scheduled Job Execution

@cindex cron
@cindex scheduling jobs
The @code{(gnu services mcron)} module provides an interface to
GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
mcron, GNU@tie{}mcron}).  GNU@tie{}mcron is similar to the traditional
Unix @command{cron} daemon; the main difference is that it is
implemented in Guile Scheme, which provides a lot of flexibility when
specifying the scheduling of jobs and their actions.

The example below defines an operating system that runs the
@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files})
and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as
well as the @command{mkid} command on behalf of an unprivileged user
(@pxref{mkid invocation,,, idutils, ID Database Utilities}).  It uses
gexps to introduce job definitions that are passed to mcron
(@pxref{G-Expressions}).

@lisp
(use-modules (guix) (gnu) (gnu services mcron))
(use-package-modules base idutils)

(define updatedb-job
  ;; Run 'updatedb' at 3AM every day.  Here we write the
  ;; job's action as a Scheme procedure.
  #~(job '(next-hour '(3))
         (lambda ()
           (execl (string-append #$findutils "/bin/updatedb")
                  "updatedb"
                  "--prunepaths=/tmp /var/tmp /gnu/store"))))

(define garbage-collector-job
  ;; Collect garbage 5 minutes after midnight every day.
  ;; The job's action is a shell command.
  #~(job "5 0 * * *"            ;Vixie cron syntax
         "guix gc -F 1G"))

(define idutils-jobs
  ;; Update the index database as user "charlie" at 12:15PM
  ;; and 19:15PM.  This runs from the user's home directory.
  #~(job '(next-minute-from (next-hour '(12 19)) '(15))
         (string-append #$idutils "/bin/mkid src")
         #:user "charlie"))

(operating-system
  ;; @dots{}
  (services (cons (mcron-service (list garbage-collector-job
                                       updatedb-job
                                       idutils-job))
                  %base-services)))
@end lisp

@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
for more information on mcron job specifications.  Below is the
reference of the mcron service.

@deffn {Scheme Procedure} mcron-service @var{jobs} [#:mcron @var{mcron2}]
Return an mcron service running @var{mcron} that schedules @var{jobs}, a
list of gexps denoting mcron job specifications.

This is a shorthand for:
@example
  (service mcron-service-type
           (mcron-configuration (mcron mcron) (jobs jobs)))
@end example
@end deffn

@defvr {Scheme Variable} mcron-service-type
This is the type of the @code{mcron} service, whose value is an
@code{mcron-configuration} object.

This service type can be the target of a service extension that provides
it additional job specifications (@pxref{Service Composition}).  In
other words, it is possible to define services that provide addition
mcron jobs to run.
@end defvr

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

@table @asis
@item @code{mcron} (default: @var{mcron2})
The mcron package to use.

@item @code{jobs}
This is a list of gexps (@pxref{G-Expressions}), where each gexp
corresponds to an mcron job specification (@pxref{Syntax, mcron job
specifications,, mcron, GNU@tie{}mcron}).
@end table
@end deftp


@node Networking Services
@subsubsection Networking Services

The @code{(gnu services networking)} module provides services to configure
the network interface.

@cindex DHCP, networking service
@deffn {Scheme Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
Return a service that runs @var{dhcp}, a Dynamic Host Configuration
Protocol (DHCP) client, on all the non-loopback network interfaces.
@end deffn

@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
       [#:gateway #f] [#:name-servers @code{'()}]
Return a service that starts @var{interface} with address @var{ip}.  If
@var{gateway} is true, it must be a string specifying the default network
gateway.
@end deffn

@cindex wicd
@cindex network management
@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
management daemon that aims to simplify wired and wireless networking.

This service adds the @var{wicd} package to the global profile, providing
several commands to interact with the daemon and configure networking:
@command{wicd-client}, a graphical user interface, and the @command{wicd-cli}
and @command{wicd-curses} user interfaces.
@end deffn

@cindex NetworkManager
@deffn {Scheme Procedure} network-manager-service @
       [#:network-manager @var{network-manager}]
Return a service that runs NetworkManager, a network connection manager
attempting to keep network connectivity active when available.
@end deffn

@cindex Connman
@deffn {Scheme Procedure} connman-service @
       [#:connman @var{connman}]
Return a service that runs @url{https://01.org/connman,Connman}, a network
connection manager.

This service adds the @var{connman} package to the global profile, providing
several the @command{connmanctl} command to interact with the daemon and
configure networking."
@end deffn

@deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @
  [#:name-service @var{%ntp-servers}]
Return a service that runs the daemon from @var{ntp}, the
@uref{http://www.ntp.org, Network Time Protocol package}.  The daemon will
keep the system clock synchronized with that of @var{servers}.
@end deffn

@defvr {Scheme Variable} %ntp-servers
List of host names used as the default NTP servers.
@end defvr

@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
Return a service to run the @uref{https://torproject.org, Tor} anonymous
networking daemon.

The daemon runs as the @code{tor} unprivileged user.  It is passed
@var{config-file}, a file-like object, with an additional @code{User tor} line
and lines for hidden services added via @code{tor-hidden-service}.  Run
@command{man tor} for information about the configuration file.
@end deffn

@cindex hidden service
@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
Define a new Tor @dfn{hidden service} called @var{name} and implementing
@var{mapping}.  @var{mapping} is a list of port/host tuples, such as:

@example
 '((22 "127.0.0.1:22")
   (80 "127.0.0.1:8080"))
@end example

In this example, port 22 of the hidden service is mapped to local port 22, and
port 80 is mapped to local port 8080.

This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
the @file{hostname} file contains the @code{.onion} host name for the hidden
service.

See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
project's documentation} for more information.
@end deffn

@deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @
         [#:interface "127.0.0.1"] [#:port 6667] @
         [#:extra-settings ""]
Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
acts as a gateway between IRC and chat networks.

The daemon will listen to the interface corresponding to the IP address
specified in @var{interface}, on @var{port}.  @code{127.0.0.1} means that only
local clients can connect, whereas @code{0.0.0.0} means that connections can
come from any networking interface.

In addition, @var{extra-settings} specifies a string to append to the
configuration file.
@end deffn

Furthermore, @code{(gnu services ssh)} provides the following services.