path: root/doc/wiki/MailLocation.txt

Mail location
=============

 * For mbox-specific settings, see <MailLocation.mbox.txt>
 * For Maildir-specific settings, see <MailLocation.Maildir.txt>
 * For dbox-specific settings, see <MailLocation.dbox.txt>

There are three different places where the mail location is looked up from:

 1. 'mail_location' setting in 'dovecot.conf' is used if nothing else overrides
    it.
 2. 'mail' <userdb field> [UserDatabase.txt] overrides 'mail_location' setting.

 3. 'location' setting inside namespaces overrides everything. Usually this
    should be used only for public and shared namespaces.

Autodetection
-------------

By default the 'mail_location' setting is empty, which means that Dovecot
attempts to locate automatically where your mails are. This is done by looking,
in order, at:

 * '~/mdbox/'
 * '~/sdbox/'
 * '~/Maildir/'
 * '~/mail/.imap/'
 * '~/mail/inbox'
 * '~/mail/mbox'
 * '~/Mail/.imap/'
 * '~/Mail/inbox'
 * '~/Mail/mbox'

For autodetection to work, one of the above locations has to be populated; when
autodetection is active, Dovecot will not attempt to create a mail folder. Note
that '.imap' is a directory, and 'inbox' and 'mbox' are files.

It's usually a good idea to explicitly specify where the mails are, even if the
autodetection happens to work, in particular to benefit from auto-creation of
the folder for new users.

Mailbox autocreation
--------------------

Dovecot in the 1.x era created mailboxes automatically regardless of whether
mail_location was set. In 2.x autocreation only gets triggered if mail_location
is correctly set. You'll see something like this if you enable debug logging:

---%<-------------------------------------------------------------------------
Debug: Namespace : /home/user/Mail doesn't exist yet, using default permissions
Debug: Namespace : Using permissions from /home/user/Mail: mode=0700
gid=default
---%<-------------------------------------------------------------------------

and a 'Mail/.imap' directory will be present once that process has concluded.
This is the easiest way to ensure a freshly created user is correctly set up
for access via Dovecot.

Format
------

The format of the mailbox location specification is as follows:

 * / <mailbox-format> [MailboxFormat.txt]/ : /path/ [ : /key/ = /value/ … ]

where:

 * /mailbox-format/ is a tag identifying one of the formats described at
   <Mailbox Formats> [MailboxFormat.txt].
 * /path/ is the path to a directory where the mail is stored. This must be an
   absolute path, not a relative path. Even if relative paths appear to work,
   this usage is deprecated and will likely stop working at some point. Do not
   use the home directory, for reasons see <Home vs. mail directory>
   [VirtualUsers.Home.txt]
 * /key/ = /value/ can appear zero or more times to set various optional
   parameters. Possible values for /key/ are:
    * 'INDEX' : specifies the location of <index files> [MailLocation.txt].
       * 'ITERINDEX' : Perform mailbox listing using the INDEX directories
         instead of the mail root directories. Mainly useful when the INDEX
         storage is on a faster storage. It takes no value. (v2.2.32+)
    * 'INBOX' : specifies the location of the <INBOX> [MailLocation.txt].
    * 'LAYOUT' : specifies the directory layout to use:
       * Maildir++: The default used by Maildir format
       * fs: The default used by mbox and dbox formats
       * index: Uses mailbox GUIDs as the directory names. The mapping between
         mailbox names and GUIDs exists in dovecot.list.index* files.
    * 'NO-NOSELECT' : Automatically delete any \ <NoSelect.txt> mailboxes that
      have no children. These mailboxes are sometimes confusing to users. Also
      if a \ <NoSelect.txt> mailbox is attempted to be created with "CREATE
      box/", it's created as selectable mailbox instead. (LAYOUT=Maildir++
      always behaves this same way.) (v2.2.32+)
    * 'UTF-8' : Store mailbox names on disk using UTF-8 instead of modified
      UTF-7.
    * 'BROKENCHAR' : Specifies an escape character that is used for broken
      mailbox names. If mailbox name can't be changed reversibly to UTF-8 and
      back, encode the problematic parts using<broken_char><hex> in the
      user-visible UTF-8 name. The broken_char itself also has to be encoded
      the same way. This can be useful with imapc to access mailbox names that
      aren't valid mUTF-7 charset from remote servers. (v2.2.32+)
    * 'CONTROL' : Specifies the location of control files under the <mbox>
      [MailLocation.mbox.txt] or <Maildir> [MailLocation.Maildir.txt] formats.
    * 'VOLATILEDIR' : Specifies the location of volatile files. This includes
      lock files and potentially other files that don't need to exist
      permanently. This is especially useful to avoid creating lock files to
      NFS or other remote filesystems. (v2.2.32+)
    * 'SUBSCRIPTIONS' : specifies the file used for storing subscriptions.  The
      default is "subscriptions".  If you're trying to avoid name collisions
      with a mailbox named "subscriptions", then also consider setting
      'MAILBOXDIR'.
    * 'MAILBOXDIR' : specifies directory name under which all mailbox
      directories are stored. With <dbox formats> [MailboxFormat.dbox.txt] the
      default is "mailboxes/" while with other mailbox formats the default is
      empty. Typically this should be changed only for <lazy_expunge namespace>
      [Plugins.Lazyexpunge.txt] with mdbox.
    * 'DIRNAME' : specifies the directory name used for mailbox directories, or
      in the case of mbox specifies the mailbox message file name. With <dbox
      formats> [MailboxFormat.dbox.txt] the default is "dbox-Mails/" while with
      other mailbox formats the default is empty. Can be used under either
      <mbox> [MailLocation.mbox.txt], <Maildir> [MailLocation.Maildir.txt] or
      <dbox> [MailLocation.dbox.txt] formats. Note that this directory is used
      only for the mail directory and the alt directory, not for index/control
      directories (but see below).
    * 'FULLDIRNAME' : Same as 'DIRNAME', but use the directory name also for
      index and control directory paths. This should be used instead of
      'DIRNAME' for new installations. (v2.2.8+)
    * 'ALT' : specifies the <Alternate storage> [MailLocation.dbox.txt] path
      for dbox formats.
 * The colons and equals signs are literal and there are no spaces in an actual
   mailbox location specification.

