Service configuration
=====================

Contents


 1. Service configuration

     1. Service basics

     2. Service privileges

     3. Service limits

     4. Service listeners

         1. unix_listeners and fifo_listeners

         2. inet_listeners

 2. Default services

     1. anvil

     2. auth

     3. auth-worker

     4. config

     5. dict

     6. director

     7. dns_client

     8. doveadm

     9. imap, pop3, managesieve

     10. imap-login, pop3-login, managesieve-login

     11. indexer

     12. indexer-worker

     13. ipc

     14. lmtp

     15. log

     16. ssl-params

     17. stats

This page describes Dovecot's services comprehensively. Most admins don't need
to know these details. The important service settings are described in the
'example-config/conf.d/10-master.conf' file.

Service basics
--------------

executable:
  The binary path to execute and its parameters. If the path doesn't begin with
  '/', it's relative to *base_dir*.

type:
  Type of this service:
   * "" is the default.
   * "startup" creates one process at startup. For example SSL parameters are
     generated at startup because of this, instead of only after the first SSL
     connection arrives.
   * "login" is used by login processes. The login processes have "all
     processes full" notification fd. It's used by the processes to figure out
     when no more client connections can be accepted because client and process
     limits have been reached. The login processes can then kill some of their
     oldest connections that haven't logged in yet.
   * "log", "config" and "anvil" are treated specially by these specific
     processes.

protocol:
  If non-empty, this service is enabled only when the protocol name is listed
  in *protocols* setting.

idle_kill:
  If a process doesn't appear to be doing anything after this much time, notify
  it that it should kill itself if it's not doing anything.*process_min_avail*
  setting overrides this. If set to 0,*default_idle_kill* is used.

Service privileges
------------------

user:
  UNIX user (UID) which runs this process. *default_login_user* setting's value
  should be used for type=login processes and *default_internal_user* should be
  used for other processes that don't require root privileges.

group:
  The primary UNIX group (GID) which runs this process.

extra_groups:
  Secondary UNIX groups that this process belongs to.

privileged_group:
  Secondary UNIX group, which is disabled by default, but can be enabled by the
  process. This setting is probably never needed
  directly.*mail_privileged_group* setting is a more user friendly way to use
  this setting for mail processes.

chroot:
  The processes are chrooted to this directory at startup. Relative to
  *base_dir*.

drop_priv_before_exec:
  Drop all privileges after forking, but before executing the binary. This is
  mainly useful for dumping core files on non-Linux OSes, since the processes
  are no longer in "setuid" mode. This setting can't be used with non-empty
  chroot.

Service limits
--------------

client_limit:
  Maximum number of simultaneous client connections. If set to 0,
  *default_client_limit* is used instead.

service_count:
  Number of client connections to handle until the process kills itself. 0
  means unlimited.

process_limit:
  Maximum number of processes that can exist for this service. If set to 0,
  *default_process_limit* is used instead.

process_min_avail:
  Minimum number of processes that always should be available to accept more
  client connections. For service_count=1 processes this decreases the latency
  for handling new connections. For service_count!=1 processes it could be set
  to the number of CPU cores on the system to balance the load among them.

vsz_limit:
  Limit the process's address space (both RLIMIT_DATA and RLIMIT_AS if
  available). When the space is reached, some memory allocations may start
  failing with "Out of memory", or the kernel may kill the process with signal
  9. This setting is mainly intended to prevent memory leaks from eating up all
  of the memory, but there can be also legitimate reasons why the process
  reaches this limit. For example a huge mailbox may not be accessed if this
  limit is too low. The default value (18446744073709551615 = 2^64-1) sets the
  limit to *default_vsz_limit*, while 0 disables the limit entirely.

Service listeners
-----------------

unix_listeners and fifo_listeners
---------------------------------

path:
  Path to the file, relative to *base_dir* setting. This is also used as the
  section name.

user:
  Owner of the file. Defaults to 0 (root).

group:
  Group of the file. Defaults to 0 (root/wheel).

mode:
  Mode of the file. Defaults to 0700. Note that 0700 is an octal value, while
  700 is a different decimal value. Setting mode to 0 disables the listener.

inet_listeners
--------------

name:
  Section name of this listener. It is meant to be descriptive for humans (e.g.
  "imap", "imaps").

address:
  Space separated list of IP addresses / host names to listen on. "*" means all
  IPv4 addresses, "::" means all IPv6 addresses. Defaults to *listen* setting.

port:
  Port number where to listen. 0 disables the listener.

ssl:
  If yes, the listener does an immediate SSL/TLS handshake after accepting a
  connection. This is needed for the legacy imaps and pop3s ports.

