Next: , Previous: , Up: Services   [Contents][Index]


6.2.7.9 Mail Services

The (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.

Dovecot Service

Scheme Procedure: dovecot-service [#:config (dovecot-configuration)]

Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.

By default, Dovecot does not need much configuration; the default configuration object created by (dovecot-configuration) will suffice if your mail is delivered to ~/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 maildir~/.mail, one would instantiate the Dovecot service like this:

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

The available configuration parameters follow. Each parameter definition is preceded by its type; for example, ‘string-list foo’ indicates that the 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 dovecot.conf file that you want to port over from some other system; see the end for more details.

Available dovecot-configuration fields are:

dovecot-configuration parameter: package dovecot

The dovecot package.

dovecot-configuration parameter: comma-separated-string-list listen

A list of IPs or hosts where to listen for connections. ‘*’ listens on all IPv4 interfaces, ‘::’ listens on all IPv6 interfaces. If you want to specify non-default ports or anything more complex, customize the address and port fields of the ‘inet-listener’ of the specific services you are interested in.

dovecot-configuration parameter: protocol-configuration-list protocols

List of protocols we want to serve. Available protocols include ‘imap’, ‘pop3’, and ‘lmtp’.

Available protocol-configuration fields are:

protocol-configuration parameter: string name

The name of the protocol.

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 ‘"/var/run/dovecot/auth-userdb"’.

protocol-configuration parameter: space-separated-string-list mail-plugins

Space separated list of plugins to load.

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 ‘10’.

dovecot-configuration parameter: service-configuration-list services

List of services to enable. Available services include ‘imap’, ‘imap-login’, ‘pop3’, ‘pop3-login’, ‘auth’, and ‘lmtp’.

Available service-configuration fields are:

service-configuration parameter: string kind

The service kind. Valid values include director, imap-login, pop3-login, lmtp, imap, pop3, auth, auth-worker, dict, tcpwrap, quota-warning, or anything else.

service-configuration parameter: listener-configuration-list listeners

Listeners for the service. A listener is either a unix-listener-configuration, a fifo-listener-configuration, or an inet-listener-configuration. Defaults to ‘()’.

Available unix-listener-configuration fields are:

unix-listener-configuration parameter: string path

Path to the file, relative to base-dir field. This is also used as the section name.

unix-listener-configuration parameter: string mode

The access mode for the socket. Defaults to ‘"0600"’.

unix-listener-configuration parameter: string user

The user to own the socket. Defaults to ‘""’.

unix-listener-configuration parameter: string group

The group to own the socket. Defaults to ‘""’.

Available fifo-listener-configuration fields are:

fifo-listener-configuration parameter: string path

Path to the file, relative to base-dir field. This is also used as the section name.

fifo-listener-configuration parameter: string mode

The access mode for the socket. Defaults to ‘"0600"’.

fifo-listener-configuration parameter: string user

The user to own the socket. Defaults to ‘""’.

fifo-listener-configuration parameter: string group

The group to own the socket. Defaults to ‘""’.

Available inet-listener-configuration fields are:

inet-listener-configuration parameter: string protocol

The protocol to listen for.

inet-listener-configuration parameter: string address

The address on which to listen, or empty for all addresses. Defaults to ‘""’.

inet-listener-configuration parameter: non-negative-integer port

The port on which to listen.

inet-listener-configuration parameter: boolean ssl?

Whether to use SSL for this service; ‘yes’, ‘no’, or ‘required’. Defaults to ‘#t’.

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 ‘1’.

service-configuration parameter: non-negative-integer process-min-avail

Number of processes to always keep waiting for more connections. Defaults to ‘0’.

service-configuration parameter: non-negative-integer vsz-limit

If you set ‘service-count 0’, you probably need to grow this. Defaults to ‘256000000’.

dovecot-configuration parameter: dict-configuration dict

Dict configuration, as created by the dict-configuration constructor.

Available dict-configuration fields are:

dict-configuration parameter: free-form-fields entries

A list of key-value pairs that this dict should hold. Defaults to ‘()’.

dovecot-configuration parameter: passdb-configuration-list passdbs

A list of passdb configurations, each one created by the passdb-configuration constructor.

Available passdb-configuration fields are:

passdb-configuration parameter: string driver

The driver that the passdb should use. Valid values include ‘pam’, ‘passwd’, ‘shadow’, ‘bsdauth’, and ‘static’. Defaults to ‘"pam"’.

passdb-configuration parameter: space-separated-string-list args

Space separated list of arguments to the passdb driver. Defaults to ‘""’.

dovecot-configuration parameter: userdb-configuration-list userdbs

List of userdb configurations, each one created by the userdb-configuration constructor.

Available userdb-configuration fields are:

userdb-configuration parameter: string driver

The driver that the userdb should use. Valid values include ‘passwd’ and ‘static’. Defaults to ‘"passwd"’.

userdb-configuration parameter: space-separated-string-list args

Space separated list of arguments to the userdb driver. Defaults to ‘""’.

userdb-configuration parameter: free-form-args override-fields

Override fields from passwd. Defaults to ‘()’.

dovecot-configuration parameter: plugin-configuration plugin-configuration

Plug-in configuration, created by the plugin-configuration constructor.

dovecot-configuration parameter: list-of-namespace-configuration namespaces

List of namespaces. Each item in the list is created by the namespace-configuration constructor.

Available namespace-configuration fields are:

namespace-configuration parameter: string name

Name for this namespace.

namespace-configuration parameter: string type

Namespace type: ‘private’, ‘shared’ or ‘public’. Defaults to ‘"private"’.

namespace-configuration parameter: string separator

Hierarchy separator to use. You should use the same separator for all namespaces or some clients get confused. ‘/’ is usually a good one. The default however depends on the underlying mail storage format. Defaults to ‘""’.

namespace-configuration parameter: string prefix

Prefix required to access this namespace. This needs to be different for all namespaces. For example ‘Public/’. Defaults to ‘""’.

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 ‘""’.

namespace-configuration parameter: boolean inbox?

There can be only one INBOX, and this setting defines which namespace has it. Defaults to ‘#f’.

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 ‘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 ‘~/mail/’, ‘~%u/mail/’ and ‘mail/’. Defaults to ‘#f’.

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. The special children value lists child mailboxes, but hides the namespace prefix. Defaults to ‘#t’.

namespace-configuration parameter: boolean subscriptions?

Namespace handles its own subscriptions. If set to #f, the parent namespace handles them. The empty prefix should always have this as #t). Defaults to ‘#t’.

namespace-configuration parameter: mailbox-configuration-list mailboxes

List of predefined mailboxes in this namespace. Defaults to ‘()’.

Available mailbox-configuration fields are:

mailbox-configuration parameter: string name

Name for this mailbox.

mailbox-configuration parameter: string auto

create’ will automatically create this mailbox. ‘subscribe’ will both create and subscribe to the mailbox. Defaults to ‘"no"’.

mailbox-configuration parameter: space-separated-string-list special-use

List of IMAP SPECIAL-USE attributes as specified by RFC 6154. Valid values are \All, \Archive, \Drafts, \Flagged, \Junk, \Sent, and \Trash. Defaults to ‘()’.

dovecot-configuration parameter: file-name base-dir

Base directory where to store runtime data. Defaults to ‘"/var/run/dovecot/"’.

dovecot-configuration parameter: string login-greeting

Greeting message for clients. Defaults to ‘"Dovecot ready."’.

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). ‘disable-plaintext-auth’ is also ignored for these networks. Typically you would specify your IMAP proxy servers here. Defaults to ‘()’.

dovecot-configuration parameter: space-separated-string-list login-access-sockets

List of login access check sockets (e.g. tcpwrap). Defaults to ‘()’.

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 ‘#f’.

dovecot-configuration parameter: boolean shutdown-clients?

Should all processes be killed when Dovecot master process shuts down. Setting this to #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 ‘#t’.

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 ‘0’.

dovecot-configuration parameter: string doveadm-socket-path

UNIX socket or host:port used for connecting to doveadm server. Defaults to ‘"doveadm-server"’.

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.

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 ‘#t’.

dovecot-configuration parameter: non-negative-integer auth-cache-size

Authentication cache size (e.g. ‘#e10e6’). 0 means it’s disabled. Note that bsdauth, PAM and vpopmail require ‘cache-key’ to be set for caching to be used. Defaults to ‘0’.

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 ‘"1 hour"’.

dovecot-configuration parameter: string auth-cache-negative-ttl

TTL for negative hits (user not found, password mismatch). 0 disables caching them completely. Defaults to ‘"1 hour"’.

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 ‘()’.

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 ‘""’.

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 ‘"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@"’.

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 ‘#@/@’ means that ‘#’ and ‘/’ characters are translated to ‘@’. Defaults to ‘""’.

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 ‘%n-AT-%d’ would change the ‘@’ into ‘-AT-’. This translation is done after ‘auth-username-translation’ changes. Defaults to ‘"%Lu"’.

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 ‘*’ as the separator, so that could be a good choice. Defaults to ‘""’.

dovecot-configuration parameter: string auth-anonymous-username

Username to use for users logging in with ANONYMOUS SASL mechanism. Defaults to ‘"anonymous"’.

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 ‘30’.

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 ‘$ALL’ (with quotes) to allow all keytab entries. Defaults to ‘""’.

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 ‘""’.

dovecot-configuration parameter: boolean auth-use-winbind?

Do NTLM and GSS-SPNEGO authentication using Samba’s winbind daemon and ‘ntlm-auth’ helper. <doc/wiki/Authentication/Mechanisms/Winbind.txt>. Defaults to ‘#f’.

dovecot-configuration parameter: file-name auth-winbind-helper-path

Path for Samba’s ‘ntlm-auth’ helper binary. Defaults to ‘"/usr/bin/ntlm_auth"’.

dovecot-configuration parameter: string auth-failure-delay

Time to delay before replying to failed authentications. Defaults to ‘"2 secs"’.

dovecot-configuration parameter: boolean auth-ssl-require-client-cert?

Require a valid SSL client certificate or the authentication fails. Defaults to ‘#f’.

dovecot-configuration parameter: boolean auth-ssl-username-from-cert?

Take the username from client’s SSL certificate, using X509_NAME_get_text_by_NID() which returns the subject’s DN’s CommonName. Defaults to ‘#f’.

dovecot-configuration parameter: space-separated-string-list auth-mechanisms

List of wanted authentication mechanisms. Supported mechanisms are: ‘plain’, ‘login’, ‘digest-md5’, ‘cram-md5’, ‘ntlm’, ‘rpa’, ‘apop’, ‘anonymous’, ‘gssapi’, ‘otp’, ‘skey’, and ‘gss-spnego’. NOTE: See also ‘disable-plaintext-auth’ setting.

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 ‘inet-listener’ is using. Defaults to ‘()’.

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 ‘()’.

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 ‘"15 min"’.

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 ‘inet-listener’ for the port. Defaults to ‘0’.

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 ‘"%Lu"’.

dovecot-configuration parameter: string log-path

Log file to use for error messages. ‘syslog’ logs to syslog, ‘/dev/stderr’ logs to stderr. Defaults to ‘"syslog"’.

dovecot-configuration parameter: string info-log-path

Log file to use for informational messages. Defaults to ‘log-path’. Defaults to ‘""’.

dovecot-configuration parameter: string debug-log-path

Log file to use for debug messages. Defaults to ‘info-log-path’. Defaults to ‘""’.

dovecot-configuration parameter: string syslog-facility

Syslog facility to use if you’re logging to syslog. Usually if you don’t want to use ‘mail’, you’ll use local0..local7. Also other standard facilities are supported. Defaults to ‘"mail"’.

dovecot-configuration parameter: boolean auth-verbose?

Log unsuccessful authentication attempts and the reasons why they failed. Defaults to ‘#f’.

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 ‘#f’.

dovecot-configuration parameter: boolean auth-debug?

Even more verbose logging for debugging purposes. Shows for example SQL queries. Defaults to ‘#f’.

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 ‘auth-debug’. Defaults to ‘#f’.

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 ‘#f’.

dovecot-configuration parameter: boolean verbose-ssl?

Show protocol level SSL errors. Defaults to ‘#f’.

dovecot-configuration parameter: string log-timestamp

Prefix for each line written to log file. % codes are in strftime(3) format. Defaults to ‘"\"%b %d %H:%M:%S \""’.

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.

dovecot-configuration parameter: string login-log-format

Login log format. %s contains ‘login-log-format-elements’ string, %$ contains the data we want to log. Defaults to ‘"%$: %s"’.

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 ‘"\"%s(%u): \""’.

dovecot-configuration parameter: string deliver-log-format

Format to use for logging mail deliveries. You can use variables:

%$

Delivery status message (e.g. ‘saved to INBOX’)

%m

Message-ID

%s

Subject

%f

From address

%p

Physical size

%w

Virtual size.

Defaults to ‘"msgid=%m: %$"’.

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 ‘mail-location’ setting.

There are a few special variables you can use, eg.:

%u

username

%n

user part in user@domain, same as %u if there’s no domain

%d

domain part in user@domain, empty if there’s no domain

%h

home director

See doc/wiki/Variables.txt for full list. Some examples:

maildir:~/Maildir
mbox:~/mail:INBOX=/var/mail/%u
mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%

Defaults to ‘""’.

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 ‘""’.

dovecot-configuration parameter: string mail-gid

Defaults to ‘""’.

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 ‘""’.

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 ‘""’.

dovecot-configuration parameter: boolean mail-full-filesystem-access?

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/. Defaults to ‘#f’.

dovecot-configuration parameter: boolean mmap-disable?

Don’t use mmap() at all. This is required if you store indexes to shared file systems (NFS or clustered file system). Defaults to ‘#f’.

dovecot-configuration parameter: boolean dotlock-use-excl?

Rely on ‘O_EXCL’ to work when creating dotlock files. NFS supports ‘O_EXCL’ since version 3, so this should be safe to use nowadays by default. Defaults to ‘#t’.

dovecot-configuration parameter: string mail-fsync

When to use fsync() or fdatasync() calls:

optimized

Whenever necessary to avoid losing important data

always

Useful with e.g. NFS when write()s are delayed

never

Never use it (best performance, but crashes can lose data).

Defaults to ‘"optimized"’.

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 ‘#f’.

dovecot-configuration parameter: boolean mail-nfs-index?

Mail index files also exist in NFS. Setting this to yes requires ‘mmap-disable? #t’ and ‘fsync-disable? #f’. Defaults to ‘#f’.

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 ‘mmap-disable’. Defaults to ‘"fcntl"’.

dovecot-configuration parameter: file-name mail-temp-dir

Directory in which LDA/LMTP temporarily stores incoming mails >128 kB. Defaults to ‘"/tmp"’.

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 ‘first-valid-uid’ is set to 0. Defaults to ‘500’.

dovecot-configuration parameter: non-negative-integer last-valid-uid

Defaults to ‘0’.

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 ‘1’.

dovecot-configuration parameter: non-negative-integer last-valid-gid

Defaults to ‘0’.

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 ‘50’.

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 ‘login-chroot’ ‘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 ‘()’.

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 ‘mail-chroot’. <doc/wiki/Chrooting.txt>. Defaults to ‘""’.

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 ‘"/var/run/dovecot/auth-userdb"’.

dovecot-configuration parameter: file-name mail-plugin-dir

Directory where to look up mail plugins. Defaults to ‘"/usr/lib/dovecot"’.

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 ‘()’.

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 ‘0’.

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 ‘"30 secs"’.

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 ‘#f’.

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 ‘dirent->d_type’ this check is free and it’s done always regardless of this setting). Defaults to ‘#f’.

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 ‘#t’.

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 ‘#f’.

dovecot-configuration parameter: space-separated-string-list mbox-read-locks

Which locking methods to use for locking mbox. There are four available:

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.

dotlock-try

Same as dotlock, but if it fails because of permissions or because there isn’t enough disk space, just skip it.

fcntl

Use this if possible. Works with NFS too if lockd is used.

flock

May not exist in all systems. Doesn’t work with NFS.

lockf

May not exist in all systems. Doesn’t work with NFS.

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.

dovecot-configuration parameter: space-separated-string-list mbox-write-locks
dovecot-configuration parameter: string mbox-lock-timeout

Maximum time to wait for lock (all of them) before aborting. Defaults to ‘"5 mins"’.

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 ‘"2 mins"’.

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 ‘#t’.

dovecot-configuration parameter: boolean mbox-very-dirty-syncs?

Like ‘mbox-dirty-syncs’, but don’t do full syncs even with SELECT, EXAMINE, EXPUNGE or CHECK commands. If this is set, ‘mbox-dirty-syncs’ is ignored. Defaults to ‘#f’.

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 ‘#t’.

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 ‘0’.

dovecot-configuration parameter: non-negative-integer mdbox-rotate-size

Maximum dbox file size until it’s rotated. Defaults to ‘2000000’.

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 ‘"1d"’.

dovecot-configuration parameter: boolean mdbox-preallocate-space?

When creating new mdbox files, immediately preallocate their size to ‘mdbox-rotate-size’. This setting currently works only in Linux with some file systems (ext4, xfs). Defaults to ‘#f’.

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 ‘""’.

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 ‘128000’.

dovecot-configuration parameter: string mail-attachment-fs

File system backend to use for saving attachments:

posix

No SiS done by Dovecot (but this might help FS’s own deduplication)

sis posix

SiS with immediate byte-by-byte comparison during saving

sis-queue posix

SiS with delayed comparison and deduplication.

Defaults to ‘"sis posix"’.

dovecot-configuration parameter: string mail-attachment-hash

Hash format to use in attachment filenames. You can add any text and variables: %{md4}, %{md5}, %{sha1}, %{sha256}, %{sha512}, %{size}. Variables can be truncated, e.g. %{sha256:80} returns only first 80 bits. Defaults to ‘"%{sha1}"’.

dovecot-configuration parameter: non-negative-integer default-process-limit

Defaults to ‘100’.

dovecot-configuration parameter: non-negative-integer default-client-limit

Defaults to ‘1000’.

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 ‘256000000’.

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 ‘"dovenull"’.

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 ‘"dovecot"’.

dovecot-configuration parameter: string ssl?

SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>. Defaults to ‘"required"’.

dovecot-configuration parameter: string ssl-cert

PEM encoded X.509 SSL/TLS certificate (public key). Defaults to ‘"</etc/dovecot/default.pem"’.

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 ‘"</etc/dovecot/private/default.pem"’.

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 ‘""’.

dovecot-configuration parameter: string ssl-ca

PEM encoded trusted certificate authority. Set this only if you intend to use ‘ssl-verify-client-cert? #t’. The file should contain the CA certificate(s) followed by the matching CRL(s). (e.g. ‘ssl-ca </etc/ssl/certs/ca.pem’). Defaults to ‘""’.

dovecot-configuration parameter: boolean ssl-require-crl?

Require that CRL check succeeds for client certificates. Defaults to ‘#t’.

dovecot-configuration parameter: boolean ssl-verify-client-cert?

Request client to send a certificate. If you also want to require it, set ‘auth-ssl-require-client-cert? #t’ in auth section. Defaults to ‘#f’.

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 ‘auth-ssl-username-from-cert? #t’. Defaults to ‘"commonName"’.

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 ‘168’.

dovecot-configuration parameter: string ssl-protocols

SSL protocols to use. Defaults to ‘"!SSLv2"’.

dovecot-configuration parameter: string ssl-cipher-list

SSL ciphers to use. Defaults to ‘"ALL:!LOW:!SSLv2:!EXP:!aNULL"’.

dovecot-configuration parameter: string ssl-crypto-device

SSL crypto device to use, for valid values run "openssl engine". Defaults to ‘""’.

dovecot-configuration parameter: string postmaster-address

Address to use when sending rejection mails. %d expands to recipient domain. Defaults to ‘"postmaster@%d"’.

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 ‘""’.

dovecot-configuration parameter: boolean quota-full-tempfail?

If user is over quota, return with temporary failure instead of bouncing the mail. Defaults to ‘#f’.

dovecot-configuration parameter: file-name sendmail-path

Binary to use for sending mails. Defaults to ‘"/usr/sbin/sendmail"’.

dovecot-configuration parameter: string submission-host

If non-empty, send mails via this SMTP host[:port] instead of sendmail. Defaults to ‘""’.

dovecot-configuration parameter: string rejection-subject

Subject: header to use for rejection mails. You can use the same variables as for ‘rejection-reason’ below. Defaults to ‘"Rejected: %s"’.

dovecot-configuration parameter: string rejection-reason

Human readable error message for rejection mails. You can use variables:

%n

CRLF

%r

reason

%s

original subject

%t

recipient

Defaults to ‘"Your message to <%t> was automatically rejected:%n%r"’.

dovecot-configuration parameter: string recipient-delimiter

Delimiter character between local-part and detail in email address. Defaults to ‘"+"’.

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 ‘""’.

dovecot-configuration parameter: boolean lda-mailbox-autocreate?

Should saving a mail to a nonexistent mailbox automatically create it?. Defaults to ‘#f’.

dovecot-configuration parameter: boolean lda-mailbox-autosubscribe?

Should automatically created mailboxes be also automatically subscribed?. Defaults to ‘#f’.

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 ‘64000’.

dovecot-configuration parameter: string imap-logout-format

IMAP logout format string:

%i

total number of bytes read from client

%o

total number of bytes sent to client.

Defaults to ‘"in=%i out=%o"’.

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 ‘""’.

dovecot-configuration parameter: string imap-idle-notify-interval

How long to wait between "OK Still here" notifications when client is IDLEing. Defaults to ‘"2 mins"’.

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 ‘""’.

dovecot-configuration parameter: string imap-id-log

ID fields sent by client to log. * means everything. Defaults to ‘""’.

dovecot-configuration parameter: space-separated-string-list imap-client-workarounds

Workarounds for various client bugs:

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".

tb-extra-mailbox-sep

Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and adds extra ‘/’ suffixes to mailbox names. This option causes Dovecot to ignore the extra ‘/’ instead of treating it as invalid mailbox name.

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.

Defaults to ‘()’.

dovecot-configuration parameter: string imap-urlauth-host

Host allowed in URLAUTH URLs sent by client. "*" allows all. Defaults to ‘""’.

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 dovecot.conf up and running. In that case, you can pass an opaque-dovecot-configuration as the #:config parameter to dovecot-service. As its name indicates, an opaque configuration does not have easy reflective capabilities.

Available opaque-dovecot-configuration fields are:

opaque-dovecot-configuration parameter: package dovecot

The dovecot package.

opaque-dovecot-configuration parameter: string string

The contents of the dovecot.conf, as a string.

For example, if your dovecot.conf is just the empty string, you could instantiate a dovecot service like this:

(dovecot-service #:config
                 (opaque-dovecot-configuration
                  (string "")))

OpenSMTPD Service

Scheme Variable: opensmtpd-service-type

This is the type of the OpenSMTPD service, whose value should be an opensmtpd-configuration object as in this example:

(service opensmtpd-service-type
         (opensmtpd-configuration
           (config-file (local-file "./my-smtpd.conf"))))
Data Type: opensmtpd-configuration

Data type representing the configuration of opensmtpd.

package (default: opensmtpd)

Package object of the OpenSMTPD SMTP server.

config-file (default: %default-opensmtpd-file)

File-like object of the OpenSMTPD configuration file to use. By default it listens on the loopback network interface, and allows for mail from users and daemons on the local machine, as well as permitting email to remote servers. Run man smtpd.conf for more information.

Exim Service

Scheme Variable: exim-service-type

This is the type of the Exim mail transfer agent (MTA), whose value should be an exim-configuration object as in this example:

(service exim-service-type
         (exim-configuration
           (config-file (local-file "./my-exim.conf"))))

In order to use an exim-service-type service you must also have a mail-aliases-service-type service present in your operating-system (even if it has no aliases).

Data Type: exim-configuration

Data type representing the configuration of exim.

package (default: exim)

Package object of the Exim server.

config-file (default: #f)

File-like object of the Exim configuration file to use. If its value is #f then use the default configuration file from the package provided in package. The resulting configuration file is loaded after setting the exim_user and exim_group configuration variables.

Mail Aliases Service

Scheme Variable: mail-aliases-service-type

This is the type of the service which provides /etc/aliases, specifying how to deliver mail to users on this system.

(service mail-aliases-service-type
         '(("postmaster" "bob")
           ("bob" "bob@example.com" "bob@example2.com")))

The configuration for a mail-aliases-service-type service is an association list denoting how to deliver mail that comes to this system. Each entry is of the form (alias addresses ...), with alias specifying the local alias and addresses specifying where to deliver this user’s mail.

The aliases aren’t required to exist as users on the local system. In the above example, there doesn’t need to be a postmaster entry in the operating-system’s user-accounts in order to deliver the postmaster mail to bob (which subsequently would deliver mail to bob@example.com and bob@example2.com).


Next: , Previous: , Up: Services   [Contents][Index]