guix.texi

thresholds will effectively limit the scheduler to printing a single job
at any time.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
Specifies the scheduling priority of filters that are run to print a
job.  The nice value ranges from 0, the highest priority, to 19, the
lowest priority.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
Specifies whether to do reverse lookups on connecting clients.  The
@code{double} setting causes @code{cupsd} to verify that the hostname
resolved from the address matches one of the addresses returned for that
hostname.  Double lookups also prevent clients with unregistered
addresses from connecting to your server.  Only set this option to
@code{#t} or @code{double} if absolutely required.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
Specifies the number of seconds to wait before killing the filters and
backend associated with a canceled or held job.

Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
Specifies the interval between retries of jobs in seconds.  This is
typically used for fax queues but can also be used with normal print
queues whose error policy is @code{retry-job} or
@code{retry-current-job}.

Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
Specifies the number of retries that are done for jobs.  This is
typically used for fax queues but can also be used with normal print
queues whose error policy is @code{retry-job} or
@code{retry-current-job}.

Defaults to @samp{5}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
Specifies whether to support HTTP keep-alive connections.

Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout
Specifies how long an idle client connection remains open, in seconds.

Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
Specifies the maximum size of print files, IPP requests, and HTML form
data.  A limit of 0 disables the limit check.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
Listens on the specified interfaces for connections.  Valid values are
of the form @var{address}:@var{port}, where @var{address} is either an
IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
indicate all addresses.  Values can also be file names of local UNIX
domain sockets.  The Listen directive is similar to the Port directive
but allows you to restrict access to specific interfaces or networks.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
Specifies the number of pending connections that will be allowed.  This
normally only affects very busy servers that have reached the MaxClients
limit, but can also be triggered by large numbers of simultaneous
connections.  When the limit is reached, the operating system will
refuse additional connections until the scheduler can accept the pending
ones.

Defaults to @samp{128}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
Specifies a set of additional access controls.

Available @code{location-access-controls} fields are:

@deftypevr {@code{location-access-controls} parameter} file-name path
Specifies the URI path to which the access control applies.
@end deftypevr

@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
Access controls for all access to this path, in the same format as the
@code{access-controls} of @code{operation-access-control}.

Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
Access controls for method-specific access to this path.

Defaults to @samp{()}.

Available @code{method-access-controls} fields are:

@deftypevr {@code{method-access-controls} parameter} boolean reverse?
If @code{#t}, apply access controls to all methods except the listed
methods.  Otherwise apply to only the listed methods.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{method-access-controls} parameter} method-list methods
Methods to which this access control applies.

Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
Access control directives, as a list of strings.  Each string should be
one directive, such as "Order allow,deny".

Defaults to @samp{()}.
@end deftypevr
@end deftypevr
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
Specifies the number of debugging messages that are retained for logging
if an error occurs in a print job.  Debug messages are logged regardless
of the LogLevel setting.

Defaults to @samp{100}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} log-level log-level
Specifies the level of logging for the ErrorLog file.  The value
@code{none} stops all logging while @code{debug2} logs everything.

Defaults to @samp{info}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
Specifies the format of the date and time in the log files.  The value
@code{standard} logs whole seconds while @code{usecs} logs microseconds.

Defaults to @samp{standard}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
Specifies the maximum number of simultaneous clients that are allowed by
the scheduler.

Defaults to @samp{100}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
Specifies the maximum number of simultaneous clients that are allowed
from a single address.

Defaults to @samp{100}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
Specifies the maximum number of copies that a user can print of each
job.

Defaults to @samp{9999}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
Specifies the maximum time a job may remain in the @code{indefinite}
hold state before it is canceled.  A value of 0 disables cancellation of
held jobs.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
Specifies the maximum number of simultaneous jobs that are allowed.  Set
to 0 to allow an unlimited number of jobs.

Defaults to @samp{500}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
Specifies the maximum number of simultaneous jobs that are allowed per
printer.  A value of 0 allows up to MaxJobs jobs per printer.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
Specifies the maximum number of simultaneous jobs that are allowed per
user.  A value of 0 allows up to MaxJobs jobs per user.

Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
Specifies the maximum time a job may take to print before it is
canceled, in seconds.  Set to 0 to disable cancellation of "stuck" jobs.

Defaults to @samp{10800}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
Specifies the maximum size of the log files before they are rotated, in
bytes.  The value 0 disables log rotation.

