Password Databases (`passdb`)

Dovecot uses passdb and userdb as part of the authentication process.

passdb authenticates the user. It also provides any other pre-login information needed for users, such as:

Which server user is proxied to.
If user should be allowed to log in at all (temporarily or permanently).

Passdb Lookups	Dovecot Proxy	Dovecot Backend
IMAP & POP3 logins	YES	YES
LMTP mail delivery	YES	YES
doveadm commands	YES	YES

Passwords

The password can be in any format that Dovecot supports, but you need to tell the format to Dovecot because it won't try to guess it.

The SQL and LDAP configuration files have the default_pass_scheme setting for this.

If you have passwords in multiple formats, or the passdb doesn't have such a setting, you'll need to prefix each password with {<scheme>}: {PLAIN}cleartext-password or {PLAIN-MD5}1a1dc91c907325c69271ddf0c944bc72.

Dovecot authenticates users against password databases. It can also be used to configure things like proxy passdb.

You can use multiple databases, so if the password doesn't match in the first database, Dovecot checks the next one. This can be useful if you want to easily support having both virtual users and also local system users (see multiple authentication databases).

Success/Failure Database

These databases simply verify if the given password is correct for the user. Dovecot doesn't get the correct password from the database, it only gets a success or a failure reply. This means that these databases can't be used with non-cleartext authentication mechanisms.

Databases that belong to this category are:

Database	Description
PAM	Pluggable Authentication Modules.
IMAP	Authenticate against remote IMAP server.
OAuth2	Authenticate against OAuth2 provider.
BSDAuth	BSD authentication (deprecated, unsupported).

Lookup Database

Dovecot does a lookup based on the username and possibly other information (e.g. IP address) and verifies the password validity itself.

Databases that support looking up only passwords, but no user or extra fields:

Database	Description
Passwd	System users (NSS, `/etc/passwd`, or similar).

INFO

Dovecot supports reading all password schemes from passwd databases (if prefix is specified), but that is of course incompatible with all other tools using/modifying the passwords.

Databases that support looking up everything:

Database	Description
Passwd-file	`/etc/passwd`-like file.
LDAP	Lightweight Directory Access Protocol.
SQL	SQL database (PostgreSQL, MySQL, SQLite, Cassandra).
Static	Static `passdb` for simple configurations.
Lua	Lua script for authentication.

Fields

Fields that the lookup can return:

`password`

User's password. See password schemes.

`password_noscheme`

