guix.texi

@item @code{issue} (default: @var{%default-issue})
A string denoting the contents of the @file{/etc/issue} file, which is
displayed when users log in on a text console.

@item @code{packages} (default: @var{%base-packages})
The set of packages installed in the global profile, which is accessible
at @file{/run/current-system/profile}.

The default set includes core utilities and it is good practice to
install non-core utilities in user profiles (@pxref{Invoking guix
package}).

@item @code{timezone}
A timezone identifying string---e.g., @code{"Europe/Paris"}.

You can run the @command{tzselect} command to find out which timezone
string corresponds to your region.  Choosing an invalid timezone name
causes @command{guix system} to fail.

@item @code{locale} (default: @code{"en_US.utf8"})
The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
Library Reference Manual}).  @xref{Locales}, for more information.

@item @code{locale-definitions} (default: @var{%default-locale-definitions})
The list of locale definitions to be compiled and that may be used at
run time.  @xref{Locales}.

@item @code{locale-libcs} (default: @code{(list @var{glibc})})
The list of GNU@tie{}libc packages whose locale data and tools are used
to build the locale definitions.  @xref{Locales}, for compatibility
considerations that justify this option.

@item @code{name-service-switch} (default: @var{%default-nss})
Configuration of the libc name service switch (NSS)---a
@code{<name-service-switch>} object.  @xref{Name Service Switch}, for
details.

@item @code{services} (default: @var{%base-services})
A list of service objects denoting system services.  @xref{Services}.

@item @code{pam-services} (default: @code{(base-pam-services)})
@cindex PAM
@cindex pluggable authentication modules
Linux @dfn{pluggable authentication module} (PAM) services.
@c FIXME: Add xref to PAM services section.

@item @code{setuid-programs} (default: @var{%setuid-programs})
List of string-valued G-expressions denoting setuid programs.
@xref{Setuid Programs}.

@item @code{sudoers-file} (default: @var{%sudoers-specification})
@cindex sudoers file
The contents of the @file{/etc/sudoers} file as a file-like object
(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).

This file specifies which users can use the @command{sudo} command, what
they are allowed to do, and what privileges they may gain.  The default
is that only @code{root} and members of the @code{wheel} group may use
@code{sudo}.

@end table
@end deftp

@node File Systems
@subsection File Systems

The list of file systems to be mounted is specified in the
@code{file-systems} field of the operating system declaration
(@pxref{Using the Configuration System}).  Each file system is declared
using the @code{file-system} form, like this:

@example
(file-system
  (mount-point "/home")
  (device "/dev/sda3")
  (type "ext4"))
@end example

As usual, some of the fields are mandatory---those shown in the example
above---while others can be omitted.  These are described below.

@deftp {Data Type} file-system
Objects of this type represent file systems to be mounted.  They
contain the following members:

@table @asis
@item @code{type}
This is a string specifying the type of the file system---e.g.,
@code{"ext4"}.

@item @code{mount-point}
This designates the place where the file system is to be mounted.

@item @code{device}
This names the ``source'' of the file system.  By default it is the name
of a node under @file{/dev}, but its meaning depends on the @code{title}
field described below.

