| 1 |
:tocdepth: 2 |
| 2 |
|
| 3 |
.. _mailbox-namespaces: |
| 4 |
|
| 5 |
================== |
| 6 |
Mailbox Namespaces |
| 7 |
================== |
| 8 |
|
| 9 |
.. TODO: Virtual domains info/new page |
| 10 |
don't share cross-domain in netnews mode with virtual domains. Bad Things happen. |
| 11 |
virtual domains don't display if you're sharing (other users/shared) within the same domain |
| 12 |
|
| 13 |
Namespace Basics |
| 14 |
================== |
| 15 |
|
| 16 |
**What is a namespace?** A namespace is a hierarchical list of mailboxes a user has access to, named to maintain uniqueness and provide access control. |
| 17 |
|
| 18 |
There are four different uses of the term "namespace" within Cyrus: |
| 19 |
|
| 20 |
1. **IMAP NAMESPACE command** |
| 21 |
|
| 22 |
This is the set of mailboxes a user has access to and is the namespace as defined by :rfc:`2342` in response to the ``IMAP NAMESPACE`` command. |
| 23 |
|
| 24 |
A user can have access to three different kinds of mailboxes: their own (known as *personal*), other people's mailboxes that they have shared access to (known as *other users*) and any mailboxes that have more than one owner (known as *shared*). |
| 25 |
|
| 26 |
More info at :ref:`imap-admin-namespaces-user-access`. |
| 27 |
|
| 28 |
2. **User namespace mode: altnamespace** |
| 29 |
|
| 30 |
Cyrus's user namespace mode controls how it responds to the ``IMAP NAMESPACE`` command and what the hierarchy of mailboxes looks like in response to an ``IMAP LIST`` command for a user. The config setting *altnamespace*: on or off in :cyrusman:`imapd.conf(5)` manages the mode. It is also affected by the hierarchy separator, which can be "/" (default: on) or "." (off) controlled by *unixhierarchysep* in :cyrusman:`imapd.conf(5)`. |
| 31 |
|
| 32 |
1. altnamespace: on (default) |
| 33 |
|
| 34 |
* personal: "" (empty string) |
| 35 |
* other users: "Other Users" (The string can be changed in :cyrusman:`imapd.conf(5)` with ``userprefix``) |
| 36 |
* shared: "Shared Folders" (The string can be changed in :cyrusman:`imapd.conf(5)` with ``sharedprefix``) |
| 37 |
|
| 38 |
2. altnamespace: off (was known as standard or regular) |
| 39 |
|
| 40 |
* personal: INBOX |
| 41 |
* other users: user |
| 42 |
* shared: "" (empty string) |
| 43 |
|
| 44 |
.. NOTE:: |
| 45 |
|
| 46 |
altnamespace mode is valid only for the *user* namespace: it doesn't affect the :ref:`administrator's view <imap-admin-namespaces-administrator>`. |
| 47 |
|
| 48 |
Consider a user "uhura". Uhura can see all the folders from user "spock", some folders from users "kirk", as well as the shared folder "commandcrew". |
| 49 |
|
| 50 |
Under altnamespace:off mode with a ``.`` separator, she sees her folders as: |
| 51 |
|
| 52 |
* INBOX |
| 53 |
* INBOX.folder-1 |
| 54 |
* INBOX.folder-2 (etc) |
| 55 |
* user.spock (this is INBOX for "spock") |
| 56 |
* user.spock.folder-x |
| 57 |
* user.kirk.folder-y ("kirk" hasn't shared their INBOX) |
| 58 |
* commandcrew |
| 59 |
|
| 60 |
Under altnamespace:on mode with a ``/`` separator, she sees her folders as: |
| 61 |
|
| 62 |
* INBOX (INBOX is special in IMAP and is always the users Inbox) |
| 63 |
* folder-1 |
| 64 |
* folder-2 (etc) |
| 65 |
* Other Users/spock |
| 66 |
* Other Users/spock/folder-x |
| 67 |
* Other Users/kirk/folder-y |
| 68 |
* Shared Folders/commandcrew |
| 69 |
|
| 70 |
.. warning:: |
| 71 |
|
| 72 |
When using a ``.`` separator (unixhierarchysep: off), user names and folder names |
| 73 |
internally swap the ``.`` with ``^``. This is because dots mark a subfolder if |
| 74 |
you're not using unixhierarchy separators. Some IMAP clients do not cope well with the ^ character, which is why |
| 75 |
unixhierarchysep: on is now the default as it allows dots in usernames and folder names. |
| 76 |
|
| 77 |
More info at :ref:`imap-admin-namespaces-mode`. |
| 78 |
|
| 79 |
3. **Administrator namespace** |
| 80 |
|
| 81 |
While a user has their three kinds of mailboxes they have access to, an administrator can see all mailboxes (optionally restricted to the administrator's own domain). As a result, the response to ``LIST`` commands is different for administrators. |
| 82 |
|
| 83 |
In the administrator namespace, all user mailboxes are presented as ``user/<username>/<folder>`` (with unixhierarchysep: on) and with ``@<domain>`` appended in virtual domain mode. Shared folders appear at the top level. The user namespace mode (altnamespace on/off) does NOT affect administrator mode; only the hierarchy separator affects display. |
| 84 |
|
| 85 |
For unixhierarchy separators: |
| 86 |
|
| 87 |
* shared/commandcrew |
| 88 |
* user/[email protected] |
| 89 |
* user/uhura/[email protected] |
| 90 |
* user/[email protected] |
| 91 |
* user/spock/[email protected] |
| 92 |
* user/[email protected] |
| 93 |
* user/[email protected] |
| 94 |
|
| 95 |
More info at :ref:`imap-admin-namespaces-administrator`. |
| 96 |
|
| 97 |
4. **Internal namespace** |
| 98 |
|
| 99 |
Developer reference only. This is how each mailbox is uniquely stored inside ``mailboxes.db``. Each mailbox name has a unique representation that is the "key" in the mailboxes.db key-value database. |
| 100 |
|
| 101 |
* commandcrew (??) |
| 102 |
* example.com!user.uhura |
| 103 |
* example.com!user.uhura.folder-1 |
| 104 |
* example.com!user.spock |
| 105 |
* example.com!user.spock.folder-x |
| 106 |
* example.com!user.kirk |
| 107 |
* example.com|user.mc^coy |
| 108 |
|
| 109 |
More info at :ref:`imap-developer-namespaces`. |
| 110 |
|
| 111 |
.. _imap-admin-namespaces-user-access: |
| 112 |
|
| 113 |
User Access Namespaces |
| 114 |
====================== |
| 115 |
|
| 116 |
.. _imap-features-namespaces-personal: |
| 117 |
|
| 118 |
Personal Namespace |
| 119 |
------------------ |
| 120 |
|
| 121 |
The personal namespace refers to the hierarchy of mailboxes that a |
| 122 |
Cyrus IMAP user owns, such as user *Nyota Uhura <[email protected]>* |
| 123 |
being the owner of the ``user/[email protected]`` hierarchy. |
| 124 |
|
| 125 |
Mailboxes in the personal namespace start with the literal string ``user``. |
| 126 |
|
| 127 |
Uhura will typically view her personal namespace such that sub-folders of |
| 128 |
her INBOX may not have a distinguished prefix -- other than perhaps |
| 129 |
``INBOX`` if ``altnamespace`` is disabled: |
| 130 |
|
| 131 |
.. parsed-literal:: |
| 132 |
|
| 133 |
INBOX |
| 134 |
Drafts |
| 135 |
Sent Items |
| 136 |
Spam |
| 137 |
Trash |
| 138 |
|
| 139 |
.. _imap-features-namespaces-other-users: |
| 140 |
|
| 141 |
Other Users Namespace |
| 142 |
--------------------- |
| 143 |
|
| 144 |
The Other Users namespace is a namespace that is reserved for mailboxes |
| 145 |
in other user's personal namespaces, that have been shared with the |
| 146 |
current user. |
| 147 |
|
| 148 |
With *Spock* and *Kirk* in the same environment, who are also sharing |
| 149 |
their personal mailboxes with *Uhura*, the |
| 150 |
:ref:`imap-features-namespaces-other-users` namespace kicks in when |
| 151 |
these mailboxes are viewed. |
| 152 |
|
| 153 |
For *Nyota Uhura <[email protected]>*, with |
| 154 |
*James Kirk <[email protected]>* sharing a selection of his mailboxes, Uhura's mailbox list looks like: |
| 155 |
|
| 156 |
.. parsed-literal:: |
| 157 |
|
| 158 |
INBOX |
| 159 |
Drafts |
| 160 |
Sent Items |
| 161 |
Spam |
| 162 |
Trash |
| 163 |
Other Users/james.kirk |
| 164 |
Other Users/james.kirk/Subfolder |
| 165 |
|
| 166 |
Note that the prefix used here is "Other Users" to show the mailbox |
| 167 |
in question is part of another user's personal namespace. |
| 168 |
|
| 169 |
The other users namespace can be suppressed in LIST commands by setting |
| 170 |
``disable_user_namespace`` to ``1`` in :cyrusman:`imapd.conf(5)`. This |
| 171 |
is useful in larger environments because of the nature of the |
| 172 |
:ref:`imap-admin-access-control-lists-discretionary` Cyrus IMAP |
| 173 |
entertains by default. |
| 174 |
|
| 175 |
.. _imap-features-namespaces-shared: |
| 176 |
|
| 177 |
Shared Namespaces |
| 178 |
----------------- |
| 179 |
|
| 180 |
Shared namespaces contain mailboxes |
| 181 |
that are not owned by any one user, though one or more actual |
| 182 |
users have administrative rights on the folders. |
| 183 |
|
| 184 |
More than one shared namespaces can be created (aside from those named |
| 185 |
``user`` as this hierarchy is reserved for the |
| 186 |
:ref:`imap-features-namespaces-personal` of each user). |
| 187 |
|
| 188 |
Examples of shared folders could include: |
| 189 |
|
| 190 |
.. rubric:: Shared mail folders for mailing list traffic |
| 191 |
|
| 192 |
* ``lists/cyrus.imap/[email protected]`` |
| 193 |
* ``lists/cyrus.imap/[email protected]`` |
| 194 |
|
| 195 |
.. rubric:: Shared mail folders for common email addresses |
| 196 |
|
| 197 |
* ``shared/[email protected]`` |
| 198 |
* ``shared/[email protected]`` |
| 199 |
* ``shared/[email protected]`` |
| 200 |
* ``shared/[email protected]`` |
| 201 |
* ``shared/[email protected]`` |
| 202 |
* ``shared/[email protected]`` |
| 203 |
|
| 204 |
The shared namespace can be suppressed in LIST commands by setting |
| 205 |
``disable_shared_namespace`` to ``1`` in :cyrusman:`imapd.conf(5)`. This |
| 206 |
is useful in larger environments that want to avoid all LIST |
| 207 |
operations which can result in large, long lists of folders. |
| 208 |
|
| 209 |
.. _imap-admin-namespaces-mode: |
| 210 |
|
| 211 |
User Namespace Mode |
| 212 |
=================== |
| 213 |
|
| 214 |
altnamespace: on or off |
| 215 |
----------------------- |
| 216 |
|
| 217 |
.. note:: |
| 218 |
If you are upgrading an existing server which uses :cyrusman:`timsieved(8)` to manage Sieve scripts and choose to swap namespace modes, you should run the script :cyrusman:`translatesieve(8)` after configuring the namespace option(s). This script will translate the folder names in fileinto actions. |
| 219 |
|
| 220 |
By default Cyrus IMAP uses *altnamespace: on* , and unixhierarchysep: on "/" (slash) character for the |
| 221 |
hierarchy separator. |
| 222 |
|
| 223 |
The following limits also apply: |
| 224 |
|
| 225 |
* Mailbox names are case-sensitive, |
| 226 |
* A mailbox name may not start with a ``.`` (dot) character, |
| 227 |
* A mailbox name may not contain two ``.`` (dot) characters in a row, |
| 228 |
* Non-ASCII characters and shell meta-characters are not permitted in |
| 229 |
mailbox names. |
| 230 |
|
| 231 |
While these limits apply under all circumstances, use of the unix hierarchy separator can also affect the display. |
| 232 |
|
| 233 |
When using the altnamespace:off namespace mode, a user's |
| 234 |
shorthand qualifier (e.g. ``john`` for ``[email protected]``) MAY NOT |
| 235 |
contain a ``.`` (dot) character, as the character is being used as a |
| 236 |
hierarchy separator in mailbox names, and would thus create a personal |
| 237 |
mailbox rather then a user's INBOX. Using ``john.doe`` for |
| 238 |
the INBOX name for user *John Doe <[email protected]>* does not work, |
| 239 |
as it would create a sub-folder ``doe`` for the INBOX ``user.john``. |
| 240 |
|
| 241 |
The same limitation goes for the use of virtual domains. Since a mailbox |
| 242 |
in a virtual domain typically uses a fully qualified user identifier |
| 243 |
(e.g. ``[email protected]``, thus including a valid (sub-)domain name), |
| 244 |
the ``.`` (dot) character is inherited from the Domain Name System |
| 245 |
naming convention. This poses a problem without the use of the ``.`` |
| 246 |
(dot) character as a mailbox hierarchy separator. |
| 247 |
|
| 248 |
|
| 249 |
Example |
| 250 |
------- |
| 251 |
|
| 252 |
In a default situation using the altnamespace:on namespace |
| 253 |
mode, a user *John Doe <[email protected]>* would start out with a |
| 254 |
mailbox ``INBOX``, and will want to create sub-folders such as |
| 255 |
for drafted and sent messages. |
| 256 |
|
| 257 |
These mailboxes will be presented to John's client as follows (assuming dot separator): |
| 258 |
|
| 259 |
* ``INBOX`` |
| 260 |
* ``Drafts`` |
| 261 |
* ``Sent Items`` |
| 262 |
|
| 263 |
Where altnamespace is set to off, this looks like: |
| 264 |
|
| 265 |
* ``INBOX`` |
| 266 |
* ``INBOX.Drafts`` |
| 267 |
* ``INBOX.Sent Items`` |
| 268 |
|
| 269 |
.. warning:: |
| 270 |
|
| 271 |
Changing ``altnamespace`` in an active operating environment will |
| 272 |
cause all IMAP clients to need to resync the entire hierarchy. |
| 273 |
|
| 274 |
---- |
| 275 |
|
| 276 |
.. _imap-admin-namespaces-administrator: |
| 277 |
|
| 278 |
Administrator Namespaces |
| 279 |
======================== |
| 280 |
|
| 281 |
An administrator -- a user for which the username is included in the |
| 282 |
``admins`` setting in :cyrusman:`imapd.conf(5)` -- has a different |
| 283 |
perspective when using the IMAP protocol to perform administrative |
| 284 |
tasks. |
| 285 |
|
| 286 |
.. NOTE:: |
| 287 |
The administrator namespace is not affected by the user namespace mode (altnamespace: on/off) |
| 288 |
|
| 289 |
With the UNIX hierarchy separator enabled, the list would look as |
| 290 |
follows: |
| 291 |
|
| 292 |
* ``user/jane`` |
| 293 |
* ``user/jane/Drafts`` |
| 294 |
* ``user/jane/Sent Items`` |
| 295 |
* ``user/john`` |
| 296 |
* ``user/john/Drafts`` |
| 297 |
* ``user/john/Sent Items`` |
| 298 |
|
| 299 |
Continuing with the UNIX hierarchy separator enabled, should virtual |
| 300 |
domains be in use, the list may appear to the administrator user |
| 301 |
``cyrus`` as follows: |
| 302 |
|
| 303 |
* ``user/[email protected]`` |
| 304 |
* ``user/jane/[email protected]`` |
| 305 |
* ``user/jane/Sent [email protected]`` |
| 306 |
* ``user/[email protected]`` |
| 307 |
* ``user/john/[email protected]`` |
| 308 |
* ``user/john/Sent [email protected]`` |
| 309 |
|
| 310 |
But the ``admins`` setting in :cyrusman:`imapd.conf(5)` allows for a |
| 311 |
username of ``[email protected]`` to be specified as an administrator as |
| 312 |
well. Should ``[email protected]`` take a peek, then the following list |
| 313 |
would appear: |
| 314 |
|
| 315 |
* ``user/jane`` |
| 316 |
* ``user/jane/Drafts`` |
| 317 |
* ``user/jane/Sent Items`` |
| 318 |
* ``user/john`` |
| 319 |
* ``user/john/Drafts`` |
| 320 |
* ``user/john/Sent Items`` |
| 321 |
|
| 322 |
.. IMPORTANT:: |
| 323 |
|
| 324 |
In multi-domain or multi-tenant environments, the following |
| 325 |
mailboxes may exist: |
| 326 |
|
| 327 |
* ``user/john`` |
| 328 |
* ``user/[email protected]`` |
| 329 |
* ``user/[email protected]`` |
| 330 |
|
| 331 |
Be aware that an unrealmed ``cyrus`` administrator user |
| 332 |
can administrator mailboxes in each of the three realms (null for |
| 333 |
``user/john``, ``example.com`` for ``user/[email protected]`` and |
| 334 |
``example.org`` for ``user/[email protected]``), but a realmed |
| 335 |
administrator ``[email protected]`` will be able to see and administer |
| 336 |
mailboxes restricted to the ``example.org`` authorization realm. |
| 337 |
In this case they will see ``[email protected]`` |
| 338 |
being presented as ``user/john`` -- not to be confused with the |
| 339 |
actually unrealmed ``user/john`` mailbox that exists on the system |
| 340 |
as well. |