guix.texi

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's owner 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 group's name.

@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 group's password.

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

That locale must be among the @dfn{locale definitions} that are known to
the system---and these are specified in the @code{locale-definitions}
slot of @code{operating-system}.  The default value includes locale
definition for some widely used locales, but not for all the available
locales, in order to save space.

If the locale specified in the @code{locale} field is not among the
definitions listed in @code{locale-definitions}, @command{guix system}
raises an error.  In that case, you should add the locale definition to
the @code{locale-definitions} field.  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
An arbitrary 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 GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU
dmd Manual}).  On a running system, the @command{deco} command allows
you to list the available services, show their status, start and stop
them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd
Manual}).  For example:

@example
# deco status dmd
@end example

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

@example
# deco 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
# deco stop nscd
Service nscd has been stopped.
# deco 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.
* Networking Services::         Network setup, SSH daemon, etc.
* X Window::                    Graphical display.
* Desktop Services::            D-Bus and desktop services.
* Database Services::           SQL databases.
* 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@footnote{Technically,
this is a list of monadic services.  @xref{The Store Monad}.} one would
expect from the system: a login service (mingetty) on each tty, syslogd,
libc's 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 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 libc's 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}.  This uses the caches defined by
@var{%nscd-default-caches}; see below.
@end defvr

@deftp {Data Type} nscd-configuration
This is the 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 nscd's 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 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 #f]
Return a service that runs @code{syslogd}.  If configuration file name
@var{config-file} is not specified, use some reasonable default
settings.
@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} console-keymap-service @var{file}
Return a service to load console keymap from @var{file} using
@command{loadkeys} command.
@end deffn

