guix.texi

root.

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

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

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

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

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

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

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

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

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

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

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

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


@node X Window
@subsubsection X Window

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

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

@cindex X session

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

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

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

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

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

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

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

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

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

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

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

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

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

makes the good ol' XlockMore usable.
@end deffn


@node Desktop Services
@subsubsection Desktop Services

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@node Database Services
@subsubsection Database Services

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

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

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

@node 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 doesn't 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 in for connections.  @samp{*}
listens in all IPv4 interfaces, @samp{::} listens in 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 master authentication server to find users.
This is used by imap (for shared users) and lda.
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 an
@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

@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
Number of processes to always keep waiting for more connections.
Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
If you set @samp{service-count 0}, you probably need to grow
this.
Defaults to @samp{256000000}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
Dict configuration, as created by the @code{dict-configuration}
constructor.

Available @code{dict-configuration} fields are:

@deftypevr {@code{dict-configuration} parameter} free-form-fields entries
A list of key-value pairs that this dict should hold.
Defaults to @samp{()}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
List of passdb configurations, each one created by the
@code{passdb-configuration} constructor.

Available @code{passdb-configuration} fields are:

@deftypevr {@code{passdb-configuration} parameter} string driver
The driver that the passdb should use.  Valid values include
@samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
@samp{static}.
Defaults to @samp{"pam"}.
@end deftypevr

@deftypevr {@code{passdb-configuration} parameter} free-form-args args
A list of key-value args to the passdb driver.
Defaults to @samp{()}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
List of userdb configurations, each one created by the
@code{userdb-configuration} constructor.

Available @code{userdb-configuration} fields are:

@deftypevr {@code{userdb-configuration} parameter} string driver
The driver that the userdb should use.  Valid values include
@samp{passwd} and @samp{static}.
Defaults to @samp{"passwd"}.
@end deftypevr

@deftypevr {@code{userdb-configuration} parameter} free-form-args args
A list of key-value args to the userdb driver.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
Override fields from passwd.
Defaults to @samp{()}.
@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
Plug-in configuration, created by the @code{plugin-configuration}
constructor.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
List of namespaces.  Each item in the list is created by the
@code{namespace-configuration} constructor.

Available @code{namespace-configuration} fields are:

