This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.
Differences between revisions 34 and 35
Revision 34 as of 2017-11-28 10:20:56
Size: 5175
Editor: 2001:2060:49:110:7064:b145:a1c0:4656
Revision 35 as of 2019-09-11 13:58:52
Size: 84
Comment: Moved to new doc
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= User Databases =

After a user has been successfully authenticated, Dovecot looks up the user's userdb information. The userdb lookup is also done by [[LDA]] to find out how to deliver mails for the user.

The user database lookup can return these fields:

 * '''uid''': User's [[UserIds#mailusers|UID]] (UNIX user ID), overrides the global {{{mail_uid}}} setting.
 * '''gid''': User's [[UserIds#gids|GID]] (UNIX group ID), overrides the global {{{mail_gid}}} setting.
 * '''home''': User's [[VirtualUsers/Home|home directory]], overrides the global {{{mail_home}}} setting. Although not required, it's [[VirtualUsers/Home|highly recommended even for virtual users]].
 * Optional [[UserDatabase/ExtraFields|extra fields]]
  * '''user''': Changes the username (can also be done by the passdb lookup)
  * Overwriting all mail-related settings, for example:
    * '''mail''': [[MailLocation|Mail location]], overrides the global {{{mail_location}}} setting.
    * '''quota_rule''' to specify per-user quota limit
  * The extra fields are also passed to [[PostLoginScripting|post-login scripts]]

The user and [[PasswordDatabase|password databases]] may be the same or they may be different depending on your needs. You can also have [[Authentication/MultipleDatabases|multiple databases]].

Currently supported user databases are:

 * [[AuthDatabase/Passwd|Passwd]]: System users (NSS, `/etc/passwd`, or similiar)
 * [[AuthDatabase/PasswdFile|Passwd-file]]: `/etc/passwd`-like file in specified location
 * [[UserDatabase/NSS|NSS]]: Name Service Switch
 * [[AuthDatabase/LDAP|LDAP]]: Lightweight Directory Access Protocol
 * [[AuthDatabase/SQL|SQL]]: SQL database (PostgreSQL, MySQL, SQLite)
 * [[AuthDatabase/Dict|Dict]]: Dict key-value database (Redis, memcached, etc.)
 * [[UserDatabase/Static|Static]]: Userdb information generated from a given template
 * [[AuthDatabase/VPopMail|VPopMail]]: External software used to handle virtual domains
 * [[UserDatabase/Prefetch|Prefetch]]: This assumes that the passdb already returned also all the required user database information
 * [[AuthDatabase/Lua|Lua]]: Lua script for authentication (v2.3.0+)

== Userdb settings ==

An example userdb entry might look like this:
userdb {
  driver = passwd-file
  args = username_format=%n /etc/dovecot/users

  default_fields = uid=vmail gid=vmail
  override_fields =

  # v2.2.10+:
  skip = never
  result_failure = continue
  result_internalfail = continue
  result_success = return-ok

  # v2.2.24+:
  auth_verbose = default

First we have the settings that provide content for the userdb lookup:

 * driver: The userdb backend name
 * args: Arguments for the userdb backend. The format of this value depends on the userdb driver. Each one uses different args.
 * default_fields: Userdb fields (and [[UserDatabase/ExtraFields|extra fields]]) that are used, unless overwritten by the userdb backend. They are in format {{{key=value key2=value2 ...}}}. The values can contain [[Variables|%variables]].
 * override_fields: Same as default_fields, but instead of providing the default values, these values override what the userdb backend returned. For example useful with [[AuthDatabase/Passwd|userdb passwd]] for overriding e.g. home directory or the uid/gid.
 * auth_verbose: If this is explicitly set to yes or no, it overrides the global auth_verbose setting. (However, auth_debug=yes overrides the auth_verbose setting.) (v2.2.24+)

Then we have the setting which specify when the userdb is used (v2.2.10+):

 * skip: Do we sometimes want to skip over this userdb?
  * never
  * found: Skip if an earlier userdb already found the user
  * notfound: Skip if previous userdbs haven't yet found the user

And finally we can control what happens when we're finished with this userdb (v2.2.10+):

 * result_success: What to do if the user was found from the userdb (default: return-ok)
 * result_failure: What to do if the user wasn't found from the userdb (default: continue)
 * result_internalfail: What to do if the userdb lookup had an internal failure (default: continue). If any of the userdbs had an internal failure and the final userdb also returns "continue", the lookup will fail with "internal error". '''WARNING''': If multiple userdbs are required (results are merged), it's important to set result_internalfail=return-fail to them, otherwise the userdb lookup could still succeed but not all the intended extra fields are set.

The result values that can be used:

 * 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".

None: UserDatabase (last edited 2019-09-11 13:58:52 by MichaelSlusarz)