← Back to branch summary

~ubuntu-branches/ubuntu/utopic/dovecot/utopic-proposed

« back to all changes in this revision

Viewing changes to doc/wiki/Namespaces.txt

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2014-01-08 09:35:49 UTC
  • mfrom: (4.1.35 sid)
  • Revision ID: package-import@ubuntu.com-20140108093549-i72o93pux8p0dlaf
Tags: 1:2.2.9-1ubuntu1
* Merge from Debian unstable, remaining changes:
  + Add mail-stack-delivery package:
    - Update d/rules
    - d/control: convert existing dovecot-postfix package to a dummy
      package and add new mail-stack-delivery package.
    - Update maintainer scripts.
    - Rename d/dovecot-postfix.* to debian/mail-stack-delivery.*
    - d/mail-stack-delivery.preinst: Move previously installed backups and
      config files to a new package namespace.
    - d/mail-stack-delivery.prerm: Added to handle downgrades.
  + Use Snakeoil SSL certificates by default:
    - d/control: Depend on ssl-cert.
    - d/dovecot-core.postinst: Relax grep for SSL_* a bit.
  + Add autopkgtest to debian/tests/*.
  + Add ufw integration:
    - d/dovecot-core.ufw.profile: new ufw profile.
    - d/rules: install profile in dovecot-core.
    - d/control: dovecot-core - suggest ufw.
  + d/dovecot-core.dirs: Added usr/share/doc/dovecot-core
  + Add apport hook:
    - d/rules, d/source_dovecot.py
  + Add upstart job:
    - d/rules, d/dovecot-core.dovecot.upstart, d/control,
      d/dovecot-core.dirs, dovecot-imapd.{postrm, postinst, prerm},
      d/dovecot-pop3d.{postinst, postrm, prerm}.
      d/mail-stack-deliver.postinst: Convert init script to upstart.
  + Use the autotools-dev dh addon to update config.guess/config.sub for
    arm64.
* Dropped changes, included in Debian:
  - Update Dovecot name to reflect distribution in login greeting.
  - Update Drac plugin for >= 2.0.0 support.
* d/control: Drop dovecot-postfix package as its no longer required.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/wiki/Namespaces.txt
19
19
Configuration
20
20
-------------
21
21
 
22
 
By default no namespaces are explicitly defined in 'dovecot.conf'. In this
23
 
situation Dovecot creates a private namespace automatically. This automatic
24
 
namespace creation isn't done when namespaces are defined, so if you intend to
25
 
simply add a new namespace, be sure to also add the default private namespace.
 
22
In v2.1+ there's a default inbox namespace added in '10-mail.conf'. If the
 
23
configuration doesn't explicitly specify a namespace (as was in v2.0 and older)
 
24
a default namespace is created automatically.
 
25
 
 
26
The section name in namespaces (e.g. 'namespace sectionname { .. } ' is used
 
27
only internally within configuration. It's not required at all, but it allows
 
28
you to update an existing namespace (like how '15-mailboxes.conf' does) or have
 
29
userdb override namespace settings for specific users
 
30
('namespace/sectionname/prefix=foo/').
 
31
 
 
32
Namespace types
 
33
---------------
26
34
 
27
35
There are 3 types of namespaces:
28
36
 
45
53
 
46
54
However, changing the separator doesn't change the on-disk "layout separator".
47
55
For example:
48
 
+-----------------------------+-----------+-----------+---------+---------------------+
49
 
| mail_location               | Layout    | Separator | Mailbox | Directory           |
50
 
|                             | separator |           | name    |                     |
51
 
+-----------------------------+-----------+-----------+---------+---------------------+
52
 
| maildir:~/Maildir           | .         | .         | foo.bar | ~/Maildir/.foo.bar/ |
53
 
+-----------------------------+-----------+-----------+---------+---------------------+
54
 
| maildir:~/Maildir           | .         | /         | foo/bar | ~/Maildir/.foo.bar/ |
55
 
+-----------------------------+-----------+-----------+---------+---------------------+
56
 
| maildir:~/Maildir:LAYOUT=fs | /         | .         | foo.bar | ~/Maildir/foo/bar/  |
57
 
+-----------------------------+-----------+-----------+---------+---------------------+
58
 
| maildir:~/Maildir:LAYOUT=fs | /         | /         | foo/bar | ~/Maildir/foo/bar/  |
59
 
+-----------------------------+-----------+-----------+---------+---------------------+
 
56
+-----------------------------+--------+-----+----------+---------------------+
 
57
| mail_location               | Layout | NS  | Mailbox  | Directory           |
 
58
|                             | sep    | sep | name     |                     |
 
59
+-----------------------------+--------+-----+----------+---------------------+
 
60
| maildir:~/Maildir           | .      | .   | foo.bar  | ~/Maildir/.foo.bar/ |
 
61
+-----------------------------+--------+-----+----------+---------------------+
 
62
| maildir:~/Maildir           | .      | /   | foo/bar  | ~/Maildir/.foo.bar/ |
 
63
+-----------------------------+--------+-----+----------+---------------------+
 
64
| maildir:~/Maildir:LAYOUT=fs | /      | .   | foo.bar  | ~/Maildir/foo/bar/  |
 
65
+-----------------------------+--------+-----+----------+---------------------+
 
66
| maildir:~/Maildir:LAYOUT=fs | /      | /   | foo/bar  | ~/Maildir/foo/bar/  |
 
67
+-----------------------------+--------+-----+----------+---------------------+
60
68
 
61
 
Note how the "Separator" changes only the "Mailbox name", but doesn't change
62
 
the directory where the mails are stored. The "layout separator" can only be
63
 
changed by changing the LAYOUT, which also affects the entire directory
 
69
Note how the "namespace separator" changes only the "Mailbox name", but doesn't
 
70
change the directory where the mails are stored. The "layout separator" can
 
71
only be changed by changing the LAYOUT, which also affects the entire directory
64
72
structure.
65
73
 
66
74
The layout separator also restricts the mailbox names. For example if the
69
77
[Plugins.Listescape.txt] plugin to add escape the mailbox names as necessary.
70
78
 
71
79
A commonly used separator is '/'. It probably causes the least amount of
72
 
trouble with different IMAP clients. '^' separator is troublesome with
73
 
Thunderbird.
 
80
trouble with different IMAP clients.'^' separator is troublesome with
 
81
Thunderbird.When '\' should be used it must be quoted, so one sets separator =
 
82
"\\"
74
83
 
75
84
You should use the same hierarchy separator for all namespaces. All list=yes
76
85
namespaces must use the same separator, but if you find it necessary (e.g. for
80
89
Namespace settings
81
90
------------------
82
91
 
 
92
 * type: See the "Namespace types" section above
 
93
 * separator: See the "Hierarchy separators" section above
83
94
 * prefix: The namespace prefix how it's visible in the NAMESPACE reply (if
84
95
   hidden=no) and mailbox list (if list=yes).
85
96
 * location: <Mailbox location> [MailLocation.txt]. The default is to use
97
108
   with prefix=foo/bar/, Dovecot first sees if there's a prefix=foo/ namespace
98
109
   with subscriptions=yes and then a namespace with an empty prefix. If neither
99
110
   is found, an error is given.
 
111
 * ignore_on_failure: Normally Dovecot fails if it can't successfully create a
 
112
   namespace. Set this to "yes" to continue even if the namespace creation
 
113
   fails (e.g. public namespace points to inaccessible location).
 
114
 * disabled: Set to "yes" to quickly disable this namespace. Especially useful
 
115
   when returned by a userdb lookup to give per-user namespaces.
 
116
 * alias_for: If multiple namespaces point to the same location, they should be
 
117
   marked as aliases against one primary namespace. This avoids duplicating
 
118
   work for some commands (listing the same mailbox multiple times). The value
 
119
   for alias_for is the primary namespace's prefix. For example if the primary
 
120
   namespace has empty prefix, set 'alias_for=' for the alias namespace. Or if
 
121
   primary has 'prefix=INBOX/', use 'alias_for=INBOX/'.
 
122
 * mailbox { .. } settings can be used to autocreate/autosubscribe mailboxes
 
123
   and set their SPECIAL-USE flags.
100
124
 
101
125
Shared Mailboxes
102
126
----------------
129
153
}
130
154
---%<-------------------------------------------------------------------------
131
155
 
132
 
Without the 'list = no' setting in the first namespace, clients see the "#mbox"
133
 
namespace as a non-selectable mailbox named "#mbox" and having child mailboxes
134
 
(ie. like a directory). The child mailboxes are all the mbox files in '~/mail'
135
 
directory.
 
156
Without the 'list = no' setting in the first namespace, clients would see the
 
157
"#mbox" namespace as a non-selectable mailbox named "#mbox" but with child
 
158
mailboxes (the mbox files in the '~/mail' directory), ie. like a directory. So
 
159
specifically with 'inbox = yes', having 'list = no' is often desirable.
136
160
 
137
161
Backwards Compatibility: UW-IMAP
138
162
--------------------------------
143
167
 
144
168
---%<-------------------------------------------------------------------------
145
169
# default namespace
146
 
namespace {
 
170
namespace inbox {
147
171
  separator = /
148
172
  prefix =
149
173
  inbox = yes
150
174
}
151
175
# for backwards compatibility:
152
 
namespace {
 
176
namespace compat1 {
153
177
  separator = /
154
178
  prefix = mail/
155
179
  hidden = yes
156
180
  list = no
157
181
  alias_for =
158
182
}
159
 
namespace {
 
183
namespace compat2 {
160
184
  separator = /
161
185
  prefix = ~/mail/
162
186
  hidden = yes
163
187
  list = no
164
188
  alias_for =
165
189
}
166
 
namespace {
 
190
namespace compat3 {
167
191
  separator = /
168
192
  prefix = ~%u/mail/
169
193
  hidden = yes
175
199
Backwards Compatibility: Courier IMAP
176
200
-------------------------------------
177
201
 
178
 
You can continue using the same INBOX. namespace as Courier:
 
202
*Recommended:* You can continue using the same INBOX. namespace as Courier:
179
203
 
180
204
---%<-------------------------------------------------------------------------
181
 
namespace {
 
205
namespace inbox {
182
206
  separator = .
183
207
  prefix = INBOX.
184
208
  inbox = yes
185
209
}
186
210
---%<-------------------------------------------------------------------------
187
211
 
188
 
Alternatively you can create the INBOX. as a compatibility name, so old clients
189
 
can continue using it while new clients will use the empty prefix namespace:
 
212
*Alternatively:* Create the INBOX. as a compatibility name, so old clients can
 
213
continue using it while new clients will use the empty prefix namespace:
190
214
 
191
215
---%<-------------------------------------------------------------------------
192
 
namespace {
 
216
namespace inbox {
193
217
  separator = /
194
218
  prefix =
195
219
  inbox = yes
196
220
}
197
221
 
198
 
namespace {
 
222
namespace compat {
199
223
  separator = .
200
224
  prefix = INBOX.
201
225
  inbox = no
210
234
"foo" child or the root "foo" mailbox in "INBOX." compatibility namespace. With
211
235
"separator=/" the difference is clear with "INBOX/foo" vs. "INBOX.foo".
212
236
 
 
237
The alternative configuration is not recommended, as it may introduce there
 
238
problems:
 
239
 
 
240
 * Although clients may do LIST INBOX.*, they may still do LSUB *, resulting in
 
241
   mixed results.
 
242
 * If clients used empty namespace with Courier, they now see the mailboxes
 
243
   with different names, resulting in redownloading of all mails (except
 
244
   INBOX).
 
245
 * Some clients may have random errors auto-detecting the proper default
 
246
   folders (Sent, Drafts etc) if the client settings refer to old paths while
 
247
   the server lists new paths.
 
248
 
213
249
Per-user Namespace Location From SQL
214
250
------------------------------------
215
251
 
241
277
..
242
278
---%<-------------------------------------------------------------------------
243
279
 
244
 
(This file was created from the wiki on 2012-04-23 04:42)
 
280
(This file was created from the wiki on 2013-11-24 04:42)