@@ -25658,9 +25658,11 @@ 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.
+for email services: @acronym{IMAP, Internet Message Access Protocol},
+@acronym{POP3, Post Office Protocol version 3}, and @acronym{LMTP,
+Local Mail Transfer Protocol} servers, as well as @acronym{MTA,
+transport agent}s. Lots of acronyms! These services are detailed in
+the subsections below.
@subsubheading Dovecot Service
@@ -25678,8 +25680,11 @@ Mail Services
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:
+For example, to specify that the mail location is a
+maildir@footnote{A mailbox format, see
+@url{https://manpages.debian.org/stretch/qmail/maildir.5.en.html}.}
+located at @file{~/.mail}, one would instantiate the Dovecot service
+like this:
@lisp
(service dovecot-service-type
@@ -25687,10 +25692,8 @@ Mail Services
(mail-location "maildir:~/.mail")))
@end lisp
-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,
+The available configuration parameters follow.
+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.
@@ -25702,688 +25705,378 @@ Mail Services
@c (generate-documentation) than to make it below and have to deal with
@c the churn as dovecot updates.
+@c %start of fragment
+@deftp {Data Type} dovecot-configuration
Available @code{dovecot-configuration} fields are:
-@deftypevr {@code{dovecot-configuration} parameter} package dovecot
+@table @asis
+@item @code{dovecot} (default: @code{dovecot}) (type: file-like)
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
+@item @code{listen} (default: @code{("*" "::")}) (type: list-of-strings)
+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 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} boolean imap-metadata?
-Whether to enable the @code{IMAP METADATA} extension as defined in
-@uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides
-a means for clients to set and retrieve per-mailbox, per-user metadata
-and annotations over IMAP.
-
-If this is @samp{#t}, you must also specify a dictionary @i{via} the
-@code{mail-attribute-dict} setting.
-
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-notify-capabilities
-Which NOTIFY capabilities to report to clients that first connect to
-the ManageSieve service, before authentication. These may differ from the
-capabilities offered to authenticated users. If this field is left empty,
-report what the Sieve interpreter supports by default.
-
-Defaults to @samp{'()}.
-@end deftypevr
-
-@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-sieve-capability
-Which SIEVE capabilities to report to clients that first connect to
-the ManageSieve service, before authentication. These may differ from the
-capabilities offered to authenticated users. If this field is left empty,
-report what the Sieve interpreter supports by default.
-
-Defaults to @samp{'()}.
-
-@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{""}.
-@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 client-limit
-Maximum number of simultaneous client connections per process. Once
-this number of connections is received, the next incoming connection
-will prompt Dovecot to spawn another process. If set to 0,
-@code{default-client-limit} is used instead.
-
-Defaults to @samp{0}.
-
-@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-limit
-Maximum number of processes that can exist for this service. If set to
-0, @code{default-process-limit} is used instead.
-
-Defaults to @samp{0}.
-
-@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
+@code{inet-listener} of the specific services you are interested in.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
+@item @code{dict} (type: dict-configuration)
Dict configuration, as created by the @code{dict-configuration}
constructor.
+@deftp {Data Type} dict-configuration
Available @code{dict-configuration} fields are:
-@deftypevr {@code{dict-configuration} parameter} free-form-fields entries
+@table @asis
+@item @code{entries} (default: @code{'()}) (type: free-form-fields)
A list of key-value pairs that this dict should hold.
-Defaults to @samp{'()}.
-@end deftypevr
-
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
-A list of passdb configurations, each one created by the
+@item @code{passdbs} (type: list-of-passdb-configurations)
+List of passdb configurations, each one created by the
@code{passdb-configuration} constructor.
+@deftp {Data Type} passdb-configuration
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
+@table @asis
+@item @code{driver} (default: @code{"pam"}) (type: string)
+The driver that the passdb should use. Valid values include @samp{pam},
+@samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}.
-@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
+@item @code{args} (type: maybe-list-of-strings)
Space separated list of arguments to the passdb driver.
-Defaults to @samp{""}.
-@end deftypevr
-
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
+@item @code{userdbs} (type: list-of-userdb-configurations)
List of userdb configurations, each one created by the
@code{userdb-configuration} constructor.
+@deftp {Data Type} userdb-configuration
Available @code{userdb-configuration} fields are:
-@deftypevr {@code{userdb-configuration} parameter} string driver
+@table @asis
+@item @code{driver} (default: @code{"passwd"}) (type: string)
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} space-separated-string-list args
+@item @code{args} (type: maybe-list-of-strings)
Space separated list of arguments to the userdb driver.
-Defaults to @samp{""}.
-@end deftypevr
-@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
+@item @code{override-fields} (default: @code{'()}) (type: alist)
Override fields from passwd.
-Defaults to @samp{'()}.
-@end deftypevr
-
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
+@item @code{plugin-configuration} (type: plugin-configuration)
Plug-in configuration, created by the @code{plugin-configuration}
constructor.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
+@item @code{namespaces} (type: list-of-namespace-configurations)
List of namespaces. Each item in the list is created by the
@code{namespace-configuration} constructor.
+@deftp {Data Type} namespace-configuration
Available @code{namespace-configuration} fields are:
-@deftypevr {@code{namespace-configuration} parameter} string name
+@table @asis
+@item @code{name} (type: string)
Name for this namespace.
-@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} string type
+@item @code{type} (default: @code{"private"}) (type: string)
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
+@item @code{separator} (default: @code{""}) (type: string)
+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.
-@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
+@item @code{prefix} (default: @code{""}) (type: string)
+Prefix required to access this namespace. This needs to be different
+for all namespaces. For example @samp{Public/}.
-@deftypevr {@code{namespace-configuration} parameter} string location
-Physical location of the mailbox. This is in the same format as
-mail_location, which is also the default for it.
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{location} (default: @code{""}) (type: string)
+Physical location of the mailbox. This is in same format as
+@code{mail-location}, which is also the default for it.
-@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
+@item @code{inbox?} (default: @code{#f}) (type: boolean)
+There can be only one INBOX, and this setting defines which namespace
+has it.
-@deftypevr {@code{namespace-configuration} parameter} boolean hidden?
+@item @code{hidden?} (default: @code{#f}) (type: boolean)
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 the LIST command. This
-makes the namespace visible for clients that do not support the NAMESPACE
+extension. You'll most likely also want to set @code{list?} to
+@code{#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/}.
+
+@item @code{list?} (default: @code{#t}) (type: boolean)
+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?
+@item @code{subscriptions?} (default: @code{#t}) (type: boolean)
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
+as @code{#t}.
-@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
+@item @code{mailboxes} (default: @code{'()}) (type: list-of-mailbox-configurations)
List of predefined mailboxes in this namespace.
-Defaults to @samp{'()}.
+@deftp {Data Type} mailbox-configuration
Available @code{mailbox-configuration} fields are:
-@deftypevr {@code{mailbox-configuration} parameter} string name
+@table @asis
+@item @code{name} (type: string)
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
+@item @code{auto} (default: @code{"no"}) (type: string)
+@samp{create} will automatically create this mailbox. @samp{subscribe}
+will both create and subscribe to the mailbox.
-@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
+@item @code{special-use} (type: maybe-list-of-strings)
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 table
+@end deftp
-@end deftypevr
+@end table
+@end deftp
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
+@item @code{base-dir} (default: @code{"/var/run/dovecot/"}) (type: string)
Base directory where to store runtime data.
-Defaults to @samp{"/var/run/dovecot/"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string login-greeting
+@item @code{login-greeting} (default: @code{"Dovecot ready."}) (type: string)
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
+@item @code{login-trusted-networks} (type: maybe-list-of-strings)
+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 would specify your IMAP proxy servers
+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
+@item @code{login-access-sockets} (type: maybe-list-of-strings)
+List of login access check sockets (e.g. tcpwrap).
-@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 is actually using the IMAP
-processes (e.g.@: shared mailboxes or if the same uid is used for multiple
-accounts).
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{verbose-proctitle?} (default: @code{#f}) (type: boolean)
+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).
-@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
+@item @code{shutdown-clients?} (default: @code{#t}) (type: boolean)
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.@: due to a security fix).
-Defaults to @samp{#t}.
-@end deftypevr
+be a problem if the upgrade is e.g. because of a security fix).
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
+@item @code{doveadm-worker-count} (default: @code{0}) (type: non-negative-integer)
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
+@item @code{doveadm-socket-path} (default: @code{"doveadm-server"}) (type: string)
+UNIX socket path or @samp{@var{host}:@var{port}} used for connecting to
+doveadm server.
-@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
+@item @code{import-environment} (default: @code{'("TZ")}) (type: list-of-strings)
+List of environment variables that are preserved on Dovecot startup and
+passed down to all of its child processes. You can also give
+@samp{@var{key}=@var{value}} pairs to always set specific settings.
-@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
+@item @code{disable-plaintext-auth?} (default: @code{#t}) (type: boolean)
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),
+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
+@item @code{auth-cache-size} (default: @code{0}) (type: non-negative-integer)
+Authentication cache size (e.g. @samp{#e10e6}). @samp{0} means it's
+disabled. Note that bsdauth, PAM and vpopmail require @code{cache-key}
+to be set for caching to be used.
+
+@item @code{auth-cache-ttl} (default: @code{"1 hour"}) (type: string)
+Time to live for cached data. After TTL expires the cached record is no
+longer used, @strong{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
+@item @code{auth-cache-negative-ttl} (default: @code{"1 hour"}) (type: string)
+TTL for negative hits (user not found, password mismatch). @samp{0}
+disables caching them completely.
-@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
+@item @code{auth-realms} (type: maybe-list-of-strings)
+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.
-@deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
+@item @code{auth-default-realm} (default: @code{""}) (type: string)
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
+both SASL realms and appending @@domain to username in plaintext logins.
-@deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
+@item @code{auth-username-chars} (default: @code{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}) (type: string)
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
+@item @code{auth-username-translation} (default: @code{""}) (type: string)
+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{@@}.
-@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
+@item @code{auth-username-format} (default: @code{"%Lu"}) (type: string)
+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
+@code{auth-username-translation} changes.
-@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
+@item @code{auth-master-user-separator} (default: @code{""}) (type: string)
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
+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
+here. The format is then @samp{@var{username}@var{separator}@var{master
+username}}. UW-IMAP uses @samp{*} as the separator, so that could be a
+good choice.
-@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
+@item @code{auth-anonymous-username} (default: @code{"anonymous"}) (type: string)
+Username for users logging in with ANONYMOUS SASL mechanism.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
+@item @code{auth-worker-max-count} (default: @code{30}) (type: non-negative-integer)
Maximum number of dovecot-auth worker processes. They're used to
-execute blocking passdb and userdb queries (e.g.@: MySQL and PAM).
+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
+@item @code{auth-gssapi-hostname} (default: @code{""}) (type: string)
+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.
-@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
-Kerberos keytab to use for the GSSAPI mechanism. Will use the
-system default (usually @file{/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
+@item @code{auth-krb5-keytab} (default: @code{""}) (type: string)
+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.
-@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.
+@item @code{auth-use-winbind?} (default: @code{#f}) (type: boolean)
+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
+@item @code{auth-winbind-helper-path} (default: @code{"/usr/bin/ntlm_auth"}) (type: string)
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
+@item @code{auth-failure-delay} (default: @code{"2 secs"}) (type: string)
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
+@item @code{auth-ssl-require-client-cert?} (default: @code{#f}) (type: boolean)
+Require a valid SSL client certificate or the authentication fails.
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
+@item @code{auth-ssl-username-from-cert?} (default: @code{#f}) (type: boolean)
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
+@item @code{auth-mechanisms} (default: @code{("plain")}) (type: list-of-strings)
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
+@item @code{director-servers} (type: maybe-list-of-strings)
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
+director service's @code{inet-listener} is using.
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
+@item @code{director-mail-servers} (type: maybe-list-of-strings)
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
+allowed too, like @samp{10.0.0.10-10.0.0.30}.
-@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
+@item @code{director-user-expire} (default: @code{"15 min"}) (type: string)
+How long to redirect users to a specific server after it no longer has
+any connections.
-@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
+@item @code{director-username-hash} (default: @code{"%Lu"}) (type: string)
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
+include %Ln if user can log in with or without @@domain, %Ld if
+mailboxes are shared within domain.
-@deftypevr {@code{dovecot-configuration} parameter} string log-path
+@item @code{log-path} (default: @code{"syslog"}) (type: string)
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
+@item @code{info-log-path} (default: @code{""}) (type: string)
Log file to use for informational messages. Defaults to
-@samp{log-path}.
-Defaults to @samp{""}.
-@end deftypevr
+@code{log-path}.
-@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
+@item @code{debug-log-path} (default: @code{""}) (type: string)
+Log file to use for debug messages. Defaults to @code{info-log-path}.
-@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
+@item @code{syslog-facility} (default: @code{"mail"}) (type: string)
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
+don't want to use @samp{mail}, you'll use @samp{local0}..@samp{local7}.
+Also other standard facilities are supported.
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
+@item @code{auth-verbose?} (default: @code{#f}) (type: boolean)
Log unsuccessful authentication attempts and the reasons why they
failed.
-Defaults to @samp{#f}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
+@item @code{auth-verbose-passwords} (default: @code{"no"}) (type: string)
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{"no"}.
-@end deftypevr
+values are @samp{no}, @samp{plain} and @samp{sha1}. @samp{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 @var{n} characters by appending @samp{:@var{n}} (e.g.
+@samp{sha1:6}).
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
-Even more verbose logging for debugging purposes. Shows for example
-SQL queries.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{auth-debug?} (default: @code{#f}) (type: boolean)
+Even more verbose logging for debugging purposes. Shows for example SQL
+queries.
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
-In case of password mismatches, log the passwords and used scheme so
-the problem can be debugged. Enabling this also enables
-@samp{auth-debug}.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{auth-debug-passwords?} (default: @code{#f}) (type: boolean)
+In case of password mismatches, log the passwords and used scheme so the
+problem can be debugged. Enabling this also enables @code{auth-debug}.
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
-Enable mail process debugging. This can help you figure out why
-Dovecot isn't finding your mails.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{mail-debug?} (default: @code{#f}) (type: boolean)
+Enable mail process debugging. This can help you figure out why Dovecot
+isn't finding your mails.
-@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
+@item @code{verbose-ssl?} (default: @code{#f}) (type: boolean)
Show protocol level SSL errors.
-Defaults to @samp{#f}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
-Prefix for each line written to log file. % codes are in
-strftime(3) format.
-Defaults to @samp{"\"%b %d %H:%M:%S \""}.
-@end deftypevr
+@item @code{log-timestamp} (default: @code{"%b %d %H:%M:%S "}) (type: string)
+Prefix for each line written to log file. % codes are in strftime(3)
+format.
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
-List of elements we want to log. The elements which have a
-non-empty variable value are joined together to form a comma-separated
-string.
-@end deftypevr
+@item @code{login-log-format-elements} (default: @code{("user=<%u>" "method=%m" "rip=%r" "lip=%l" "mpid=%e" "%c")}) (type: list-of-strings)
+List of elements we want to log. The elements which have a non-empty
+variable value are joined together to form a comma-separated string.
-@deftypevr {@code{dovecot-configuration} parameter} string login-log-format
-Login log format. %s contains @samp{login-log-format-elements}
-string, %$ contains the data we want to log.
-Defaults to @samp{"%$: %s"}.
-@end deftypevr
+@item @code{login-log-format} (default: @code{"%$: %s"}) (type: string)
+Login log format. @samp{%s} contains @code{login-log-format-elements}
+string, @samp{%$} contains the data we want to log.
-@deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
-Log prefix for mail processes. See doc/wiki/Variables.txt for list
-of possible variables you can use.
-Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
-@end deftypevr
+@item @code{mail-log-prefix} (default: @code{"%s(%u)<%@{pid@}><%@{session@}>: "}) (type: string)
+Log prefix for mail processes. See doc/wiki/Variables.txt for list of
+possible variables you can use.
-@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
+@item @code{deliver-log-format} (default: @code{"msgid=%m: %$"}) (type: string)
Format to use for logging mail deliveries. You can use variables:
@table @code
@item %$
-Delivery status message (e.g.@: @samp{saved to INBOX})
+Delivery status message (e.g. @samp{saved to INBOX})
@item %m
Message-ID
@item %s
@@ -26395,28 +26088,25 @@ Mail Services
@item %w
Virtual size.
@end table
-Defaults to @samp{"msgid=%m: %$"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-location
-Location for users' mailboxes. The default is empty, which means
-that Dovecot tries to find the mailboxes automatically. This won't work
-if the user doesn't yet have any mail, so you should explicitly tell
+@item @code{mail-location} (default: @code{""}) (type: string)
+Location for users' mailboxes. The default is empty, which means that
+Dovecot tries to find the mailboxes automatically. This won't work if
+the user doesn't yet have any mail, so you should explicitly tell
Dovecot the full location.
-If you're using mbox, giving a path to the INBOX
-file (e.g.@: @file{/var/mail/%u}) isn't enough. You'll also need to tell Dovecot
-where the other mailboxes are kept. This is called the @emph{root mail
-directory}, and it must be the first path given in the
-@samp{mail-location} setting.
-
-There are a few special variables you can use, e.g.:
+If you're using mbox, giving a path to the
+INBOX file (e.g. /var/mail/%u) isn't enough. You'll also need to tell
+Dovecot where the other mailboxes are kept. This is called the ``root
+mail directory'', and it must be the first path given in the
+@code{mail-location} setting.
+There are a few special variables you can use, eg.:
@table @samp
@item %u
username
@item %n
-user part in user@@domain, same as %u if there's no domain
+user part in user@@domain, same as @samp{%u} if there's no domain
@item %d
domain part in user@@domain, empty if there's no domain
@item %h
@@ -26429,240 +26119,174 @@ Mail Services
@item mbox:~/mail:INBOX=/var/mail/%u
@item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
@end table
-Defaults to @samp{""}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-uid
-System user and group used to access mails. If you use multiple,
-userdb can override these by returning uid or gid fields. You can use
-either numbers or names. <doc/wiki/UserIds.txt>.
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{mail-uid} (default: @code{""}) (type: string)
+System user and group used to access mails. If you use multiple, userdb
+can override these by returning uid or gid fields. You can use either
+numbers or names. <doc/wiki/UserIds.txt>.
-@deftypevr {@code{dovecot-configuration} parameter} string mail-gid
+@item @code{mail-gid} (default: @code{""}) (type: string)
-Defaults to @samp{""}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
-Group to enable temporarily for privileged operations. Currently
-this is used only with INBOX when either its initial creation or
-dotlocking fails. Typically this is set to @samp{"mail"} to give access to
+@item @code{mail-privileged-group} (default: @code{""}) (type: string)
+Group to enable temporarily for privileged operations. Currently this
+is used only with INBOX when either its initial creation or dotlocking
+fails. Typically this is set to @samp{"mail"} to give access to
@file{/var/mail}.
-Defaults to @samp{""}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
-Grant access to these supplementary groups for mail processes.
-Typically these are used to set up access to shared mailboxes. Note
-that it may be dangerous to set these if users can create symlinks
-(e.g.@: if @samp{mail} group is set here, @code{ln -s /var/mail ~/mail/var}
-could allow a user to delete others' mailboxes, or @code{ln -s
-/secret/shared/box ~/mail/mybox} would allow reading it). Defaults to
-@samp{""}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} string mail-attribute-dict
-The location of a dictionary used to store @code{IMAP METADATA}
-as defined by @uref{https://tools.ietf.org/html/rfc5464, RFC@tie{}5464}.
-The IMAP METADATA commands are available only if the ``imap''
-protocol configuration's @code{imap-metadata?} field is @samp{#t}.
+@item @code{mail-access-groups} (default: @code{""}) (type: string)
+Grant access to these supplementary groups for mail processes. Typically
+these are used to set up access to shared mailboxes. Note that it may
+be dangerous to set these if users can create symlinks (e.g. if
+@samp{"mail"} group is set here, @samp{ln -s /var/mail ~/mail/var} could
+allow a user to delete others' mailboxes, or @samp{ln -s
+/secret/shared/box ~/mail/mybox} would allow reading it).
-Defaults to @samp{""}.
-
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
+@item @code{mail-full-filesystem-access?} (default: @code{#f}) (type: boolean)
Allow full file system access to clients. There's no access checks
-other than what the operating system does for the active UID/GID@. It
+other than what the operating system does for the active UID/GID. It
works with both maildir and mboxes, allowing you to prefix mailboxes
-names with e.g.@: @file{/path/} or @file{~user/}.
-Defaults to @samp{#f}.
-@end deftypevr
+names with e.g. @samp{/path/} or @samp{~user/}.
-@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
-Don't use @code{mmap()} at all. This is required if you store indexes to
-shared file systems (NFS or clustered file system).
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{mmap-disable?} (default: @code{#f}) (type: boolean)
+Don't use @code{mmap()} at all. This is required if you store indexes
+to shared file systems (NFS or clustered file system).
-@deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
-Rely on @samp{O_EXCL} to work when creating dotlock files. NFS
-supports @samp{O_EXCL} since version 3, so this should be safe to use
-nowadays by default.
-Defaults to @samp{#t}.
-@end deftypevr
+@item @code{dotlock-use-excl?} (default: @code{#t}) (type: boolean)
+Rely on @code{O_EXCL} to work when creating dotlock files. NFS supports
+@code{O_EXCL} since version 3, so this should be safe to use nowadays by
+default.
-@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
-When to use fsync() or fdatasync() calls:
+@item @code{mail-fsync} (default: @code{"optimized"}) (type: string)
+When to use @code{fsync()} or @code{fdatasync()} calls:
@table @code
@item optimized
Whenever necessary to avoid losing important data
@item always
-Useful with e.g.@: NFS when @code{write()}s are delayed
+Useful with e.g. NFS when @code{write()}s are delayed
@item never
Never use it (best performance, but crashes can lose data).
@end table
-Defaults to @samp{"optimized"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
-Mail storage exists in NFS@. Set this to yes to make Dovecot flush
-NFS caches whenever needed. If you're using only a single mail server
-this isn't needed.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{mail-nfs-storage?} (default: @code{#f}) (type: boolean)
+Mail storage exists in NFS. Set this to yes to make Dovecot flush NFS
+caches whenever needed. If you're using only a single mail server this
+isn't needed.
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
-Mail index files also exist in NFS@. Setting this to yes requires
+@item @code{mail-nfs-index?} (default: @code{#f}) (type: boolean)
+Mail index files also exist in NFS. Setting this to yes requires
@samp{mmap-disable? #t} and @samp{fsync-disable? #f}.
-Defaults to @samp{#f}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string lock-method
+@item @code{lock-method} (default: @code{"fcntl"}) (type: string)
Locking method for index files. Alternatives are fcntl, flock and
dotlock. Dotlocking uses some tricks which may create more disk I/O
than other locking methods. NFS users: flock doesn't work, remember to
-change @samp{mmap-disable}.
-Defaults to @samp{"fcntl"}.
-@end deftypevr
+change @code{mmap-disable}.
-@deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
-Directory in which LDA/LMTP temporarily stores incoming mails >128
-kB.
-Defaults to @samp{"/tmp"}.
-@end deftypevr
+@item @code{mail-temp-dir} (default: @code{"/tmp"}) (type: string)
+Directory in which LDA/LMTP temporarily stores incoming mails >128 kB.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
+@item @code{first-valid-uid} (default: @code{500}) (type: non-negative-integer)
Valid UID range for users. This is mostly to make sure that users can't
-log in as daemons or other system users. Note that denying root logins is
-hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
-is set to 0.
-Defaults to @samp{500}.
-@end deftypevr
+log in as daemons or other system users. Note that denying root logins
+is hardcoded to dovecot binary and can't be done even if
+@code{first-valid-uid} is set to @samp{0}.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid
+@item @code{last-valid-uid} (default: @code{0}) (type: non-negative-integer)
-Defaults to @samp{0}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
-Valid GID range for users. Users having non-valid GID as primary group ID
-aren't allowed to log in. If user belongs to supplementary groups with
-non-valid GIDs, those groups are not set.
-Defaults to @samp{1}.
-@end deftypevr
+@item @code{first-valid-gid} (default: @code{1}) (type: non-negative-integer)
+Valid GID range for users. Users having non-valid GID as primary group
+ID aren't allowed to log in. If user belongs to supplementary groups
+with non-valid GIDs, those groups are not set.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid
+@item @code{last-valid-gid} (default: @code{0}) (type: non-negative-integer)
-Defaults to @samp{0}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
+@item @code{mail-max-keyword-length} (default: @code{50}) (type: non-negative-integer)
Maximum allowed length for mail keyword name. It's only forced when
trying to create new keywords.
-Defaults to @samp{50}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
-List of directories under which chrooting is allowed for mail
-processes (i.e.@: @file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}
-too). This setting doesn't affect @samp{login-chroot}
-@samp{mail-chroot} or auth chroot settings. If this setting is empty,
-@samp{/./} in home dirs are ignored. WARNING: Never add directories here
-which local users can modify, that may lead to root exploit. Usually
-this should be done only if you don't allow shell access for users.
-<doc/wiki/Chrooting.txt>.
-Defaults to @samp{'()}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
-Default chroot directory for mail processes. This can be overridden
-for specific users in user database by giving @samp{/./} in user's home
-directory (e.g.@: @samp{/home/./user} chroots into @file{/home}). Note that usually
-there is no real need to do chrooting, Dovecot doesn't allow users to
-access files outside their mail directory anyway. If your home
-directories are prefixed with the chroot directory, append @samp{/.} to
-@samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
-Defaults to @samp{""}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} file-name 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
+@item @code{valid-chroot-dirs} (default: @code{()}) (type: list-of-strings)
+List of directories under which chrooting is allowed for
+@emph{mail processes}. The values are interpreted recursively (e.g.,
+@file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}).
+This setting doesn't affect @emph{login processes} or
+@emph{authentication processes} but it does affect @code{mail-chroot}
+since it applies to the @emph{mail processes}.
+@quotation Warning
+Never add directories here which local users can modify, that may lead to
+root exploit. Usually this should be done only if you don't allow shell
+access for users.
+See @url{https://doc.dovecot.org/admin_manual/chrooting/,
+Chrooting@comma{} Dovecot documentation} for more information.
+@end quotation
-@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
+@item @code{mail-chroot} (default: @code{""}) (type: string)
+Default chroot directory for mail processes. This can be overridden for
+specific users in user database by giving @samp{/./} in user's home
+directory (e.g. @file{/home/./user} chroots into @file{/home}). Note
+that usually there is no real need to do chrooting, Dovecot doesn't
+allow users to access files outside their mail directory anyway. If
+your home directories are prefixed with the chroot directory, append
+@samp{/.} to @code{mail-chroot}. See
+@url{https://doc.dovecot.org/admin_manual/chrooting/,
+Chrooting@comma{}Dovecot documentation} for more information.
+
+@item @code{auth-socket-path} (default: @code{"/var/run/dovecot/auth-userdb"}) (type: string)
+UNIX socket path to master authentication server to find users. This is
+used by imap (for shared users) and lda.
+
+@item @code{mail-plugin-dir} (default: @code{"/usr/lib/dovecot"}) (type: string)
Directory where to look up mail plugins.
-Defaults to @samp{"/usr/lib/dovecot"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
+@item @code{mail-plugins} (type: maybe-list-of-strings)
List of plugins to load for all services. Plugins specific to IMAP,
-LDA, etc.@: are added to this list in their own .conf files.
-Defaults to @samp{'()}.
-@end deftypevr
+LDA, etc. are added to this list in their own @file{.conf} files.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
+@item @code{mail-cache-min-mail-count} (default: @code{0}) (type: non-negative-integer)
The minimum number of mails in a mailbox before updates are done to
cache file. This allows optimizing Dovecot's behavior to do less disk
writes at the cost of more disk reads.
-Defaults to @samp{0}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
-When IDLE command is running, mailbox is checked once in a while to
-see if there are any new mails or other changes. This setting defines
-the minimum time to wait between those checks. Dovecot can also use
-dnotify, inotify and kqueue to find out immediately when changes
-occur.
-Defaults to @samp{"30 secs"}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
-Save mails with CR+LF instead of plain LF@. This makes sending those
-mails take less CPU, especially with sendfile() syscall with Linux and
-FreeBSD@. But it also creates a bit more disk I/O which may just make it
-slower. Also note that if other software reads the mboxes/maildirs,
-they may handle the extra CRs wrong and cause problems.
-Defaults to @samp{#f}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
-By default LIST command returns all entries in maildir beginning
-with a dot. Enabling this option makes Dovecot return only entries
-which are directories. This is done by stat()ing each entry, so it
-causes more disk I/O.
- (For systems setting struct @samp{dirent->d_type} this check is free
-and it's done always regardless of this setting).
-Defaults to @samp{#f}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
-When copying a message, do it with hard links whenever possible.
-This makes the performance much better, and it's unlikely to have any
-side effects.
-Defaults to @samp{#t}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
-Assume Dovecot is the only MUA accessing Maildir: Scan cur/
-directory only when its mtime changes unexpectedly or when we can't find
-the mail otherwise.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{mailbox-idle-check-interval} (default: @code{"30 secs"}) (type: string)
+When IDLE command is running, mailbox is checked once in a while to see
+if there are any new mails or other changes. This setting defines the
+minimum time to wait between those checks. Dovecot can also use
+dnotify, inotify and kqueue to find out immediately when changes occur.
+
+@item @code{mail-save-crlf?} (default: @code{#f}) (type: boolean)
+Save mails with CR+LF instead of plain LF. This makes sending those
+mails take less CPU, especially with @code{sendfile()} syscall with
+Linux and FreeBSD. But it also creates a bit more disk I/O which may
+just make it slower. Also note that if other software reads the
+mboxes/maildirs, they may handle the extra CRs wrong and cause problems.
+
+@item @code{maildir-stat-dirs?} (default: @code{#f}) (type: boolean)
+By default LIST command returns all entries in maildir beginning with a
+dot. Enabling this option makes Dovecot return only entries which are
+directories. This is done by @code{stat()}ing each entry, so it causes
+more disk I/O. (For systems setting struct @code{dirent->d_type} this
+check is free and it's done always regardless of this setting).
+
+@item @code{maildir-copy-with-hardlinks?} (default: @code{#t}) (type: boolean)
+When copying a message, do it with hard links whenever possible. This
+makes the performance much better, and it's unlikely to have any side
+effects.
+
+@item @code{maildir-very-dirty-syncs?} (default: @code{#f}) (type: boolean)
+Assume Dovecot is the only MUA accessing Maildir: Scan cur/ directory
+only when its mtime changes unexpectedly or when we can't find the mail
+otherwise.
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
+@item @code{mbox-read-locks} (default: @code{("fcntl")}) (type: list-of-strings)
Which locking methods to use for locking mbox. There are four
available:
-
@table @code
@item dotlock
-Create <mailbox>.lock file. This is the oldest and most NFS-safe
-solution. If you want to use /var/mail/ like directory, the users will
-need write access to that directory.
+Create @file{@var{mailbox}.lock} file. This is the oldest and most
+NFS-safe solution. If you want to use @file{/var/mail/}-like directory,
+the users will need write access to that directory.
@item dotlock-try
Same as dotlock, but if it fails because of permissions or because there
isn't enough disk space, just skip it.
@@ -26673,101 +26297,81 @@ Mail Services
@item lockf
May not exist in all systems. Doesn't work with NFS.
@end table
+You can use multiple locking methods; if you do the order
+they're declared in is important to avoid deadlocks if other MTAs/MUAs
+are using multiple locking methods as well. Some operating systems
+don't allow using some of them simultaneously.
-You can use multiple locking methods; if you do the order they're declared
-in is important to avoid deadlocks if other MTAs/MUAs are using multiple
-locking methods as well. Some operating systems don't allow using some of
-them simultaneously.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks
+@item @code{mbox-write-locks} (default: @code{("dotlock" "fcntl")}) (type: list-of-strings)
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
+@item @code{mbox-lock-timeout} (default: @code{"5 mins"}) (type: string)
Maximum time to wait for lock (all of them) before aborting.
-Defaults to @samp{"5 mins"}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
-If dotlock exists but the mailbox isn't modified in any way,
-override the lock file after this much time.
-Defaults to @samp{"2 mins"}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
-When mbox changes unexpectedly we have to fully read it to find out
-what changed. If the mbox is large this can take a long time. Since
-the change is usually just a newly appended mail, it'd be faster to
-simply read the new mails. If this setting is enabled, Dovecot does
-this but still safely fallbacks to re-reading the whole mbox file
-whenever something in mbox isn't how it's expected to be. The only real
-downside to this setting is that if some other MUA changes message
-flags, Dovecot doesn't notice it immediately. Note that a full sync is
-done with SELECT, EXAMINE, EXPUNGE and CHECK commands.
-Defaults to @samp{#t}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
-Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
+@item @code{mbox-dotlock-change-timeout} (default: @code{"2 mins"}) (type: string)
+If dotlock exists but the mailbox isn't modified in any way, override
+the lock file after this much time.
+
+@item @code{mbox-dirty-syncs?} (default: @code{#t}) (type: boolean)
+When mbox changes unexpectedly we have to fully read it to find out what
+changed. If the mbox is large this can take a long time. Since the
+change is usually just a newly appended mail, it'd be faster to simply
+read the new mails. If this setting is enabled, Dovecot does this but
+still safely fallbacks to re-reading the whole mbox file whenever
+something in mbox isn't how it's expected to be. The only real downside
+to this setting is that if some other MUA changes message flags, Dovecot
+doesn't notice it immediately. Note that a full sync is done with
+SELECT, EXAMINE, EXPUNGE and CHECK commands.
+
+@item @code{mbox-very-dirty-syncs?} (default: @code{#f}) (type: boolean)
+Like @code{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
EXAMINE, EXPUNGE or CHECK commands. If this is set,
-@samp{mbox-dirty-syncs} is ignored.
-Defaults to @samp{#f}.
-@end deftypevr
+@code{mbox-dirty-syncs} is ignored.
-@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
-Delay writing mbox headers until doing a full write sync (EXPUNGE
-and CHECK commands and when closing the mailbox). This is especially
-useful for POP3 where clients often delete all mails. The downside is
-that our changes aren't immediately visible to other MUAs.
-Defaults to @samp{#t}.
-@end deftypevr
+@item @code{mbox-lazy-writes?} (default: @code{#t}) (type: boolean)
+Delay writing mbox headers until doing a full write sync (EXPUNGE and
+CHECK commands and when closing the mailbox). This is especially useful
+for POP3 where clients often delete all mails. The downside is that our
+changes aren't immediately visible to other MUAs.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
-If mbox size is smaller than this (e.g.@: 100k), don't write index
-files. If an index file already exists it's still read, just not
-updated.
-Defaults to @samp{0}.
-@end deftypevr
+@item @code{mbox-min-index-size} (default: @code{0}) (type: non-negative-integer)
+If mbox size is smaller than this (e.g. 100k), don't write index files.
+If an index file already exists it's still read, just not updated.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
+@item @code{mdbox-rotate-size} (default: @code{10000000}) (type: non-negative-integer)
Maximum dbox file size until it's rotated.
-Defaults to @samp{10000000}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
+@item @code{mdbox-rotate-interval} (default: @code{"1d"}) (type: string)
Maximum dbox file age until it's rotated. Typically in days. Day
begins from midnight, so 1d = today, 2d = yesterday, etc. 0 = check
disabled.
-Defaults to @samp{"1d"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
+@item @code{mdbox-preallocate-space?} (default: @code{#f}) (type: boolean)
When creating new mdbox files, immediately preallocate their size to
@samp{mdbox-rotate-size}. This setting currently works only in Linux
with some file systems (ext4, xfs).
-Defaults to @samp{#f}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
-sdbox and mdbox support saving mail attachments to external files,
-which also allows single instance storage for them. Other backends
-don't support this for now.
-
-WARNING: This feature hasn't been tested much yet. Use at your own risk.
+@item @code{mail-attribute-dict} (default: @code{""}) (type: string)
+The location of a dictionary used to store @code{IMAP METADATA} as
+defined by @uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}. The
+IMAP METADATA commands are available only if the ``imap'' protocol
+configuration's @code{imap-metadata?} field is @samp{#t}.
+@item @code{mail-attachment-dir} (default: @code{""}) (type: string)
Directory root where to store mail attachments. Disabled, if empty.
-Defaults to @samp{""}.
-@end deftypevr
+sdbox and mdbox support saving mail attachments to external files, which
+also allows single instance storage for them. Other backends don't
+support this for now.
+@quotation Warning
+This feature hasn't been tested much yet. Use at your own risk.
+@end quotation
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
+@item @code{mail-attachment-min-size} (default: @code{128000}) (type: non-negative-integer)
Attachments smaller than this aren't saved externally. It's also
possible to write a plugin to disable saving specific attachments
externally.
-Defaults to @samp{128000}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
+@item @code{mail-attachment-fs} (default: @code{"sis posix"}) (type: string)
File system backend to use for saving attachments:
@table @code
@item posix
@@ -26777,153 +26381,101 @@ Mail Services
@item sis-queue posix
SiS with delayed comparison and deduplication.
@end table
-Defaults to @samp{"sis posix"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
+@item @code{mail-attachment-hash} (default: @code{"%@{sha1@}"}) (type: string)
Hash format to use in attachment filenames. You can add any text and
variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
-@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be
-truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
-Defaults to @samp{"%@{sha1@}"}.
-@end deftypevr
+@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can
+be truncated, e.g. @code{%@{sha256:80@}} returns only first 80 bits.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit
+@item @code{default-process-limit} (default: @code{100}) (type: non-negative-integer)
-Defaults to @samp{100}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit
+@item @code{default-client-limit} (default: @code{1000}) (type: non-negative-integer)
-Defaults to @samp{1000}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
-Default VSZ (virtual memory size) limit for service processes.
-This is mainly intended to catch and kill processes that leak memory
-before they eat up everything.
-Defaults to @samp{256000000}.
-@end deftypevr
+@item @code{default-vsz-limit} (default: @code{256000000}) (type: non-negative-integer)
+Default VSZ (virtual memory size) limit for service processes. This is
+mainly intended to catch and kill processes that leak memory before they
+eat up everything.
-@deftypevr {@code{dovecot-configuration} parameter} string default-login-user
+@item @code{default-login-user} (default: @code{"dovenull"}) (type: string)
Login user is internally used by login processes. This is the most
untrusted user in Dovecot system. It shouldn't have access to anything
at all.
-Defaults to @samp{"dovenull"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
-Internal user is used by unprivileged processes. It should be
-separate from login user, so that login processes can't disturb other
-processes.
-Defaults to @samp{"dovecot"}.
-@end deftypevr
+@item @code{default-internal-user} (default: @code{"dovecot"}) (type: string)
+Internal user is used by unprivileged processes. It should be separate
+from login user, so that login processes can't disturb other processes.
-@deftypevr {@code{dovecot-configuration} parameter} string ssl?
+@item @code{ssl?} (default: @code{"required"}) (type: string)
SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>.
-Defaults to @samp{"required"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
+@item @code{ssl-cert} (default: @code{"</etc/dovecot/default.pem"}) (type: string)
PEM encoded X.509 SSL/TLS certificate (public key).
-Defaults to @samp{"</etc/dovecot/default.pem"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-key
-PEM encoded SSL/TLS private key. The key is opened before
-dropping root privileges, so keep the key file unreadable by anyone but
-root.
-Defaults to @samp{"</etc/dovecot/private/default.pem"}.
-@end deftypevr
+@item @code{ssl-key} (default: @code{"</etc/dovecot/private/default.pem"}) (type: string)
+PEM encoded SSL/TLS private key. The key is opened before dropping root
+privileges, so keep the key file unreadable by anyone but root.
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
-If key file is password protected, give the password here.
-Alternatively give it when starting dovecot with -p parameter. Since
-this file is often world-readable, you may want to place this setting
-instead to a different.
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{ssl-key-password} (default: @code{""}) (type: string)
+If key file is password protected, give the password here. Alternatively
+give it when starting dovecot with -p parameter. Since this file is
+often world-readable, you may want to place this setting instead to a
+different.
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
-PEM encoded trusted certificate authority. Set this only if you
-intend to use @samp{ssl-verify-client-cert? #t}. The file should
-contain the CA certificate(s) followed by the matching
-CRL(s). (e.g.@: @samp{ssl-ca </etc/ssl/certs/ca.pem}).
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{ssl-ca} (default: @code{""}) (type: string)
+PEM encoded trusted certificate authority. Set this only if you intend
+to use @samp{ssl-verify-client-cert? #t}. The file should contain the
+CA certificate(s) followed by the matching CRL(s). (e.g. @samp{ssl-ca
+</etc/ssl/certs/ca.pem}).
-@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
+@item @code{ssl-require-crl?} (default: @code{#t}) (type: boolean)
Require that CRL check succeeds for client certificates.
-Defaults to @samp{#t}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
-Request client to send a certificate. If you also want to require
-it, set @samp{auth-ssl-require-client-cert? #t} in auth section.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{ssl-verify-client-cert?} (default: @code{#f}) (type: boolean)
+Request client to send a certificate. If you also want to require it,
+set @samp{auth-ssl-require-client-cert? #t} in auth section.
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
+@item @code{ssl-cert-username-field} (default: @code{"commonName"}) (type: string)
Which field from certificate to use for username. commonName and
x500UniqueIdentifier are the usual choices. You'll also need to set
@samp{auth-ssl-username-from-cert? #t}.
-Defaults to @samp{"commonName"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
+@item @code{ssl-min-protocol} (default: @code{"TLSv1"}) (type: string)
Minimum SSL protocol version to accept.
-Defaults to @samp{"TLSv1"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
+@item @code{ssl-cipher-list} (default: @code{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}) (type: string)
SSL ciphers to use.
-Defaults to @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
-SSL crypto device to use, for valid values run "openssl engine".
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{ssl-crypto-device} (default: @code{""}) (type: string)
+SSL crypto device to use, for valid values run @samp{openssl engine}.
-@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
-Address to use when sending rejection mails.
-%d expands to recipient domain.
-Defaults to @samp{"postmaster@@%d"}.
-@end deftypevr
+@item @code{postmaster-address} (default: @code{"postmaster@@%d"}) (type: string)
+Address to use when sending rejection mails. Default is
+postmaster@@<your domain>. %d expands to recipient domain.
-@deftypevr {@code{dovecot-configuration} parameter} string hostname
-Hostname to use in various parts of sent mails (e.g.@: in Message-Id)
-and in LMTP replies. Default is the system's real hostname@@domain.
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{hostname} (default: @code{""}) (type: string)
+Hostname to use in various parts of sent mails (e.g. in Message-Id) and
+in LMTP replies. Default is the system's real hostname@@domain.
-@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
-If user is over quota, return with temporary failure instead of
-bouncing the mail.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{quota-full-tempfail?} (default: @code{#f}) (type: boolean)
+If user is over quota, return with temporary failure instead of bouncing
+the mail.
-@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
+@item @code{sendmail-path} (default: @code{"/usr/sbin/sendmail"}) (type: string)
Binary to use for sending mails.
-Defaults to @samp{"/usr/sbin/sendmail"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string submission-host
-If non-empty, send mails via this SMTP host[:port] instead of
-sendmail.
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{submission-host} (default: @code{""}) (type: string)
+If non-empty, send mails via this SMTP host[:port] instead of sendmail.
-@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
+@item @code{rejection-subject} (default: @code{"Rejected: %s"}) (type: string)
Subject: header to use for rejection mails. You can use the same
variables as for @samp{rejection-reason} below.
-Defaults to @samp{"Rejected: %s"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
+@item @code{rejection-reason} (default: @code{"Your message to <%t> was automatically rejected:%n%r"}) (type: string)
Human readable error message for rejection mails. You can use
variables:
-
@table @code
@item %n
CRLF
@@ -26934,44 +26486,28 @@ Mail Services
@item %t
recipient
@end table
-Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
-Delimiter character between local-part and detail in email
-address.
-Defaults to @samp{"+"}.
-@end deftypevr
+@item @code{recipient-delimiter} (default: @code{"+"}) (type: string)
+Delimiter character between local-part and detail in email address.
-@deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
-Header where the original recipient address (SMTP's RCPT TO:
-address) is taken from if not available elsewhere. With dovecot-lda -a
-parameter overrides this. A commonly used header for this is
-X-Original-To.
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{lda-original-recipient-header} (default: @code{""}) (type: string)
+Header where the original recipient address (SMTP's RCPT TO: address) is
+taken from if not available elsewhere. With dovecot-lda -a parameter
+overrides this. A commonly used header for this is X-Original-To.
-@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
-Should saving a mail to a nonexistent mailbox automatically create
-it?.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{lda-mailbox-autocreate?} (default: @code{#f}) (type: boolean)
+Should saving a mail to a nonexistent mailbox automatically create it?
-@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
+@item @code{lda-mailbox-autosubscribe?} (default: @code{#f}) (type: boolean)
Should automatically created mailboxes be also automatically
-subscribed?.
-Defaults to @samp{#f}.
-@end deftypevr
+subscribed?
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
+@item @code{imap-max-line-length} (default: @code{64000}) (type: non-negative-integer)
Maximum IMAP command line length. Some clients generate very long
command lines with huge mailboxes, so you may need to raise this if you
-get "Too long argument" or "IMAP command line too large" errors
-often.
-Defaults to @samp{64000}.
-@end deftypevr
+get ``Too long argument'' or ``IMAP command line too large'' errors often.
-@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
+@item @code{imap-logout-format} (default: @code{"in=%i out=%o deleted=%@{deleted@} expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} body_bytes=%@{fetch_body_bytes@}"}) (type: string)
IMAP logout format string:
@table @code
@item %i
@@ -26979,65 +26515,197 @@ Mail Services
@item %o
total number of bytes sent to client.
@end table
-See @file{doc/wiki/Variables.txt} for a list of all the variables you can use.
-Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} body_bytes=%@{fetch_body_bytes@}"}.
-@end deftypevr
+See @file{doc/wiki/Variables.txt} for a list of all the variables
+you can use.
-@deftypevr {@code{dovecot-configuration} parameter} string imap-capability
+@item @code{imap-capability} (default: @code{""}) (type: string)
Override the IMAP CAPABILITY response. If the value begins with '+',
-add the given capabilities on top of the defaults (e.g.@: +XFOO XBAR).
-Defaults to @samp{""}.
-@end deftypevr
+add the given capabilities on top of the defaults (e.g. +XFOO XBAR).
-@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
-How long to wait between "OK Still here" notifications when client
-is IDLEing.
-Defaults to @samp{"2 mins"}.
-@end deftypevr
+@item @code{imap-idle-notify-interval} (default: @code{"2 mins"}) (type: string)
+How long to wait between "OK Still here" notifications when client is
+IDLEing.
-@deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
+@item @code{imap-id-send} (default: @code{""}) (type: string)
ID field names and values to send to clients. Using * as the value
makes Dovecot use the default value. The following fields have default
values currently: name, version, os, os-version, support-url,
support-email.
-Defaults to @samp{""}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
+@item @code{imap-id-log} (default: @code{""}) (type: string)
ID fields sent by client to log. * means everything.
-Defaults to @samp{""}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
+@item @code{imap-client-workarounds} (type: maybe-list-of-strings)
Workarounds for various client bugs:
-
@table @code
@item delay-newmail
Send EXISTS/RECENT new mail notifications only when replying to NOOP and
CHECK commands. Some clients ignore them otherwise, for example OSX
Mail (<v2.1). Outlook Express breaks more badly though, without this it
-may show user "Message no longer in server" errors. Note that OE6
-still breaks even with this workaround if synchronization is set to
-"Headers Only".
-
+may show user "Message no longer in server" errors. Note that OE6 still
+breaks even with this workaround if synchronization is set to "Headers
+Only".
@item tb-extra-mailbox-sep
Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and
-adds extra @samp{/} suffixes to mailbox names. This option causes Dovecot to
-ignore the extra @samp{/} instead of treating it as invalid mailbox name.
-
+adds extra @samp{/} suffixes to mailbox names.
+This option causes Dovecot to ignore the extra @samp{/}
+instead of treating it as invalid mailbox name.
@item tb-lsub-flags
-Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox).
-This makes Thunderbird realize they aren't selectable and show them
-greyed out, instead of only later giving "not selectable" popup error.
+Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g. mbox). This
+makes Thunderbird realize they aren't selectable and show them greyed
+out, instead of only later giving "not selectable" popup error.
@end table
-Defaults to @samp{'()}.
-@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
+@item @code{imap-urlauth-host} (default: @code{""}) (type: string)
Host allowed in URLAUTH URLs sent by client. "*" allows all.
-Defaults to @samp{""}.
-@end deftypevr
+@item @code{protocols} (type: list-of-protocol-configurations)
+List of protocols we want to serve. Available protocols include
+@samp{imap}, @samp{pop3}, and @samp{lmtp}.
+
+@deftp {Data Type} protocol-configuration
+Available @code{protocol-configuration} fields are:
+
+@table @asis
+@item @code{name} (type: string)
+The name of the protocol.
+
+@item @code{auth-socket-path} (default: @code{"/var/run/dovecot/auth-userdb"}) (type: string)
+UNIX socket path to master authentication server to find users. This is
+used by imap (for shared users) and lda.
+
+@item @code{mail-plugins} (default: @code{("$mail_plugins")}) (type: list-of-strings)
+Space separated list of plugins to load.
+
+@item @code{mail-max-userip-connections} (default: @code{10}) (type: non-negative-integer)
+Maximum number of IMAP connections allowed for a user from each IP
+address. NOTE: The username is compared case-sensitively.
+
+@item @code{imap-metadata?} (default: @code{#f}) (type: boolean)
+Whether to enable the @code{IMAP METADATA} extension as defined in
+@uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides
+a means for clients to set and retrieve per-mailbox, per-user metadata
+and annotations over IMAP. If this is @samp{#t}, you must also specify
+a dictionary @i{via} the @code{mail-attribute-dict} setting.
+
+@item @code{managesieve-notify-capability} (type: maybe-list-of-strings)
+Which NOTIFY capabilities to report to clients that first connect to the
+ManageSieve service, before authentication. These may differ from the
+capabilities offered to authenticated users. If this field is left
+empty, report what the Sieve interpreter supports by default.
+
+@item @code{managesieve-sieve-capability} (type: maybe-list-of-strings)
+Which SIEVE capabilities to report to clients that first connect to the
+ManageSieve service, before authentication. These may differ from the
+capabilities offered to authenticated users. If this field is left
+empty, report what the Sieve interpreter supports by default.
+@end table
+@end deftp
+
+@item @code{services} (type: list-of-service-configurations)
+List of services to enable. Available services include @samp{imap},
+@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
+@samp{lmtp}.
+
+@deftp {Data Type} service-configuration
+Available @code{service-configuration} fields are:
+
+@table @asis
+@item @code{kind} (type: string)
+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.
+
+@item @code{listeners} (default: @code{()}) (type: list-of-listener-configurations)
+Listeners for the service. A listener is either an
+@code{unix-listener-configuration}, a
+@code{fifo-listener-configuration}, or an
+@code{inet-listener-configuration}.
+
+@deftp {Data Type} unix-listener-configuration
+Available @code{unix-listener-configuration} fields are:
+
+@table @asis
+@item @code{path} (type: string)
+Path to the file, relative to @code{dovecot-configuration}'s
+@code{base-dir} field. This is also used as the section name.
+
+@item @code{mode} (default: @code{"0600"}) (type: string)
+The access mode for the socket.
+
+@item @code{user} (default: @code{""}) (type: string)
+The user to own the the socket.
+
+@item @code{group} (default: @code{""}) (type: string)
+The group to own the socket.
+@end table
+@end deftp
+
+@deftp {Data Type} fifo-listener-configuration
+Available @code{fifo-listener-configuration} fields are:
+
+@table @asis
+@item @code{path} (type: string)
+Path to the file, relative to @code{dovecot-configuration}'s
+@code{base-dir} field. This is also used as the section name.
+
+@item @code{mode} (default: @code{"0600"}) (type: string)
+The access mode for the socket.
+
+@item @code{user} (default: @code{""}) (type: string)
+The user to own the the socket.
+
+@item @code{group} (default: @code{""}) (type: string)
+The group to own the socket.
+@end table
+@end deftp
+
+@deftp {Data Type} inet-listener-configuration
+Available @code{inet-listener-configuration} fields are:
+
+@table @asis
+@item @code{protocol} (type: string)
+The protocol to listen for.
+
+@item @code{address} (default: @code{""}) (type: string)
+The address on which to listen, or empty for all addresses.
+
+@item @code{port} (type: non-negative-integer)
+The port on which to listen.
+
+@item @code{ssl?} (default: @code{#t}) (type: boolean)
+Whether to use SSL for this service; @samp{yes}, @samp{no}, or
+@samp{required}.
+@end table
+@end deftp
+
+@item @code{client-limit} (default: @code{0}) (type: non-negative-integer)
+Maximum number of simultaneous client connections per process. Once
+this number of connections is received, the next incoming connection
+will prompt Dovecot to spawn another process. If set to 0,
+@code{default-client-limit} is used instead.
+
+@item @code{service-count} (default: @code{1}) (type: non-negative-integer)
+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>.
+
+@item @code{process-limit} (default: @code{0}) (type: non-negative-integer)
+Maximum number of processes that can exist for this service. If set to
+0, @code{default-process-limit} is used instead.
+
+@item @code{process-min-avail} (default: @code{0}) (type: non-negative-integer)
+Number of processes to always keep waiting for more connections.
+
+@item @code{vsz-limit} (default: @code{256000000}) (type: non-negative-integer)
+If you set @samp{service-count 0}, you probably need to grow this.
+@end table
+@end deftp
+
+@end table
+@end deftp
+@c %end of fragment
Whew! Lots of configuration options. The nice thing about it though is
that Guix has a complete interface to Dovecot's configuration
@@ -27045,29 +26713,32 @@ Mail Services
but also offers reflective capabilities as well: users can write code to
inspect and transform configurations from within Scheme.
-However, it could be that you just want to get a @code{dovecot.conf} up
-and running. In that case, you can pass an
-@code{opaque-dovecot-configuration} as the @code{#:config} parameter to
-@code{dovecot-service}. As its name indicates, an opaque configuration
-does not have easy reflective capabilities.
+However, it could be that you just want to get a @file{dovecot.conf} up
+and running. In that case, you can use the
+@code{opaque-dovecot-configuration} constructor instead. As its name
+indicates, an opaque configuration does not have easy reflective
+capabilities.
+@c %start of fragment
+@deftp {Data Type} opaque-dovecot-configuration
Available @code{opaque-dovecot-configuration} fields are:
-@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
+@table @asis
+@item @code{dovecot} (default: @code{dovecot}) (type: file-like)
The dovecot package.
-@end deftypevr
-@deftypevr {@code{opaque-dovecot-configuration} parameter} string string
-The contents of the @code{dovecot.conf}, as a string.
-@end deftypevr
+@item @code{string} (type: string)
+The contents of the @code{dovecot.conf} to use.
+@end table
+@end deftp
+@c %end of fragment
-For example, if your @code{dovecot.conf} is just the empty string, you
+For example, if your @file{dovecot.conf} is just the empty string, you
could instantiate a dovecot service like this:
@lisp
-(dovecot-service #:config
- (opaque-dovecot-configuration
- (string "")))
+(service dovecot-service-type (opaque-dovecot-configuration
+ (string "")))
@end lisp
@subsubheading OpenSMTPD Service
@@ -44,6 +44,7 @@ (define-module (gnu services mail)
#:use-module (ice-9 match)
#:use-module (ice-9 format)
#:use-module (srfi srfi-1)
+ #:use-module (srfi srfi-71)
#:export (dovecot-service ; deprecated
dovecot-service-type
dovecot-configuration
@@ -85,96 +86,113 @@ (define-module (gnu services mail)
;;; Commentary:
;;;
-;;; This module provides service definitions for the Dovecot POP3 and IMAP
-;;; mail server.
+;;; This module provides service definitions for email related services.
;;;
-;;; Code:
+
+
+;;;
+;;; Dovecot
+;;;
+
+(define (non-negative-integer? val)
+ (and (exact-integer? val) (not (negative? val))))
+
+(define (escape-string value)
+ "Escape a string value according to Dovecot configuration file syntax
+rules. (see: <https://doc.dovecot.org/settings/types/#string>)"
+ (let ((value* (format #f "~s" value)))
+ ;; Surround VALUE with quotes only when it contains whitespace.
+ (if (string-any char-set:whitespace value)
+ value*
+ (substring/shared value* 1
+ (- (string-length value*) 1)))))
(define (uglify-field-name field-name)
(let ((str (symbol->string field-name)))
(string-join (string-split (if (string-suffix? "?" str)
- (substring str 0 (1- (string-length str)))
+ (string-drop-right str 1)
str)
- #\-)
- "_")))
-
-(define (serialize-field field-name val)
- (format #t "~a=~a\n" (uglify-field-name field-name) val))
-
-(define (serialize-string field-name val)
- (serialize-field field-name val))
-
-(define (space-separated-string-list? val)
- (and (list? val)
- (and-map (lambda (x)
- (and (string? x) (not (string-index x #\space))))
- val)))
-(define (serialize-space-separated-string-list field-name val)
- (match val
- (() #f)
- (_ (serialize-field field-name (string-join val " ")))))
-
-(define (comma-separated-string-list? val)
- (and (list? val)
- (and-map (lambda (x)
- (and (string? x) (not (string-index x #\,))))
- val)))
-(define (serialize-comma-separated-string-list field-name val)
- (serialize-field field-name (string-join val ",")))
-
-(define (file-name? val)
- (and (string? val)
- (string-prefix? "/" val)))
-(define (serialize-file-name field-name val)
- (serialize-string field-name val))
-
-(define (colon-separated-file-name-list? val)
- (and (list? val)
- ;; Trailing slashes not needed and not
- (and-map file-name? val)))
-(define (serialize-colon-separated-file-name-list field-name val)
- (serialize-field field-name (string-join val ":")))
-
-(define (serialize-boolean field-name val)
- (serialize-string field-name (if val "yes" "no")))
-
-(define (non-negative-integer? val)
- (and (exact-integer? val) (not (negative? val))))
-(define (serialize-non-negative-integer field-name val)
- (serialize-field field-name val))
-
-(define (hours? val) (non-negative-integer? val))
-(define (serialize-hours field-name val)
- (serialize-field field-name (format #f "~a hours" val)))
-
-(define (free-form-fields? val)
- (match val
- (() #t)
- ((((? symbol?) . (? string?)) . val) (free-form-fields? val))
- (_ #f)))
-(define (serialize-free-form-fields field-name val)
- (for-each (match-lambda ((k . v) (serialize-field k v))) val))
-
-(define (free-form-args? val)
- (match val
- (() #t)
- ((((? symbol?) . (? string?)) . val) (free-form-args? val))
- (_ #f)))
-(define (serialize-free-form-args field-name val)
- (serialize-field field-name
- (string-join
- (map (match-lambda ((k . v) (format #f "~a=~a" k v))) val)
- " ")))
+ #\-) "_")))
+
+(define (serialize-field field-name value)
+ #~(format #f "~a=~a~%" #$(uglify-field-name field-name) #$value))
+
+(define (serialize-string field-name value)
+ (serialize-field field-name (escape-string value)))
+
+(define serialize-non-negative-integer serialize-field)
+
+(define (serialize-boolean field-name value)
+ (serialize-string field-name (if value "yes" "no")))
+
+(define (make-serialize-list-with-delimiter delimiter)
+ (lambda (field-name value)
+ (serialize-field field-name
+ #~(string-join (list #$@value) #$delimiter))))
+
+(define serialize-list-of-strings
+ (make-serialize-list-with-delimiter " "))
+
+(define (serialize-alist field-name value)
+ (let ((datum
+ (generic-serialize-alist list
+ (lambda (key value)
+ #~(format #f "~a=~a" '#$key '#$value))
+ value)))
+ (serialize-list-of-strings field-name datum)))
+
+(define free-form-fields? alist?)
+(define (serialize-free-form-fields _ value)
+ #~(string-append #$@(generic-serialize-alist list serialize-field value)))
+
+(define-maybe list-of-strings)
+
+;; Note: The newline after '{' (Left Curly Bracket (U+007B)) is mandatory.
+;; See <https://doc.dovecot.org/configuration_manual/config_file/> for a
+;; description of the Dovecot config file syntax.
+(define* (make-serialize-section section-type fields #:optional section-name)
+ "Return a serializing procedure for a Dovecot config section with
+SECTION-TYPE followed by FIELDS in its body.
+If SECTION-NAME —a symbol denoting the name of a CONFIGURATION-FIELD— is
+provided then the value of that field is used as the section name and it is
+excluded from serialization within the body."
+ (letrec
+ ((proc
+ (case-lambda
+ ;; The procedure can be directly used by serialize-configuration
+ ;; or for mapping over a list of record-types representing sections.
+ ((_ value) (proc value))
+ ((value)
+ (let ((fields* section-name*
+ (apply values
+ (if section-name
+ (list
+ (filter-configuration-fields
+ fields (list section-name) #t)
+ (serialize-configuration
+ value (filter-configuration-fields
+ fields (list section-name))))
+ (list fields #f)))))
+ #~(format #f "~a ~@[~a ~]{~%~a}~%"
+ '#$section-type #$section-name*
+ #$(serialize-configuration value fields*)))))))
+ proc))
+
+(define (make-serialize-list-of-sections proc)
+ (lambda (_ value)
+ #~(string-append #$@(map proc value))))
+
+(define (serialize-section-name _ value)
+ "Custom serializer for string fields that are considered section names."
+ (escape-string value))
(define-configuration dict-configuration
(entries
(free-form-fields '())
"A list of key-value pairs that this dict should hold."))
-(define (serialize-dict-configuration field-name val)
- (format #t "dict {\n")
- (serialize-configuration val dict-configuration-fields)
- (format #t "}\n"))
+(define serialize-dict-configuration
+ (make-serialize-section "dict" dict-configuration-fields))
(define-configuration passdb-configuration
(driver
@@ -183,17 +201,15 @@ (define-configuration passdb-configuration
@samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
@samp{static}.")
(args
- (space-separated-string-list '())
+ maybe-list-of-strings
"Space separated list of arguments to the passdb driver."))
-(define (serialize-passdb-configuration field-name val)
- (format #t "passdb {\n")
- (serialize-configuration val passdb-configuration-fields)
- (format #t "}\n"))
-(define (passdb-configuration-list? val)
- (and (list? val) (and-map passdb-configuration? val)))
-(define (serialize-passdb-configuration-list field-name val)
- (for-each (lambda (val) (serialize-passdb-configuration field-name val)) val))
+(define list-of-passdb-configurations?
+ (list-of passdb-configuration?))
+
+(define serialize-list-of-passdb-configurations
+ (make-serialize-list-of-sections
+ (make-serialize-section "passdb" passdb-configuration-fields)))
(define-configuration userdb-configuration
(driver
@@ -201,111 +217,103 @@ (define-configuration userdb-configuration
"The driver that the userdb should use. Valid values include
@samp{passwd} and @samp{static}.")
(args
- (space-separated-string-list '())
+ maybe-list-of-strings
"Space separated list of arguments to the userdb driver.")
(override-fields
- (free-form-args '())
+ (alist '())
"Override fields from passwd."))
-(define (serialize-userdb-configuration field-name val)
- (format #t "userdb {\n")
- (serialize-configuration val userdb-configuration-fields)
- (format #t "}\n"))
-(define (userdb-configuration-list? val)
- (and (list? val) (and-map userdb-configuration? val)))
-(define (serialize-userdb-configuration-list field-name val)
- (for-each (lambda (val) (serialize-userdb-configuration field-name val)) val))
-
-(define-configuration unix-listener-configuration
- (path
- (string (configuration-missing-field 'unix-listener 'path))
- "Path to the file, relative to @code{base-dir} field. This is also used as
-the section name.")
- (mode
- (string "0600")
- "The access mode for the socket.")
- (user
- (string "")
- "The user to own the the socket.")
- (group
- (string "")
- "The group to own the socket."))
-
-(define (serialize-unix-listener-configuration field-name val)
- (format #t "unix_listener ~a {\n" (unix-listener-configuration-path val))
- (serialize-configuration val (cdr unix-listener-configuration-fields))
- (format #t "}\n"))
-
-(define-configuration fifo-listener-configuration
- (path
- (string (configuration-missing-field 'fifo-listener 'path))
- "Path to the file, relative to @code{base-dir} field. This is also used as
-the section name.")
- (mode
- (string "0600")
- "The access mode for the socket.")
- (user
- (string "")
- "The user to own the the socket.")
- (group
- (string "")
- "The group to own the socket."))
-
-(define (serialize-fifo-listener-configuration field-name val)
- (format #t "fifo_listener ~a {\n" (fifo-listener-configuration-path val))
- (serialize-configuration val (cdr fifo-listener-configuration-fields))
- (format #t "}\n"))
+(define list-of-userdb-configurations?
+ (list-of userdb-configuration?))
+
+(define serialize-list-of-userdb-configurations
+ (make-serialize-list-of-sections
+ (make-serialize-section "userdb" userdb-configuration-fields)))
+
+(let-syntax
+ ;; Both unix-listener-configuration and fifo-listener-configuration share
+ ;; the same configuration structure yet should be considered as distinct
+ ;; record-types, use a macro to define these structures in a single run.
+ ((define-listener-configuration
+ (syntax-rules ()
+ ((_ id ...)
+ (begin
+ (define-configuration id
+ (path
+ string
+ "Path to the file, relative to @code{dovecot-configuration}'s
+@code{base-dir} field. This is also used as the section name."
+ (serializer serialize-section-name))
+ (mode
+ (string "0600")
+ "The access mode for the socket.")
+ (user
+ (string "")
+ "The user to own the the socket.")
+ (group
+ (string "")
+ "The group to own the socket.")) ...)))))
+ (define-listener-configuration
+ unix-listener-configuration
+ fifo-listener-configuration))
(define-configuration inet-listener-configuration
(protocol
- (string (configuration-missing-field 'inet-listener 'protocol))
- "The protocol to listen for.")
+ string
+ "The protocol to listen for."
+ (serializer serialize-section-name))
(address
(string "")
"The address on which to listen, or empty for all addresses.")
(port
- (non-negative-integer
- (configuration-missing-field 'inet-listener 'port))
+ non-negative-integer
"The port on which to listen.")
(ssl?
(boolean #t)
"Whether to use SSL for this service; @samp{yes}, @samp{no}, or
@samp{required}."))
-(define (serialize-inet-listener-configuration field-name val)
- (format #t "inet_listener ~a {\n" (inet-listener-configuration-protocol val))
- (serialize-configuration val (cdr inet-listener-configuration-fields))
- (format #t "}\n"))
+(define (listener-configuration? value)
+ (or (unix-listener-configuration? value)
+ (fifo-listener-configuration? value)
+ (inet-listener-configuration? value)))
-(define (listener-configuration? val)
- (or (unix-listener-configuration? val)
- (fifo-listener-configuration? val)
- (inet-listener-configuration? val)))
-(define (serialize-listener-configuration field-name val)
+(define list-of-listener-configurations?
+ (list-of listener-configuration?))
+
+(define (serialize-listener-configuration config)
+ "Serializer for unix-listener-configuration, fifo-listener-configuration
+and inet-listener-configuration record-types."
(cond
- ((unix-listener-configuration? val)
- (serialize-unix-listener-configuration field-name val))
- ((fifo-listener-configuration? val)
- (serialize-fifo-listener-configuration field-name val))
- ((inet-listener-configuration? val)
- (serialize-inet-listener-configuration field-name val))
- (else (configuration-field-error #f field-name val))))
-(define (listener-configuration-list? val)
- (and (list? val) (and-map listener-configuration? val)))
-(define (serialize-listener-configuration-list field-name val)
- (for-each (lambda (val)
- (serialize-listener-configuration field-name val))
- val))
+ ((unix-listener-configuration? config)
+ ((make-serialize-section "unix_listener"
+ unix-listener-configuration-fields 'path)
+ config))
+ ((fifo-listener-configuration? config)
+ ((make-serialize-section "fifo_listener"
+ fifo-listener-configuration-fields 'path)
+ config))
+ ((inet-listener-configuration? config)
+ ((make-serialize-section "inet_listener"
+ inet-listener-configuration-fields 'protocol)
+ config))
+ (else
+ (scm-error 'wrong-type-arg 'serialize-listener-configuration
+ "Wrong type argument: ~S" (list config) (list config)))))
+
+(define serialize-list-of-listener-configurations
+ (make-serialize-list-of-sections serialize-listener-configuration))
(define-configuration service-configuration
(kind
- (string (configuration-missing-field 'service 'kind))
+ string
"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.")
+@code{tcpwrap}, @code{quota-warning}, or anything else."
+ (serializer serialize-section-name))
(listeners
- (listener-configuration-list '())
+ (list-of-listener-configurations '())
"Listeners for the service. A listener is either an
@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
an @code{inet-listener-configuration}.")
@@ -334,27 +342,24 @@ (define-configuration service-configuration
"If you set @samp{service-count 0}, you probably need to grow
this."))
-(define (serialize-service-configuration field-name val)
- (format #t "service ~a {\n" (service-configuration-kind val))
- (serialize-configuration val (cdr service-configuration-fields))
- (format #t "}\n"))
-(define (service-configuration-list? val)
- (and (list? val) (and-map service-configuration? val)))
-(define (serialize-service-configuration-list field-name val)
- (for-each (lambda (val)
- (serialize-service-configuration field-name val))
- val))
+(define list-of-service-configurations?
+ (list-of service-configuration?))
+
+(define serialize-list-of-service-configurations
+ (make-serialize-list-of-sections
+ (make-serialize-section "service" service-configuration-fields 'kind)))
(define-configuration protocol-configuration
(name
- (string (configuration-missing-field 'protocol 'name))
- "The name of the protocol.")
+ string
+ "The name of the protocol."
+ (serializer serialize-section-name))
(auth-socket-path
(string "/var/run/dovecot/auth-userdb")
"UNIX socket path to master authentication server to find users.
This is used by imap (for shared users) and lda.")
(mail-plugins
- (space-separated-string-list '("$mail_plugins"))
+ (list-of-strings '("$mail_plugins"))
"Space separated list of plugins to load.")
(mail-max-userip-connections
(non-negative-integer 10)
@@ -370,45 +375,45 @@ (define-configuration protocol-configuration
If this is @samp{#t}, you must also specify a dictionary @i{via} the
@code{mail-attribute-dict} setting.")
(managesieve-notify-capability
- (space-separated-string-list '())
+ maybe-list-of-strings
"Which NOTIFY capabilities to report to clients that first connect to
the ManageSieve service, before authentication. These may differ from the
capabilities offered to authenticated users. If this field is left empty,
report what the Sieve interpreter supports by default.")
(managesieve-sieve-capability
- (space-separated-string-list '())
+ maybe-list-of-strings
"Which SIEVE capabilities to report to clients that first connect to
the ManageSieve service, before authentication. These may differ from the
capabilities offered to authenticated users. If this field is left empty,
report what the Sieve interpreter supports by default."))
-(define (serialize-protocol-configuration field-name val)
- (format #t "protocol ~a {\n" (protocol-configuration-name val))
- (serialize-configuration val (cdr protocol-configuration-fields))
- (format #t "}\n"))
-(define (protocol-configuration-list? val)
- (and (list? val) (and-map protocol-configuration? val)))
-(define (serialize-protocol-configuration-list field-name val)
- (serialize-field 'protocols
- (string-join (map protocol-configuration-name val) " "))
- (for-each (lambda (val)
- (serialize-protocol-configuration field-name val))
- val))
+(define list-of-protocol-configurations?
+ (list-of protocol-configuration?))
+
+(define serialize-protocol-configuration
+ (make-serialize-section "protocol" protocol-configuration-fields 'name))
+
+(define (serialize-list-of-protocol-configurations _ value)
+ #~(string-append
+ ;; Serialize the top level 'protocol=…' setting.
+ #$(serialize-list-of-strings 'protocols
+ (map protocol-configuration-name value))
+ ;; Serialize the protocol sections.
+ #$@(map serialize-protocol-configuration value)))
(define-configuration plugin-configuration
(entries
(free-form-fields '())
"A list of key-value pairs that this dict should hold."))
-(define (serialize-plugin-configuration field-name val)
- (format #t "plugin {\n")
- (serialize-configuration val plugin-configuration-fields)
- (format #t "}\n"))
+(define serialize-plugin-configuration
+ (make-serialize-section "plugin" plugin-configuration-fields))
(define-configuration mailbox-configuration
(name
- (string (error "mailbox name is required"))
- "Name for this mailbox.")
+ string
+ "Name for this mailbox."
+ (serializer serialize-section-name))
(auto
(string "no")
@@ -416,26 +421,25 @@ (define-configuration mailbox-configuration
@samp{subscribe} will both create and subscribe to the mailbox.")
(special-use
- (space-separated-string-list '())
+ maybe-list-of-strings
"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}."))
-(define (serialize-mailbox-configuration field-name val)
- (format #t "mailbox \"~a\" {\n" (mailbox-configuration-name val))
- (serialize-configuration val (cdr mailbox-configuration-fields))
- (format #t "}\n"))
-(define (mailbox-configuration-list? val)
- (and (list? val) (and-map mailbox-configuration? val)))
-(define (serialize-mailbox-configuration-list field-name val)
- (for-each (lambda (val)
- (serialize-mailbox-configuration field-name val))
- val))
+(define list-of-mailbox-configurations?
+ (list-of mailbox-configuration?))
+
+(define serialize-mailbox-configuration
+ (make-serialize-section "mailbox" mailbox-configuration-fields 'name))
+
+(define serialize-list-of-mailbox-configurations
+ (make-serialize-list-of-sections serialize-mailbox-configuration))
(define-configuration namespace-configuration
(name
- (string (error "namespace name is required"))
- "Name for this namespace.")
+ string
+ "Name for this namespace."
+ (serializer serialize-section-name))
(type
(string "private")
@@ -456,7 +460,7 @@ (define-configuration namespace-configuration
(location
(string "")
"Physical location of the mailbox. This is in same format as
-mail_location, which is also the default for it.")
+@code{mail-location}, which is also the default for it.")
(inbox?
(boolean #f)
@@ -466,11 +470,11 @@ (define-configuration namespace-configuration
(hidden?
(boolean #f)
"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/}.")
+extension. You'll most likely also want to set @code{list?} to @code{#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/}.")
(list?
(boolean #t)
@@ -483,22 +487,18 @@ (define-configuration namespace-configuration
(boolean #t)
"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}.)")
+as @code{#t}.")
(mailboxes
- (mailbox-configuration-list '())
+ (list-of-mailbox-configurations '())
"List of predefined mailboxes in this namespace."))
-(define (serialize-namespace-configuration field-name val)
- (format #t "namespace ~a {\n" (namespace-configuration-name val))
- (serialize-configuration val (cdr namespace-configuration-fields))
- (format #t "}\n"))
-(define (list-of-namespace-configuration? val)
- (and (list? val) (and-map namespace-configuration? val)))
-(define (serialize-list-of-namespace-configuration field-name val)
- (for-each (lambda (val)
- (serialize-namespace-configuration field-name val))
- val))
+(define list-of-namespace-configurations?
+ (list-of namespace-configuration?))
+
+(define serialize-list-of-namespace-configurations
+ (make-serialize-list-of-sections
+ (make-serialize-section "namespace" namespace-configuration-fields 'name)))
(define-configuration dovecot-configuration
(dovecot
@@ -506,12 +506,13 @@ (define-configuration dovecot-configuration
"The dovecot package.")
(listen
- (comma-separated-string-list '("*" "::"))
+ (list-of-strings '("*" "::"))
"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.")
+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 @code{inet-listener} of the specific
+services you are interested in."
+ (serializer (make-serialize-list-with-delimiter ",")))
(dict
(dict-configuration (dict-configuration))
@@ -519,12 +520,12 @@ (define-configuration dovecot-configuration
constructor.")
(passdbs
- (passdb-configuration-list (list (passdb-configuration (driver "pam"))))
+ (list-of-passdb-configurations (list (passdb-configuration)))
"List of passdb configurations, each one created by the
@code{passdb-configuration} constructor.")
(userdbs
- (userdb-configuration-list (list (userdb-configuration (driver "passwd"))))
+ (list-of-userdb-configurations (list (userdb-configuration)))
"List of userdb configurations, each one created by the
@code{userdb-configuration} constructor.")
@@ -534,7 +535,7 @@ (define-configuration dovecot-configuration
constructor.")
(namespaces
- (list-of-namespace-configuration
+ (list-of-namespace-configurations
(list
(namespace-configuration
(name "inbox")
@@ -552,7 +553,7 @@ (define-configuration dovecot-configuration
@code{namespace-configuration} constructor.")
(base-dir
- (file-name "/var/run/dovecot/")
+ (string "/var/run/dovecot/")
"Base directory where to store runtime data.")
(login-greeting
@@ -560,7 +561,7 @@ (define-configuration dovecot-configuration
"Greeting message for clients.")
(login-trusted-networks
- (space-separated-string-list '())
+ maybe-list-of-strings
"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
@@ -568,7 +569,7 @@ (define-configuration dovecot-configuration
here.")
(login-access-sockets
- (space-separated-string-list '())
+ maybe-list-of-strings
"List of login access check sockets (e.g. tcpwrap).")
(verbose-proctitle?
@@ -592,13 +593,14 @@ (define-configuration dovecot-configuration
(doveadm-socket-path
(string "doveadm-server")
- "UNIX socket or host:port used for connecting to doveadm server.")
+ "UNIX socket path or @samp{@var{host}:@var{port}} used for connecting to
+doveadm server.")
(import-environment
- (space-separated-string-list '("TZ"))
+ (list-of-strings '("TZ"))
"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.")
+@samp{@var{key}=@var{value}} pairs to always set specific settings.")
;;; Authentication processes
@@ -612,14 +614,14 @@ (define-configuration dovecot-configuration
(auth-cache-size
(non-negative-integer 0)
- "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.")
+ "Authentication cache size (e.g. @samp{#e10e6}). @samp{0} means it's
+disabled. Note that bsdauth, PAM and vpopmail require @code{cache-key} to be
+set for caching to be used.")
(auth-cache-ttl
(string "1 hour")
"Time to live for cached data. After TTL expires the cached record
-is no longer used, *except* if the main database lookup returns internal
+is no longer used, @strong{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
@@ -628,10 +630,10 @@ (define-configuration dovecot-configuration
(auth-cache-negative-ttl
(string "1 hour")
"TTL for negative hits (user not found, password mismatch).
-0 disables caching them completely.")
+@samp{0} disables caching them completely.")
(auth-realms
- (space-separated-string-list '())
+ maybe-list-of-strings
"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
@@ -665,21 +667,20 @@ (define-configuration dovecot-configuration
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.")
+@code{auth-username-translation} changes.")
(auth-master-user-separator
(string "")
"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.")
+here. The format is then
+@samp{@var{username}@var{separator}@var{master username}}. UW-IMAP uses
+@samp{*} as the separator, so that could be a good choice.")
(auth-anonymous-username
(string "anonymous")
- "Username to use for users logging in with ANONYMOUS SASL
-mechanism.")
+ "Username for users logging in with ANONYMOUS SASL mechanism.")
(auth-worker-max-count
(non-negative-integer 30)
@@ -707,7 +708,7 @@ (define-configuration dovecot-configuration
<doc/wiki/Authentication/Mechanisms/Winbind.txt>.")
(auth-winbind-helper-path
- (file-name "/usr/bin/ntlm_auth")
+ (string "/usr/bin/ntlm_auth")
"Path for Samba's @samp{ntlm-auth} helper binary.")
(auth-failure-delay
@@ -726,7 +727,7 @@ (define-configuration dovecot-configuration
CommonName.")
(auth-mechanisms
- (space-separated-string-list '("plain"))
+ (list-of-strings '("plain"))
"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},
@@ -734,15 +735,15 @@ (define-configuration dovecot-configuration
@samp{disable-plaintext-auth} setting.")
(director-servers
- (space-separated-string-list '())
+ maybe-list-of-strings
"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.")
+director service's @code{inet-listener} is using.")
(director-mail-servers
- (space-separated-string-list '())
+ maybe-list-of-strings
"List of IPs or hostnames to all backend mail servers. Ranges are
-allowed too, like 10.0.0.10-10.0.0.30.")
+allowed too, like @samp{10.0.0.10-10.0.0.30}.")
(director-user-expire
(string "15 min")
@@ -765,18 +766,18 @@ (define-configuration dovecot-configuration
(info-log-path
(string "")
"Log file to use for informational messages. Defaults to
-@samp{log-path}.")
+@code{log-path}.")
(debug-log-path
(string "")
"Log file to use for debug messages. Defaults to
-@samp{info-log-path}.")
+@code{info-log-path}.")
(syslog-facility
(string "mail")
"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.")
+don't want to use @samp{mail}, you'll use @samp{local0}..@samp{local7}.
+Also other standard facilities are supported.")
(auth-verbose?
(boolean #f)
@@ -785,11 +786,11 @@ (define-configuration dovecot-configuration
(auth-verbose-passwords
(string "no")
- "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).")
+ "In case of password mismatches, log the attempted password. Valid values
+are @samp{no}, @samp{plain} and @samp{sha1}. @samp{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 @var{n}
+characters by appending @samp{:@var{n}} (e.g. @samp{sha1:6}).")
(auth-debug?
(boolean #f)
@@ -800,7 +801,7 @@ (define-configuration dovecot-configuration
(boolean #f)
"In case of password mismatches, log the passwords and used scheme so
the problem can be debugged. Enabling this also enables
-@samp{auth-debug}.")
+@code{auth-debug}.")
(mail-debug?
(boolean #f)
@@ -812,12 +813,12 @@ (define-configuration dovecot-configuration
"Show protocol level SSL errors.")
(log-timestamp
- (string "\"%b %d %H:%M:%S \"")
+ (string "%b %d %H:%M:%S ")
"Prefix for each line written to log file. % codes are in
strftime(3) format.")
(login-log-format-elements
- (space-separated-string-list
+ (list-of-strings
'("user=<%u>" "method=%m" "rip=%r" "lip=%l" "mpid=%e" "%c"))
"List of elements we want to log. The elements which have a
non-empty variable value are joined together to form a comma-separated
@@ -825,11 +826,11 @@ (define-configuration dovecot-configuration
(login-log-format
(string "%$: %s")
- "Login log format. %s contains @samp{login-log-format-elements}
-string, %$ contains the data we want to log.")
+ "Login log format. @samp{%s} contains @code{login-log-format-elements}
+string, @samp{%$} contains the data we want to log.")
(mail-log-prefix
- (string "\"%s(%u)<%{pid}><%{session}>: \"")
+ (string "%s(%u)<%{pid}><%{session}>: ")
"Log prefix for mail processes. See doc/wiki/Variables.txt for list
of possible variables you can use.")
@@ -862,9 +863,9 @@ (define-configuration dovecot-configuration
If you're using mbox, giving a path to the INBOX
file (e.g. /var/mail/%u) isn't enough. You'll also need to tell Dovecot
-where the other mailboxes are kept. This is called the \"root mail
-directory\", and it must be the first path given in the
-@samp{mail-location} setting.
+where the other mailboxes are kept. This is called the ``root mail
+directory'', and it must be the first path given in the
+@code{mail-location} setting.
There are a few special variables you can use, eg.:
@@ -872,7 +873,7 @@ (define-configuration dovecot-configuration
@item %u
username
@item %n
-user part in user@@domain, same as %u if there's no domain
+user part in user@@domain, same as @samp{%u} if there's no domain
@item %d
domain part in user@@domain, empty if there's no domain
@item %h
@@ -900,46 +901,46 @@ (define-configuration dovecot-configuration
(string "")
"Group to enable temporarily for privileged operations. Currently
this is used only with INBOX when either its initial creation or
-dotlocking fails. Typically this is set to \"mail\" to give access to
-/var/mail.")
+dotlocking fails. Typically this is set to @samp{\"mail\"} to give access to
+@file{/var/mail}.")
(mail-access-groups
(string "")
"Grant access to these supplementary groups for mail processes.
Typically these are used to set up access to shared mailboxes. Note
-that it may be dangerous to set these if users can create
-symlinks (e.g. if \"mail\" group is set here, ln -s /var/mail ~/mail/var
-could allow a user to delete others' mailboxes, or ln -s
-/secret/shared/box ~/mail/mybox would allow reading it).")
+that it may be dangerous to set these if users can create symlinks (e.g. if
+@samp{\"mail\"} group is set here, @samp{ln -s /var/mail ~/mail/var} could
+allow a user to delete others' mailboxes, or
+@samp{ln -s /secret/shared/box ~/mail/mybox} would allow reading it).")
(mail-full-filesystem-access?
(boolean #f)
"Allow full file system access to clients. There's no access checks
other than what the operating system does for the active UID/GID. It
works with both maildir and mboxes, allowing you to prefix mailboxes
-names with e.g. /path/ or ~user/.")
+names with e.g. @samp{/path/} or @samp{~user/}.")
;;; Mail processes
(mmap-disable?
(boolean #f)
- "Don't use mmap() at all. This is required if you store indexes to
+ "Don't use @code{mmap()} at all. This is required if you store indexes to
shared file systems (NFS or clustered file system).")
(dotlock-use-excl?
(boolean #t)
- "Rely on @samp{O_EXCL} to work when creating dotlock files. NFS
-supports @samp{O_EXCL} since version 3, so this should be safe to use
+ "Rely on @code{O_EXCL} to work when creating dotlock files. NFS
+supports @code{O_EXCL} since version 3, so this should be safe to use
nowadays by default.")
(mail-fsync
(string "optimized")
- "When to use fsync() or fdatasync() calls:
+ "When to use @code{fsync()} or @code{fdatasync()} calls:
@table @code
@item optimized
Whenever necessary to avoid losing important data
@item always
-Useful with e.g. NFS when write()s are delayed
+Useful with e.g. NFS when @code{write()}s are delayed
@item never
Never use it (best performance, but crashes can lose data).
@end table")
@@ -960,10 +961,10 @@ (define-configuration dovecot-configuration
"Locking method for index files. Alternatives are fcntl, flock and
dotlock. Dotlocking uses some tricks which may create more disk I/O
than other locking methods. NFS users: flock doesn't work, remember to
-change @samp{mmap-disable}.")
+change @code{mmap-disable}.")
(mail-temp-dir
- (file-name "/tmp")
+ (string "/tmp")
"Directory in which LDA/LMTP temporarily stores incoming mails >128
kB.")
@@ -971,8 +972,8 @@ (define-configuration dovecot-configuration
(non-negative-integer 500)
"Valid UID range for users. This is mostly to make sure that users can't
log in as daemons or other system users. Note that denying root logins is
-hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
-is set to 0.")
+hardcoded to dovecot binary and can't be done even if @code{first-valid-uid}
+is set to @samp{0}.")
(last-valid-uid
(non-negative-integer 0)
@@ -994,40 +995,45 @@ (define-configuration dovecot-configuration
trying to create new keywords.")
(valid-chroot-dirs
- (colon-separated-file-name-list '())
- "List of directories under which chrooting is allowed for mail
-processes (i.e. /var/mail will allow chrooting to /var/mail/foo/bar
-too). This setting doesn't affect @samp{login-chroot}
-@samp{mail-chroot} or auth chroot settings. If this setting is empty,
-\"/./\" in home dirs are ignored. WARNING: Never add directories here
-which local users can modify, that may lead to root exploit. Usually
-this should be done only if you don't allow shell access for users.
-<doc/wiki/Chrooting.txt>.")
+ (list-of-strings '())
+ "List of directories under which chrooting is allowed for @emph{mail
+processes}. The values are interpreted recursively (e.g., @file{/var/mail}
+will allow chrooting to @file{/var/mail/foo/bar}).
+This setting doesn't affect @emph{login processes} or
+@emph{authentication processes} but it does affect @code{mail-chroot} since
+it applies to the @emph{mail processes}.
+@quotation Warning
+Never add directories here which local users can modify, that may lead to
+root exploit. Usually this should be done only if you don't allow shell
+access for users. See @url{https://doc.dovecot.org/admin_manual/chrooting/,
+Chrooting@comma{} Dovecot documentation} for more information.
+@end quotation"
+ (serializer (make-serialize-list-with-delimiter ":")))
(mail-chroot
(string "")
"Default chroot directory for mail processes. This can be overridden
-for specific users in user database by giving /./ in user's home
-directory (e.g. /home/./user chroots into /home). Note that usually
-there is no real need to do chrooting, Dovecot doesn't allow users to
-access files outside their mail directory anyway. If your home
-directories are prefixed with the chroot directory, append \"/.\" to
-@samp{mail-chroot}. <doc/wiki/Chrooting.txt>.")
+for specific users in user database by giving @samp{/./} in user's home
+directory (e.g. @file{/home/./user} chroots into @file{/home}).
+Note that usually there is no real need to do chrooting, Dovecot doesn't allow
+users to access files outside their mail directory anyway. If your home
+directories are prefixed with the chroot directory, append @samp{/.} to
+@code{mail-chroot}. See @url{https://doc.dovecot.org/admin_manual/chrooting/,
+Chrooting@comma{} Dovecot documentation} for more information.")
(auth-socket-path
- (file-name "/var/run/dovecot/auth-userdb")
+ (string "/var/run/dovecot/auth-userdb")
"UNIX socket path to master authentication server to find users.
This is used by imap (for shared users) and lda.")
(mail-plugin-dir
- (file-name "/usr/lib/dovecot")
+ (string "/usr/lib/dovecot")
"Directory where to look up mail plugins.")
(mail-plugins
- (space-separated-string-list '())
+ maybe-list-of-strings
"List of plugins to load for all services. Plugins specific to IMAP,
-LDA, etc. are added to this list in their own .conf files.")
-
+LDA, etc. are added to this list in their own @file{.conf} files.")
(mail-cache-min-mail-count
(non-negative-integer 0)
@@ -1046,7 +1052,7 @@ (define-configuration dovecot-configuration
(mail-save-crlf?
(boolean #f)
"Save mails with CR+LF instead of plain LF. This makes sending those
-mails take less CPU, especially with sendfile() syscall with Linux and
+mails take less CPU, especially with @code{sendfile()} syscall with Linux and
FreeBSD. But it also creates a bit more disk I/O which may just make it
slower. Also note that if other software reads the mboxes/maildirs,
they may handle the extra CRs wrong and cause problems.")
@@ -1055,9 +1061,9 @@ (define-configuration dovecot-configuration
(boolean #f)
"By default LIST command returns all entries in maildir beginning
with a dot. Enabling this option makes Dovecot return only entries
-which are directories. This is done by stat()ing each entry, so it
+which are directories. This is done by @code{stat()}ing each entry, so it
causes more disk I/O.
- (For systems setting struct @samp{dirent->d_type} this check is free
+ (For systems setting struct @code{dirent->d_type} this check is free
and it's done always regardless of this setting).")
(maildir-copy-with-hardlinks?
@@ -1073,14 +1079,14 @@ (define-configuration dovecot-configuration
the mail otherwise.")
(mbox-read-locks
- (space-separated-string-list '("fcntl"))
+ (list-of-strings '("fcntl"))
"Which locking methods to use for locking mbox. There are four
available:
@table @code
@item dotlock
-Create <mailbox>.lock file. This is the oldest and most NFS-safe
-solution. If you want to use /var/mail/ like directory, the users will
+Create @file{@var{mailbox}.lock} file. This is the oldest and most NFS-safe
+solution. If you want to use @file{/var/mail/}-like directory, the users will
need write access to that directory.
@item dotlock-try
Same as dotlock, but if it fails because of permissions or because there
@@ -1099,7 +1105,7 @@ (define-configuration dovecot-configuration
them simultaneously.")
(mbox-write-locks
- (space-separated-string-list '("dotlock" "fcntl"))
+ (list-of-strings '("dotlock" "fcntl"))
"")
(mbox-lock-timeout
@@ -1125,9 +1131,9 @@ (define-configuration dovecot-configuration
(mbox-very-dirty-syncs?
(boolean #f)
- "Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
-EXAMINE, EXPUNGE or CHECK commands. If this is set,
-@samp{mbox-dirty-syncs} is ignored.")
+ "Like @code{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
+EXAMINE, EXPUNGE or CHECK commands. If this is set, @code{mbox-dirty-syncs}
+is ignored.")
(mbox-lazy-writes?
(boolean #t)
@@ -1168,13 +1174,13 @@ (define-configuration dovecot-configuration
(mail-attachment-dir
(string "")
- "sdbox and mdbox support saving mail attachments to external files,
+ "Directory root where to store mail attachments. Disabled, if empty.
+sdbox and mdbox support saving mail attachments to external files,
which also allows single instance storage for them. Other backends
don't support this for now.
-
-WARNING: This feature hasn't been tested much yet. Use at your own risk.
-
-Directory root where to store mail attachments. Disabled, if empty.")
+@quotation Warning
+This feature hasn't been tested much yet. Use at your own risk.
+@end quotation")
(mail-attachment-min-size
(non-negative-integer #e128e3)
@@ -1278,7 +1284,7 @@ (define-configuration dovecot-configuration
(ssl-crypto-device
(string "")
- "SSL crypto device to use, for valid values run \"openssl engine\".")
+ "SSL crypto device to use, for valid values run @samp{openssl engine}.")
(postmaster-address
(string "postmaster@%d")
@@ -1296,7 +1302,7 @@ (define-configuration dovecot-configuration
bouncing the mail.")
(sendmail-path
- (file-name "/usr/sbin/sendmail")
+ (string "/usr/sbin/sendmail")
"Binary to use for sending mails.")
(submission-host
@@ -1340,12 +1346,12 @@ (define-configuration dovecot-configuration
(lda-mailbox-autocreate?
(boolean #f)
"Should saving a mail to a nonexistent mailbox automatically create
-it?.")
+it?")
(lda-mailbox-autosubscribe?
(boolean #f)
"Should automatically created mailboxes be also automatically
-subscribed?.")
+subscribed?")
(imap-max-line-length
@@ -1388,7 +1394,7 @@ (define-configuration dovecot-configuration
"ID fields sent by client to log. * means everything.")
(imap-client-workarounds
- (space-separated-string-list '())
+ maybe-list-of-strings
"Workarounds for various client bugs:
@table @code
@@ -1409,43 +1415,48 @@ (define-configuration dovecot-configuration
Show \\Noselect flags for LSUB replies with LAYOUT=fs (e.g. mbox).
This makes Thunderbird realize they aren't selectable and show them
greyed out, instead of only later giving \"not selectable\" popup error.
-@end table
-")
+@end table")
(imap-urlauth-host
(string "")
"Host allowed in URLAUTH URLs sent by client. \"*\" allows all.")
(protocols
- (protocol-configuration-list
- (list (protocol-configuration
- (name "imap"))))
+ (list-of-protocol-configurations
+ (list (protocol-configuration (name "imap"))))
"List of protocols we want to serve. Available protocols include
@samp{imap}, @samp{pop3}, and @samp{lmtp}.")
(services
- (service-configuration-list
+ (list-of-service-configurations
(list
(service-configuration
(kind "imap-login")
(client-limit 0)
(process-limit 0)
(listeners
- (list
- (inet-listener-configuration (protocol "imap") (port 143) (ssl? #f))
- (inet-listener-configuration (protocol "imaps") (port 993) (ssl? #t)))))
+ (list (inet-listener-configuration (protocol "imap")
+ (port 143)
+ (ssl? #f))
+ (inet-listener-configuration (protocol "imaps")
+ (port 993)
+ (ssl? #t)))))
(service-configuration
(kind "pop3-login")
(listeners
- (list
- (inet-listener-configuration (protocol "pop3") (port 110) (ssl? #f))
- (inet-listener-configuration (protocol "pop3s") (port 995) (ssl? #t)))))
+ (list (inet-listener-configuration (protocol "pop3")
+ (port 110)
+ (ssl? #f))
+ (inet-listener-configuration (protocol "pop3s")
+ (port 995)
+ (ssl? #t)))))
(service-configuration
(kind "lmtp")
(client-limit 1)
(process-limit 0)
(listeners
- (list (unix-listener-configuration (path "lmtp") (mode "0666")))))
+ (list (unix-listener-configuration (path "lmtp")
+ (mode "0666")))))
(service-configuration
(kind "imap")
(client-limit 1)
@@ -1480,8 +1491,7 @@ (define-configuration opaque-dovecot-configuration
"The dovecot package.")
(string
- (string (configuration-missing-field 'opaque-dovecot-configuration
- 'string))
+ string
"The contents of the @code{dovecot.conf} to use."))
(define %dovecot-accounts
@@ -1504,72 +1514,73 @@ (define %dovecot-accounts
(home-directory "/var/empty")
(shell (file-append shadow "/sbin/nologin")))))
+(define (dovecot-configuration->file config)
+ (mixed-text-file
+ "dovecot.conf"
+ #~(begin
+ (use-modules (ice-9 format))
+ #$(if (opaque-dovecot-configuration? config)
+ (opaque-dovecot-configuration-string config)
+ (serialize-configuration config dovecot-configuration-fields)))))
+
(define (%dovecot-activation config)
;; Activation gexp.
- (let ((config-str
- (cond
- ((opaque-dovecot-configuration? config)
- (opaque-dovecot-configuration-string config))
- (else
- (with-output-to-string
- (lambda ()
- (serialize-configuration config
- dovecot-configuration-fields)))))))
- (with-imported-modules (source-module-closure '((gnu build activation)))
- #~(begin
- (use-modules (guix build utils) (gnu build activation))
- (define (build-subject parameters)
- (string-concatenate
- (map (lambda (pair)
- (let ((k (car pair)) (v (cdr pair)))
- (define (escape-char str chr)
- (string-join (string-split str chr) (string #\\ chr)))
- (string-append "/" k "="
- (escape-char (escape-char v #\=) #\/))))
- (filter (lambda (pair) (cdr pair)) parameters))))
- (define* (create-self-signed-certificate-if-absent
- #:key private-key public-key (owner (getpwnam "root"))
- (common-name (gethostname))
- (organization-name "Guix")
- (organization-unit-name "Default Self-Signed Certificate")
- (subject-parameters `(("CN" . ,common-name)
- ("O" . ,organization-name)
- ("OU" . ,organization-unit-name)))
- (subject (build-subject subject-parameters)))
- ;; Note that by default, OpenSSL outputs keys in PEM format. This
- ;; is what we want.
- (unless (file-exists? private-key)
- (cond
- ((zero? (system* (string-append #$openssl "/bin/openssl")
- "genrsa" "-out" private-key "2048"))
- (chown private-key (passwd:uid owner) (passwd:gid owner))
- (chmod private-key #o400))
- (else
- (format (current-error-port)
- "Failed to create private key at ~a.\n" private-key))))
- (unless (file-exists? public-key)
- (cond
- ((zero? (system* (string-append #$openssl "/bin/openssl")
- "req" "-new" "-x509" "-key" private-key
- "-out" public-key "-days" "3650"
- "-batch" "-subj" subject))
- (chown public-key (passwd:uid owner) (passwd:gid owner))
- (chmod public-key #o444))
- (else
- (format (current-error-port)
- "Failed to create public key at ~a.\n" public-key)))))
- (let ((user (getpwnam "dovecot")))
- (mkdir-p/perms "/var/run/dovecot" user #o755)
- (mkdir-p/perms "/var/lib/dovecot" user #o755)
- (mkdir-p/perms "/etc/dovecot" user #o755)
- (copy-file #$(plain-file "dovecot.conf" config-str)
- "/etc/dovecot/dovecot.conf")
- (mkdir-p/perms "/etc/dovecot/private" user #o700)
- (create-self-signed-certificate-if-absent
- #:private-key "/etc/dovecot/private/default.pem"
- #:public-key "/etc/dovecot/default.pem"
- #:owner (getpwnam "root")
- #:common-name (format #f "Dovecot service on ~a" (gethostname))))))))
+ (with-imported-modules (source-module-closure '((gnu build activation)))
+ #~(begin
+ (use-modules (guix build utils)
+ (gnu build activation))
+ (define (build-subject parameters)
+ (string-concatenate
+ (map (lambda (pair)
+ (let ((k (car pair)) (v (cdr pair)))
+ (define (escape-char str chr)
+ (string-join (string-split str chr) (string #\\ chr)))
+ (string-append "/" k "="
+ (escape-char (escape-char v #\=) #\/))))
+ (filter (lambda (pair) (cdr pair)) parameters))))
+ (define* (create-self-signed-certificate-if-absent
+ #:key private-key public-key (owner (getpwnam "root"))
+ (common-name (gethostname))
+ (organization-name "Guix")
+ (organization-unit-name "Default Self-Signed Certificate")
+ (subject-parameters `(("CN" . ,common-name)
+ ("O" . ,organization-name)
+ ("OU" . ,organization-unit-name)))
+ (subject (build-subject subject-parameters)))
+ ;; Note that by default, OpenSSL outputs keys in PEM format. This
+ ;; is what we want.
+ (unless (file-exists? private-key)
+ (cond
+ ((zero? (system* (string-append #$openssl "/bin/openssl")
+ "genrsa" "-out" private-key "2048"))
+ (chown private-key (passwd:uid owner) (passwd:gid owner))
+ (chmod private-key #o400))
+ (else
+ (format (current-error-port)
+ "Failed to create private key at ~a.\n" private-key))))
+ (unless (file-exists? public-key)
+ (cond
+ ((zero? (system* (string-append #$openssl "/bin/openssl")
+ "req" "-new" "-x509" "-key" private-key
+ "-out" public-key "-days" "3650"
+ "-batch" "-subj" subject))
+ (chown public-key (passwd:uid owner) (passwd:gid owner))
+ (chmod public-key #o444))
+ (else
+ (format (current-error-port)
+ "Failed to create public key at ~a.\n" public-key)))))
+ (let ((user (getpwnam "dovecot")))
+ (mkdir-p/perms "/var/run/dovecot" user #o755)
+ (mkdir-p/perms "/var/lib/dovecot" user #o755)
+ (mkdir-p/perms "/etc/dovecot" user #o755)
+ (copy-file #$(dovecot-configuration->file config)
+ "/etc/dovecot/dovecot.conf")
+ (mkdir-p/perms "/etc/dovecot/private" user #o700)
+ (create-self-signed-certificate-if-absent
+ #:private-key "/etc/dovecot/private/default.pem"
+ #:public-key "/etc/dovecot/default.pem"
+ #:owner (getpwnam "root")
+ #:common-name (format #f "Dovecot service on ~a" (gethostname)))))))
(define (dovecot-shepherd-service config)
"Return a list of <shepherd-service> for CONFIG."
@@ -1603,19 +1614,20 @@ (define %dovecot-pam-services
(list (unix-pam-service "dovecot")))
(define dovecot-service-type
- (service-type (name 'dovecot)
- (extensions
- (list (service-extension shepherd-root-service-type
- dovecot-shepherd-service)
- (service-extension account-service-type
- (const %dovecot-accounts))
- (service-extension pam-root-service-type
- (const %dovecot-pam-services))
- (service-extension activation-service-type
- %dovecot-activation)))
- (description "Run Dovecot, a mail server that can run POP3,
-IMAP, and LMTP.")
- (default-value (dovecot-configuration))))
+ (service-type
+ (name 'dovecot)
+ (extensions
+ (list (service-extension shepherd-root-service-type
+ dovecot-shepherd-service)
+ (service-extension account-service-type
+ (const %dovecot-accounts))
+ (service-extension pam-root-service-type
+ (const %dovecot-pam-services))
+ (service-extension activation-service-type
+ %dovecot-activation)))
+ (description "Run Dovecot, a mail server that can run POP3, IMAP,
+and LMTP.")
+ (default-value (dovecot-configuration))))
(define-deprecated (dovecot-service #:key (config (dovecot-configuration)))
dovecot-service-type