This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.
Differences between revisions 1 and 17 (spanning 16 versions)
Revision 1 as of 2006-11-05 14:20:54
Size: 1396
Editor: TimoSirainen
Comment:
Revision 17 as of 2009-03-15 22:35:23
Size: 3708
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
A user database typically returns these fields: A user database lookup typically returns [[UserDatabase|uid, gid, home and mail]] fields. Other possibilities are:
Line 5: Line 5:
 * `uid`: UNIX user ID to use for the mail process. This is a required field.
 * `gid`: Primary UNIX group ID to use for the mail process. This is a required field.
 * `home`: Home directory for the user. Although not required, it's highly recommended since some files are stored in the user's home directory (currently only [wiki:LDA deliver]).
 * `mail`: Specifies where to find mails for the user. Overrides `mail_location` setting in `dovecot.conf`.
 * '''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.
  * This field is called '''system_user''' in v1.1 and older.
 * '''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}}}.
Line 10: Line 12:
Some less commonly used special fields are: These fields can be returned the exact same way as uid, gid, home and mail fields. Below are examples for some user databases.
Line 12: Line 14:
 * `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_user`: If this is given, the user's groups are read from `/etc/group` (or wherever NIS is configured to taken them from). (This will some day be replaced by group ID lists given by userdbs.)
== Overriding settings ==
Line 16: Line 16:
Most of the mail process settings in `dovecot.conf` can be overridden by simply returning the same setting with a different value. For example if `dovecot.conf` has `pop3_enable_last=no`, but you want to enable it for a specific user, you can simply return `pop3_enable_last=yes` extra field. However note that for boolean values the `=yes` value part is irrelevant, returning `pop3_enable_last=no` would enable the setting just the same. 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.

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

 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.

At each step if the environment variable already exists, it's replaced with the new value (ie. the setting is overridden).

Note that

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

== Examples ==

=== SQL ===

dovecot-sql.conf:
{{{
# NOTE: \ line splitting works only with v1.1+
user_query = SELECT home, uid, gid, \
  'quota=maildir:storage=1024' as quota, mail_plugins \
  FROM users WHERE userid = '%u'
}}}

=== LDAP ===

dovecot-ldap.conf:
{{{
user_attrs = homeDirectory=home,uidNumber=uid,gidNumber=gid,quotaDovecot=quota,mail_plugins
}}}

=== 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 [[PasswordDatabase/ExtraFields|passdb extra fields]].

{{{
# 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
user2:{plain}pass2:1001:1001::/home/user2::userdb_mail=maildir:~/Maildir userdb_quota_rule=*:storage=200M
}}}

User database extra fields

A user database lookup typically returns uid, gid, home and mail fields. Other possibilities are:

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

    • This field is called system_user in v1.1 and older.

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

These fields can be returned the exact same way as uid, gid, home and mail 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=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.

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

  1. All actual settings are first placed into environment variables. The environment name may be different than the setting name.
  2. Everything inside plugin section is placed into environment variables. %variables in values are expanded first.

  3. Everything from userdb lookup is placed into environment variables.
  4. At this point if post-login scripting is used, it may modify the environment if wanted.

  5. imap/pop3 reads the settings from environment variables. It doesn't matter how they got there, they're read the exact same way.

At each step if the environment variable already exists, it's replaced with the new value (ie. the setting is overridden).

Note that

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

Examples

SQL

dovecot-sql.conf:

# NOTE: \ line splitting works only with v1.1+
user_query = SELECT home, uid, gid, \
  'quota=maildir:storage=1024' as quota, mail_plugins \
  FROM users WHERE userid = '%u'

LDAP

dovecot-ldap.conf:

user_attrs = homeDirectory=home,uidNumber=uid,gidNumber=gid,quotaDovecot=quota,mail_plugins

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.

# 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
user2:{plain}pass2:1001:1001::/home/user2::userdb_mail=maildir:~/Maildir userdb_quota_rule=*:storage=200M

None: UserDatabase/ExtraFields (last edited 2018-01-05 15:58:25 by AkiTuomi)