Defaults to @samp{1048576}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
Specifies the maximum amount of time to allow between files in a
multiple file print job, in seconds.

Defaults to @samp{300}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string page-log-format
Specifies the format of PageLog lines.  Sequences beginning with percent
(@samp{%}) characters are replaced with the corresponding information,
while all other characters are copied literally.  The following percent
sequences are recognized:

@table @samp
@item %%
insert a single percent character

@item %@{name@}
insert the value of the specified IPP attribute

@item %C
insert the number of copies for the current page

@item %P
insert the current page number

@item %T
insert the current date and time in common log format

@item %j
insert the job ID

@item %p
insert the printer name

@item %u
insert the username
@end table

A value of the empty string disables page logging.  The string @code{%p
%u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@}
%@{job-name@} %@{media@} %@{sides@}} creates a page log with the
standard items.

Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
Passes the specified environment variable(s) to child processes; a list
of strings.

Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
Specifies named access control policies.

Available @code{policy-configuration} fields are:

@deftypevr {@code{policy-configuration} parameter} string name
Name of the policy.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} string job-private-access
Specifies an access list for a job's private values.  @code{@@ACL} maps
to the printer's requesting-user-name-allowed or
requesting-user-name-denied values.  @code{@@OWNER} maps to the job's
owner.  @code{@@SYSTEM} maps to the groups listed for the
@code{system-group} field of the @code{files-config} configuration,
which is reified into the @code{cups-files.conf(5)} file.  Other
possible elements of the access list include specific user names, and
@code{@@@var{group}} to indicate members of a specific group.  The
access list may also be simply @code{all} or @code{default}.

Defaults to @samp{"@@OWNER @@SYSTEM"}.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} string job-private-values
Specifies the list of job values to make private, or @code{all},
@code{default}, or @code{none}.

Defaults to @samp{"job-name job-originating-host-name
job-originating-user-name phone"}.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} string subscription-private-access
Specifies an access list for a subscription's private values.
@code{@@ACL} maps to the printer's requesting-user-name-allowed or
requesting-user-name-denied values.  @code{@@OWNER} maps to the job's
owner.  @code{@@SYSTEM} maps to the groups listed for the
@code{system-group} field of the @code{files-config} configuration,
which is reified into the @code{cups-files.conf(5)} file.  Other
possible elements of the access list include specific user names, and
@code{@@@var{group}} to indicate members of a specific group.  The
access list may also be simply @code{all} or @code{default}.

Defaults to @samp{"@@OWNER @@SYSTEM"}.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} string subscription-private-values
Specifies the list of job values to make private, or @code{all},
@code{default}, or @code{none}.

Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
notify-subscriber-user-name notify-user-data"}.
@end deftypevr

@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
Access control by IPP operation.

Defaults to @samp{()}.
@end deftypevr
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
Specifies whether job files (documents) are preserved after a job is
printed.  If a numeric value is specified, job files are preserved for
the indicated number of seconds after printing.  Otherwise a boolean
value applies indefinitely.

