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 'pam_unix.so'
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<passwd> [AuthDatabase.Passwd.txt] (NSS) or <static>
[UserDatabase.Static.txt] 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.
Caching
-------
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
<variables> [Variables.txt] 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.
Examples:
---%<-------------------------------------------------------------------------
# 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
}
---%<-------------------------------------------------------------------------
Examples
--------
Linux
-----
Here is an example '/etc/pam.d/dovecot' configuration file which uses standard
UNIX authentication:
---%<-------------------------------------------------------------------------
auth required pam_unix.so nullok
account required pam_unix.so
---%<-------------------------------------------------------------------------
Solaris
-------
For Solaris you will have to edit '/etc/pam.conf'. Here is a working Solaris
example:
---%<-------------------------------------------------------------------------
imap auth required pam_unix_auth.so.1
imap account required pam_unix_account.so.1
imap session required pam_unix_session.so.1
---%<-------------------------------------------------------------------------
Mac OS X
--------
On Mac OS X, the '/etc/pam.d/dovecot' file should look like this:
---%<-------------------------------------------------------------------------
auth required pam_nologin.so
auth sufficient pam_securityserver.so
auth sufficient pam_unix.so
auth required pam_deny.so
account required pam_permit.so
password required pam_deny.so
session required pam_uwtmp.so
---%<-------------------------------------------------------------------------
(This file was created from the wiki on 2007-06-15 04:42)
