summaryrefslogtreecommitdiffstats
path: root/doc/wiki/PasswordDatabase.PAM.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/wiki/PasswordDatabase.PAM.txt')
-rw-r--r--doc/wiki/PasswordDatabase.PAM.txt234
1 files changed, 234 insertions, 0 deletions
diff --git a/doc/wiki/PasswordDatabase.PAM.txt b/doc/wiki/PasswordDatabase.PAM.txt
new file mode 100644
index 0000000..29646cf
--- /dev/null
+++ b/doc/wiki/PasswordDatabase.PAM.txt
@@ -0,0 +1,234 @@
+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).
+
+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 '%s' 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:
+
+ * Use '/etc/pam.d/imap' and '/etc/pam.d/pop3':
+
+ ---%<----------------------------------------------------------------------
+ passdb {
+ driver = pam
+ args = %s
+ }
+ ---%<----------------------------------------------------------------------
+
+ * Use '/etc/pam.d/mail':
+
+ ---%<----------------------------------------------------------------------
+ passdb {
+ driver = pam
+ 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 {
+ driver = 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.
+
+Limiting the number of PAM lookups
+----------------------------------
+
+Usually in other software PAM is used to do only a single lookup in a process,
+so PAM plugin writers haven't done much testing on what happens when multiple
+lookups are done. Because of this, many PAM plugins leak memory and possibly
+have some other problems when doing multiple lookups. If you notice that PAM
+authentication stops working after some time, you can limit the number of
+lookups done by the auth worker process before it dies:
+
+---%<-------------------------------------------------------------------------
+passdb {
+ driver = pam
+ args = max_requests=100
+}
+---%<-------------------------------------------------------------------------
+
+The default max_requests value is 100.
+
+Username changing
+-----------------
+
+A PAM module can change the username.
+
+Making PAM plugin failure messages visible
+------------------------------------------
+
+You can replace the default "Authentication failed" reply with PAM's failure
+reply by setting:
+
+---%<-------------------------------------------------------------------------
+passdb {
+ driver = pam
+ args = failure_show_msg=yes
+}
+---%<-------------------------------------------------------------------------
+
+This can be useful with e.g. pam_opie to find out which one time password
+you're supposed to give:
+
+---%<-------------------------------------------------------------------------
+1 LOGIN username otp
+1 NO otp-md5 324 0x1578 ext, Response:
+---%<-------------------------------------------------------------------------
+
+Restrict IP-Addresses allowed to connect via PAM
+------------------------------------------------
+
+You can restrict the IP-Addresses allowed to connect via PAM:
+
+---%<-------------------------------------------------------------------------
+passdb {
+ driver = pam
+ override_fields = allow_nets=10.1.100.0/23,2001:db8:a0b:12f0::/64
+}
+---%<-------------------------------------------------------------------------
+
+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 {
+ driver = pam
+ # username and service
+ args = cache_key=%u%s *
+}
+---%<-------------------------------------------------------------------------
+
+---%<-------------------------------------------------------------------------
+# 1MB auth cache size
+auth_cache_size = 1024
+passdb {
+ driver = 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 (using 'args = *' instead of the default 'dovecot' service):
+
+---%<-------------------------------------------------------------------------
+imap auth requisite pam_authtok_get.so.1
+imap auth required pam_unix_auth.so.1
+imap account requisite pam_roles.so.1
+imap account required pam_unix_account.so.1
+imap session required pam_unix_session.so.1
+pop3 auth requisite pam_authtok_get.so.1
+pop3 auth required pam_unix_auth.so.1
+pop3 account requisite pam_roles.so.1
+pop3 account required pam_unix_account.so.1
+pop3 session required pam_unix_session.so.1
+---%<-------------------------------------------------------------------------
+
+Mac OS X
+--------
+
+On Mac OS X, the '/etc/pam.d/dovecot' file might look like this:
+
+---%<-------------------------------------------------------------------------
+auth required pam_opendirectory.so try_first_pass
+account required pam_nologin.so
+account required pam_opendirectory.so
+password required pam_opendirectory.so
+---%<-------------------------------------------------------------------------
+
+...which, as the equivalent of '/etc/pam.d/login' on OS X 10.9. For very old
+versions of OS X (e.g. 10.4), can be represented (where?) as the following in
+the on that OS:
+
+---%<-------------------------------------------------------------------------
+passdb {
+ driver = pam
+ args = login
+}
+---%<-------------------------------------------------------------------------
+
+On older versions of Mac OS X, "passwd" can be used as a userdb to fill in UID,
+GID, and homedir information after PAM was used as a passdb, even though
+Directory Services prevents "passdb passwd" from working as a username/password
+authenticator. This will provide full system user authentication with true
+homedir mail storage, without resorting to a single virtual mail user or LDAP:
+
+---%<-------------------------------------------------------------------------
+userdb {
+ driver = passwd
+}
+---%<-------------------------------------------------------------------------
+
+(This file was created from the wiki on 2019-06-19 12:42)