diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 1371 |
1 files changed, 1371 insertions, 0 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index f63e3669fa..06d70ba8a4 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -181,6 +181,7 @@ Services * X Window:: Graphical display. * Desktop Services:: D-Bus and desktop services. * Database Services:: SQL databases. +* Mail Services:: IMAP, POP3, SMTP, and all that. * Web Services:: Web servers. * Various Services:: Other services. @@ -6377,6 +6378,7 @@ declaration. * X Window:: Graphical display. * Desktop Services:: D-Bus and desktop services. * Database Services:: SQL databases. +* Mail Services:: IMAP, POP3, SMTP, and all that. * Web Services:: Web servers. * Various Services:: Other services. @end menu @@ -7100,6 +7102,1375 @@ The PostgreSQL daemon loads its runtime configuration from @var{data-directory}. @end deffn +@node Mail Services +@subsubsection Mail Services + +The @code{(gnu services mail)} module provides Guix service definitions +for mail services. Currently the only implemented service is Dovecot, +an IMAP, POP3, and LMTP server. + +Guix does not yet have a mail transfer agent (MTA), although for some +lightweight purposes the @code{esmtp} relay-only MTA may suffice. Help +is needed to properly integrate a full MTA, such as Postfix. Patches +welcome! + +To add an IMAP/POP3 server to a GuixSD system, add a +@code{dovecot-service} to the operating system definition: + +@deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)] +Return a service that runs the Dovecot IMAP/POP3/LMTP mail server. +@end deffn + +By default, Dovecot doesn't need much configuration; the default +configuration object created by @code{(dovecot-configuration)} will +suffice if your mail is delivered to @code{~/Maildir}. A self-signed +certificate will be generated for TLS-protected connections, though +Dovecot will also listen on cleartext ports by default. There are a +number of options though which mail administrators might need to change, +and as is the case with other services, Guix allows the system +administrator to specify these parameters via a uniform Scheme interface. + +For example, to specify that mail is located at @code{maildir~/.mail}, +one would instantiate the Dovecot service like this: + +@example +(dovecot-service #:config + (dovecot-configuration + (mail-location "maildir:~/.mail"))) +@end example + +The available configuration parameters follow. Each parameter +definition is preceded by its type; for example, @samp{string-list foo} +indicates that the @code{foo} parameter should be specified as a list of +strings. There is also a way to specify the configuration as a string, +if you have an old @code{dovecot.conf} file that you want to port over +from some other system; see the end for more details. + +@c The following documentation was initially generated by +@c (generate-documentation) in (gnu services mail). Manually maintained +@c documentation is better, so we shouldn't hesitate to edit below as +@c needed. However if the change you want to make to this documentation +@c can be done in an automated way, it's probably easier to change +@c (generate-documentation) than to make it below and have to deal with +@c the churn as dovecot updates. + +Available @code{dovecot-configuration} fields are: + +@deftypevr {@code{dovecot-configuration} parameter} package dovecot +The dovecot package. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen +A list of IPs or hosts where to listen in for connections. @samp{*} +listens in all IPv4 interfaces, @samp{::} listens in all IPv6 +interfaces. If you want to specify non-default ports or anything more +complex, customize the address and port fields of the +@samp{inet-listener} of the specific services you are interested in. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols +List of protocols we want to serve. Available protocols include +@samp{imap}, @samp{pop3}, and @samp{lmtp}. + +Available @code{protocol-configuration} fields are: + +@deftypevr {@code{protocol-configuration} parameter} string name +The name of the protocol. +@end deftypevr + +@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path +UNIX socket path to master authentication server to find users. +This is used by imap (for shared users) and lda. +Defaults to @samp{"/var/run/dovecot/auth-userdb"}. +@end deftypevr + +@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins +Space separated list of plugins to load. +@end deftypevr + +@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections +Maximum number of IMAP connections allowed for a user from each IP +address. NOTE: The username is compared case-sensitively. +Defaults to @samp{10}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services +List of services to enable. Available services include @samp{imap}, +@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and +@samp{lmtp}. + +Available @code{service-configuration} fields are: + +@deftypevr {@code{service-configuration} parameter} string kind +The service kind. Valid values include @code{director}, +@code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap}, +@code{pop3}, @code{auth}, @code{auth-worker}, @code{dict}, +@code{tcpwrap}, @code{quota-warning}, or anything else. +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners +Listeners for the service. A listener is either an +@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or +an @code{inet-listener-configuration}. +Defaults to @samp{()}. + +Available @code{unix-listener-configuration} fields are: + +@deftypevr {@code{unix-listener-configuration} parameter} file-name path +The file name on which to listen. +@end deftypevr + +@deftypevr {@code{unix-listener-configuration} parameter} string mode +The access mode for the socket. +Defaults to @samp{"0600"}. +@end deftypevr + +@deftypevr {@code{unix-listener-configuration} parameter} string user +The user to own the the socket. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{unix-listener-configuration} parameter} string group +The group to own the socket. +Defaults to @samp{""}. +@end deftypevr + + +Available @code{fifo-listener-configuration} fields are: + +@deftypevr {@code{fifo-listener-configuration} parameter} file-name path +The file name on which to listen. +@end deftypevr + +@deftypevr {@code{fifo-listener-configuration} parameter} string mode +The access mode for the socket. +Defaults to @samp{"0600"}. +@end deftypevr + +@deftypevr {@code{fifo-listener-configuration} parameter} string user +The user to own the the socket. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{fifo-listener-configuration} parameter} string group +The group to own the socket. +Defaults to @samp{""}. +@end deftypevr + + +Available @code{inet-listener-configuration} fields are: + +@deftypevr {@code{inet-listener-configuration} parameter} string protocol +The protocol to listen for. +@end deftypevr + +@deftypevr {@code{inet-listener-configuration} parameter} string address +The address on which to listen, or empty for all addresses. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port +The port on which to listen. +@end deftypevr + +@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl? +Whether to use SSL for this service; @samp{yes}, @samp{no}, or +@samp{required}. +Defaults to @samp{#t}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count +Number of connections to handle before starting a new process. +Typically the only useful values are 0 (unlimited) or 1. 1 is more +secure, but 0 is faster. <doc/wiki/LoginProcess.txt>. +Defaults to @samp{1}. +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail +Number of processes to always keep waiting for more connections. +Defaults to @samp{0}. +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit +If you set @samp{service-count 0}, you probably need to grow +this. +Defaults to @samp{256000000}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict +Dict configuration, as created by the @code{dict-configuration} +constructor. + +Available @code{dict-configuration} fields are: + +@deftypevr {@code{dict-configuration} parameter} free-form-fields entries +A list of key-value pairs that this dict should hold. +Defaults to @samp{()}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs +List of passdb configurations, each one created by the +@code{passdb-configuration} constructor. + +Available @code{passdb-configuration} fields are: + +@deftypevr {@code{passdb-configuration} parameter} string driver +The driver that the passdb should use. Valid values include +@samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and +@samp{static}. +Defaults to @samp{"pam"}. +@end deftypevr + +@deftypevr {@code{passdb-configuration} parameter} free-form-args args +A list of key-value args to the passdb driver. +Defaults to @samp{()}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs +List of userdb configurations, each one created by the +@code{userdb-configuration} constructor. + +Available @code{userdb-configuration} fields are: + +@deftypevr {@code{userdb-configuration} parameter} string driver +The driver that the userdb should use. Valid values include +@samp{passwd} and @samp{static}. +Defaults to @samp{"passwd"}. +@end deftypevr + +@deftypevr {@code{userdb-configuration} parameter} free-form-args args +A list of key-value args to the userdb driver. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields +Override fields from passwd. +Defaults to @samp{()}. +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration +Plug-in configuration, created by the @code{plugin-configuration} +constructor. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces +List of namespaces. Each item in the list is created by the +@code{namespace-configuration} constructor. + +Available @code{namespace-configuration} fields are: + +@deftypevr {@code{namespace-configuration} parameter} string name +Name for this namespace. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} string type +Namespace type: @samp{private}, @samp{shared} or @samp{public}. +Defaults to @samp{"private"}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} string separator +Hierarchy separator to use. You should use the same separator for +all namespaces or some clients get confused. @samp{/} is usually a good +one. The default however depends on the underlying mail storage +format. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} string prefix +Prefix required to access this namespace. This needs to be +different for all namespaces. For example @samp{Public/}. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} string location +Physical location of the mailbox. This is in same format as +mail_location, which is also the default for it. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} boolean inbox? +There can be only one INBOX, and this setting defines which +namespace has it. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} boolean hidden? +If namespace is hidden, it's not advertised to clients via NAMESPACE +extension. You'll most likely also want to set @samp{list? #f}. This is mostly +useful when converting from another server with different namespaces +which you want to deprecate but still keep working. For example you can +create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/} +and @samp{mail/}. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} boolean list? +Show the mailboxes under this namespace with LIST command. This +makes the namespace visible for clients that don't support NAMESPACE +extension. The special @code{children} value lists child mailboxes, but +hides the namespace prefix. +Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions? +Namespace handles its own subscriptions. If set to @code{#f}, the +parent namespace handles them. The empty prefix should always have this +as @code{#t}.) +Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes +List of predefined mailboxes in this namespace. +Defaults to @samp{()}. + +Available @code{mailbox-configuration} fields are: + +@deftypevr {@code{mailbox-configuration} parameter} string name +Name for this mailbox. +@end deftypevr + +@deftypevr {@code{mailbox-configuration} parameter} string auto +@samp{create} will automatically create this mailbox. +@samp{subscribe} will both create and subscribe to the mailbox. +Defaults to @samp{"no"}. +@end deftypevr + +@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use +List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154. +Valid values are @code{\All}, @code{\Archive}, @code{\Drafts}, +@code{\Flagged}, @code{\Junk}, @code{\Sent}, and @code{\Trash}. +Defaults to @samp{()}. +@end deftypevr + +@end deftypevr + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir +Base directory where to store runtime data. +Defaults to @samp{"/var/run/dovecot/"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string login-greeting +Greeting message for clients. +Defaults to @samp{"Dovecot ready."}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks +List of trusted network ranges. Connections from these IPs are +allowed to override their IP addresses and ports (for logging and for +authentication checks). @samp{disable-plaintext-auth} is also ignored +for these networks. Typically you'd specify your IMAP proxy servers +here. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets +List of login access check sockets (e.g. tcpwrap). +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle? +Show more verbose process titles (in ps). Currently shows user name +and IP address. Useful for seeing who are actually using the IMAP +processes (e.g. shared mailboxes or if same uid is used for multiple +accounts). +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients? +Should all processes be killed when Dovecot master process shuts down. +Setting this to @code{#f} means that Dovecot can be upgraded without +forcing existing client connections to close (although that could also +be a problem if the upgrade is e.g. because of a security fix). +Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count +If non-zero, run mail commands via this many connections to doveadm +server, instead of running them directly in the same process. +Defaults to @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path +UNIX socket or host:port used for connecting to doveadm server. +Defaults to @samp{"doveadm-server"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment +List of environment variables that are preserved on Dovecot startup +and passed down to all of its child processes. You can also give +key=value pairs to always set specific settings. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth? +Disable LOGIN command and all other plaintext authentications unless +SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP +matches the local IP (i.e. you're connecting from the same computer), +the connection is considered secure and plaintext authentication is +allowed. See also ssl=required setting. +Defaults to @samp{#t}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size +Authentication cache size (e.g. @samp{#e10e6}). 0 means it's disabled. +Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set +for caching to be used. +Defaults to @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl +Time to live for cached data. After TTL expires the cached record +is no longer used, *except* if the main database lookup returns internal +failure. We also try to handle password changes automatically: If +user's previous authentication was successful, but this one wasn't, the +cache isn't used. For now this works only with plaintext +authentication. +Defaults to @samp{"1 hour"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl +TTL for negative hits (user not found, password mismatch). +0 disables caching them completely. +Defaults to @samp{"1 hour"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms +List of realms for SASL authentication mechanisms that need them. +You can leave it empty if you don't want to support multiple realms. +Many clients simply use the first one listed here, so keep the default +realm first. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm +Default realm/domain to use if none was specified. This is used for +both SASL realms and appending @@domain to username in plaintext +logins. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars +List of allowed characters in username. If the user-given username +contains a character not listed in here, the login automatically fails. +This is just an extra check to make sure user can't exploit any +potential quote escaping vulnerabilities with SQL/LDAP databases. If +you want to allow all characters, set this value to empty. +Defaults to @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation +Username character translations before it's looked up from +databases. The value contains series of from -> to characters. For +example @samp{#@@/@@} means that @samp{#} and @samp{/} characters are +translated to @samp{@@}. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-username-format +Username formatting before it's looked up from databases. You can +use the standard variables here, e.g. %Lu would lowercase the username, +%n would drop away the domain if it was given, or @samp{%n-AT-%d} would +change the @samp{@@} into @samp{-AT-}. This translation is done after +@samp{auth-username-translation} changes. +Defaults to @samp{"%Lu"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator +If you want to allow master users to log in by specifying the master +username within the normal username string (i.e. not using SASL +mechanism's support for it), you can specify the separator character +here. The format is then <username><separator><master username>. +UW-IMAP uses @samp{*} as the separator, so that could be a good +choice. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username +Username to use for users logging in with ANONYMOUS SASL +mechanism. +Defaults to @samp{"anonymous"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count +Maximum number of dovecot-auth worker processes. They're used to +execute blocking passdb and userdb queries (e.g. MySQL and PAM). +They're automatically created and destroyed as needed. +Defaults to @samp{30}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname +Host name to use in GSSAPI principal names. The default is to use +the name returned by gethostname(). Use @samp{$ALL} (with quotes) to +allow all keytab entries. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab +Kerberos keytab to use for the GSSAPI mechanism. Will use the +system default (usually /etc/krb5.keytab) if not specified. You may +need to change the auth service to run as root to be able to read this +file. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind? +Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon +and @samp{ntlm-auth} helper. +<doc/wiki/Authentication/Mechanisms/Winbind.txt>. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path +Path for Samba's @samp{ntlm-auth} helper binary. +Defaults to @samp{"/usr/bin/ntlm_auth"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay +Time to delay before replying to failed authentications. +Defaults to @samp{"2 secs"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert? +Require a valid SSL client certificate or the authentication +fails. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert? +Take the username from client's SSL certificate, using +@code{X509_NAME_get_text_by_NID()} which returns the subject's DN's +CommonName. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms +List of wanted authentication mechanisms. Supported mechanisms are: +@samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5}, +@samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi}, +@samp{otp}, @samp{skey}, and @samp{gss-spnego}. NOTE: See also +@samp{disable-plaintext-auth} setting. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers +List of IPs or hostnames to all director servers, including ourself. +Ports can be specified as ip:port. The default port is the same as what +director service's @samp{inet-listener} is using. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers +List of IPs or hostnames to all backend mail servers. Ranges are +allowed too, like 10.0.0.10-10.0.0.30. +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string director-user-expire +How long to redirect users to a specific server after it no longer +has any connections. +Defaults to @samp{"15 min"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer director-doveadm-port +TCP/IP port that accepts doveadm connections (instead of director +connections) If you enable this, you'll also need to add +@samp{inet-listener} for the port. +Defaults to @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash +How the username is translated before being hashed. Useful values +include %Ln if user can log in with or without @@domain, %Ld if mailboxes +are shared within domain. +Defaults to @samp{"%Lu"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string log-path +Log file to use for error messages. @samp{syslog} logs to syslog, +@samp{/dev/stderr} logs to stderr. +Defaults to @samp{"syslog"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string info-log-path +Log file to use for informational messages. Defaults to +@samp{log-path}. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path +Log file to use for debug messages. Defaults to +@samp{info-log-path}. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility +Syslog facility to use if you're logging to syslog. Usually if you +don't want to use @samp{mail}, you'll use local0..local7. Also other +standard facilities are supported. +Defaults to @samp{"mail"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose? +Log unsuccessful authentication attempts and the reasons why they +failed. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords? +In case of password mismatches, log the attempted password. Valid +values are no, plain and sha1. sha1 can be useful for detecting brute +force password attempts vs. user simply trying the same password over +and over again. You can also truncate the value to n chars by appending +":n" (e.g. sha1:6). +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug? +Even more verbose logging for debugging purposes. Shows for example +SQL queries. +Defaults to @samp{#f}. +@end deftypevr + +@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 + +@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 + +@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl? +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 + +@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 + +@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 + +@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): \""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format +Format to use for logging mail deliveries. You can use variables: +@table @code +@item %$ +Delivery status message (e.g. @samp{saved to INBOX}) +@item %m +Message-ID +@item %s +Subject +@item %f +From address +@item %p +Physical size +@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 +Dovecot the full location. + +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. + +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 +@item %d +domain part in user@@domain, empty if there's no domain +@item %h +home director +@end table + +See doc/wiki/Variables.txt for full list. Some examples: +@table @samp +@item maildir:~/Maildir +@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 + +@deftypevr {@code{dovecot-configuration} parameter} string mail-gid + +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 "mail" to give access to +/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 "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). +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access? +Allow full filesystem 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/. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable? +Don't use mmap() at all. This is required if you store indexes to +shared filesystems (NFS or clustered filesystem). +Defaults to @samp{#f}. +@end deftypevr + +@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 + +@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync +When to use fsync() or 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 +@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 + +@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index? +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 +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 + +@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 + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid +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 + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid + +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 + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid + +Defaults to @samp{0}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length +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. /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>. +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 /./ 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>. +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 + +@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir +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 +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 + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count +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 + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks +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. +@item dotlock-try +Same as dotlock, but if it fails because of permissions or because there +isn't enough disk space, just skip it. +@item fcntl +Use this if possible. Works with NFS too if lockd is used. +@item flock +May not exist in all systems. Doesn't work with NFS. +@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. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks + +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout +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, +EXAMINE, EXPUNGE or CHECK commands. If this is set, +@samp{mbox-dirty-syncs} is ignored. +Defaults to @samp{#f}. +@end deftypevr + +@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 + +@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 + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size +Maximum dbox file size until it's rotated. +Defaults to @samp{2000000}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval +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? +When creating new mdbox files, immediately preallocate their size to +@samp{mdbox-rotate-size}. This setting currently works only in Linux +with some filesystems (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. + +Directory root where to store mail attachments. Disabled, if empty. +Defaults to @samp{""}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size +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 +Filesystem backend to use for saving attachments: +@table @code +@item posix +No SiS done by Dovecot (but this might help FS's own deduplication) +@item sis posix +SiS with immediate byte-by-byte comparison during saving +@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 +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 + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit + +Defaults to @samp{100}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit + +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 + +@deftypevr {@code{dovecot-configuration} parameter} string default-login-user +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 + +@deftypevr {@code{dovecot-configuration} parameter} string ssl? +SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>. +Defaults to @samp{"required"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert +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 + +@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 + +@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 + +@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl? +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 + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field +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} hours ssl-parameters-regenerate +How often to regenerate the SSL parameters file. Generation is +quite CPU intensive operation. The value is in hours, 0 disables +regeneration entirely. +Defaults to @samp{168}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-protocols +SSL protocols to use. +Defaults to @samp{"!SSLv2"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list +SSL ciphers to use. +Defaults to @samp{"ALL:!LOW:!SSLv2:!EXP:!aNULL"}. +@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 + +@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address +Address to use when sending rejection mails. +Default is postmaster@@<your domain>. %d expands to recipient domain. +Defaults to @samp{""}. +@end deftypevr + +@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 + +@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 + +@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path +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 + +@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject +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 +Human readable error message for rejection mails. You can use +variables: + +@table @code +@item %n +CRLF +@item %r +reason +@item %s +original subject +@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 + +@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 + +@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 + +@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe? +Should automatically created mailboxes be also automatically +subscribed?. +Defaults to @samp{#f}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length +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 + +@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format +IMAP logout format string: +@table @code +@item %i +total number of bytes read from client +@item %o +total number of bytes sent to client. +@end table +Defaults to @samp{"in=%i out=%o"}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string imap-capability +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 + +@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 + +@deftypevr {@code{dovecot-configuration} parameter} string imap-id-send +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 +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 +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". + +@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. + +@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. +@end table +Defaults to @samp{()}. +@end deftypevr + +@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host +Host allowed in URLAUTH URLs sent by client. "*" allows all. +Defaults to @samp{""}. +@end deftypevr + + +Whew! Lots of configuration options. The nice thing about it though is +that GuixSD has a complete interface to Dovecot's configuration +language. This allows not only a nice way to declare configurations, +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} paramter to +@code{dovecot-service}. As its name indicates, an opaque configuration +does not have easy reflective capabilities. + +Available @code{opaque-dovecot-configuration} fields are: + +@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot +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 + +For example, if your @code{dovecot.conf} is just the empty string, you +could instantiate a dovecot service like this: + +@example +(dovecot-service #:config + (opaque-dovecot-configuration + (string ""))) +@end example + @node Web Services @subsubsection Web Services |