path: root/doc/wiki/Namespaces.txt

Namespaces
==========

Contents


 1. Namespaces

     1. Configuration

         1. Namespace types

         2. Hierarchy separators

         3. Namespace settings

         4. From userdb

     2. Shared Mailboxes

     3. Examples

         1. Mixed mbox and Maildir

         2. Backwards Compatibility: UW-IMAP

         3. Backwards Compatibility: Courier IMAP

         4. Per-user Namespace Location From SQL

         5. Hidden subscription namespace

Dovecot supports fully configurable namespaces. Their original and primary
purpose is to provide Namespace IMAP extension (RFC 2342
[http://www.faqs.org/rfcs/rfc2342.html]) support, which allows giving IMAP
clients hints about where to locate mailboxes and whether they're private,
shared or public. Unfortunately most IMAP clients don't support this extension.

Dovecot namespaces can be used for several other purposes too:

 * Changing the hierarchy separator
 * Providing backwards compatibility when switching from another IMAP server
 * Provides support for <public> [SharedMailboxes.Public.txt] and <shared>
   [SharedMailboxes.Shared.txt] mailboxes
 * Allows having mails in multiple different locations with possibly different
   formats

Configuration
-------------

In v2.1+ there's a default inbox namespace added in '10-mail.conf'. If the
configuration doesn't explicitly specify a namespace (as was in v2.0 and older)
a default namespace is created automatically.

The section name in namespaces (e.g. 'namespace sectionname { .. } ' is used
only internally within configuration. It's not required at all, but it allows
you to update an existing namespace (like how '15-mailboxes.conf' does) or have
userdb override namespace settings for specific users
('namespace/sectionname/prefix=foo/').

Namespace types
---------------

There are 3 types of namespaces:

 * private: Typically contains only user's own private mailboxes.
 * shared: Contains other users' <shared mailboxes>
   [SharedMailboxes.Shared.txt].
 * public: Contains <public mailboxes> [SharedMailboxes.Public.txt].

Hierarchy separators
--------------------

Hierarchy separator specifies the character that is used to separate a parent
mailbox from its child mailbox. For example if you have a mailbox "foo" with a
child mailbox "bar", the full path to the child mailbox would be "foo/bar" if
the separator was '/'. With a separator '.' it would be "foo.bar".

IMAP clients, Sieve scripts and many parts of Dovecot configuration use the
configured separator when referring to mailboxes. This means that if you change
the separator, you may break things.

However, changing the separator doesn't change the on-disk "layout separator".
For example:
+-----------------------------+--------+-----+----------+---------------------+
| mail_location               | Layout | NS  | Mailbox  | Directory           |
|                             | sep    | sep | name     |                     |
+-----------------------------+--------+-----+----------+---------------------+
| maildir:~/Maildir           | .      | .   | foo.bar  | ~/Maildir/.foo.bar/ |
+-----------------------------+--------+-----+----------+---------------------+
| maildir:~/Maildir           | .      | /   | foo/bar  | ~/Maildir/.foo.bar/ |
+-----------------------------+--------+-----+----------+---------------------+
| maildir:~/Maildir:LAYOUT=fs | /      | .   | foo.bar  | ~/Maildir/foo/bar/  |
+-----------------------------+--------+-----+----------+---------------------+
| maildir:~/Maildir:LAYOUT=fs | /      | /   | foo/bar  | ~/Maildir/foo/bar/  |
+-----------------------------+--------+-----+----------+---------------------+

Note how the "namespace separator" changes only the "Mailbox name", but doesn't
change the directory where the mails are stored. The "layout separator" can
only be changed by changing the LAYOUT, which also affects the entire directory
structure.

The layout separator also restricts the mailbox names. For example if the
layout separator is '.', you can't just set separator to '/' and create a
mailbox named "foo.bar". If you need to do this, you can use <listescape>
[Plugins.Listescape.txt] plugin to add escape the mailbox names as necessary.

A commonly used separator is '/'. It probably causes the least amount of
trouble with different IMAP clients.'^' separator is troublesome with
Thunderbird.When '\' should be used it must be quoted, so one sets separator =
"\\"

You should use the same hierarchy separator for all namespaces. All list=yes
namespaces must use the same separator, but if you find it necessary (e.g. for
backwards compatibility namespaces) you may use different separators for
list=no namespaces.

Namespace settings
------------------

 * type: See the "Namespace types" section above
 * separator: See the "Hierarchy separators" section above
 * prefix: The namespace prefix how it's visible in the NAMESPACE reply (if
   hidden=no) and mailbox list (if list=yes).
 * location: <Mailbox location> [MailLocation.txt]. The default is to use
   'mail_location' setting.
 * inbox: "yes", if this namespace contains the user's INBOX. There is only one
   INBOX, so only one namespace can have inbox=yes.
 * hidden: "yes", if this namespace shouldn't be listed in NAMESPACE reply.
 * list: "yes" (default), if this namespace and its mailboxes should be listed
   by LIST command when the namespace prefix isn't explicitly specified as a
   parameter. "children" means the namespace prefix list listed only if it has
   child mailboxes.
 * subscriptions: "yes" (default) if this namespace should handle its own
   subscriptions. If "no", then the first parent namespace with
   subscriptions=yes will handle it. For example if it's "no" for a namespace
   with prefix=foo/bar/, Dovecot first sees if there's a prefix=foo/ namespace
   with subscriptions=yes and then a namespace with an empty prefix. If neither
   is found, an error is given.
 * ignore_on_failure: Normally Dovecot fails if it can't successfully create a
   namespace. Set this to "yes" to continue even if the namespace creation
   fails (e.g. public namespace points to inaccessible location).
 * disabled: Set to "yes" to quickly disable this namespace. Especially useful
   when returned by a userdb lookup to give per-user namespaces.
 * alias_for: If multiple namespaces point to the same location, they should be
   marked as aliases against one primary namespace. This avoids duplicating
   work for some commands (listing the same mailbox multiple times). The value
   for alias_for is the primary namespace's prefix. For example if the primary
   namespace has empty prefix, set 'alias_for=' for the alias namespace. Or if
   primary has 'prefix=INBOX/', use 'alias_for=INBOX/'.
 * mailbox { .. } settings can be used to autocreate/autosubscribe mailboxes
   and set their SPECIAL-USE flags.

From userdb
-----------

To change namespace settings from userdb, you need to return
"namespace/<name>/setting=value". To create a namespace, make sure you first
return "namespace=<name>[,<name>,...]" and settings after this. Note that the
"namespace" setting must list all the namespaces that are used - there's
currently no way to simply "add" a namespace.

---%<-------------------------------------------------------------------------
userdb {
   driver = static
   args = namespace=inbox,special
namespace/special/location=sdbox:/var/special/%u
namespace/special/prefix=special/
}
---%<-------------------------------------------------------------------------

Shared Mailboxes
----------------

See <SharedMailboxes.txt>.

Examples
--------

Mixed mbox and Maildir
----------------------

If you have your INBOX as mbox in '/var/mail/username' and the rest of the
mailboxes in Maildir format under '~/Maildir', you can do this by creating two
namespaces:

---%<-------------------------------------------------------------------------
namespace {
  separator = /
  prefix = "#mbox/"
  location = mbox:~/mail:INBOX=/var/mail/%u
  inbox = yes
  hidden = yes
  list = no
}
namespace {
  separator = /
  prefix =
  location = maildir:~/Maildir
}
---%<-------------------------------------------------------------------------

Without the 'list = no' setting in the first namespace, clients would see the
"#mbox" namespace as a non-selectable mailbox named "#mbox" but with child
mailboxes (the mbox files in the '~/mail' directory), ie. like a directory. So
specifically with 'inbox = yes', having 'list = no' is often desirable.

Backwards Compatibility: UW-IMAP
--------------------------------

When switching from UW-IMAP and you don't want to give users full access to
filesystem, you can create hidden namespaces which allow users to access their
mails using their existing namespace settings in clients.

---%<-------------------------------------------------------------------------
# default namespace
namespace inbox {
  separator = /
  prefix =
  inbox = yes
}
# for backwards compatibility:
namespace compat1 {
  separator = /
  prefix = mail/
  hidden = yes
  list = no
  alias_for =
}
namespace compat2 {
  separator = /
  prefix = ~/mail/
  hidden = yes
  list = no
  alias_for =
}
namespace compat3 {
  separator = /
  prefix = ~%u/mail/
  hidden = yes
  list = no
  alias_for =
}
---%<-------------------------------------------------------------------------

Backwards Compatibility: Courier IMAP
-------------------------------------

*Recommended:* You can continue using the same INBOX. namespace as Courier:

---%<-------------------------------------------------------------------------
namespace inbox {
  separator = .
  prefix = INBOX.
  inbox = yes
}
---%<-------------------------------------------------------------------------

*Alternatively:* Create the INBOX. as a compatibility name, so old clients can
continue using it while new clients will use the empty prefix namespace:

---%<-------------------------------------------------------------------------
namespace inbox {
  separator = /
  prefix =
  inbox = yes
}

namespace compat {
  separator = .
  prefix = INBOX.
  inbox = no
  hidden = yes
  list = no
  alias_for =
}
---%<-------------------------------------------------------------------------

The "separator=/" allows the INBOX to have child mailboxes. Otherwise with
"separator=." it wouldn't be possible to know if "INBOX.foo" means INBOX's
"foo" child or the root "foo" mailbox in "INBOX." compatibility namespace. With
"separator=/" the difference is clear with "INBOX/foo" vs. "INBOX.foo".

The alternative configuration is not recommended, as it may introduce there
problems:

 * Although clients may do LIST INBOX.*, they may still do LSUB *, resulting in
   mixed results.
 * If clients used empty namespace with Courier, they now see the mailboxes
   with different names, resulting in redownloading of all mails (except
   INBOX).
 * Some clients may have random errors auto-detecting the proper default
   folders (Sent, Drafts etc) if the client settings refer to old paths while
   the server lists new paths.

See also <Migration.Courier.txt>.

Per-user Namespace Location From SQL
------------------------------------

You need to give the namespace a name, for example "docs" below:

---%<-------------------------------------------------------------------------
namespace docs {
  type = public
  separator = /
  prefix = Public/
}
---%<-------------------------------------------------------------------------

Then you have an SQL table like:

---%<-------------------------------------------------------------------------
CREATE TABLE Namespaces (
..
  Location varchar(255) NOT NULL,
..
)
---%<-------------------------------------------------------------------------

Now if you want to set the namespace location from the Namespaces table, use
something like:

---%<-------------------------------------------------------------------------
user_query = SELECT Location as 'namespace/docs/location' FROM Namespaces WHERE
..
---%<-------------------------------------------------------------------------

Hidden subscription namespace
-----------------------------

If you follow some advice to separate your INBOX, shared/ and public/
namespaces by choosing INBOX/ as your prefix for the inboxes you will see, that
you run into troubles with subscriptions.Thats, because there is no parent
namespace for shared/ and public/ if you set 'subscriptions = no' for those
namespaces.If you set 'subscriptions = yes' for shared/ and public/ you will
see yourself in the situation, that all users share the same subscription files
under the location of those mailboxes.One good solution is, to create a so
called "hidden subscription namespace" with subscriptions turned on and setting
'subscriptions = no' for the other namespaces:

---%<-------------------------------------------------------------------------
namespace subscriptions {
  subscriptions = yes
  prefix = ""
  list = no
  hidden = yes
}

namespace inbox {
  inbox = yes
  location =
  subscriptions = no
  mailbox Drafts {
    auto = subscribe
    special_use = \Drafts
  }
  mailbox Sent {
    auto = subscribe
    special_use = \Sent
  }
  mailbox "Sent Messages" {
    special_use = \Sent
  }
  mailbox Spam {
    auto = subscribe
    special_use = \Junk
  }
  mailbox Trash {
    auto = subscribe
    special_use = \Trash
  }
  prefix = INBOX/
  separator = /
}
namespace {
  type = shared
  prefix = shared/%%u/
  location = mdbox:%%h/mdbox:INDEXPVT=%h/mdbox/shared
  list = children
  subscriptions = no
}
namespace {
  type = public
  separator = /
  prefix = public/
  location = mdbox:/usr/local/mail/public/mdbox:INDEXPVT=%h
  subscriptions = no
  list = children
}
---%<-------------------------------------------------------------------------

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