This documentation is for Dovecot v1.x, see wiki2 for v2.x documentation.


Authentication is split into four parts:

  1. Authentication mechanisms
  2. Password schemes
  3. Password databases
  4. User databases

Authentication Mechanisms

Authentication mechanism means the protocol that an IMAP or POP3 client uses to communicate with Dovecot to perform the authentication. The most simple one is PLAIN, in which the client simply sends the password unencrypted to Dovecot. All clients support PLAIN authentication, but obviously there's the problem that anyone listening the network can steal the password. For that reason (and some others) other mechanisms were implemented.

Non-PLAIN mechanisms have one major disadvantage however. In server side the password must be stored in a special format or in plaintext. This makes it impossible to use most mechanisms with commonly used DES and MD5 crypted passwords.

Today however many people use SSL, and there's no problem with sending unencrypted password inside SSL secured connection. So if you're using SSL, you probably don't need to bother worrying about anything else than PLAIN mechanism.

Other non-PLAIN mechanisms include:

Password Schemes

Passwords can be stored in password database in many different formats. Usually they should be stored encrypted just to make sure if an attacker gets into your computer he can't easily read everyone's passwords.

With non-PLAIN authentication mechanisms you either have to store the password in their special format (which is incompatible with everything else except PLAIN), or you'll have to store the passwords as plaintext.

With PLAIN mechanism it doesn't matter in which format the password is stored locally, because Dovecot will internally encrypt the sent plaintext password to match the storage scheme.

Often you already have the passwords in some specific format, so best idea is to just keep using them. Otherwise just pick one to use, for example SHA1.

Currently supported password schemes are:

Default password scheme can usually be specified for password database. You can override it by prefixing password with {SCHEME}. For example "{PLAIN}password". Note that not all password databases support changing the scheme. With some you might cause incompatibilities with other software using it (eg. passwd, shadow) and with others it simply isn't possible at all because of the way they work (eg. PAM).

Dovecot 1.0-tests contain dovecotpw utility which can be used to easily generate passwords for wanted scheme.

Password Databases

Dovecot authenticates user using password database. It needs to contain only user names and their passwords.

Dovecot 1.0-tests support defining multiple password databases, so that if password doesn't match in the first database, it checks the next one. This can be useful if you want to easily support having both local system users in /etc/passwd but also virtual users. This isn't possible in 0.99 releases.

Currently supported password databases:

User Databases

Dovecot gets user's UID, GID, home directory and mail location from user database after user is authenticated. User and password databases may be the same one or they may be different depending on your needs.

For more information about UID and GID, see UserIds. For more information about home directory and mail location see VirtualUsers.

Currently supported user databases:

Database Descriptions


Most commonly used as user database. Many systems use shadow passwords nowadays so it doesn't usually work as password database. BSDs are an exception to this, they still set the password field even with shadow passwords.


Works at least with Linux and Solaris, but nowadays PAM is usually preferred to this.


Pluggable Authentication Modules. This is the most common way to authenticate users nowadays. The PAM configuration is usually in /etc/pam.d/ directory. By default Dovecot uses dovecot PAM service name, so the configuration is read from /etc/pam.d/dovecot file. You can change this by appending the wanted service name after auth_passdb = pam, eg. auth_passdb = pam imap would use /etc/pam.d/imap. You can also set the service to * in which case Dovecot automatically uses either imap or pop3 service depending on which one user is using to login.

By giving -session parameter you can make Dovecot open a PAM session and close it immediately. Some PAM plugins need this. [1.0-test79 and later only]

PAM doesn't provide a user database, so you have to use something else for that - passwd or static usually.

We should work with Linux PAM, Solaris PAM, OpenPAM (FreeBSD) and ApplePAM (Mac OS X).

Here's an example /etc/pam.d/dovecot configuration file which uses standard UNIX authentication:

auth    required nullok
account required


This is compatible with regular /etc/passwd, and a password file used by libpam-pwdfile. It's in the following format:


For password database, it's enough to have only user and password fields. For user database, you need to set also uid and gid and preferrably home (see VirtualUsers).

Flags are currently unused.

mail field can be used to override default_mail_env setting in configuration file.

The password field can be in three formats:


See doc/dovecot-ldap.conf for more information. Password and user databases may use different configuration files to keep the information in separate locations. If both refer to same file, they share the same LDAP connection.


See doc/dovecot-mysql.conf for more information. Password and user databases may use different configuration files to keep the information in separate locations. If both refer to same file, they share the same SQL connection.


See doc/dovecot-pgsql.conf for more information. Password and user databases may use different configuration files to keep the information in separate locations. If both refer to same file, they share the same SQL connection.


Static user database can be used when you want to use only single UID and GID for all users and home directory can be specified with a simple template. The syntax is:

auth_passdb = static uid=<uid> gid=<gid> home=<dir template> mail=<dir template>

The home and mail are both optional. The directory templates can use variables just like default_mail_env setting in config file. See [wiki:Variables Variables].


FIXME: I'm not actually sure who uses this. Some BSDs I guess.. at least openbsd


This is an external software intended to make handling virtual domains easier. Supports Qmail and Postfix. See []

Currently vpopmail works only with PLAIN mechanism. vpopmail also supports storing passwords in plaintext which would allow adding support for other mechanisms, but for now no-one has been interested.