@deftypevr {@code{namespace-configuration} parameter} string name
Name for this namespace.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} string type
Namespace type: @samp{private}, @samp{shared} or @samp{public}.
Defaults to @samp{"private"}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} string separator
Hierarchy separator to use. You should use the same separator for
all namespaces or some clients get confused.  @samp{/} is usually a good
one.  The default however depends on the underlying mail storage
format.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} string prefix
Prefix required to access this namespace.  This needs to be
different for all namespaces. For example @samp{Public/}.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} string location
Physical location of the mailbox. This is in same format as
mail_location, which is also the default for it.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} boolean inbox?
There can be only one INBOX, and this setting defines which
namespace has it.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} boolean hidden?
If namespace is hidden, it's not advertised to clients via NAMESPACE
extension. You'll most likely also want to set @samp{list? #f}.  This is mostly
useful when converting from another server with different namespaces
which you want to deprecate but still keep working.  For example you can
create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/}
and @samp{mail/}.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} boolean list?
Show the mailboxes under this namespace with LIST command. This
makes the namespace visible for clients that don't support NAMESPACE
extension.  The special @code{children} value lists child mailboxes, but
hides the namespace prefix.
Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
Namespace handles its own subscriptions.  If set to @code{#f}, the
parent namespace handles them.  The empty prefix should always have this
as @code{#t}.)
Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
List of predefined mailboxes in this namespace.
Defaults to @samp{()}.

Available @code{mailbox-configuration} fields are:

@deftypevr {@code{mailbox-configuration} parameter} string name
Name for this mailbox.
@end deftypevr

@deftypevr {@code{mailbox-configuration} parameter} string auto
@samp{create} will automatically create this mailbox.
@samp{subscribe} will both create and subscribe to the mailbox.
Defaults to @samp{"no"}.
@end deftypevr

@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154.
Valid values are @code{\All}, @code{\Archive}, @code{\Drafts},
@code{\Flagged}, @code{\Junk}, @code{\Sent}, and @code{\Trash}.
Defaults to @samp{()}.
@end deftypevr

@end deftypevr

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
Base directory where to store runtime data.
Defaults to @samp{"/var/run/dovecot/"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string login-greeting
Greeting message for clients.
Defaults to @samp{"Dovecot ready."}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
List of trusted network ranges.  Connections from these IPs are
allowed to override their IP addresses and ports (for logging and for
authentication checks).  @samp{disable-plaintext-auth} is also ignored
for these networks.  Typically you'd specify your IMAP proxy servers
here.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
List of login access check sockets (e.g. tcpwrap).
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
Show more verbose process titles (in ps).  Currently shows user name
and IP address.  Useful for seeing who are actually using the IMAP
processes (e.g. shared mailboxes or if same uid is used for multiple
accounts).
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
Should all processes be killed when Dovecot master process shuts down.
Setting this to @code{#f} means that Dovecot can be upgraded without
forcing existing client connections to close (although that could also
be a problem if the upgrade is e.g. because of a security fix).
Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
If non-zero, run mail commands via this many connections to doveadm
server, instead of running them directly in the same process.
Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
UNIX socket or host:port used for connecting to doveadm server.
Defaults to @samp{"doveadm-server"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
List of environment variables that are preserved on Dovecot startup
and passed down to all of its child processes.  You can also give
key=value pairs to always set specific settings.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
Disable LOGIN command and all other plaintext authentications unless
SSL/TLS is used (LOGINDISABLED capability).  Note that if the remote IP
matches the local IP (i.e. you're connecting from the same computer),
the connection is considered secure and plaintext authentication is
allowed.  See also ssl=required setting.
Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size
Authentication cache size (e.g. @samp{#e10e6}).  0 means it's disabled.
Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set
for caching to be used.
Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl
Time to live for cached data.  After TTL expires the cached record
is no longer used, *except* if the main database lookup returns internal
failure.  We also try to handle password changes automatically: If
user's previous authentication was successful, but this one wasn't, the
cache isn't used.  For now this works only with plaintext
authentication.
Defaults to @samp{"1 hour"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl
TTL for negative hits (user not found, password mismatch).
0 disables caching them completely.
Defaults to @samp{"1 hour"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms
List of realms for SASL authentication mechanisms that need them.
You can leave it empty if you don't want to support multiple realms.
Many clients simply use the first one listed here, so keep the default
realm first.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
Default realm/domain to use if none was specified.  This is used for
both SASL realms and appending @@domain to username in plaintext
logins.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
List of allowed characters in username.  If the user-given username
contains a character not listed in here, the login automatically fails.
This is just an extra check to make sure user can't exploit any
potential quote escaping vulnerabilities with SQL/LDAP databases.  If
you want to allow all characters, set this value to empty.
Defaults to @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation
Username character translations before it's looked up from
databases.  The value contains series of from -> to characters.  For
example @samp{#@@/@@} means that @samp{#} and @samp{/} characters are
translated to @samp{@@}.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-username-format
Username formatting before it's looked up from databases.  You can
use the standard variables here, e.g. %Lu would lowercase the username,
%n would drop away the domain if it was given, or @samp{%n-AT-%d} would
change the @samp{@@} into @samp{-AT-}.  This translation is done after
@samp{auth-username-translation} changes.
Defaults to @samp{"%Lu"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
If you want to allow master users to log in by specifying the master
username within the normal username string (i.e. not using SASL
mechanism's support for it), you can specify the separator character
here.  The format is then <username><separator><master username>.
UW-IMAP uses @samp{*} as the separator, so that could be a good
choice.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username
Username to use for users logging in with ANONYMOUS SASL
mechanism.
Defaults to @samp{"anonymous"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
Maximum number of dovecot-auth worker processes.  They're used to
execute blocking passdb and userdb queries (e.g. MySQL and PAM).
They're automatically created and destroyed as needed.
Defaults to @samp{30}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname
Host name to use in GSSAPI principal names.  The default is to use
the name returned by gethostname().  Use @samp{$ALL} (with quotes) to
allow all keytab entries.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
Kerberos keytab to use for the GSSAPI mechanism.  Will use the
system default (usually /etc/krb5.keytab) if not specified.  You may
need to change the auth service to run as root to be able to read this
file.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind?
Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon
and @samp{ntlm-auth} helper.
<doc/wiki/Authentication/Mechanisms/Winbind.txt>.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path
Path for Samba's @samp{ntlm-auth} helper binary.
Defaults to @samp{"/usr/bin/ntlm_auth"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay
Time to delay before replying to failed authentications.
Defaults to @samp{"2 secs"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert?
Require a valid SSL client certificate or the authentication
fails.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
Take the username from client's SSL certificate, using
@code{X509_NAME_get_text_by_NID()} which returns the subject's DN's
CommonName.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms
List of wanted authentication mechanisms.  Supported mechanisms are:
@samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
@samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
@samp{otp}, @samp{skey}, and @samp{gss-spnego}.  NOTE: See also
@samp{disable-plaintext-auth} setting.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
List of IPs or hostnames to all director servers, including ourself.
Ports can be specified as ip:port.  The default port is the same as what
director service's @samp{inet-listener} is using.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
List of IPs or hostnames to all backend mail servers.  Ranges are
allowed too, like 10.0.0.10-10.0.0.30.
Defaults to @samp{()}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
How long to redirect users to a specific server after it no longer
has any connections.
Defaults to @samp{"15 min"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer director-doveadm-port
TCP/IP port that accepts doveadm connections (instead of director
connections) If you enable this, you'll also need to add
@samp{inet-listener} for the port.
Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
How the username is translated before being hashed.  Useful values
include %Ln if user can log in with or without @@domain, %Ld if mailboxes
are shared within domain.
Defaults to @samp{"%Lu"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string log-path
Log file to use for error messages.  @samp{syslog} logs to syslog,
@samp{/dev/stderr} logs to stderr.
Defaults to @samp{"syslog"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string info-log-path
Log file to use for informational messages.  Defaults to
@samp{log-path}.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
Log file to use for debug messages.  Defaults to
@samp{info-log-path}.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
Syslog facility to use if you're logging to syslog.  Usually if you
don't want to use @samp{mail}, you'll use local0..local7.  Also other
standard facilities are supported.
Defaults to @samp{"mail"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
Log unsuccessful authentication attempts and the reasons why they
failed.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords?
In case of password mismatches, log the attempted password.  Valid
values are no, plain and sha1.  sha1 can be useful for detecting brute
force password attempts vs.  user simply trying the same password over
and over again.  You can also truncate the value to n chars by appending
":n" (e.g. sha1:6).
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
Even more verbose logging for debugging purposes.  Shows for example
SQL queries.
Defaults to @samp{#f}.