guix.texi

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-job
  ;; 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 additional
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 Log Rotation
@subsubsection Log Rotation

@cindex rottlog
@cindex log rotation
Log files such as those found in @file{/var/log} tend to grow endlessly,
so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
their contents in separate files, possibly compressed.  The @code{(gnu
services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).

The example below defines an operating system that provides log rotation
with the default settings.

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

(operating-system
  ;; @dots{}
  (services (cons* (mcron-service)
                   (service rottlog-service-type (rottlog-configuration)) 
                   %base-services)))
@end lisp

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

This service type can define mcron jobs (@pxref{Scheduled Job
Execution}) to run the rottlog service.
@end defvr

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

@table @asis
@item @code{rottlog} (default: @code{rottlog})
The Rottlog package to use.

@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
rottlog, GNU Rot[t]log Manual}).

@item @code{periodic-rotations} (default: @code{`(("weekly" %default-rotatations))})
A list of Rottlog period-name/period-config tuples.

For example, taking an example from the Rottlog manual (@pxref{Period
Related File Examples,,, rottlog, GNU Rot[t]log Manual}), a valid tuple
might be:

@example
("daily" ,(plain-file "daily"
                      "\
     /var/log/apache/* @{
        storedir apache-archives
        rotate 6
        notifempty
        nocompress
     @}"))
@end example

@item @code{jobs}
This is a list of gexps where each gexp corresponds to an mcron job
specification (@pxref{Scheduled Job Execution}).
@end table
@end deftp

@defvr {Scheme Variable} %default-rotations
Specifies weekly rotation of @var{%rotated-files} and
@code{"/var/log/shepherd.log"}.
@end defvr

@defvr {Scheme Variable} %rotated-files
The list of syslog-controlled files to be rotated.  By default it is:
@code{'("/var/log/messages" "/var/log/secure")}.
@end defvr

@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}] @
  [#:servers @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.

@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

@deffn {Scheme Variable} openssh-service-type
This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
shell daemon, @command{sshd}.  Its value must be an
@code{openssh-configuration} record as in this example:

@example
(service openssh-service-type
         (openssh-configuration
           (x11-forwarding? #t)
           (permit-root-login 'without-password)))
@end example

See below for details about @code{openssh-configuration}.
@end deffn

@deftp {Data Type} openssh-configuration
This is the configuration record for OpenSSH's @command{sshd}.

@table @asis
@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
Name of the file where @command{sshd} writes its PID.

@item @code{port-number} (default: @code{22})
TCP port on which @command{sshd} listens for incoming connections.

@item @code{permit-root-login} (default: @code{#f})
This field determines whether and when to allow logins as root.  If
@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
If it's the symbol @code{'without-password}, then root logins are
permitted but not with password-based authentication.

@item @code{allow-empty-passwords?} (default: @code{#f})
When true, users with empty passwords may log in.  When false, they may
not.

@item @code{password-authentication?} (default: @code{#t})
When true, users may log in with their password.  When false, they have
other authentication methods.

@item @code{public-key-authentication?} (default: @code{#t})
When true, users may log in using public key authentication.  When
false, users have to use other authentication method.

Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
This is used only by protocol version 2.

@item @code{rsa-authentication?} (default: @code{#t})
When true, users may log in using pure RSA authentication.  When false,
users have to use other means of authentication.  This is used only by
protocol 1.

@item @code{x11-forwarding?} (default: @code{#f})
When true, forwarding of X11 graphical client connections is
enabled---in other words, @command{ssh} options @option{-X} and
@option{-Y} will work.

@item @code{protocol-number} (default: @code{2})
The SSH protocol number to use.
@end table
@end deftp

@deffn {Scheme Procedure} dropbear-service [@var{config}]
Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
daemon} with the given @var{config}, a @code{<dropbear-configuration>}
object.

For example, to specify a Dropbear service listening on port 1234, add
this call to the operating system's @code{services} field:

@example
(dropbear-service (dropbear-configuration
                    (port-number 1234)))
@end example
@end deffn

@deftp {Data Type} dropbear-configuration
This data type represents the configuration of a Dropbear SSH daemon.

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

@item @code{port-number} (default: 22)
The TCP port where the daemon waits for incoming connections.

@item @code{syslog-output?} (default: @code{#t})
Whether to enable syslog output.

@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
File name of the daemon's PID file.

@item @code{root-login?} (default: @code{#f})
Whether to allow @code{root} logins.

@item @code{allow-empty-passwords?} (default: @code{#f})
Whether to allow empty passwords.

@item @code{password-authentication?} (default: @code{#t})
Whether to enable password-based authentication.
@end table
@end deftp

@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 '()] [#:debug? #f]
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.

@deftp {Data Type} sddm-configuration
This is the data type representing the sddm service configuration.

@table @asis
@item @code{display-server} (default: "x11")
Select display server to use for the greeter. Valid values are "x11"
or "wayland".

@item @code{numlock} (default: "on")
Valid values are "on", "off" or "none".

@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
Command to run when halting.

@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
Command to run when rebooting.

@item @code{theme} (default "maldives")
Theme to use. Default themes provided by SDDM are "elarun" or "maldives".

@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
Directory to look for themes.

@item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
Directory to look for faces.

@item @code{default-path} (default "/run/current-system/profile/bin")
Default PATH to use.

@item @code{minimum-uid} (default 1000)
Minimum UID to display in SDDM.

@item @code{maximum-uid} (default 2000)
Maximum UID to display in SDDM

@item @code{remember-last-user?} (default #t)
Remember last user.

@item @code{remember-last-session?} (default #t)
Remember last session.

@item @code{hide-users} (default "")
Usernames to hide from SDDM greeter.

@item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
Users with shells listed will be hidden from the SDDM greeter.

@item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
Script to run before starting a wayland session.

@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
Directory to look for desktop files starting wayland sessions.

@item @code{xorg-server-path} (default @code{xorg-start-command})
Path to xorg-server.

@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
Path to xauth.

@item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
Path to Xephyr.

@item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
Script to run after starting xorg-server.

@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
Script to run before stopping xorg-server.

@item @code{xsession-command} (default: @code{xinitr })
Script to run before starting a X session.

@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
Directory to look for desktop files starting X sessions.

@item @code{minimum-vt} (default: 7)
Minimum VT to use.

@item @code{xserver-arguments} (default "-nolisten tcp")
Arguments to pass to xorg-server.

@item @code{auto-login-user} (default "")
User to use for auto-login.

@item @code{auto-login-session} (default "")
Desktop file to use for auto-login.

@item @code{relogin?} (default #f)
Relogin after logout.

@end table
@end deftp

@deffn {Scheme Procedure} sddm-service config
Return a service that spawns the SDDM graphical login manager for config of
type @code{<sddm-configuration>}.

@example
  (sddm-service (sddm-configuration
                 (auto-login-user "Alice")
                 (auto-login-session "xfce.desktop")))
@end example
@end deffn

@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}, 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.  It also defines services that provide specific desktop
environments like GNOME and XFCE.

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

Additionally, the @code{gnome-desktop-service} and
@code{xfce-desktop-service} procedures can add GNOME and/or XFCE to a
system.  To ``add GNOME'' means that system-level services like the
backlight adjustment helpers and the power management utilities are
added to the system, extending @code{polkit} and @code{dbus}
appropriately, allowing GNOME to operate with elevated privileges on a
limited number of special-purpose system interfaces.  Additionally,
adding a service made by @code{gnome-desktop-service} adds the GNOME
metapackage to the system profile.  Likewise, adding the XFCE service
not only adds the @code{xfce} metapackage to the system profile, but it
also gives the Thunar file manager the ability to open a ``root-mode''
file management window, if the user authenticates using the
administrator's password via the standard polkit graphical interface.

@deffn {Scheme Procedure} gnome-desktop-service
Return a service that adds the @code{gnome} package to the system
profile, and extends polkit with the actions from
@code{gnome-settings-daemon}.
@end deffn

@deffn {Scheme Procedure} xfce-desktop-service
Return a service that adds the @code{xfce} package to the system profile,
and extends polkit with the ability for @code{thunar} to manipulate the
file system as root from within a user session, after the user has
authenticated with the administrator's password.
@end deffn

Because the GNOME and XFCE desktop services pull in so many packages,
the default @code{%desktop-services} variable doesn't include either of
them by default.  To add GNOME or XFCE, just @code{cons} them onto
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:

@example
(use-modules (gnu))
(use-service-modules desktop)
(operating-system
  ...
  ;; cons* adds items to the list given as its last argument.
  (services (cons* (gnome-desktop-service)
                   (xfce-desktop-service)
                   %desktop-services))
  ...)
@end example

These desktop environments will then be available as options in the
graphical login window.

The actual service definitions included in @code{%desktop-services} and
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 to 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 an @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 a 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 whether 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 the GNOME date-and-time utility to ask for the
current location in order to set the time zone, and allowing the
IceCat and Epiphany web browsers to request location information.
IceCat 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

@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}]
Return a service that runs the @command{bluetoothd} daemon, which manages
all the Bluetooth devices and provides a number of D-Bus interfaces.

Users need to be in the @code{lp} group to access the D-Bus service.
@end deffn

@node Database Services
@subsubsection Database Services

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

@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

@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)]
Return a service that runs @command{mysqld}, the MySQL or MariaDB
database server.

The optional @var{config} argument specifies the configuration for
@command{mysqld}, which should be a @code{<mysql-configuraiton>} object.
@end deffn

@deftp {Data Type} mysql-configuration
Data type representing the configuration of @var{mysql-service}.

@table @asis
@item @code{mysql} (default: @var{mariadb})
Package object of the MySQL database server, can be either @var{mariadb}
or @var{mysql}.

For MySQL, a temporary root password will be displayed at activation time.
For MariaDB, the root password is empty.
@end table
@end deftp

@node Mail Services
@subsubsection Mail Services

The @code{(gnu services mail)} module provides Guix service definitions
for mail services.  Currently the only implemented service is Dovecot,