Like password, but if a password begins with {, assume it belongs to the password itself instead of treating it as a password schemes prefix. This is usually needed only if you use cleartext passwords.

`user`

Returning a user field can be used to change the username.

Typically used only for case changes (e.g. UseR -> user). See passdb: User Extra Fields.

`username`

Like user, but doesn't drop existing domain name (e.g. username=foo for user@domain gives foo@domain).

`domain`

Updates the domain part of the username.

User Extra Fields

Other special passdb: Extra Fields.

Settings

`passdb`

Default	[None]
Value	Named List Filter
Dependencies	`passdb_driver`
See Also	passdb `passdb_name` `passdb_driver`

Creates a new passdb. The filter name refers to the passdb_name setting.

`passdb_args`

Default	[None]
Value	string

Arguments for the passdb driver. The format of this value depends on the passdb driver. Each one uses different args.

`passdb_default_password_scheme`

Default	`PLAIN` specific passdb have different defaults
Value	string

The scheme that passwords are in the passdb, unless overridden by the passdb entry (typically by prefixing with {SCHEME}).

`passdb_deny`

Default	`no`
Value	boolean

If yes and the user is found from the denied user database the authentication will fail.

`passdb_driver`

Default	[None]
Value	string
See Also	`passdb_name` passdb

The driver used for this password database. If empty, defaults to passdb_name. See passdb for the list of available drivers.

`passdb_fields`

Default	[None]
Value	String List
See Also	passdb: Extra Fields

Passdb fields (and passdb: Extra Fields). The values can contain %variables. All %variables used here reflect the state after the current passdb lookup, and can refer to fields returned by previous passdb lookups. Depending on the passdb driver, it can also refer to variable fields returned by it (e.g. %{ldap:fieldName}).

INFO

The LDAP driver provides additional specific variables, see LDAP authentication for more details.

For example:

passdb ldap {
  fields {
    user = %{ldap:userId}
    proxy = yes
    host = %{ldap:proxyHost}
  }
}

`passdb_fields_import_all`

Default	`yes` For `passdb ldap` the default is `no`.
Value	boolean
See Also	`passdb_fields`

If yes, import all fields returned by the passdb lookup. If no, require passdb_fields to explicitly add wanted fields.

`passdb_master`

Default	`no`
Value	boolean

If yes and the user is found from the master users the user is allowed to login as other users.

`passdb_mechanisms_filter`

Default	[None]
Value	Boolean List
Changes	Added: 2.4.0

Skip the passdb if non-empty and the current auth mechanism is not listed here. If the value contains lookup, it matches for non-authenticating passdb lookups (e.g. lmtp/doveadm lookups).

Example:

passdb passwd-file {
  driver = passwd-file
  mechanisms_filter = PLAIN LOGIN
  # ...
}

`passdb_name`

Default	[None]
Value	string
See Also	`passdb` `passdb_driver`

Name of the passdb. The passdb filter name refers to this setting. If the passdb_driver setting is empty, the passdb_name is used as the driver. This allows doing e.g.:

passdb passwd-file {
  passwd_file_path = /etc/dovecot/passwd

`passdb_pam_failure_show_msg`

Default	`no`
Value	boolean

Replace the default Authentication failed reply with PAM's failure.

`passdb_pam_max_requests`

Default	[None]
Value	unsigned integer
See Also	`service_restart_request_count`

Number of requests a auth-worker process handles for passdb pam before it dies. This configures similar behaviour as the service_restart_request_count setting but it limits only the number of pam passdb requests, not all requests to be handled by an auth-worker.

`passdb_pam_service_name`

Default	`dovecot`
Value	string

The PAM service name to be used with the pam passdb.

`passdb_pam_session`

Default	`no`
Value	boolean

Make Dovecot open a PAM session and close it immediately.

`passdb_pam_setcred`

Default	`no`
Value	boolean

Make Dovecot create PAM credentials. The credentials are never deleted, which may cause problems with some PAM plugins.

`passdb_result_failure`

Default	`continue`
Value	string
Allowed Values	`return-okreturnreturn-failcontinuecontinue-okcontinue-fail`
See Also	passdb: Result Values

What to do after the passdb authentication failed. Possible values and their meaning are described fully at passdb: Result Values.

`passdb_result_internalfail`

Default	`continue`
Value	string
Allowed Values	`return-okreturnreturn-failcontinuecontinue-okcontinue-fail`
See Also	passdb: Result Values

What to do after the passdb authentication failed due to an internal error. Possible values and their meaning are described fully at passdb: Result Values. If any of the passdbs had an internal failure and the final passdb also returns continue the authentication will fail with internal error.

`passdb_result_success`

Default	`return-ok`
Value	string
Allowed Values	`return-okreturnreturn-failcontinuecontinue-okcontinue-fail`
See Also	passdb: Result Values

What to do after the passdb authentication succeeded. Possible values and their meaning are described fully at passdb: Result Values.

This is commonly used together with master passdb to specify that even after a successful master user authentication, the authentication should continue to the actual non-master passdb to lookup the user.

`passdb_skip`

Default	`never`
Value	string
Allowed Values	`neverauthenticatedunauthenticated`

Configures when passdbs should be skipped:

Value	Description
`never`	Never skip over this passdb.
`authenticated`	Skip if an earlier passdb already authenticated the user successfully.
`unauthenticated`	Skip if user hasn't yet been successfully authenticated by the previous passdbs.

`passdb_sql_query`

Default	[None]
Value	string

SQL query to lookup the passdb fields (password and other extra fields).

`passdb_sql_update_query`

Default	[None]
Value	string

SQL query to update the password. Currently used only by the OTP auth mechanism.

`passdb_static_password`

Default	[None]
Value	string
Changes	Added: 2.4.0

The static password to be used for all users authenticating using this passdb.

`passdb_use_worker`

Default	`no` specific passdb have different defaults
Value	boolean

If yes, run the passdb lookup in auth-worker process instead of the main auth process.

`passdb_username_filter`

Default	[None]
Value	string
Changes	Added: 2.2.30

Skip the passdb if non-empty and the username doesn't match the filter. This is mainly used to assign specific passdbs to specific domains. Space or comma-separated list of username filters that can have * or ? wildcards. If any of the filters matches, the filter succeeds. Define negative matches by preceding !. If any of the negative filter matches, the filter won't succeed.

Example:

Filter: *@example.com *@example2.com !user@example.com
Matches:
- any@example.com
- user@example2.com
Won't match:
- user@example.com

Result Values

The following values control the behavior of a passdb lookup result:

`return-ok`

Return success, don't continue to the next passdb.

`return-fail`

Return failure, don't continue to the next passdb.

`return`

Return earlier passdb's success or failure, don't continue to the next passdb. If this was the first passdb, return failure.

`continue-ok`

Set the current authentication state to "success", and continue to the next passdb.

The following passdbs will skip password verification.

INFO

When using this value on a master passdb { master = yes }, execution will jump to the first non-master passdb instead of continuing with the next master passdb.

`continue-fail`

Set the current authentication state to "failure", and continue to the next passdb.

The following passdbs will still verify the password.

INFO

When using this value on a master passdb { master = yes }, execution will jump to the first non-master passdb instead of continuing with the next master passdb.

`continue`

Continue to the next passdb without changing the authentication state. The initial state is "failure found". If this was set in passdb_result_success, the following passdbs will skip password verification.

INFO

When using this value on a master passdb (master = yes), execution will jump to the first non-master passdb instead of continuing with the next master passdb.

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.

How to return these extra fields depends on the password database you use. Some passdbs don't support returning them at all, such as PAM authentication database.

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.

Changed: 2.4.0

Extra fields can now also be set to empty string, while previously they were changed to yes. Extra fields without value (without =) will default to yes.

`userdb_<field>`

The password database may also return fields prefixed with userdb_. These fields are only saved and used later as if they came from the userdb: Extra Fields.

Typically this is used only when using prefetch authentication database.

Suffixes

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

`:default`

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

Changed: 2.4.0

This was called :protected in earlier versions.

`:remove`

Remove this field entirely.

Fields

`user`

Change the username (eg. lowercase it).

This is mostly useful in case-insensitive username lookups to get the username returned back using the same casing always. Otherwise depending on your configuration it may cause problems, such as /var/mail/user and /var/mail/User mailboxes created for the same user.

SQL Example

An example passdb_sql_query would be:

passdb sql {
  query = SELECT concat(user, '@', domain) AS user, password \
    FROM users \
    WHERE user = '%{user | username}' and domain = '%{user | domain}'
}

You can also update "username" and "domain" fields separately:

passdb sql {
  query = SELECT user AS username, domain, password \
    FROM users \
    WHERE user = '%{user | username}' and domain = '%{user | domain}'
}

`login_user`

Master passdb can use this to change the username.

`allow_nets`

Allow user to log in from only specified IPs (checks against remote client IP).

This field is a comma separated list of IP addresses and/or networks where the user is allowed to log in from. If the user tries to log in from elsewhere, the authentication will fail the same way as if a wrong password was given.

Example: allow_nets=127.0.0.0/8,192.168.0.0/16,1.2.3.4,4.5.6.7.

IPv6 addresses are also allowed. IPv6 mapped IPv4 addresses (eg. ::ffff:1.2.3.4) are converted to standard IPv4 addresses before matching. Example: allow_nets=::1,2001:abcd:abcd::0:0/80,1.2.3.4.

Using local matches any auth connection that doesn't have an IP address. This usually means internal auth lookups from, e.g., doveadm. Example: allow_nets=127.0.0.0/8,local.

Example

passwd-file authentication database example:

user:{plain}password::::::allow_nets=192.168.0.0/24

'local' Keyword

The keyword local is accepted for Non-IP connections like Unix socket.

For example, with a Postfix/LMTP delivery setup, you must include local for Postfix to verify the email account:

passdb static {
  password = test
  fields {
    allow_nets = local,127.0.0.1/32
  }
}

Otherwise, you will see this error in the log: "[/var/run/dovecot/lmtp] said: 550 5.1.1 test2@example.com User doesn't exist: test2@example.com (in reply to RCPT TO command))".

`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).

See allow_nets for additional documentation.

`proxy`

Proxy the connection to another IMAP/POP3 server.

See proxy passdb.

`proxy_maybe`

Proxy the connection to another IMAP/POP3 server.

See proxy passdb.

`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.

Commonly used with proxy passdb and login referrals, but may also be used standalone.

One way to use this would be:

nologin=
reason=System is being upgraded, please try again later.

Unfortunately many clients don't show the reason to the user at all and just assume that the password was given wrong, so it might not be a good idea to use this unless the system will be down for days and you don't have a better way to notify the users.

WARNING

The nologin field is mainly intended for user logins (IMAP, POP3, ManageSieve). It is ignored with doveadm, because the intention is that admin could still be able to access a disabled user via doveadm.

Changed: 2.4.0 The nologin field prevents LMTP access now as long as lmtp_proxy = yes. However, the reason field is ignored.

INFO

If you want to entirely block the user from logging in (i.e. account is suspended), with no IMAP referral information provided, you must ensure that neither proxy nor host are defined as one of the passdb extra fields.

The order of preference is: proxy, host, then nologin.

`nodelay`

Don't delay reply to client in case of an authentication failure. However, this doesn't affect internal failure delays (auth_internal_failure_delay).

If the authentication fails, Dovecot typically waits 0-2 seconds (auth_failure_delay) before sending back the "authentication failed" reply. If this field is set, no such delay is done. Additionally, authentication penalty won't be increased.

Commonly used with proxy passdb and login referrals, but may also be used standalone.

INFO

If PAM authentication database is used as the passdb, it adds an extra delay which can't be removed by this setting.

`nopassword`

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

`fail`

If set, explicitly fails the passdb lookup.

`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.

`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.

`noauthenticate`

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

`forward_<anything>`

In a proxy, pass the variable to the next hop (backend) as forward_<anything>.

See forwarding fields.

`event_<name>`

Import name=value to login events.

Examples

SQL

passdb sql {
  query = SELECT userid AS user, password, 'Y' as proxy, host \
    FROM users WHERE userid = '%{user}'
  }
}

LDAP

dovecot.conf

passdb ldap {
  ...
  fields {
    user     =  %{ldap:user}
    password =  %{ldap:userPassword}
    proxy    =  %{ldap:proxyEnabled}
    host     =  %{ldap:hostName}
  }
}

WARNING

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.:

dovecot.conf

fields {
    user     = %{ldap:user}
    password = %{ldap:userPassword}
    host     = %{ldap:hostName}
    proxy    = y
}

passwd-file

user:{plain}pass::::::proxy=y host=127.0.0.1

Databases

Mechanisms

Formats

Extensions

Password Databases (passdb) ​

Passwords ​

Success/Failure Database ​

Lookup Database ​

Fields ​

password ​

password_noscheme ​

user ​

username ​

domain ​

User Extra Fields ​

Settings ​

passdb

passdb_args

passdb_default_password_scheme

passdb_deny

passdb_driver

passdb_fields

passdb_fields_import_all

passdb_master

passdb_mechanisms_filter

passdb_name

passdb_pam_failure_show_msg

passdb_pam_max_requests

passdb_pam_service_name

passdb_pam_session

passdb_pam_setcred

passdb_result_failure

passdb_result_internalfail

passdb_result_success

passdb_skip

passdb_sql_query

passdb_sql_update_query

passdb_static_password

passdb_use_worker

passdb_username_filter

Result Values ​

return-ok ​

return-fail ​

return ​

continue-ok ​

continue-fail ​

continue ​

Extra Fields ​

userdb_<field> ​

Suffixes ​

:default ​

:remove ​

Fields ​

user ​

SQL Example ​

login_user ​

allow_nets ​

Example ​

'local' Keyword ​

allow_real_nets ​

proxy ​

proxy_maybe ​

host ​

nologin ​

nodelay ​

nopassword ​

fail ​

k5principals ​

delay_until=<UNIX timestamp>[+<max random secs>] ​

noauthenticate ​

forward_<anything> ​

event_<name> ​

Examples ​

SQL ​

LDAP ​

passwd-file ​

Password Databases (`passdb`)

Passwords

Success/Failure Database

Lookup Database

Fields

`password`

`password_noscheme`

`user`

`username`

`domain`

User Extra Fields

Settings

`passdb`

`passdb_args`

`passdb_default_password_scheme`

`passdb_deny`

`passdb_driver`

`passdb_fields`

`passdb_fields_import_all`

`passdb_master`

`passdb_mechanisms_filter`

`passdb_name`

`passdb_pam_failure_show_msg`

`passdb_pam_max_requests`

`passdb_pam_service_name`

`passdb_pam_session`

`passdb_pam_setcred`

`passdb_result_failure`

`passdb_result_internalfail`

`passdb_result_success`

`passdb_skip`

`passdb_sql_query`

`passdb_sql_update_query`

`passdb_static_password`

`passdb_use_worker`

`passdb_username_filter`

Result Values

`return-ok`

`return-fail`

`return`

`continue-ok`

`continue-fail`

`continue`

Extra Fields

`userdb_<field>`

Suffixes

`:default`

`:remove`

Fields

`user`

SQL Example

`login_user`

`allow_nets`

Example

'local' Keyword

`allow_real_nets`

`proxy`

`proxy_maybe`

`host`

`nologin`

`nodelay`

`nopassword`

`fail`

`k5principals`

`delay_until=<UNIX timestamp>[+<max random secs>]`

`noauthenticate`

`forward_<anything>`

`event_<name>`

Examples

SQL

LDAP

passwd-file