User database extra fields

A user database lookup typically returns uid, gid and home fields. See User Databases (userdb), as per traditional /etc/passwd lookups. Other fields may also be stored in the userdb, and these are called ‘extra fields’. Possibilities are:

  • mail Mail Location Settings, overrides the global mail_location setting.

  • nice: Set the mail process’s priority to be the given value.

  • chroot: Chroot to given directory. Overrides mail_chroot setting in dovecot.conf.

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

  • event_<name>: Import name=value to mail user event.

  • user: User can be overridden (normally set in passdb, see Password databases (passdb)).

  • noreplicate: See Configuration.

  • event_<name>: Import name=value to mail user event.

    New in version v2.3.21.

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

It’s possible to override settings from dovecot.conf (most commonly quota_rule to set per-user quota limits or also plugin-settings).

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

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.

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

Changed in version v3.0.0;v2.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.

Overriding settings

Most commonly settings are overridden from plugin section. For example if your plugin section has quota_rule=*:storage=100M value and the userdb lookup returns quota_rule=*:storage=200M, the original quota setting gets overridden. In fact if the lookup always returns a quota_rule field, there’s no point in having the quota_rule setting in the plugin section 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. Any unknown setting is placed into the plugin {} section (e.g. foo=bar will be parsed as if it were plugin { foo=bar }).

  3. Last, if Post-login scripting is used, it may modify the settings if wanted.

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

namespace default {
  inbox = yes
  separator = .
  location = maildir:~/Maildir
}

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

Examples

SQL

dovecot-sql.conf:

user_query = SELECT home, uid, gid, \
  CONCAT('*:bytes=', quota_bytes) AS quota_rule, \
  separator AS "namespace/default/separator" \
  FROM users WHERE username = '%n' and domain = '%d'

LDAP

dovecot-ldap.conf:

user_attrs = \
  =home=%{ldap:homeDirectory}, \
  =uid=%{ldap:uidNumber},
  =gid=%{ldap:gidNumber},
  =quota_rule=*:bytes=%{ldap:quotaBytes},
  =namespace/default/separator=%{ldap:mailSeparator}

passwd-file

Below are examples that show how to give two userdb extra fields (mail 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=mbox:~/mail userdb_quota_rule=*:storage=100M userdb_namespace/default/separator=/
user2:{plain}pass2:1001:1001::/home/user2::userdb_mail=maildir:~/Maildir userdb_quota_rule=*:storage=200M