Dovecot processes
=================

Dovecot is split into multiple processes where each process does only one
thing. This is partially because it makes the code cleaner, but alsobecause it
allows setting up different privileges for each process. Themost important
processes are:

 * Master process (dovecot)
 * Login processes (imap-login, pop3-login)
 * Authentication process (dovecot-auth)
 * Mail processes (imap, pop3)

Master process
--------------

This process keeps all the other processes running. If a child process dies, 
another one is restarted automatically. It always runs as root,unless you're
specifically running everything under a single normal UID.

The master process reads the configuration file and exports the settings to
other processes via environment variables.

All logging also goes through master process. This avoids problems with
rotating log files, as there's only a single process to send a signal toreopen
the log file. Also writing to the same log file (if not using syslog)isn't
necessarily safe to do in multiple processes concurrently.

Making the logging go through master process gives also a couple of advantages
from security and reliability point of view: All log lines canbe prefixed with
the process's name and the username who was logged in, withoutthe possibility
for the process itself to forge them. Flooding logs canalso be prevented. By
default Dovecot allows non-privileged processes towrite 10 lines per second
before it begins to delay reading their input,which finally causes the badly
behaving process to start blocking onwriting to stderr instead of eating all
the CPU and disk space.

In Dovecot 2.0 design the master process is split to three parts: Master
process which does nothing more than keep the processes running, configprocess
which handles reading the configuration file (supporting also eg.SQL storages!)
and log process which handles the logging.

Login processes
---------------

The login processes implement the minimum of IMAP and POP3 protocols required
before user logs in successfully. There are separate processes(and binaries) to
handle IMAP and POP3 protocols.

This processes are run with least possible privileges. Unfortunately the
default UNIX security model still allows them to do much more than theywould
have to: Accept new connections on a socket, connect to new UNIXsockets and
read and write to existing file descriptors. Still, the loginprocess is by
default run under a user account that has no special accessto anything, and
inside a non-writable chroot where only a couple of filesexist. Doing any
damage inside there should be difficult.

When a new connection comes, one of the login processes accept()s it. After
that the client typically does nothing more than ask the server'scapability
list and then log in. The client may also start TLS sessionbefore logging in.

Authentication is done by talking to authentication process. The login process
is completely untrusted by authentication process, so even ifattacker is able
to execute arbitrary code inside a login process, he can'tlog in without a
valid username and password.

After receiving a successful authentication reply from authentication process,
the login process sends the file descriptor to master processwhich creates a
new mail process and transfers the fd into it. Before doingthat, the master
process verifies from authentication process that theauthentication really was
successful.

By default each login process will handle only a single connection and
afterwards kill itself (but see SSL proxying below). This way attacker can't
see other people'sconnections. This can however be disabled
('login_process_per_connection=no'), in which case the security of the design
suffers greatly.

A newly thought out idea to balance security and performance is to use a
separate process for each connection, but instead of destroying the process
after the login is finished, it could be reused for the next connection. To
avoid leaving sensitive information into memory (such as usernames and
passwords), most of the memory is allocated using 'system_clean_pool', which
causes the memory frees and reallocations to clear the memory before freeing
it. Also the connection to authentication process is reopened to make sure the
previous connection's authentication attempt can't be reused in any way. This
cleaning isn't done in Dovecot v1.0.

The login processes handle SSL/TLS connections themselves completely. They keep
proxying the connection to mail processes for the entire lifetime ofthe
connection. This way if a security hole is found from the SSL library,an
authenticated user still can't execute code outside the login process.

See <LoginProcess.txt> for more information about different settings related to
login processes.

Authentication process
----------------------

Authentication process handles everything related to the actual authentication:
SASL authentication mechanisms, looking up and verifyingthe passwords and
looking up user information.

It listens for two different kinds of connections: untrusted authentication
client connections (from login processes) and master connections (frommaster
process, but also from Dovecot LDA). The client connections are onlyallowed to
try to authenticate. The master connections are allowed to askif an
authentication request with given ID was successful, and also to lookup user
information based on a username. This user lookup feature is usedby Dovecot
LDA.

Each client connection tells their process ID to the authentication process in
a handshake. If a connection with the same PID already exists, an erroris
logged and the new connection is refused. Although this makes DoSattacks
possible, it won't go unnoticed for long and I don't see this as areal issue
for now.

Having authentication process know the PID of the client connection allows all
authentication requests to be mapped to one specific client connection.Since
the master process knows the login process's real PID, it's used whenasking
from authentication process if the request was successful. Thismakes it
impossible for a login process to try to fake another login process's login
requests. Faking PIDs will also bequite pointless.

Once the master process has done the verification request for a successful
authentication request, the request is freed from memory. The requests arealso
freed about 2 minutes after their creation, regardless of the statethey
currently are in.

For blocking password and user database backends (eg. MySQL) separate "worker
processes" are used. Initially there exists only one of them, butmore are
created as needed.<PAM> [PasswordDatabase.PAM.txt] can be configured to use
worker processes instead of doing the forking itself, but this isn't currently
done by default and there may be problems related to it. Also<checkpassword>
[PasswordDatabase.CheckPassword.txt] currently does the forking itself.

Mail processes
--------------

These processes handle the actual post-login mail handling using the privileges
of the logged in user. It's possible to chroot these processes,but practically
it's usually more trouble than worth.

See <mail process design> [Design.MailProcess.txt] for their internal design
documentation.

(This file was created from the wiki on 2008-06-20 04:42)
