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: Change the username (eg. lowercase it). See User extra field.

  • login_user: Master passdb can use this to change the username.

    New in version v2.2.13.

  • allow_nets: Allow user to log in from only specified IPs (checks against remote client IP). See allow_nets extra field.

    • allow_real_nets: Allow user’s network connection to log in from only specified IPs (checks against real remote IP, e.g. a Dovecot proxy).

  • proxy and proxy_maybe: Proxy the connection to another IMAP/POP3 server. See Proxy PasswordDatabase.

  • host: Send login referral to client (if proxy=y field isn’t set). See Login referrals.

  • nologin: User isn’t actually allowed to log in even if the password matches, with optionally a different reason given as the authentication failure message. See Nologin extra field.

  • nodelay: Don’t delay reply to client in case of an authentication failure. See Nodelay extra field.

  • nopassword: If you want to allow all passwords, use an empty password and this field.

  • fail: If set, explicitly fails the passdb lookup.

    New in version v2.2.22.

  • k5principals: if using auth_mechanisms = gssapi , may contain Kerberos v5 principals allowed to map to the current user, bypassing the internal call to krb5_kuserok() . The database must support credentials lookup.

    New in version v2.2.

  • delay_until= <UNIX timestamp>[+<max random secs>] : Delay login until this time. The timestamp must be less than 5 minutes into future or the login will fail with internal error. The extra random seconds can be used to avoid a load spike of everybody getting logged in at exactly the same time.

    New in version v2.2.25.

  • noauthenticate: Do not perform any authentication, just store extra fields if user is found.

    New in version v2.2.26+/v2.3.

  • forward_<anything>: In proxy/director, pass the variable to next hop as forward_<anything>.

    New in version v2.2.26+/v2.3.

  • event_<name>: Import name=value to login events.

    New in version v2.3.21.

How to return these extra fields depends on the password database you use. See Password databases (passdb) pages on how to do it. Some passdbs however don’t support returning them at all, such as PAM.

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 Databases (userdb) extra fields. Typically this is done only when using Prefetch User Database.

Note

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 nonexistent if its value is NULL.

The following suffixes added to a field name are handled specially:

:protected

Set this field only if it hasn’t been set before.

:remove

Remove this field entirely.

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