1 files changed, 75 insertions, 0 deletions
diff --git a/doc/wiki/PasswordDatabase.ExtraFields.Host.txt b/doc/wiki/PasswordDatabase.ExtraFields.Host.txt
new file mode 100644
index 0000000..3a822c2
--- /dev/null
+++ b/doc/wiki/PasswordDatabase.ExtraFields.Host.txt
@@ -0,0 +1,75 @@
+Login referrals
+===============
+
+Login referrals are an IMAP extension specified by RFC 2221
+[https://tools.ietf.org/html/rfc2221]. Their purpose is to redirect clients to
+an different IMAP4 server in case of hardware failures or organizational
+changes. No client action is needed to invoke the LOGIN-REFERRALS capability:
+the redirection is triggered by the server and occurs transparently.
+
+A security consideration is in order. As also stated by RFC 2221, a man in the
+middle attack may use a rogue 'password catching' server to collectlogin data
+and redirect your clients to their own rogue IMAP4 server. Although this would
+be avoided by enforcing SSL/TLS. Login referrals are not supported by many
+clients, so you probably don't want to use them anyway.
+
+Dovecot does not use login referrals by default.
+
+Configuration
+-------------
+
+Note that the "host" field is also used by <proxying>
+[PasswordDatabase.ExtraFields.Proxy.txt]. Login referrals are used only if the
+proxy field isn't set.
+
+Login referrals can be used in two ways:
+
+ 1. Tell the client to log into another server without allowing to log in
+    locally.
+ 2. Suggest the client to log into another server, but log it in anyway.
+
+The following fields can be used to configure login referrals:
+
+ * 'host=s': The destination server's hostname. This field is required for
+   login referrals to be used.
+ * 'port=s': The destination server's port. The default is 143.
+ * 'destuser=s': Tell client to use a different username when logging in.
+ * 'reason=s': Optional reason to use as the reply to the login command. The
+   default is "Logged in, but you should use this server instead."
+
+Using the above settings you can suggest client to log in elsewhere. To require
+it, you'll also have to return:
+
+ * 'nologin': User is not allowed to log in.
+ * 'reason=s': Optional reason. The default is "Try this server instead.".
+
+Client support
+--------------
+
+The following clients are known to support login referrals:
+
+ * Pine
+ * Outlook (but not Outlook Express)
+
+Examples
+--------
+
+Forward user to another server after successful authentication:
+
+---%<-------------------------------------------------------------------------
+password_query = SELECT password, host, 'Y' as nologin FROM users WHERE userid
+= '%u'
+---%<-------------------------------------------------------------------------
+
+Forward all users to another server without authentication:
+
+---%<-------------------------------------------------------------------------
+password_query = \
+  SELECT NULL AS password, 'Y' AS nopassword \
+  'imap2.example.com' AS host, \
+  'This server is down, try another one.' AS reason, \
+  'Y' AS nologin, \
+  'Y' AS nodelay
+---%<-------------------------------------------------------------------------
+
+(This file was created from the wiki on 2019-06-19 12:42)