This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.
Differences between revisions 1 and 66 (spanning 65 versions)
Revision 1 as of 2005-03-05 20:24:41
Size: 1998
Editor: TimoSirainen
Comment:
Revision 66 as of 2016-04-21 18:52:48
Size: 9734
Editor: TimoSirainen
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
In configuration file the default mail location is set using `default_mail_env` setting.  * For mbox-specific settings, see [[MailLocation/mbox]]
 * For Maildir-specific settings, see [[MailLocation/Maildir]]
 * For dbox-specific settings, see [[MailLocation/dbox]]
Line 5: Line 7:
You can use some variables in the value: There are three different places where the mail location is looked up from:
Line 7: Line 9:
 * %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
 * %h - home directory
 1. {{{mail_location}}} setting in {{{dovecot.conf}}} is used if nothing else overrides it.
 1. {{{mail}}} [[UserDatabase|userdb field]] overrides {{{mail_location}}} setting.
 1. {{{location}}} setting inside namespaces overrides everything. Usually this should be used only for public and shared namespaces.
Line 12: Line 13:
In 1.0-test versions there are more, see [wiki:Variables Variables]. 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 at `~/Maildir`, `/var/mail/username`, `~/mail` and `~/Mail` in that order. It's usually a good idea to explicitly specify where the mails are, even if the autodetection happens to work. Autodetection commonly fails for new users who don't have the mail directory created yet.
Line 14: Line 15:
Typically with maildir this would be set to: == Format ==

The format of the mailbox location specification is as follows:

  ''[[MailboxFormat|mailbox-format]]'' : ''path'' [ : ''key'' = ''value'' … ]

