1 files changed, 89 insertions, 0 deletions
diff --git a/doc/wiki/VirtualUsers.Home.txt b/doc/wiki/VirtualUsers.Home.txt
new file mode 100644
index 0000000..02b4f57
--- /dev/null
+++ b/doc/wiki/VirtualUsers.Home.txt
@@ -0,0 +1,89 @@
+Home Directories for Virtual Users
+==================================
+
+Home directory is a per-user directory where *Dovecot can save user-specific
+files*.
+
+ * Dovecot's home directories have nothing to do with system users' home
+   directories.
+ * It's irrelevant if it's under '/home/' or '/var/mail/' or wherever.
+ * If you have trouble understanding this, mentally replace all occurrences of
+   "home directory" with "mail user's private state directory".
+
+And in particular:
+
+ * Never configure your userdb to return the same home directory for multiple
+   users!
+ * Home directory must be an absolute path, don't even try to use relative
+   paths!
+
+Some uses for home directory are:
+
+ * By default <Sieve> [Pigeonhole.Sieve.txt] scripts are in user's home
+   directory.
+ * Duplicate mail check database is in user's home directory. Suppression of
+   duplicate rejects/vacations won't work if home directory isn't specified.
+ * Debugging: If an imap or pop3 process crashes, the core file is written to
+   the user's home directory.
+
+Home vs. mail directory
+-----------------------
+
+Home directory shouldn't be the same as mail directory with mbox or Maildir
+formats (but with dbox/obox it's fine). It's possible to do that, but you might
+run into trouble with it sooner or later. Some problems with this are:
+
+ * Non-mailbox files may show up as mailboxes.
+    * If you see this with Maildir, 'maildir_stat_dirs=yes' hides them.
+ * Or user just might not be able to create mailbox with wanted name, because
+   there already exists a conflicting file
+    * e.g. with Maildir if you have '.dovecot.sieve' file, user can't create a
+      mailbox called "dovecot.sieve" (i.e. "dovecot" mailbox that has a "sieve"
+      child)
+ * And vice versa: If user creates "dovecot.sieve" mailbox, Dovecot will
+   probably start logging all kinds of errors because the mailbox directory
+   isn't a valid <Sieve> [Pigeonhole.Sieve.txt] script.
+ * If you ever intend to migrate to another mailbox format, it's much easier to
+   do if you can have both old and new mail directories under the user's home
+   directory.
+
+Ways to set up home directory
+-----------------------------
+
+The directory layouts for home and mail directories could look like one of
+these (in the preferred order):
+
+ 1. Mail directory under home, for example: home='/var/vmail/domain/user/'
+    mail='/var/vmail/domain/user/mail/'
+ 2. Completely distinct home and mail directories:
+    home='/home/virtual/domain/user/' mail='/var/vmail/domain/user/'
+ 3. Home directory under mail, for example:
+     * Maildir: home='/var/vmail/domain/user/home/'
+       mail='/var/vmail/domain/user/'
+     * mbox: There's really no good and safe way to do it.
+ 4. The home directory is the same as the mail directory.
+
+If for example home='/var/vmail/domain/user/'
+mail='/var/vmail/domain/user/mail/', set:
+
+---%<-------------------------------------------------------------------------
+mail_home = /var/vmail/%d/%n
+mail_location = maildir:~/mail
+---%<-------------------------------------------------------------------------
+
+Examples
+--------
+
+LDAP with relative directory paths
+----------------------------------
+
+If your LDAP database uses e.g. 'mailDirectory = domain/user/', you can use it
+as a base for home directory:
+
+---%<-------------------------------------------------------------------------
+user_attrs = .., mailDirectory=home=/var/vmail/%$
+---%<-------------------------------------------------------------------------
+
+Then just use 'mail_location = maildir:~/Maildir'.
+
+(This file was created from the wiki on 2019-06-19 12:42)