Password database extra fields
==============================

The primary purpose of a password database lookup is to return the password for
a given user. It may however also return other fields which are treated
specially:

 * * <user> [PasswordDatabase.ExtraFields.User.txt]*: Change the username (eg.
   lowercase it).
 * *login_user*: Master passdb can use this to change the username. (v2.2.13+)
 * * <allow_nets> [PasswordDatabase.ExtraFields.AllowNets.txt]*: Allow user to
   log in from only specified IPs.
 * * <proxy and proxy_maybe> [PasswordDatabase.ExtraFields.Proxy.txt]*: Proxy
   the connection to another IMAP/POP3 server.
 * * <host> [PasswordDatabase.ExtraFields.Host.txt]*: Send login referral to
   client (if proxy=y field isn't set).
 * * <nologin> [PasswordDatabase.ExtraFields.NoLogin.txt]*: User isn't actually
   allowed to log in even if the password matches, with optionally a different
   reason given as the authentication failure message.
 * * <nodelay> [PasswordDatabase.ExtraFields.NoDelay.txt]*: Don't delay reply
   to client in case of an authentication failure.
 * *nopassword*: If you want to allow all passwords, use an empty password and
   this field.
 * *fail*: If set, explicitly fails the passdb lookup. (v2.2.22+)

How to return these extra fields depends on the password database you use. See
the <password database> [PasswordDatabase.txt] pages on how to do it. Some
passdbs however don't support returning them at all, such as <PAM>
[PasswordDatabase.PAM.txt].

The password database may also return fields prefixed with 'userdb_'. These
fields are only saved and used later as if they came from the <user database>
[UserDatabase.txt]'s extra fields. Typically this is done only when using
<prefetch userdb> [UserDatabase.Prefetch.txt].

Note that boolean fields are true always if the field exists. So 'nodelay',
'nodelay=yes', 'nodelay=no' and 'nodelay=0' all mean that the nodelay field is
true. With SQL the field is considered to be non-existent if its value is NULL.

Examples
--------

SQL
---

*dovecot-sql.conf.ext*:

---%<-------------------------------------------------------------------------
password_query = SELECT userid as user, password, 'Y' as proxy, host \
  FROM users WHERE userid = '%u'
---%<-------------------------------------------------------------------------

LDAP
----

*dovecot-ldap.conf*:

---%<-------------------------------------------------------------------------
pass_attrs = \
  =user=%{ldap:user}, \
  =password=%{ldap:userPassword},
  =proxy=%{ldap:proxyEnabled}, \
  =host=%{ldap:hostName}
---%<-------------------------------------------------------------------------

Note about the "proxy", "proxy_maybe" and any other boolean type fields: these
represent an existence test. Currently this translates to "will proxy (or
proxy_maybe) if this attribute exists".  This allows the proxy behaviour to be
selectable per user.  To have it "always" on, use a template, e.g.:

---%<-------------------------------------------------------------------------
pass_attrs = \
  =user=%{ldap:user}, \
  =password=%{ldap:userPassword},
  =proxy=y, \
  =host=%{ldap:hostName}
---%<-------------------------------------------------------------------------

passwd-file
-----------

---%<-------------------------------------------------------------------------
user:{plain}pass::::::proxy=y host=127.0.0.1
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2016-03-30 04:43)