guix.texi

         "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 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 Procedure} openssh-service [#:pid-file "/var/run/sshd.pid"] @
       [#:port-number 22] [#:permit-root-login 'without-password] @
       [#:allow-empty-passwords #f] [#:password-authentication? #t] @
       [#:pubkey-authentication? #t] [#:rsa-authentication? #t] @
       [#:x11-forwarding? #f] [#:protocol-number "2"]
Run the @command{sshd} program from @var{openssh} on port
@var{port-number}.  @command{sshd} runs an SSH daemon and writes its PID
to @var{pid-file}.  It understands SSH protocol
@var{protocol-number}. The @var{protocol-number} can be either 1 or 2.

@var{permit-root-login} takes one of @code{#t}, @code{'without-password}
and @code{#f}.  It is used to allow root login through SSH.
@code{'without-password} means that root login is allowed, but not with
password-based authentication.

When @var{allow-empty-passwords?} is true, users with empty passwords
may log in.  When false, they may not.

When @var{password-authentication?} is true, users may log in with their
password.  When false, they have to use other means of authentication.

When @var{pubkey-authentication?} is true, users may log in using public
key authentication.  When false, users have to use other means of
authentication.  Authorized public keys are stored in
@file{~/.ssh/authorized_keys}.  This is used only by protocol version 2.

When @var{rsa-authentication?} is 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.

When @var{x11-forwarding?} is true, @command{ssh} options @option{-X}
and @option{-Y} will work.
@end deffn

@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,
an IMAP, POP3, and LMTP server.

Guix does not yet have a mail transfer agent (MTA), although for some
lightweight purposes the @code{esmtp} relay-only MTA may suffice.  Help
is needed to properly integrate a full MTA, such as Postfix.  Patches
welcome!

To add an IMAP/POP3 server to a GuixSD system, add a
@code{dovecot-service} to the operating system definition:

@deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
@end deffn

By default, Dovecot does not need much configuration; the default
configuration object created by @code{(dovecot-configuration)} will
suffice if your mail is delivered to @code{~/Maildir}.  A self-signed
certificate will be generated for TLS-protected connections, though
Dovecot will also listen on cleartext ports by default.  There are a
number of options, though, which mail administrators might need to change,
and as is the case with other services, Guix allows the system
administrator to specify these parameters via a uniform Scheme interface.

For example, to specify that mail is located at @code{maildir~/.mail},
one would instantiate the Dovecot service like this:

@example
(dovecot-service #:config
                 (dovecot-configuration
                  (mail-location "maildir:~/.mail")))
@end example

The available configuration parameters follow.  Each parameter
definition is preceded by its type; for example, @samp{string-list foo}
indicates that the @code{foo} parameter should be specified as a list of
strings.  There is also a way to specify the configuration as a string,
if you have an old @code{dovecot.conf} file that you want to port over
from some other system; see the end for more details.

@c The following documentation was initially generated by
@c (generate-documentation) in (gnu services mail).  Manually maintained
@c documentation is better, so we shouldn't hesitate to edit below as
@c needed.  However if the change you want to make to this documentation
@c can be done in an automated way, it's probably easier to change
@c (generate-documentation) than to make it below and have to deal with
@c the churn as dovecot updates.

Available @code{dovecot-configuration} fields are:

@deftypevr {@code{dovecot-configuration} parameter} package dovecot
The dovecot package.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
A list of IPs or hosts where to listen for connections.  @samp{*}
listens on all IPv4 interfaces, @samp{::} listens on all IPv6
interfaces.  If you want to specify non-default ports or anything more
complex, customize the address and port fields of the
@samp{inet-listener} of the specific services you are interested in.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
List of protocols we want to serve.  Available protocols include
@samp{imap}, @samp{pop3}, and @samp{lmtp}.

Available @code{protocol-configuration} fields are:

@deftypevr {@code{protocol-configuration} parameter} string name
The name of the protocol.
@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
UNIX socket path to the master authentication server to find users.
This is used by imap (for shared users) and lda.
It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
Space separated list of plugins to load.
@end deftypevr

@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
Maximum number of IMAP connections allowed for a user from each IP
address.  NOTE: The username is compared case-sensitively.
Defaults to @samp{10}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
List of services to enable.  Available services include @samp{imap},
@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
@samp{lmtp}.

Available @code{service-configuration} fields are:

@deftypevr {@code{service-configuration} parameter} string kind
The service kind.  Valid values include @code{director},
@code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap},
@code{pop3}, @code{auth}, @code{auth-worker}, @code{dict},
@code{tcpwrap}, @code{quota-warning}, or anything else.
@end deftypevr

@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
Listeners for the service.  A listener is either a
@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
an @code{inet-listener-configuration}.
Defaults to @samp{()}.

Available @code{unix-listener-configuration} fields are:

@deftypevr {@code{unix-listener-configuration} parameter} file-name path
The file name on which to listen.
@end deftypevr

@deftypevr {@code{unix-listener-configuration} parameter} string mode
The access mode for the socket.
Defaults to @samp{"0600"}.
@end deftypevr

@deftypevr {@code{unix-listener-configuration} parameter} string user
The user to own the socket.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{unix-listener-configuration} parameter} string group
The group to own the socket.
Defaults to @samp{""}.
@end deftypevr


Available @code{fifo-listener-configuration} fields are:

@deftypevr {@code{fifo-listener-configuration} parameter} file-name path
The file name on which to listen.
@end deftypevr

@deftypevr {@code{fifo-listener-configuration} parameter} string mode
The access mode for the socket.
Defaults to @samp{"0600"}.
@end deftypevr

@deftypevr {@code{fifo-listener-configuration} parameter} string user
The user to own the socket.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{fifo-listener-configuration} parameter} string group
The group to own the socket.
Defaults to @samp{""}.
@end deftypevr


Available @code{inet-listener-configuration} fields are:

@deftypevr {@code{inet-listener-configuration} parameter} string protocol
The protocol to listen for.
@end deftypevr

@deftypevr {@code{inet-listener-configuration} parameter} string address
The address on which to listen, or empty for all addresses.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
The port on which to listen.
@end deftypevr

@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
Whether to use SSL for this service; @samp{yes}, @samp{no}, or
@samp{required}.
Defaults to @samp{#t}.
@end deftypevr

@end deftypevr

@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
Number of connections to handle before starting a new process.
Typically the only useful values are 0 (unlimited) or 1.  1 is more
secure, but 0 is faster.  <doc/wiki/LoginProcess.txt>.
Defaults to @samp{1}.
@end deftypevr