Mail Location Settings¶
Note
For an overview of Dovecot’s supported mailbox formats, see Mailbox Formats.
There are three different places where the mail location is looked up from:
mail_location
indovecot.conf
is used if nothing else overrides it.mail User Databases (userdb) overrides
mail_location
setting.location
setting inside Namespaces overrides everything. Usually this should be used only for public and shared namespaces.
Format¶
The format of the mailbox location specification is:
<mailbox-format> : <path> [ : <key> = <value> [ : <key2> = <value2> ... ] ]
where:
mailbox-format
is a tag identifying one of the formats described at Mailbox formats.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 (see Home vs. mail directory).key = value
can appear zero or more times to set various optional parameters.The colons and equals signs are literal and there are no spaces in an actual mailbox location specification.
Keys¶
Note
This table is intended as an abstract list of what keys exist; see the individual mailbox format pages for further information on how to use these keys.
List of available keys:
Key |
Value Description |
---|---|
|
Location of Dovecot index files.
New in version v2.2.32. |
|
Location of the INBOX path. |
|
Directory layout to use: |
|
Automatically delete any New in version v2.2.32. |
|
Store mailbox names on disk using UTF-8 instead of modified UTF-7 (mUTF-7). |
|
Specifies an escape character that is used for broken or
otherwise inaccessible mailbox names. If mailbox name
can’t be changed reversibly to UTF-8 and back, encode the
problematic parts using New in version v2.2.32. Changed in version v2.3.14: Conflicting separators are also escaped. |
|
Specifies the location of control files. |
|
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. New in version v2.2.32. |
|
Specifies the filename used for storing subscriptions. The
default is |
|
Specifies directory name under which all mailbox directories are stored. The default is empty unless otherwise described in the mailbox format pages. |
|
Specifies the directory name used for mailbox, index, and
control directory paths. See the individual mailbox format
pages for further information. This key replaced the
deprecated New in version v2.2.8. |
|
Specifies the alternate storage path. |
Deprecated Keys¶
Key |
Replaced By |
Value Description |
---|---|---|
|
|
Specifies the directory name used for mailbox directories, or in the case of mbox specifies the mailbox message file name. Note DIRNAME is not used for index or
control directories, while
Deprecated since version v2.2.8. |
Variables¶
You can use several variables in the mail_location
setting.
See Config Variables for a full list, but the most commonly used ones
are:
Variable |
Description |
---|---|
|
Full username. |
|
User part in |
|
Domain part in |
Directory Hashing¶
You can use three different kinds of hashes in Config Variables.
%N
is MD5-based “new hash” which works similarly to%H
except it gives more uniform results.Example:
%2.256N
would return maximum 256 different hashes in range00..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.Example:
%1Mu/%2.1Mu/%u
returns directories from0/0/user
tof/f/user
.
%H
returns a 32bit hash of the given string as hex.This is the old, deprecated method.
%N
should be used instead.
Index Files¶
Index files are by default stored under the same directory as mails.
You may want to change the index file location if you’re using NFS or if you’re setting up Shared mailboxes.
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.
Index files can be disabled completely by appending :INDEX=MEMORY
. This
is not recommended for production use, as the index files will need to be
generated on every access.
Private Index Files¶
New in version v2.2.
The recommended way to enable private flags for shared mailboxes is to create
private indexes with :INDEXPVT=<path>
. See Public Mailboxes
for more information.
INBOX Path¶
INBOX path can be specified to exist elsewhere than the rest of the mailboxes.
Example:
mail_location = maildir:~/Maildir:INBOX=~/Maildir/.INBOX
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
.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.
Custom Autodetection¶
If you need something besides the default autodetection, you can use Post-login scripting.
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 "$@"
Mailbox Autocreation¶
Autocreation is only triggered if mail_location
is
correctly set. You’ll see something like this if you enable
debug logging
(example for mbox
mailbox
format):
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.
Home-less Users¶
Having a home directory for users is highly recommended. At a minimum, the Pigeonhole Sieve plugin requires a home directory to work. See Home Directories for Virtual Users 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 Databases (userdb) return
mail
extra field.
Note that %h
doesn’t work in the userdb queries or templates. ~/
gets
expanded later, so use it instead.
Note
Since a location specified within a Namespaces overrides
mail_location
, 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 Multiple Mailbox Formats¶
It’s possible to use different mailbox formats same user by configuring multiple namespaces. See Namespaces. Each mailbox format has to live in a different namespace. Mixing mailbox formats within the same namespace is not supported.
Custom Namespace Location¶
If you need to override namespace’s location, first give it a name (inbox
in this example):
namespace inbox {
}
Then in the executable 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" "$@"