Adding upstream version 1:2.3.19.1+dfsg1.upstream/1%2.3.19.1+dfsg1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 393 insertions, 0 deletions

diff --git a/doc/wiki/Namespaces.txt b/doc/wiki/Namespaces.txt
new file mode 100644
index 0000000..3d05dac
--- /dev/null
+++ b/doc/wiki/Namespaces.txt
@@ -0,0 +1,393 @@
+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)