Mailbox Namespaces

Cyrus IMAP supports the personal, the other users and zero or more shared namespaces.

With a history in news-groups, Cyrus IMAP versions prior to version 3.0 default to using the netnews namespace convention.

Note

Cyrus IMAP documentation is a work in progress. The completion of this particular part of the documentation is pending the resolution of :task:`47`.

Namespace Convention: netnews

By default, up to versions prior to Cyrus IMAP version 3.0, Cyrus IMAP uses the netnews namespace convention – a . (dot) character is used as the hierarchy separator.

Further implications and limitations of this convention include:

  • Mailbox names are case-sensitive,

  • A mailbox name may not start with a . (dot) character,

  • A mailbox name may not contain two . (dot) characters in a row,

  • non-ASCII characters and shell meta-characters are not permitted in mailbox names.

While the aforementioned implications of the netnews namespace convention apply under all circumstances, some of the implications imposed by the netnews namespace convention can be influenced by specifying additional configuration options to Cyrus IMAP, such as is the case with the hierarchy seperator.

When using the netnews namespace convention, the default, a user’s shorthand qualifier (e.g. john for john@example.org) MAY NOT contain a . (dot) character, as the character is being used as a hierarchy separator in mailbox names, and would thus create a personal mailbox rather then a user’s INBOX. Therefore, using john.doe for the INBOX name for user John Doe <john.doe@example.org> does not work, as it would create a sub-folder doe for the INBOX user.john.

The same limitation goes for the use of virtual domains. Since a mailbox in a virtual domain typically uses a fully qualified user identifier (e.g. john@example.org, thus including a valid (sub-)domain name), the . (dot) character is inherited from the Domain Name System naming convention. This poses a problem without the use of the . (dot) character as a mailbox hierarchy separator.

To illustrate the effects on an environment, please examine the following procedure, starting from a clean Cyrus IMAP installation:

Example Effects of Using the Netnews Namespace Convention

In imapd.conf(5), ensure the following settings are configured:

  • unixhierarchysep: 0, to ensure the use of the netnews namespace convention regardless of defaults, and

  • delete_mode: immediate, to allow us to clean up afterward,

  • virtdomains: userid, to allow both realmed and unrealmed mailbox names.

See also

  • Check configuration settings with cyr_info

We’ll attempt to create a mailbox for the user John Doe <john@example.org> using the shorthand qualifier (e.g. john), and the fully qualified user identifier (e.g. john@example.org).

$ cyradm -u cyrus localhost
verify error:num=18:self signed certificate
IMAP Password:
localhost> lm
localhost> cm user/john
createmailbox: Invalid mailbox name
localhost> cm user.john
localhost> lm
user.john (HasNoChildren)
localhost> lam user.john
john lrswipkxtecda

The mailbox user.john has been created succesfully using the shorthand qualifier, and could not be created using the unix hierarchy separator.

However, realmed mailboxes can also not be created:

localhost> cm user.john@example.org
createmailbox: Permission denied

Let’s try to avoid the possibility of any conflict occuring, and remove user.john first:

localhost> sam user.john cyrus all
localhost> dm user.john
localhost> cm user.john@example.org
createmailbox: Permission denied

A mailbox name of user.john@example.org is still not considered valid.

Namespace Convention: “not netnews”

An alternative hierarchy separator can be used to allow the use of . (dot) characters in mailbox names: the UNIX hierarchy separator.

The UNIX hierarchy separator is a / (forward slash) character, and is configured by setting in imapd.conf(5):

  • unixhierarchysep: 1

See also

  • Check configuration settings with cyr_info

Restart the cyrus-imapd service and attempt to create a mailbox for user john@example.org using the shorthand qualifier (e.g. john), and the fully qualified user identifier (e.g. john@example.org).

$ cyradm -u cyrus localhost
verify error:num=18:self signed certificate
IMAP Password:
localhost> lm
localhost> cm user/john
localhost> lm
user/john (HasNoChildren)
localhost> cm user/john@example.org
localhost> lm
user/john (HasNoChildren)
user/john@example.org (HasNoChildren)
localhost> lam user/john
john lrswipkxtecda
localhost> lam user/john@example.org
john@example.org lrswipkxtecda
localhost> sam user/john cyrus all
localhost> sam user/john@example.org cyrus all
localhost> dm user/john
localhost> dm user/john@example.org
localhost> lm
localhost>

As you can see, the mailbox has been created succesfully using the shorthand qualifier, and has been created using the fully qualified user identifier as well.

Alternate Namespace

In a default situation, with Cyrus IMAP versions prior to version 3.0 using the netnews namespace convention, a user John Doe <john@example.org> would start out with a mailbox INBOX, and will quickly want to create sub-folders such as for drafted and sent messages.

These mailboxes will be presented to John’s client as follows:

  • INBOX

  • INBOX.Drafts

  • INBOX.Sent Items

With the UNIX hierarchy separator enabled, the list would look as follows:

  • INBOX

  • INBOX/Drafts

  • INBOX/Sent Items

Cyrus IMAP allows the configuration of an alternative namespace, where the INBOX folder holds no sub-folders. Compared to the previous two lists this would look as follows (independent from the use of the UNIX hierarchy separator):

  • INBOX

  • Drafts

  • Sent Items