@deffn {Scheme Procedure} gpm-service-type [#: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


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

@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.  Run @command{man tor} for information about the configuration file.
@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 service.

@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
       [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
       [#:allow-empty-passwords? #f] [#:root-login? #f] @
       [#:syslog-output? #t] [#:x11-forwarding? #t] @
       [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
       [#:public-key-authentication? #t] [#:initialize? #t]
Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
@var{host-key} must designate a file containing the host key, and readable
only by root.

When @var{daemonic?} is true, @command{lshd} will detach from the
controlling terminal and log its output to syslogd, unless one sets
@var{syslog-output?} to false.  Obviously, it also makes lsh-service
depend on existence of syslogd service.  When @var{pid-file?} is true,
@command{lshd} writes its PID to the file called @var{pid-file}.

When @var{initialize?} is true, automatically create the seed and host key
upon service activation if they do not exist yet.  This may take long and
require interaction.

When @var{initialize?} is false, it is up to the user to initialize the
randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
a key pair with the private key stored in file @var{host-key} (@pxref{lshd
basics,,, lsh, LSH Manual}).

When @var{interfaces} is empty, lshd listens for connections on all the
network interfaces; otherwise, @var{interfaces} must be a list of host names
or addresses.

@var{allow-empty-passwords?} specifies whether to accept log-ins with empty
passwords, and @var{root-login?} specifies whether to accept log-ins as
root.

The other options should be self-descriptive.
@end deffn

@defvr {Scheme Variable} %facebook-host-aliases
This variable contains a string for use in @file{/etc/hosts}
(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}).  Each
line contains a entry that maps a known server name of the Facebook
on-line service---e.g., @code{www.facebook.com}---to the local
host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.

This variable is typically used in the @code{hosts-file} field of an
@code{operating-system} declaration (@pxref{operating-system Reference,
@file{/etc/hosts}}):

@example
(use-modules (gnu) (guix))

(operating-system
  (host-name "mymachine")
  ;; ...
  (hosts-file
    ;; Create a /etc/hosts file with aliases for "localhost"
    ;; and "mymachine", as well as for Facebook servers.
    (plain-file "hosts"
                (string-append (local-host-aliases host-name)
                               %facebook-host-aliases))))
@end example

This mechanism can prevent programs running locally, such as Web
browsers, from accessing Facebook.
@end defvr

The @code{(gnu services avahi)} provides the following definition.

@deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @
          [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
          [#:ipv6? #t] [#:wide-area? #f] @
          [#:domains-to-browse '()]
Return a service that runs @command{avahi-daemon}, a system-wide
mDNS/DNS-SD responder that allows for service discovery and
"zero-configuration" host name lookups (see @uref{http://avahi.org/}), and
extends the name service cache daemon (nscd) so that it can resolve
@code{.local} host names using
@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}.  Additionally,
add the @var{avahi} package to the system profile so that commands such as
@command{avahi-browse} are directly usable.

If @var{host-name} is different from @code{#f}, use that as the host name to
publish for this machine; otherwise, use the machine's actual host name.

When @var{publish?} is true, publishing of host names and services is allowed;
in particular, avahi-daemon will publish the machine's host name and IP
address via mDNS on the local network.

When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.

Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
sockets.
@end deffn


@node X Window
@subsubsection X Window

Support for the X Window graphical display system---specifically
Xorg---is provided by the @code{(gnu services xorg)} module.  Note that
there is no @code{xorg-service} procedure.  Instead, the X server is
started by the @dfn{login manager}, currently SLiM.

@deffn {Scheme Procedure} slim-service [#:allow-empty-passwords? #f] @
  [#:auto-login? #f] [#:default-user ""] [#:startx] @
  [#:theme @var{%default-slim-theme}] @
  [#:theme-name @var{%default-slim-theme-name}]
Return a service that spawns the SLiM graphical login manager, which in
turn starts the X display server with @var{startx}, a command as returned by
@code{xorg-start-command}.

@cindex X session

SLiM automatically looks for session types described by the @file{.desktop}
files in @file{/run/current-system/profile/share/xsessions} and allows users
to choose a session from the log-in screen using @kbd{F1}.  Packages such as
@var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files;
adding them to the system-wide set of packages automatically makes them
available at the log-in screen.

In addition, @file{~/.xsession} files are honored.  When available,
@file{~/.xsession} must be an executable that starts a window manager
and/or other X clients.

When @var{allow-empty-passwords?} is true, allow logins with an empty
password.  When @var{auto-login?} is true, log in automatically as
@var{default-user}.

If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
@var{theme} must be a gexp denoting the name of a directory containing the
theme to use.  In that case, @var{theme-name} specifies the name of the
theme.
@end deffn

@defvr {Scheme Variable} %default-theme
@defvrx {Scheme Variable} %default-theme-name
The G-Expression denoting the default SLiM theme and its name.
@end defvr

@deffn {Scheme Procedure} xorg-start-command [#:guile] @
  [#:configuration-file #f] [#:xorg-server @var{xorg-server}]
Return a derivation that builds a @var{guile} script to start the X server
from @var{xorg-server}.  @var{configuration-file} is the server configuration
file or a derivation that builds it; when omitted, the result of
@code{xorg-configuration-file} is used.

Usually the X server is started by a login manager.
@end deffn

@deffn {Scheme Procedure} xorg-configuration-file @
  [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
Return a configuration file for the Xorg server containing search paths for
all the common drivers.

@var{drivers} must be either the empty list, in which case Xorg chooses a
graphics driver automatically, or a list of driver names that will be tried in
this order---e.g., @code{(\"modesetting\" \"vesa\")}.

Likewise, when @var{resolutions} is the empty list, Xorg chooses an
appropriate screen resolution; otherwise, it must be a list of
resolutions---e.g., @code{((1024 768) (640 480))}.

Last, @var{extra-config} is a list of strings or objects appended to the
@code{text-file*} argument list.  It is used to pass extra text to be added
verbatim to the configuration file.
@end deffn

@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{name}]
Add @var{package}, a package for a screen-locker or screen-saver whose
command is @var{program}, to the set of setuid programs and add a PAM entry
for it.  For example:

@lisp
(screen-locker-service xlockmore "xlock")
@end lisp

makes the good ol' XlockMore usable.
@end deffn


@node Desktop Services
@subsubsection Desktop Services

The @code{(gnu services desktop)} module provides services that are
usually useful in the context of a ``desktop'' setup---that is, on a
machine running a graphical display server, possibly with graphical user
interfaces, etc.

To simplify things, the module defines a variable containing the set of
services that users typically expect on a machine with a graphical
environment and networking:

@defvr {Scheme Variable} %desktop-services
This is a list of services that builds upon @var{%base-services} and
adds or adjust services for a typical ``desktop'' setup.

In particular, it adds a graphical login manager (@pxref{X Window,
@code{slim-service}}), screen lockers,
a network management tool (@pxref{Networking
Services, @code{wicd-service}}), energy and color management services,
the @code{elogind} login and seat manager, the Polkit privilege service,
the GeoClue location service, an NTP client (@pxref{Networking
Services}), the Avahi daemon, and has the name service switch service
configured to be able to use @code{nss-mdns} (@pxref{Name Service
Switch, mDNS}).
@end defvr

The @var{%desktop-services} variable can be used as the @code{services}
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).

The actual service definitions provided by @code{(gnu services dbus)}
and @code{(gnu services desktop)} are described below.

@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
Return a service that runs the ``system bus'', using @var{dbus}, with
support for @var{services}.

@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
facility.  Its system bus is used to allow system services to communicate
and be notified of system-wide events.

@var{services} must be a list of packages that provide an
@file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
and policy files.  For example, to allow avahi-daemon to use the system bus,
@var{services} must be equal to @code{(list avahi)}.
@end deffn

@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
Return a service that runs the @code{elogind} login and
seat management daemon.  @uref{https://github.com/andywingo/elogind,
Elogind} exposes a D-Bus interface that can be used to know which users
are logged in, know what kind of sessions they have open, suspend the
system, inhibit system suspend, reboot the system, and other tasks.

Elogind handles most system-level power events for a computer, for
example suspending the system when a lid is closed, or shutting it down
when the power button is pressed.

The @var{config} keyword argument specifies the configuration for
elogind, and should be the result of a @code{(elogind-configuration
(@var{parameter} @var{value})...)} invocation.  Available parameters and
their default values are:

@table @code
@item kill-user-processes?
@code{#f}
@item kill-only-users
@code{()}
@item kill-exclude-users
@code{("root")}
@item inhibit-delay-max-seconds
@code{5}
@item handle-power-key
@code{poweroff}
@item handle-suspend-key
@code{suspend}
@item handle-hibernate-key
@code{hibernate}
@item handle-lid-switch
@code{suspend}
@item handle-lid-switch-docked
@code{ignore}
@item power-key-ignore-inhibited?
@code{#f}
@item suspend-key-ignore-inhibited?
@code{#f}
@item hibernate-key-ignore-inhibited?
@code{#f}
@item lid-switch-ignore-inhibited?
@code{#t}
@item holdoff-timeout-seconds
@code{30}
@item idle-action
@code{ignore}
@item idle-action-seconds
@code{(* 30 60)}
@item runtime-directory-size-percent
@code{10}
@item runtime-directory-size
@code{#f}
@item remove-ipc?
@code{#t}
@item suspend-state
@code{("mem" "standby" "freeze")}
@item suspend-mode
@code{()}
@item hibernate-state
@code{("disk")}
@item hibernate-mode
@code{("platform" "shutdown")}
@item hybrid-sleep-state
@code{("disk")}
@item hybrid-sleep-mode
@code{("suspend" "platform" "shutdown")}
@end table
@end deffn

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

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

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

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

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

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

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

@node Database Services
@subsubsection Database Services

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

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

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

@node Web Services
@subsubsection Web Services

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

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

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

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

@end deffn

@node Various Services