Variables
---------

You can use several variables in the 'mail_location' setting. See
<Variables.txt> for a full list, but the most commonly used ones are:

 * '%u': Full username.
 * '%n': User part in user@domain, same as %u if there's no domain.
 * '%d': Domain part in user@domain, empty if there's no domain.

Typical settings
----------------

Typically with Maildir it would be set to:

---%<-------------------------------------------------------------------------
mail_location = maildir:~/Maildir
---%<-------------------------------------------------------------------------

with mbox:

---%<-------------------------------------------------------------------------
mail_location = mbox:~/mail:INBOX=/var/mail/%u
---%<-------------------------------------------------------------------------

or if you'd like to use the <dbox> [MailboxFormat.dbox.txt] format:

---%<-------------------------------------------------------------------------
# single-dbox
mail_location = sdbox:~/dbox
---%<-------------------------------------------------------------------------

or:

---%<-------------------------------------------------------------------------
# multi-dbox
mail_location = mdbox:~/mdbox
---%<-------------------------------------------------------------------------

Use only absolute paths. Even if relative paths would appear to work, they
might just as well break some day.

Directory hashing
-----------------

You can use two different kinds of hashes in <variables> [Variables.txt]:

 * %H modifiers returns a 32bit hash of the given string as hex. For example
   '%2.256H' would return max. 256 different hashes in range 00 .. ff.
 * %M returns a MD5 hash of the string as hex. This can be used for two level
   hashing by getting substrings of the MD5 hash. For example '%1Mu/%2.1Mu/%u'
   returns directories from '0/0/user' to 'f/f/user'.

Index files
-----------

Index files are by default stored under the same directory as mails. With
maildir they are stored in the actual maildirs, with mbox they are stored under
'.imap/' directory. You may want to change the index file location if you're
using <NFS.txt> or if you're setting up <shared mailboxes>
[SharedMailboxes.txt].

You can change the index file location by adding ':INDEX=<path>' to
mail_location. For example:

---%<-------------------------------------------------------------------------
mail_location = maildir:~/Maildir:INDEX=/var/indexes/%u
---%<-------------------------------------------------------------------------

The index directories are created automatically, but note that it requires that
Dovecot has actually access to create the directories. Either make sure that
the index root directory ('/var/indexes' in the above example) is writable to
the logged in user, or create the user's directory with proper permissions
before the user logs in.

