Virtual Users
=============

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>
[AuthDatabase.Passwd.txt] lookup and a <SQL> [AuthDatabase.SQL.txt] lookup
return the same<userdb> [UserDatabase.txt] information, Dovecot's behavior is
identical.

Password and user databases
---------------------------

Dovecot supports many different <password databases> [PasswordDatabase.txt] and
<user databases> [UserDatabase.txt]. With virtual users the most commonly used
ones are<LDAP> [AuthDatabase.LDAP.txt], <SQL> [AuthDatabase.SQL.txt] and
<passwd-file> [AuthDatabase.PasswdFile.txt]. The databases usually contain the
following information:

 * Username
 * Password
 * UNIX User ID (UID) and primary UNIX Group ID (GID)
 * Home directory and/or mail location

Usernames
---------

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> [Variables.txt]), nothing breaks if you use for
example "domain%user" style usernames instead. However some<authentication
mechanisms> [Authentication.Mechanisms.txt] 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.

Passwords
---------

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

UNIX UIDs
---------

The most important thing you need to understand is that *Dovecot doesn't access
the users' mails as the /dovecot/ user*! See <UserIds.txt> for more information
about what /dovecot/ is really used for. So *don't* put /dovecot/ into /mail/
group, and don't make mails owned by /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. Note the UIDs aren't required to be in
'/etc/passwd'. Neither Dovecot nor your kernel cares about that. You just have
to be careful with the UID allocation so that the virtual user's UID won't
accidentally be used for something else as well.

By default Dovecot allows users to log in only with UID numbers 500 and above.
This check tries to make sure that no-one can ever log in as daemons or other
system users. If you're using an UID lower than 500, you'll need to change the
'first_valid_uid' setting.

UNIX GIDs
---------

Pretty much the same applies to GIDs as th UIDs above. By default Dovecot saves
files using 0600 mode, so it doesn't matter much what the files' group is. If
you use multiple UIDs and you wish to create shared mailboxes, setting up the
groups properly may make your configuration more secure. For example if you
have two teams and their mailboxes are shared only to their team members, you
could create a group for each team and set the shared mailbox's group to the
team's group and permissions to 0660, so neither team can even accidentally see
each others' shared mailboxes.

Currently Dovecot supports specifying only the primary group, however if your
userdb returns 'system_user' field, the non-primary groups are taken from
'/etc/group' for that user. In a future version the whole GID list will be
configurable without help from '/etc/group'.

It's also possible to give all the users an extra group with 'mail_extra_group'
setting.

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. Currently the home
directory is used for two purposes:

 * Debugging: If imap or pop3 process crashes, the core file is written to the
   user's home directory. Without a home directory it will be more difficult to
   debug the crashes. See http://www.dovecot.org/bugreport.html for more
   information.
 * <Sieve plugin> [LDA.Sieve.txt] stores the user's Sieve script and a mail
   duplicate database in the user's home directory. It's not possible to use
   the Sieve plugin without users having a home directory.

In future there will probably be other uses as well.

The directory layouts for home and mail directories could look like one of
these (in the preferred order):

 1. Mail directory under home, for example: home='/var/mail/user/'
    mail='/var/mail/user/mail/'
 2. Completely distinct home and mail directories: home='/home/virtual/user/'
    mail='/var/mail/user/'
 3. Home directory under mail, for example:
     * Maildir: home='/var/mail/user/home/' mail='/var/mail/user/'
     * mbox: home='/var/mail/user/.imap/.imap/' mail='/var/mail/user/'
        * The '.imap/.imap/' is the only safe name for the home directory.
          Otherwise it's possible that the home directory either shows up as a
          normal mailbox, or that it can be deleted by creating and deleting a
          mailbox (eg.'.imap/home/' directory gets deleted with "DELETE home"
          IMAP command).
 4. Home directory is the same as mail directory. The problem with this is that
    the created files may show up as mailboxes. This is especially problematic
    with mbox.

Mail location
-------------

The userdb can return 'mail' <extra field> [UserDatabase.ExtraFields.txt] to
override the default 'mail_location' setting. Usually you shouldn't need this.

Examples
========

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 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> [UserDatabase.Static.txt]:

---%<-------------------------------------------------------------------------
mail_location = maildir:~/Maildir
passdb pam {
}
userdb static {
  args = uid=vmail gid=vmail home=/var/mail/virtual/%d/%u
}
auth_userdb =
---%<-------------------------------------------------------------------------

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

 * VPopMail [http://www.inter7.com/vpopmail/]: Dovecot <supports VPopMail
   directly> [AuthDatabase.VPopMail.txt].
 * Linuxconf [http://www.solucorp.qc.ca/linuxconf/]: See
   <Migration.Linuxconf.txt>
 * Also see the Examples / Scenarios in <FrontPage.txt> 

(This file was created from the wiki on 2007-04-13 14:32)
