This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.
Differences between revisions 6 and 7
Revision 6 as of 2007-03-25 05:48:43
Size: 4987
Editor: 68-116-217-17
Revision 7 as of 2007-06-27 20:22:14
Size: 5100
Editor: TimoSirainen
Deletions are marked like this. Additions are marked like this.
Line 49: Line 49:

== Username changing ==

A PAM module can change the username, but this works only with {{{blocking=yes}}}.

PAM - Pluggable Authentication Modules

This is the most common way to authenticate system users nowadays. PAM is not itself a password database, but rather its configuration tells the system how exactly to do the authentication. Usually this means using the module, which authenticates user from the system's shadow password file.

Because PAM is not an actual database, only plaintext authentication mechanisms can be used with PAM. PAM cannot be used as a user database either (although static user templates could be used to provide the same effect). Usually PAM is used with [wiki:AuthDatabase/Passwd passwd] (NSS) or [wiki:UserDatabase/Static static] user databases.

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

Non-forking PAM lookups

By default dovecot-auth forks a new process for each PAM lookup, which is then destroyed after the lookup is done. This may have some problems however because the forked processes share all the file descriptors with the parent process. For example if you're using nss_ldap and your PAM plugin does a NSS lookup, it's entirely possible that two PAM child processes are using the same LDAP connection to do the lookup at the same time and they get their replies mixed, causing wrong user's information to be used.

Setting blocking=yes uses the alternative way: dovecot-auth worker processes do the PAM lookups. This however currently means that a worker process is doing one PAM lookup after another. Usually PAM is used to do only a single lookup in a process, so this may cause memory leaks in PAM plugins to eat your memory or maybe other problems.

passdb pam {
  args = blocking=yes

Service name

The PAM configuration is usually in the /etc/pam.d/ directory, but some systems may use a single file, /etc/pam.conf. By default Dovecot uses dovecot as the PAM service name, so the configuration is read from /etc/pam.d/dovecot. You can change this by giving the wanted service name in the args parameter. You can also set the service to * in which case Dovecot automatically uses either imap or pop3 as the service, depending on the actual service the user is logging in to. Here are a few examples:

passdb pam {
  # use /etc/pam.d/imap and /etc/pam.d/pop3
  args = *

passdb pam {
  # use /etc/pam.d/mail
  args = mail

PAM sessions

By giving a session=yes parameter, you can make Dovecot open a PAM session and close it immediately. Some PAM plugins need this, for instance pam_mkhomedir. With this parameter, dovecot.conf might look something like this:

passdb pam {
  args = session=yes dovecot

PAM credentials

By giving a setcred=yes parameter, you can make Dovecot create PAM credentials. Some PAM plugins need this. The credentials are never deleted however, so using this might cause problems with other PAM plugins.

Username changing

A PAM module can change the username, but this works only with blocking=yes.


Dovecot supports caching password lookups by setting auth_cache_size to non-zero value. For this to work with PAM, you'll also have to give cache_key parameter. Usually the user is authenticated only based on the username and password, but PAM plugins may do all kinds of other checks as well, so this can't be relied on. For this reason the cache_key must contain all the [wiki:Variables variables] that may affect authentication. The commonly used variables are:

  • %u - Username. You'll most likely want to use this.

  • %s - Service. If you use * as the service name you'll most likely want to use this.

  • %r - Remote IP address. Use this if you do any IP related checks.

  • %l - Local IP address. Use this if you do any checks based on the local IP address that was connected to.


# 1MB auth cache size
auth_cache_size = 1024

passdb pam {
  # username and service
  args = cache_key=%u%s *

# 1MB auth cache size
auth_cache_size = 1024

passdb pam {
  # username, remote IP and local IP
  args = cache_key=%u%r%l dovecot



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

auth    required nullok
account required 


For Solaris you will have to edit /etc/pam.conf. Here is a working Solaris example:

imap    auth    required
imap    account required
imap    session required 

Mac OS X

On Mac OS X, the /etc/pam.d/dovecot file should look like this:

auth       required
auth       sufficient
auth       sufficient
auth       required
account    required
password   required
session    required 

None: PasswordDatabase/PAM (last edited 2019-09-12 08:23:18 by MichaelSlusarz)