mbox configuration
==================

See <MailboxFormat.mbox.txt> for a complete description of how Dovecot has
implemented mbox support.

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

In many systems the user's mails are by default stored in '/var/mail/username'
file. This file is called INBOX in IMAP world. Since IMAP supports multiple
mailboxes, you'll need to have a directory for them as well. Usually '~/mail'
is a good choice for this. For installation such as this, the mail location is
specified with:

---%<-------------------------------------------------------------------------
# %u is replaced with the username that logs in
mail_location = mbox:~/mail:INBOX=/var/mail/%u
---%<-------------------------------------------------------------------------

It's in no way a requirement to have the INBOX in '/var/mail/' directory. In
fact this often just brings problems because Dovecot might not be able to write
dotlock files to the directory (see below). You can avoid this completely by
just keeping everything in '~/mail/':

---%<-------------------------------------------------------------------------
# INBOX exists in ~/mail/inbox
mail_location = mbox:~/mail
---%<-------------------------------------------------------------------------

Locking
-------

Make sure that all software accessing the mboxes are using the same locking
methods in the same order. The order is important to prevent deadlocking. From
Dovecot's side you can change these from 'mbox_read_locks' and
'mbox_write_locks' settings. See <MboxLocking.txt> for more information.

/var/mail/ dotlocks
-------------------

Often mbox write locks include dotlock, which means that Dovecot needs to
create a new "<mbox>.lock" file to the directory where the mbox file exists. If
your INBOXes are in '/var/mail/' directory you may have to give Dovecot write
access to the directory. There are two ways the '/var/mail/' directory's
permissions have traditionally been set up:

 * Sticky bit set, allowing anyone to create new files but not overwrite or
   delete existing files owned by someone else (ie. same as /tmp)
 * Directory owned by a mail group and the directory set to group-writable

You can give Dovecot access to mail group by setting:

---%<-------------------------------------------------------------------------
mail_extra_groups = mail
---%<-------------------------------------------------------------------------

Optimizations
-------------

The settings below are related to mbox performance. See
<MailboxFormat.mbox.txt> for more complete description of what they do.

 * 'mbox_lazy_writes=yes' (default): Metadata updates, such as writing X-UID
   headers or flag changes, aren't written to mbox file until the mailbox is
   closed or CHECK or EXPUNGE IMAP commands are sent by the client. The mbox
   rewrites can be costly, so this may avoid a lot of disk writes.
 * 'mbox_dirty_syncs=yes' (default): Dovecot assumes that external mbox file
   changes only mean that new messages were appended to it. Without this
   setting Dovecot re-reads the whole mbox file whenever it changes. There are
   various safeguards in place to make this setting safe even when other
   changes than appends were done to the mbox. The only downside to this
   setting is that external message flag modifications may not be visible
   immediately.
 * 'mbox_very_dirty_syncs=yes' (not default): When opening mbox file that has
   been changed externally, don't re-read it. Otherwise similar to
   'mbox_dirty_syncs=yes'.
 * 'mbox_min_index_size=n': If mbox file is smaller than n kilobytes, don't
   update its index files. If an index file exists for it, it's still read
   however.

Only /var/mail/ mboxes
----------------------

With POP3 it's been traditional that users have their mails only in the
'/var/mail/' directory. IMAP however supports having multiple mailboxes, so
each user has to have a private directory where the mailboxes are stored.
Dovecot also needs a directory for its index files unless you disable them
completely.

If you *really* want to use Dovecot as a plain POP3 server without index files,
you can work around the problem of not having the per-user directory:

 * Set users' home directory in userdb to some empty non-writable directory,
   for example '/var/empty'
 * Modify 'mail_location' setting so that the mail root directory is also the
   empty directory and append ':INDEX=MEMORY' to it. For example:
   'mail_location = mbox:/var/empty:INBOX=/var/mail/%u:INDEX=MEMORY'
 * Note that if you have IMAP users, they'll see the '/var/empty' as the
   directory containing other mailboxes than INBOX. If the directory is
   writable, all the users will have their mailboxes shared.

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