where:

 * ''mailbox-format'' is a tag identifying one of the formats described at [[MailboxFormat|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, for reasons see [[VirtualUsers/Home|Home vs. mail directory]]
 * ''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|index files]].
  * {{{INBOX}}} : specifies the location of the [[#INBOX path|INBOX]].
  * {{{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.
  * {{{UTF-8}}} : Store mailbox names on disk using UTF-8 instead of modified UTF-7.
  * {{{CONTROL}}} : specifies the location of control files under the [[MailLocation/mbox#Control_files|mbox]] or [[MailLocation/Maildir#Control_files|Maildir]] formats.
  * {{{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 [[MailboxFormat/dbox|dbox formats]] the default is "mailboxes/" while with other mailbox formats the default is empty. Typically this should be changed only for [[Plugins/Lazyexpunge|lazy_expunge namespace]] with mdbox.
  * {{{DIRNAME}}} : specifies the directory name used for mailbox directories, or in the case of mbox specifies the mailbox message file name. With [[MailboxFormat/dbox|dbox formats]] the default is "dbox-Mails/" while with other mailbox formats the default is empty. Can be used under either [[MailLocation/mbox#Message_file_name|mbox]], [[MailLocation/Maildir#Mailbox_directory_name|Maildir]] or [[MailLocation/dbox#Mailbox_directory_name|dbox]] 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 [[MailLocation/dbox#Alternate_storage|Alternate storage]] 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]] 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:
Line 17: Line 54:
default_mail_env = maildir:%h/Maildir mail_location = maildir:~/Maildir
Line 20: Line 57:
or with mbox: with mbox:
Line 23: Line 60:
default_mail_env = mbox:%h/mail:INBOX=/var/mail/%u mail_location = mbox:~/mail:INBOX=/var/mail/%u
Line 26: Line 63:
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 can change these by adding `:INDEX=location` to location string. For example: or if you'd like to use the [[MailboxFormat/dbox|dbox]] format:
Line 29: Line 66:
default_mail_env = mbox:%h/mail:INBOX=/var/mail/%u:INDEX=%h/indexes # single-dbox
mail_location = sdbox:~/dbox
Line 32: Line 70:
If you didn't set home directory, %h can't be used. Instead you can do something like: or:
Line 35: Line 73:
default_mail_env = maildir:/home/%u/Maildir # multi-dbox
mail_location = mdbox:~/mdbox
Line 38: Line 77:
With virtual users the mail and home directories are probably the same. In that case you would just do: 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]]:

 * %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}}}.

<<Anchor(indexfiles)>>
== 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]] or if you're setting up [[SharedMailboxes|shared mailboxes]].

You can change the index file location by adding {{{:INDEX=<path>}}} to mail_location. For example:
Line 41: Line 94:
default_mail_env = maildir:%h mail_location = maildir:~/Maildir:INDEX=/var/indexes/%u
Line 44: Line 97:
= Per-user mail locations = 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.
Line 46: Line 99:
It's possible to override `default_mail_env` for specific users in authentication userdb. If you really want to, you can also disable the index files completely by appending {{{:INDEX=MEMORY}}}.
Line 48: Line 101:
== SQL == == Private index files (v2.2+) ==
Line 50: Line 103:
Return `mail` field in `user_query`, for example: Since v2.2 the recommended way to enable private flags for shared mailboxes is to create private indexes with :INDEXPVT=<path>. See [[SharedMailboxes/Public]] for more information.

== INBOX path ==

INBOX path can be specified to exist elsewhere than the rest of the mailboxes, for example:
Line 53: Line 110:
user_query = SELECT home, uid, gid, mail FROM users WHERE user = '%u' mail_location = mbox:~/mail:INBOX=/var/mail/%u
mail_location = maildir:~/Maildir:INBOX=~/Maildir/.INBOX
Line 56: Line 114:
== LDAP == Note that it's still not possible to mix maildir and mbox formats this way. You need to use [[Namespaces|namespaces]] for that.
Line 58: Line 116:
Specify mail attribute in `user_attrs`, for example: == Homeless users ==

Having a home directory for users is highly recommended. The [[Pigeonhole]] [[Pigeonhole/Sieve|Sieve plugin]] already requires a home directory to work, and it probably won't be the last feature to require a home. See [[VirtualUsers#homedirs]] 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:
Line 61: Line 123:
user_attrs = uid,homeDirectory,mailLocation,,uidNumber,gidNumber 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 [[UserDatabase|user database]] return `mail` [[UserDatabase/ExtraFields|extra field]]. See the [[UserDatabase|user database]] 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 [[Namespaces|namespace]] 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
Line 64: Line 144:
== passwd-file ==

The mail attribute is set as last field in passwd-file, for example:
=== Passwd-file ===
Line 69: Line 147:
user:{PLAIN}password:1000:1000::/home/user:/bin/false::mbox:%h/mail:INBOX=/var/mail/%u 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]].

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
 1. mbox: ~/mail, and /var/mail/%u if it exists
 1. 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:

{{{#!plain
#!/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 "$@"
Line 72: Line 178:
= Mixing mbox and maildir = === Custom namespace location ===
Line 74: Line 180:
With 1.0-tests it's possible to use both mboxes and maildirs for same user with namespaces. See [wiki:Namespaces Namespaces]. If you need to override namespace's location, first give it a name ("user" below):

{{{
namespace user {
  ..
}
}}}

Then in the script use:

{{{#!plain
#!/bin/sh

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

export USERDB_KEYS="$USERDB_KEYS namespace/user/location"
exec env "NAMESPACE/USER/LOCATION=$location" "$@"
}}}

Mail location

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 overrides mail_location setting.

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

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 at ~/Maildir, /var/mail/username, ~/mail and ~/Mail in that order. It's usually a good idea to explicitly specify where the mails are, even if the autodetection happens to work. Autodetection commonly fails for new users who don't have the mail directory created yet.

Format

The format of the mailbox location specification is as follows:

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, for reasons see Home vs. mail directory

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

    • INBOX : specifies the location of the INBOX.

    • 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.
    • UTF-8 : Store mailbox names on disk using UTF-8 instead of modified UTF-7.

    • CONTROL : specifies the location of control files under the mbox or Maildir formats.

    • 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 the default is "mailboxes/" while with other mailbox formats the default is empty. Typically this should be changed only for lazy_expunge namespace 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 the default is "dbox-Mails/" while with other mailbox formats the default is empty. Can be used under either mbox, Maildir or dbox 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 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 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 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:

  • %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 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.

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 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 for that.

Homeless users

Having a home directory for users is highly recommended. The Pigeonhole Sieve plugin already requires a home directory to work, and it probably won't be the last feature to require a home. See VirtualUsers#homedirs 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 return mail extra field. See the user database 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 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.

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 ("user" below):

namespace user {
  ..
}

Then in the script use:

#!/bin/sh

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

export USERDB_KEYS="$USERDB_KEYS namespace/user/location"
exec env "NAMESPACE/USER/LOCATION=$location" "$@"

None: MailLocation (last edited 2019-09-11 14:05:46 by MichaelSlusarz)