Debian Codegraph @

doc/html/_sources/imap/concepts/features/namespaces.rst.txt

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