To configure the use of the alternative namespace, use the altnamespace setting in imapd.conf(5) and set it to 1.

Note

Changing altnamespace in a currently operating environment will cause all IMAP clients to need to resync the entire hierarchy.

Internal Namespace

The internal namespace refers to how Cyrus IMAP maintains lists of mailboxes. It is literaly internal to Cyrus IMAP, and should be considered in contrast to Administrator Namespaces.

Personal Namespace

A mailbox in the Personal Namespace is a mailbox that belongs to a user account. As such, in the internal namespace, these mailboxes start with the literal string user..

For a realmed mailbox such as user/john@example.org however – remember we have needed to configure virtdomains to any value other than off, and unixhierarchysep to 1 –, is stored internally as example.org!user.john.

Since dot characters are allowed in the mailbox names, one may have a naming convention that leads user John Doe to hold an email address of john.doe@example.org. The internal representation of this mailbox is example.org!user.john^doe.

Note

A second user mailbox, if shared with John, would present itself to John as being in the Other Users Namespace, however the internal accounting for it remains the same.

Administrator Namespaces

An administrator – a user for which the username is included in the admins setting in imapd.conf(5) – has a different perspective when using the IMAP protocol to perform administrative tasks.

An administrator user cyrus for example, may see the following mailboxes:

  • user.jane

  • user.jane.Drafts

  • user.jane.Sent Items

  • user.john

  • user.john.Drafts

  • user.john.Sent Items

This would be the case with the netnews namespace convention (i.e. unixhierarchysep: 0), and regardless of the altnamespace setting.

With the UNIX hierarchy separator enabled, the list would look as follows:

  • user/jane

  • user/jane/Drafts

  • user/jane/Sent Items

  • user/john

  • user/john/Drafts

  • user/john/Sent Items

Continuing with the UNIX hierarchy separator enabled, should virtual domains be in use, the list may appear to the administrator user cyrus as follows:

  • user/jane@example.org

  • user/jane/Drafts@example.org

  • user/jane/Sent Items@example.org

  • user/john@example.org

  • user/john/Drafts@example.org

  • user/john/Sent Items@example.org

But the admins setting in imapd.conf(5) allows for a username of admin@example.org to be specified as an administrator as well. Should admin@example.org take a peek, then the following list would appear:

  • user/jane

  • user/jane/Drafts

  • user/jane/Sent Items

  • user/john

  • user/john/Drafts

  • user/john/Sent Items

Important

In multi-domain or multi-tenant environments, the following mailboxes may exist:

  • user/john

  • user/john@example.com

  • user/john@example.org

Let it be understood that an unrealmed cyrus administrator user can administrator mailboxes in each of the three realms (null for user/john, example.com for user/john@example.com and example.org for user/john@example.org), but a realmed administrator admin@example.org will only be able to administer mailboxes within the example.org authorization realm, and will only see mailboxes within that realm example.org, in this case being presented as user/john – not to be confused with the actually unrealmed user/john mailbox that exists on the system as well.

Personal Namespace

The personal namespace refers to the hierarchy of mailboxes that a Cyrus IMAP user owns, such as user John Doe <john.doe@example.org> being the owner of the user/john.doe@example.org hierarchy.

John will typically view his personal namespace such that sub-folders of his INBOX may not have a distinguished prefix – other than perhaps INBOX if altnamespace is disabled:

INBOX
Drafts
Sent Items
Spam
Trash

With John and Jane in the same environment, in case mailboxes from each user’s personal namespace are shared with the other user, the Other Users Namespace namespace kicks in when these mailboxes are viewed.

For John Doe <john.doe@example.org>, with Jane Doe <jane.doe@example.org> sharing a selection of the mailboxes in her personal namespace:

INBOX
Drafts
Sent Items
Spam
Trash
Other Users/jane.doe
Other Users/jane.doe/Subfolder

Note that the prefix used here is “Other Users” to indicate the mailbox in question is in fact a part of another user’s personal namespace.

Other Users Namespace

The Other Users namespace is a namespace that is reserved for mailboxes in other user’s personal namespaces, that have been shared with the current user.

The other users namespace can be suppressed in LIST commands by setting disable_user_namespace to 1 in imapd.conf(5). This can be advantageous to larger environments because of the nature of the Discretionary Access Control Cyrus IMAP entertains by default.

Shared Namespaces

Shared namespaces contain – as the name already suggests – mailboxes that are not owned by any one particular user, albeit one or more actual users may have administrative rights on the folders.

Multiple shared namespaces can be created, aside from those named user – as this hierarchy is reserved for the Personal Namespace of each user.

Examples of shared folders could include:

Shared mail folders for mailing list traffic

  • lists/cyrus.foundation/announce@example.org

  • lists/cyrus.foundation/devel@example.org

Shared mail folders for common email addresses

  • shared/contact@example.org

  • shared/hostmaster@example.org

  • shared/info@example.org

  • shared/postmaster@example.org

  • shared/root@example.org

  • shared/webmaster@example.org

The shared namespace can be suppressed in LIST commands by setting disable_shared_namespace to 1 in imapd.conf(5). This can be advantageous to larger environments that want to avoid all LIST operations to result in very large, long lists of folders.

Back to IMAP Features