If you really want to, you can also disable the index files completely by
appending ':INDEX=MEMORY'.

Private index files (v2.2+)
---------------------------

Since v2.2 the recommended way to enable private flags for shared mailboxes is
to create private indexes with :INDEXPVT=<path>. See
<SharedMailboxes.Public.txt> for more information.

INBOX path
----------

INBOX path can be specified to exist elsewhere than the rest of the mailboxes,
for example:

---%<-------------------------------------------------------------------------
mail_location = mbox:~/mail:INBOX=/var/mail/%u
mail_location = maildir:~/Maildir:INBOX=~/Maildir/.INBOX
---%<-------------------------------------------------------------------------

Note that it's still not possible to mix maildir and mbox formats this way. You
need to use <namespaces> [Namespaces.txt] for that.

Homeless users
--------------

Having a home directory for users is highly recommended. The <Pigeonhole.txt>
<Sieve plugin> [Pigeonhole.Sieve.txt] already requires a home directory to
work, and it probably won't be the last feature to require a home. See
<VirtualUsers#homedirs> [VirtualUsers.txt] for more reasons why it's a good
idea, and how to give Dovecot a home directory even if you don't have a "real
home directory".

If you really don't want to set any home directory, you can use something like:

---%<-------------------------------------------------------------------------
mail_location = maildir:/home/%u/Maildir
---%<-------------------------------------------------------------------------

Per-user mail locations
-----------------------

It's possible to override the default 'mail_location' for specific users by
making the <user database> [UserDatabase.txt] return 'mail' <extra field>
[UserDatabase.ExtraFields.txt]. See the <user database> [UserDatabase.txt] page
for the specific userdb you're using for more information how to do this. 
Below are however a couple of examples.

Note that %h doesn't work in the userdb queries or templates. ~/ gets expanded
later, so use it instead.

Note also that since 'location' specified within a <namespace> [Namespaces.txt]
overrides mail_location setting, in case you specified that parameter, you'll
have to override in in the user database, specifying 'namespace/inbox/location'
extra field instead of 'mail'.

SQL
---

---%<-------------------------------------------------------------------------
user_query = SELECT home, uid, gid, mail FROM users WHERE user = '%u'
---%<-------------------------------------------------------------------------

LDAP
----

---%<-------------------------------------------------------------------------
user_attrs = homeDirectory=home, uidNumber=uid, gidNumber=gid,
mailLocation=mail
---%<-------------------------------------------------------------------------

Passwd-file
-----------

---%<-------------------------------------------------------------------------
user:{PLAIN}password:1000:1000::/home/user::userdb_mail=mbox:~/mail:INBOX=/var/mail/%u
---%<-------------------------------------------------------------------------

Mixing mbox and maildir
-----------------------

It's possible to use both mboxes and maildirs for the same user by configuring
multiple namespaces. See <Namespaces.txt>.

Having both mboxes and maildirs mixed within the same namespace isn't currently
supported.

Custom mailbox location detection
---------------------------------

Dovecot by default detects the mailboxes in this order:

 1. maildir: ~/Maildir
 2. mbox: ~/mail, and /var/mail/%u if it exists
 3. mbox: ~/Mail, and /var/mail/%u if it exists

If you need something else, you can override the 'mail_executable' setting to
run a script, which sets the MAIL environment properly. For example:

---%<-------------------------------------------------------------------------
#!/bin/sh

if [ -d $HOME/.maildir ]; then
  export MAIL=maildir:$HOME/.maildir
else
  export MAIL=mbox:$HOME/mail:INBOX=/var/mail/$USER
fi
export USERDB_KEYS="$USERDB_KEYS mail"

exec "$@"
---%<-------------------------------------------------------------------------

Custom namespace location
-------------------------

If you need to override namespace's location, first give it a name ("inbox"
below):

---%<-------------------------------------------------------------------------
namespace inbox {
  ..
}
---%<-------------------------------------------------------------------------

Then in the script use:

---%<-------------------------------------------------------------------------
#!/bin/sh

# do the lookup here
location=mbox:$HOME/mail

export USERDB_KEYS="$USERDB_KEYS namespace/inbox/location"
exec env "NAMESPACE/INBOX/LOCATION=$location" "$@"
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2019-06-19 12:42)