This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.
Differences between revisions 15 and 36 (spanning 21 versions)
Revision 15 as of 2009-02-06 19:54:31
Size: 3634
Editor: TimoSirainen
Comment:
Revision 36 as of 2018-01-05 15:58:25
Size: 4079
Editor: AkiTuomi
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
A user database lookup typically returns [:UserDatabase:uid, gid, home and mail] fields. Other possibilities are: A user database lookup typically returns [[UserDatabase|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'. Possibilities are:
Line 5: Line 5:
 * '''mail''': [[MailLocation|Mail location]], overrides the global {{{mail_location}}} setting.
Line 7: Line 8:
 * '''system_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). (v1.2+)
 * It's possible to override settings from {{{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 gi
ven filename.
 * It's possible to override settings from {{{dovecot.conf}}} (most commonly quota_rule to set per-user quota limits or also plugin-settings).
 * '''user''': User can be overriden (normally set in [[PasswordDatabase|passdb]]).
 * '''noreplicate''': User will not be replicated using replicator (see [[Replication]])
 * The extra fields are also passed to [[PostLoginScripting|post-login scripts]].
Line 11: Line 16:
These fields can be returned the exact same way as uid, gid, home and mail fields. Below are examples for some user databases. 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.

These fields can be returned the exact same way as uid, gid, and home fields. Below are examples for some user databases.
Line 15: Line 24:
Most commonly settings are overridden from plugin section. For example if your plugin section has {{{quota=maildir:storage=1024}}} value and the userdb lookup returns {{{quota=maildir:storage=2048}}}, the original quota setting gets overridden. In fact if the lookup always returns a quota field, there's no point in having the quota setting in plugin section at all, because it always gets overridden anyway. 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.
Line 19: Line 28:
 1. All actual settings are first placed into environment variables. The environment name may be different than the setting name.
 1. Everything inside plugin section is placed into environment variables. [:Variables:%variables] in values are expanded first.
 1. Everything from userdb lookup is placed into environment variables.
 1. At this point if [:PostLoginScripting:post-login scripting is used], it may modify the environment if wanted.
 1. imap/pop3 reads the settings from environment variables. It doesn't matter how they got there, they're read the exact same way.
 1. First all actual settings are first read into memory.
 1. 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 }`).
 1. Last, if [[PostLoginScripting|post-login scripting is used]], it may modify the settings if wanted.
Line 25: Line 32:
At each step if the environment variable already exists, it's replaced with the new value (ie. the setting is overridden). If you want to override settings inside sections, you can separate the section name and key with '/'. For example:
Line 27: Line 34:
Note that {{{
namespace default {
  inbox = yes
  separator = .
  location = maildir:~/Maildir
}
}}}
Line 29: Line 42:
 * If you want to override a setting from userdb you must use its environment name, not the setting name. See PostLoginScripting for how to find out what the environment is named.
 * Boolean settings are checked simply by the environment variables' existence and their values are ignored. For example having a userdb lookup return {{{mmap_disable=no}}} would still enable it.
The separator setting can be overridden by returning {{{namespace/default/separator=.}}} extra field.
Line 38: Line 50:
# NOTE: \ line splitting works only with v1.1+
Line 40: Line 51:
  'quota=maildir:storage=1024' as quota, mail_plugins \
  FROM users WHERE userid = '%u'
  CONCAT('*:bytes=', quota_bytes) AS quota_rule, \
  separator AS "namespace/default/separator" \
  FROM users WHERE username = '%n' and domain = '%d'
Line 48: Line 60:
user_attrs = homeDirectory=home,uidNumber=uid,gidNumber=gid,quotaDovecot=quota,mail_plugins user_attrs = \
  =home=%{ldap:homeDirectory}, \
  =uid=%{ldap:uidNumber},
  =gid=%{ldap:gidNumber},
  =quota_rule=*:bytes=%{ldap:quotaBytes},
  =namespace/default/separator=%{ldap:mailSeparator}
Line 53: Line 70:
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 [:PasswordDatabase/ExtraFields:passdb extra fields]. 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 [[PasswordDatabase/ExtraFields|passdb extra fields]].
Line 56: Line 73:
# v1.0 quota format:
user:{plain}pass:1000:1000::/home/user::userdb_mail=mbox:~/mail userdb_quota=maildir:storage=102400
# v1.1 quota format:
user:{plain}pass:1000:1000::/home/user::userdb_mail=mbox:~/mail userdb_quota_rule=*:storage=100M
user:{plain}pass:1000:1000::/home/user::userdb_mail=mbox:~/mail userdb_quota_rule=*:storage=100M userdb_namespace/default/separator=/

User database 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'. Possibilities are:

  • mail: Mail location, 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.

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

  • user: User can be overriden (normally set in passdb).

  • noreplicate: User will not be replicated using replicator (see Replication)

  • The extra fields are also passed to post-login scripts.

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.

These fields can be returned the exact same way as uid, gid, and home fields. Below are examples for some user databases.

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

None: UserDatabase/ExtraFields (last edited 2019-09-11 14:07:49 by MichaelSlusarz)