@item @code{title} (default: @code{'device})
This is a symbol that specifies how the @code{device} field is to be
interpreted.

When it is the symbol @code{device}, then the @code{device} field is
interpreted as a file name; when it is @code{label}, then @code{device}
is interpreted as a partition label name; when it is @code{uuid},
@code{device} is interpreted as a partition unique identifier (UUID).

UUIDs may be converted from their string representation (as shown by the
@command{tune2fs -l} command) using the @code{uuid} form@footnote{The
@code{uuid} form expects 16-byte UUIDs as defined in
@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}.  This is the
form of UUID used by the ext2 family of file systems and others, but it
is different from ``UUIDs'' found in FAT file systems, for instance.},
like this:

@example
(file-system
  (mount-point "/home")
  (type "ext4")
  (title 'uuid)
  (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
@end example

The @code{label} and @code{uuid} options offer a way to refer to disk
partitions without having to hard-code their actual device
name@footnote{Note that, while it is tempting to use
@file{/dev/disk/by-uuid} and similar device names to achieve the same
result, this is not recommended: These special device nodes are created
by the udev daemon and may be unavailable at the time the device is
mounted.}.

However, when the source of a file system is a mapped device (@pxref{Mapped
Devices}), its @code{device} field @emph{must} refer to the mapped
device name---e.g., @file{/dev/mapper/root-partition}---and consequently
@code{title} must be set to @code{'device}.  This is required so that
the system knows that mounting the file system depends on having the
corresponding device mapping established.

@item @code{flags} (default: @code{'()})
This is a list of symbols denoting mount flags.  Recognized flags
include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
access to special files), @code{no-suid} (ignore setuid and setgid
bits), and @code{no-exec} (disallow program execution.)

@item @code{options} (default: @code{#f})
This is either @code{#f}, or a string denoting mount options.

@item @code{mount?} (default: @code{#t})
This value indicates whether to automatically mount the file system when
the system is brought up.  When set to @code{#f}, the file system gets
an entry in @file{/etc/fstab} (read by the @command{mount} command) but
is not automatically mounted.

@item @code{needed-for-boot?} (default: @code{#f})
This Boolean value indicates whether the file system is needed when
booting.  If that is true, then the file system is mounted when the
initial RAM disk (initrd) is loaded.  This is always the case, for
instance, for the root file system.

@item @code{check?} (default: @code{#t})
This Boolean indicates whether the file system needs to be checked for
errors before being mounted.

@item @code{create-mount-point?} (default: @code{#f})
When true, the mount point is created if it does not exist yet.

@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{create-home-directory?} (default: @code{#t})
Indicates whether the home directory of this account should be created
if it does not exist yet.

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

GuixSD has a broad definition of ``service'' (@pxref{Service
Composition}), but many services are managed by the GNU@tie{}Shepherd
(@pxref{Shepherd Services}).  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.
* Log Rotation::                The rottlog 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.
* Network File System::         NFS related services.
* Miscellaneous 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} login-service @var{config}
Return a service to run login according to @var{config}, a
@code{<login-configuration>} object, which specifies the message of the day,
among other things.
@end deffn

@deftp {Data Type} login-configuration
This is the data type representing the configuration of login.

@table @asis

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

@item @code{allow-empty-passwords?} (default: @code{#t})
Allow empty passwords by default so that first-time users can log in when
the 'root' account has just been created.

@end table
@end deftp

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

@deffn {Scheme Procedure} kmscon-service-type @var{config}
Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
according to @var{config}, a @code{<kmscon-configuration>} object, which
specifies the tty to run, among other things.
@end deffn

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

@table @asis

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

@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
A gexp denoting the name of the log-in program. The default log-in program is
@command{login} from the Shadow tool suite.

@item @code{login-arguments} (default: @code{'("-p")})
A list of arguments to pass to @command{login}.

@item @code{hardware-acceleration?} (default: #f)
Whether to use hardware acceleration.

@item @code{kmscon} (default: @var{kmscon})
The Kmscon 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

@anchor{syslog-configuration-type}
@deftp {Data Type} syslog-configuration
This data type represents the configuration of the syslog daemon.

@table @asis
@item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
The syslog daemon to use.

@item @code{config-file} (default: @code{%default-syslog.conf})
The syslog configuration file to use.

@end table
@end deftp

@anchor{syslog-service}
@deffn {Scheme Procedure} syslog-service @var{config}
Return a service that runs a syslog daemon according to @var{config}.

@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 keys listed in
@code{authorized-keys}---by default that of @code{hydra.gnu.org}
(@pxref{Substitutes}).

@vindex %default-authorized-guix-keys
@item @code{authorized-keys} (default: @var{%default-authorized-guix-keys})
The list of authorized key files for archive imports, as a list of
string-valued gexps (@pxref{Invoking guix archive}).  By default, it
contains that of @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