User Databases (userdb)

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

passdb authenticated the user. userdb lookup then retrieves post-login information specific to the authenticated user. This may include:

• Mailbox location information
• Quota limit
• Overriding settings for the user (almost any setting can be overridden)

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

The userdb and passdb may be the same or they may be different depending on your needs. You can also have multiple authentication databases.

Fields

The user database lookup can return these fields:

uid

User's UID (UNIX user ID), overrides the global mail_uid setting.

gid

User's GID (UNIX group ID), overrides the global mail_gid setting.

home

User's home directory, overrides the global mail_home setting.

Although not required, it's highly recommended even for virtual users.

Optional Extra Fields

The extra fields are also passed to post-login scripts. See post-login scripting. You can override settings in dovecot.conf, see userdb: Extra Fields.

user

Changes the username (can also be done by the passdb lookup).

Supported Databases

Database	Description
Passwd	System users (NSS, /etc/passwd, or similar).
Passwd-file	/etc/passwd-like file.
LDAP	Lightweight Directory Access Protocol.
SQL	SQL database (PostgreSQL, MySQL, SQLite, Cassandra).
Static	Userdb information generated from a given template.
Prefetch	Prefetch database. This assumes that the passdb already returned also all the required user database information.
Lua	Lua script for authentication.

Settings

userdb

Default	[None]
Value	Named List Filter
Dependencies	userdb_driver
See Also	userdb userdb_name userdb_driver

Creates a new userdb. The filter name refers to the userdb_name setting.

userdb_args

Default	[None]
Value	string

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

userdb_driver

Default	[None]
Value	string
See Also	userdb_name userdb

The driver used for this user database. If empty, defaults to userdb_name. See userdb for the list of available drivers.

userdb_fields

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

Userdb fields (and userdb: Extra Fields). The values can contain %variables. All %variables used here reflect the state after the current userdb lookup, and can refer to fields returned by previous userdb lookups. Depending on the userdb 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:

userdb ldap {
  fields {
    user = %{ldap:userId}
    home = /home/%{ldap:mailboxPath}
    uid = vmail
    gid = vmail
  }
}

userdb_fields_import_all

Default	yes For userdb ldap the default is no.
Value	boolean
See Also	userdb_fields

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

userdb_name

Default	[None]
Value	string
See Also	userdb userdb_driver

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

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

userdb_result_failure

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

What to do if the user was not found from the userdb. Possible values and their meaning are described fully at userdb: Result Values.

userdb_result_internalfail

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

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

userdb_result_success

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

What to do if the user was successfully found from the userdb. Possible values and their meaning are described fully at userdb: Result Values.

userdb_skip

Default	never
Value	string
Allowed Values	neverfoundnotfound

Configures when userdbs should be skipped:

Value	Description
never	Never skip over this userdb.
found	Skip if an earlier userdbs already found the user.
notfound	Skip if previous userdbs haven't yet found the user.

userdb_sql_iterate_query

Default	[None]
Value	string

SQL query to list all available usernames.

userdb_sql_query

Default	[None]
Value	string

SQL query to lookup the userdb fields.

userdb_static_allow_all_users

Default	no
Value	boolean
Changes	Added: 2.4.0

Skip user existence verification via passdb lookup.

userdb_use_worker

Default	no specific userdb have different defaults
Value	boolean

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

Result Values

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

return-ok

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

return-fail

Return "user doesn't exist", don't continue to the next userdb.

return

Return earlier userdb's success or failure, don't continue to the next userdb. If this was the first userdb, return "user doesn't exist".

continue-ok

Set the current user existence state to "found", and continue to the next userdb.

continue-fail

Set the current user existence state to "not found", and continue to the next userdb.

continue

Continue to the next userdb without changing the user existence state. The initial state is "not found".

Extra Fields

A user database lookup typically returns uid, gid, and home fields, as per traditional /etc/passwd lookups.

Other fields may also be stored in the userdb, and these are called 'extra fields'.

These fields can be returned the exact same way as uid, gid, and home fields.

It's also possible to override settings from dovecot.conf. For example the mail_path and quota_storage_size settings are commonly overridden to provide per-user mail path or quota limit.

The extra fields are also passed to post-login scripting.

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.

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.

For example you can return uid:remove to remove the uid field from the userdb reply. This differs from uid= in that the field is removed entirely (and default is used) instead of just being set to an empty value.

Fields

nice

Set the mail process's priority to be the given value.

chroot

Chroot to given directory. Overrides mail_chroot.

system_groups_user

Specifies the username whose groups are read from /etc/group (or wherever NSS is configured to taken them from).

The logged in user has access to those groups.

This may be useful for shared mailboxes.

userdb_import

This allows returning multiple extra fields in one TAB-separated field. It's useful for userdbs which are a bit less flexible for returning a variable number of fields (e.g. SQL).

uidgid_file

Get uid and gid for user based on the given filename.

user

User can be overridden (normally set in passdb).

event_<name>

Import name=value to mail user event.

Overriding Settings

For example if you have quota_storage_size=100M in doveconf.conf and the userdb lookup returns quota_storage_size=200M, the original quota setting gets overridden. In fact, if the lookup always returns a quota_storage_size field, there's no point in having quota_storage_size in dovecot.conf at all, because it always gets overridden anyway.

To understand how imap and pop3 processes see their settings, it may be helpful to know how Dovecot internally passes them:

1. First all actual settings are first read into memory.
2. Next all the extra fields returned by userdb lookup are used to override the settings.
3. Last, if post-login scripting is used, it may modify the settings.

If you want to override settings inside sections, you can separate the section name and key with /. For example:

namespace default {
  inbox = yes
  separator = .
}

The separator setting can be overridden by returning namespace/default/separator extra field.

Examples

SQL

dovecot.conf

userdb sql {
  query = SELECT home, uid, gid, CONCAT(quota_bytes, 'B') AS quota_storage_size, separator AS "namespace/default/separator" \
    FROM users \
    WHERE username = '%{user | username}' and domain = '%{user | domain}'
}

LDAP

dovecot.conf

userdb ldap {
  ...
  fields {
    home       = %{ldap:homeDirectory}
    uid        = %{ldap:uidNumber}
    gid        = %{ldap:gidNumber}
    quota_storage_size = %{ldap:quotaBytes}B
    namespace/default/separator = %{ldap:mailSeparator}
  }
}

passwd-file

Example that shows how to give two userdb extra fields (mail_driver and quota).

Note that all userdb extra fields must be prefixed with userdb_, otherwise they're treated as passdb: Extra Fields.

user:{plain}pass:1000:1000::/home/user::userdb_mail_driver=mbox userdb_mail_path=~/mail userdb_quota_storage_size=100M userdb_namespace/default/separator=/
user2:{plain}pass2:1001:1001::/home/user2::userdb_mail_driver=maildir userdb_mail_path=~/Maildir userdb_quota_storage_size=200M

See Also

• authentication caching