Default services
================

anvil
-----

The anvil process tracks state of users and their connections.

 * *chroot=empty* and *user=$default_internal_user*, because anvil doesn't need
   access to anything.
 * *process_limit=1*, because there can be only one.
 * *idle_kill=4294967295s*, because it should never die or all of its tracked
   state would be lost.
 * "doveadm who" and some other doveadm commands connect to anvil's UNIX
   listener and request its state.

auth
----

The master auth process. There are 4 types of auth client connections:

 1. client: Only SASL authentication is allowed. This can be safely exposed to
    entire world.
 2. userdb: userdb lookups and passdb lookups (without the password itself) can
    be done for any user, and a list of users can be requested. This may or may
    not be a security issue. Access to userdb lookup is commonly needed by
    dovecot-lda, doveadm and other tools.
 3. login: Starts a two phase user login by performing authenticating (same as
    "client" type). Used by login processes.
 4. master: Finishes the two phase user login by performing a userdb lookup
    (similar to "userdb" type). Used by post-login processes (e.g. imap, pop3).

With UNIX listeners the client type is selected based on the filename after the
last "-" in the filename. For example "anything-userdb" is of "userdb" type.
The default type is "client" for inet insteners and unrecognized UNIX
listeners. You can add as many client and userdb listeners as you want (and you
probably shouldn't touch the login/master listeners).

 * *client_limit* should be large enough to handle all the simultaneous
   connections. Typically only login processes use long lasting auth
   connections, while other processes do only quick lookups and disconnect
   afterwards.
 * *process_limit=1*, because there can be only one auth master process.
 * *user=$default_internal_user*, because it typically doesn't need permissions
   to do anything (PAM lookups are done by auth-workers).
 * *chroot* could be set (to e.g. "empty") if passdb/userdb doesn't need to
   read any files (e.g. SQL, LDAP config is read before chroot)

auth-worker
-----------

Auth master process connects to auth worker processes. It is mainly used by
passdbs and userdbs that do potentially long running lookups. For example MySQL
supports only synchronous lookups, so each query is run in a separate auth
worker process that does nothing else during the query. PostgreSQL and LDAP
supports asynchronous lookups, so those don't use worker processes at all. With
some passdbs and userdbs you can select if worker processes should be used.

 * *client_limit=1*, because only the master auth process connects to auth
   worker.
 * *service_count=1*, because auth master stops extra idling workers by
   disconnecting from them.
 * *process_limit* should be a bit higher than *auth_worker_max_count* setting.

 * *user=root* by default, because by default PAM authentication is used, which
   usually requires reading '/etc/shadow'. If this isn't needed, it's a good
   idea to change this to something else, such as *$default_internal_user*.
 * *chroot* could also be set if possible.

config
------

Config process reads and parses the 'dovecot.conf' file, and exports the parsed
data in simpler format to config clients.

 * *user=root*, because the process needs to be able to reopen the config files
   during a config reload, and often some parts of the config having secrets
   are readable only by root.
 * Only root should be able to connect to its UNIX listener, unless there are
   no secrets in the configuration. Passwords are obviously secrets, but less
   obviously *ssl_key* is also a secret, since it contains the actual SSL key
   data instead of only a filename.

dict
----

Dovecot has a "lib-dict" API for doing simple key-value lookups/updates in
various backends (SQL, file, others in future). This is optionally used by
things like quota, expire plugin and other things in future. It would be
wasteful for each mail process to separately create a connection to SQL, so
usually they go through the "proxy" dict backend. These proxy connections are
the client connections of dict processes.

 * *client_limit=1*, because dict lookups are synchronous and the client is
   supposed to disconnect immediately after the lookup.
 * *user=$default_internal_user*, because the proxy dict lookups are typically
   SQL lookups, which require no filesystem access. (The SQL config files are
   read while still running as root.)
 * The dict clients can do any kind of dict lookups and updates for all users,
   so they can be rather harmful if exposed to an attacker. That's why by
   default only root can connect to dict socket. Unfortunately that is too
   restrictive for all setups, so the permissions need to be changed so that
   Dovecot's mail processes (and only them) can connect to it.

director
--------

<Director.txt> tracker process, which hooks into all auth-client and
auth-userdb connections.

 * *process_limit=1*, because only one process can keep track of everyone's
   state.
 * *user=$default_internal_user*, because director doesn't access any files.
 * *chroot* can't be set, because it still needs to be connect to auth process.

 * Connections are basically proxying auth connections, so they have similar
   security considerations.

dns_client
----------

Used by "lib-dns" library to perform asynchronous DNS lookups. The dns-client
processes internally use the synchronous 'gethostbyname()' function.

 * *client_limit=1*, because the DNS lookup is synchronous.
 * *user=$default_internal_user*, because typically no special privileged files
   need to be read.
 * *chroot* can be used only if it contains 'etc/resolv.conf' and other files
   necessary for DNS lookups.

doveadm
-------

It's possible to run doveadm mail commands via doveadm server processes. This
is useful for running doveadm commands for multiple users simultaneously, and
it's also useful in a multiserver system where doveadm can automatically
connect to the correct backend to run the command.

 * *client_limit=1*, because doveadm command execution is synchronous.
 * *service_count=1* just in case there were any memory leaks. This could be
   set to some larger value (or 0) for higher performance.
 * *user=root*, but the privileges are (temporarily) dropped to the mail user's
   privileges after userdb lookup. If only a single UID is used, user can be
   set to the mail UID for higher security, because the process can't gain root
   privileges anymore.

imap, pop3, managesieve
-----------------------

Post-login process for handling IMAP/POP3/ManageSieve client connections.

 * *client_limit* may be increased from the default 1 to save some CPU and
   memory, but it also increases the latency when one process serving multiple
   clients it waiting for a long time for a lock or disk I/O. In future these
   waits may be reduced or avoided completely, but for now it's not safe to set
   this value higher than 1 in enterprise mail systems. For small mostly-idling
   hobbyist servers a larger number may work without problems.
 * *service_count* can be changed from 1 if only a single UID is used for mail
   users. This is improves performance, but it's less secure, because bugs in
   code may leak email data from another user's earlier connection.
 * *process_limit* defaults to 1024, which means that the number of
   simultaneous IMAP (or POP3 or <ManageSieve.txt>) connections is limited by
   this setting. If you expect more connections, increase this value.

imap-login, pop3-login, managesieve-login
-----------------------------------------

See <LoginProcess.txt>.

indexer
-------

Indexer master process, which tracks and prioritizes indexing requests from
mail processes. The actual indexing is done by indexer-worker processes. The
indexing means both updating Dovecot's internal index and cache files with new
messages and more importantly updating full text search indexes (if enabled).
The indexer master process guarantees that the FTS index is never modified by
more than one process.

 * *process_limit=1*, because only one process can keep the FTS guarantee.
 * *user=$default_internal_user*, because the process doesn't need any
   permissions.
 * *chroot* could be set to *$base_dir* for extra security. It still needs to
   be able to connect to indexer-worker socket.

indexer-worker
--------------

Indexer worker process.

 * *client_limit=1*, because indexing is a synchronous operation.
 * *process_limit* defaults to 10, because the FTS index updating can eat a lot
   of CPU and disk I/O. You may need to adjust this value depending on your
   system.
 * *user=root*, but the privileges are (temporarily) dropped to the mail user's
   privileges after userdb lookup. If only a single UID is used, user can be
   set to the mail UID for higher security, because the process can't gain root
   privileges anymore.

ipc
---

IPC hub process.

 * *process_limit=1*, because there can be only one hub.
 * *chroot=empty* and *user=$default_internal_user*, because it doesn't need
   any files and there are no outbound connections.
 * The "ipc" UNIX socket can be used to send any commands to other processes,
   such as killing a specific user's connection. It is somewhat security
   sensitive.

lmtp
----

LMTP process for delivering new mails.

 * *client_limit=1*, because most of the time spent on an LMTP client is spent
   waiting for disk I/O and other blocking operations. There's no point in
   having more clients waiting around during that doing nothing.
 * *user=root*, but the privileges are (temporarily) dropped to the mail user's
   privileges after userdb lookup. If only a single UID is used, user can be
   set to the mail UID for higher security, because the process can't gain root
   privileges anymore.

log
---

All processes started via Dovecot master process log their messages via the
"log" process. This allows some nice features compared to directly logging via
syslog.

 * *process_limit=1*, because the log process keeps track of all the other
   logging processes.
 * *user=root*, because it guarantees being able to write to syslog socket and
   to the log files directly.

ssl-params
----------

Build SSL parameters every n days, based on *ssl_parameters_regenerate*
setting.

 * *type=startup* so that the (re)generation can be started immediately at
   startup when needed, instead of waiting until the first SSL handshake
   starts.

stats
-----

Mail process statistics tracking. Its behavior is very similar to the anvil
process, but anvil's data is of higher importance and lower traffic than stats,
so stats are tracked in a separate process.

(This file was created from the wiki on 2013-11-24 04:42)