Maildir
-------

We support Courier-compatible Maildir++. INBOX is the ~/Maildir directory,
all the other folders named as ".<folder>.<subfolder>.<etc>" under it, any
directories not starting with a dot are simply ignored. Deleting folders is
made atomic by renaming them as "..<folder name>" and deleting the
directory after that. So, all directories beginning with ".." are deleted
whenever they're noticed. Indexes are stored into each folder's root
directory.

Custom flags saved using a..z letters as Maildir file flags. .customflags
file is then used to map the letters to names (a=0, b=1, etc).


mbox
----

mbox storage requires an IMAP root directory where to store IMAP folders
and some other information. mbox file for INBOX is a special case which may
exist elsewhere in filesystem.

All files in the IMAP root directory not beginning with a "." are treated
as IMAP folders. Directories are treated as being IMAP subfolders.

Dovecot's indexes are stored in ".imap/<mailbox name>/" directories under
the folder directories.

MAIL environment for mbox is: <root folder>|<INBOX path>[:INBOX=<path>].
For example ~/Mail:INBOX=/var/mail/username.

indexes
-------

It's possible to specify different location for index files. This could be
wanted if mailboxes are accessed via remote filesystem (eg. NFS). Indexes
are mmap()ed and fcntl() locked, so they may not work too well with NFS, or
at least they'll work a bit slowly.

Indexes don't contain anything really important in them, so it doesn't
matter if they're lost or are out of sync. Dovecot just rebuilds or
refreshes them. This would allow creating a cluster where each computer
keeps the indexes locally while accessing the actual mailboxes via NFS. To
avoid unnecessarily rebuilding indexes all the time, the users should be
redirected to their primary server whenever possible.

Currently the only annoying thing with recreating indexes is that the
message UIDs will change, which may cause more traffic to clients, and
depending on client software may cause loss of some message-specific
settings. This will be fixed later by storing the UIDs permanently to
mailboxes.

Adding :INDEX=<dir> to MAIL environment overrides the default location. The
given directory must exist.


Detecting what to use
---------------------

imap process detects the storage from MAIL-environment. It's preferred
format is "<storage>:<data>", for example "maildir:~/Maildir". It's anyway
allowed to be in pretty much any format as long as some of the storages
recognizes it as a valid data, so for example "MAIL=~/mail" is first
checked by maildir storage to see if it's valid maildir and mbox storage
after that.

If the MAIL environment isn't given at all, all storages are gone through
and asked if they can find a usable mail folder. Also as a special case, if
MAILDIR environment exists, maildir storage is used with the directory
specified in it.

Maildir storage is autodetected by checking if <directory>/cur/ exists and
we have rwx access to it. If directory isn't known, / and ~/Maildir are
checked. / is checked because we could be chrooted.

mbox storage requires detecting INBOX location and IMAP root directory. If
MAIL environment points to file (+rw) it's treated as the INBOX file. If it
points to directory (+rwx) which contains .imap/ (+rwx), inbox (+rw) or
mbox (+rw) it's treated as IMAP root directory. If INBOX isn't known,
imap_root/inbox file is used by default. If root directory isn't known, we
try to find it from /, ~/mail or ~/Mail.


Files created by Dovecot
------------------------

.subscriptions: One folder per line listing subscribed IMAP folders.
There's only one of these files in the root mail directory (~/Maildir/ or
~/mail/.imap/).

Then there's the per-folder files:

.imap.index: Fixed width mail index records.

.imap.index.data: Variable width data, for example mail file name and
cached body, envelope, etc.

.imap.index.log: Log file describing made changes. This file is used to
mark external changes (expunges and flag changes) temporarily until they're
synced into IMAP clients. If multiple Dovecots have the same folder open,
this can be a big speedup.

.imap.index.tree: Binary tree used for looking up messages from .imap.index
file. This is used for both UID lookups and message sequence lookups.
Sequences can be looked up directly from the index as long as no messages
have been expunged, but after that it gets slow unless it's compressed.
Using this file however can keep the sequence lookups and expunges fast in
all situations without requiring compression.

.customflags: Lists custom message flags. First line is header which
Dovecots check to see if the file has changed. Other lines list the flags
in format "<flag number> <flag name>". Currently there can be 26 different
flags (0..25).

.imap.index.log and .imap.index.tree files can be deleted without any data
loss, they're simply recreated/rebuilt when they're noticed missing.

Deleting .imap.index and .imap.index.data files results in loss of message
UIDs. That may be a bad thing with some IMAP clients which store some data
about message locally and identifies the message by it's UID.

Deleting .customflags results in loss of custom flag names for Maildir.
With mbox the .customflags is simply recreated based on the flags listed
in the mbox file itself (ie. no data loss).