This documentation is for Dovecot v1.x, see wiki2 for v2.x documentation.

Virtual Users

There are many ways to configure Dovecot to use virtual users. If you have no idea how you want your users to be configured, select some HOWTO and follow its instructions.

Users are often categorized as being either system users (in /etc/passwd) or virtual users (not in /etc/passwd). However from Dovecot's point of view there isn't much of a difference between them. If a passwd lookup and a SQL lookup return the same userdb information, Dovecot's behavior is identical.

Password and user databases

Dovecot supports many different password databases and user databases. With virtual users the most commonly used ones are LDAP, SQL and passwd-file. The databases usually contain the following information:

Usernames and domains

Dovecot doesn't care much about domains in usernames. IMAP and POP3 protocols currently have no concept of "domain", so the username is just something that shows up in your logs and maybe in some configuration, but they have no direct functionality.

So although Dovecot makes it easier to handle "user@domain" style usernames (eg. %n and %d variables), nothing breaks if you use for example "domain%user" style usernames instead. However some authentication mechanisms do have an explicit support for realms (pretty much the same as domains). If those mechanisms are used, the username is changed to be "user@realm".

And of course there's no need to have domains at all in the usernames.


The password can be in any format that Dovecot supports, but you need to tell the format to Dovecot because it won't try to guess it. The SQL and LDAP configuration files have the default_pass_scheme setting for this. If you have passwords in multiple formats, or the passdb doesn't have such a setting, you'll need to prefix each password with "{<scheme>}", for example "{PLAIN}plaintext-password" or "{PLAIN-MD5}1a1dc91c907325c69271ddf0c944bc72".


The most important thing you need to understand is that Dovecot doesn't access the users' mails as the dovecot user! So don't put dovecot into the mail group, and don't make mails owned by the dovecot user. That will only make your Dovecot installation less secure.

So, if not the dovecot user, what then? You can decide that yourself. You can create, for example, one vmail user which owns all the mails, or you can assign a separate UID for each user. See UserIds#mailusers for more information about different ways to allocate UIDs for users.


Unless you're using shared mailboxes and multiple UIDs, it doesn't really matter what GIDs you use. You can, for example, use a single GID for all users, or create a separate GID for each user. See UserIds#gids for more information.

Home directories

Some people are opposed to the idea of virtual users having home directories, but no matter what you call it, it's a good idea to have a directory where user-specific configuration and other state is stored. See VirtualUsers/Home more information.

Mail location

The userdb can return the mail field to override the default mail_location setting. Usually you shouldn't need this.


Dynamic passwd-file locations

mail_location = maildir:/home/%d/%n/Maildir
userdb passwd-file {
  args = /home/%d/etc/passwd
passdb passwd-file {
  args = /home/%d/etc/shadow

In the above examples users are expected to log in as "user@domain". Their mail is kept in their home directory at /home/<domain>/<username>/Maildir.

The usernames in the passwd and shadow files are expected to contain only the user part, no domain. This is because the path itself already contained %d to specify the domain. If you want the files to contain full user@domain names, you can use %0.d instead of %d.

static userdb

Many people store only usernames and passwords in their database and don't want to deal with UIDs or GIDs. In that case the easiest way to get Dovecot running is to use the static userdb:

mail_location = maildir:~/Maildir
passdb pam {
userdb static {
  args = uid=vmail gid=vmail home=/var/mail/virtual/%d/%n

This makes Dovecot look up the mails from /var/mail/virtual/<domain>/<user>/Maildir/ directory, which should be owned by vmail user and vmail group.

Existing virtual user management software

None: VirtualUsers (last edited 2009-11-09 22:42:21 by TimoSirainen)