Defaults to @samp{86400}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
Specifies whether the job history is preserved after a job is printed.
If a numeric value is specified, the job history is preserved for the
indicated number of seconds after printing.  If @code{#t}, the job
history is preserved until the MaxJobs limit is reached.

Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
Specifies the amount of time to wait for job completion before
restarting the scheduler.

Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string rip-cache
Specifies the maximum amount of memory to use when converting documents
into bitmaps for a printer.

Defaults to @samp{"128m"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string server-admin
Specifies the email address of the server administrator.

Defaults to @samp{"root@@localhost.localdomain"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
The ServerAlias directive is used for HTTP Host header validation when
clients connect to the scheduler from external interfaces.  Using the
special name @code{*} can expose your system to known browser-based DNS
rebinding attacks, even when accessing sites through a firewall.  If the
auto-discovery of alternate names does not work, we recommend listing
each alternate name with a ServerAlias directive instead of using
@code{*}.

Defaults to @samp{*}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string server-name
Specifies the fully-qualified host name of the server.

Defaults to @samp{"localhost"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
Specifies what information is included in the Server header of HTTP
responses.  @code{None} disables the Server header.  @code{ProductOnly}
reports @code{CUPS}.  @code{Major} reports @code{CUPS 2}.  @code{Minor}
reports @code{CUPS 2.0}.  @code{Minimal} reports @code{CUPS 2.0.0}.
@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
the output of the @code{uname} command.  @code{Full} reports @code{CUPS
2.0.0 (@var{uname}) IPP/2.0}.

Defaults to @samp{Minimal}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} string set-env
Set the specified environment variable to be passed to child processes.

Defaults to @samp{"variable value"}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
Listens on the specified interfaces for encrypted connections.  Valid
values are of the form @var{address}:@var{port}, where @var{address} is
either an IPv6 address enclosed in brackets, an IPv4 address, or
@code{*} to indicate all addresses.

Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
Sets encryption options.  By default, CUPS only supports encryption
using TLS v1.0 or higher using known secure cipher suites.  The
@code{AllowRC4} option enables the 128-bit RC4 cipher suites, which are
required for some older clients that do not implement newer ones.  The
@code{AllowSSL3} option enables SSL v3.0, which is required for some
older clients that do not support TLS v1.0.

Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
Specifies whether the scheduler requires clients to strictly adhere to
the IPP specifications.

Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
Specifies the HTTP request timeout, in seconds.

Defaults to @samp{300}.

@end deftypevr

@deftypevr {@code{cups-configuration} parameter} boolean web-interface?
Specifies whether the web interface is enabled.

Defaults to @samp{#f}.
@end deftypevr

At this point you're probably thinking ``oh dear, Guix manual, I like
you but you can stop already with the configuration options''.  Indeed.
However, one more point: it could be that you have an existing
@code{cupsd.conf} that you want to use.  In that case, you can pass an
@code{opaque-cups-configuration} as the configuration of a
@code{cups-service-type}.

Available @code{opaque-cups-configuration} fields are:

@deftypevr {@code{opaque-cups-configuration} parameter} package cups
The CUPS package.
@end deftypevr

@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
The contents of the @code{cupsd.conf}, as a string.
@end deftypevr

@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
The contents of the @code{cups-files.conf} file, as a string.
@end deftypevr

For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
strings of the same name, you could instantiate a CUPS service like
this:

@example
(service cups-service-type
         (opaque-cups-configuration
           (cupsd.conf cupsd.conf)
           (cups-files.conf cups-files.conf)))
@end example


@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

@cindex database
@cindex SQL
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''] @
       [#:port 5432] [#:locale ``en_US.utf8'']
Return a service that runs @var{postgresql}, the PostgreSQL database
server.

The PostgreSQL daemon loads its runtime configuration from @var{config-file},
creates a database cluster with @var{locale} as the default
locale, stored in @var{data-directory}.  It then listens on @var{port}.
@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-configuration>} 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.

@item @code{port} (default: @code{3306})
TCP port on which the database server listens for incoming connections.
@end table
@end deftp

@defvr {Scheme Variable} memcached-service-type
This is the service type for the @uref{https://memcached.org/,
Memcached} service, which provides a distributed in memory cache.  The
value for the service type is a @code{memcached-configuration} object.
@end defvr

@example
(service memcached-service-type)
@end example

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

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

@item @code{interfaces} (default: @code{'("0.0.0.0")})
Network interfaces on which to listen.

@item @code{tcp-port} (default: @code{11211})
Port on which to accept connections on,

@item @code{udp-port} (default: @code{11211})
Port on which to accept UDP connections on, a value of 0 will disable
listening on a UDP socket.

@item @code{additional-options} (default: @code{'()})
Additional command line options to pass to @code{memcached}.
@end table
@end deftp

@defvr {Scheme Variable} redis-service-type
This is the service type for the @uref{https://redis.io/, Redis}
key/value store, whose value is a @code{redis-configuration} object.
@end defvr

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

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

@item @code{bind} (default: @code{"127.0.0.1"})
Network interface on which to listen.

@item @code{port} (default: @code{6379})
Port on which to accept connections on, a value of 0 will disable
listening on a TCP socket.

@item @code{working-directory} (default: @code{"/var/lib/redis"})
Directory in which to store the database and related files.
@end table
@end deftp

@node Mail Services
@subsubsection Mail Services

@cindex mail
@cindex email
The @code{(gnu services mail)} module provides Guix service definitions
for email services: IMAP, POP3, and LMTP servers, as well as mail
transport agents (MTAs).  Lots of acronyms!  These services are detailed
in the subsections below.

@subsubheading Dovecot Service

@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} string path
Path to the file, relative to @code{base-dir} field.  This is also used as
the section name.
@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} string path
Path to the file, relative to @code{base-dir} field.  This is also used as
the section name.
@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{""}.