1 files changed, 105 insertions, 0 deletions
diff --git a/doc/wiki/PasswordDatabase.ExtraFields.txt b/doc/wiki/PasswordDatabase.ExtraFields.txt
new file mode 100644
index 0000000..bffebfb
--- /dev/null
+++ b/doc/wiki/PasswordDatabase.ExtraFields.txt
@@ -0,0 +1,105 @@
+Password database extra fields
+==============================
+
+The primary purpose of a password database lookup is to return the password for
+a given user. It may however also return other fields which are treated
+specially:
+
+ * * <user> [PasswordDatabase.ExtraFields.User.txt]*: Change the username (eg.
+   lowercase it).
+ * *login_user*: Master passdb can use this to change the username. (v2.2.13+)
+ * * <allow_nets> [PasswordDatabase.ExtraFields.AllowNets.txt]*: Allow user to
+   log in from only specified IPs (checks against remote client IP).
+    * *allow_real_nets*: Allow user's network connection to log in from only
+      specified IPs (checks against /real/ remote IP, e.g. a Dovecot proxy).
+ * * <proxy and proxy_maybe> [PasswordDatabase.ExtraFields.Proxy.txt]*: Proxy
+   the connection to another IMAP/POP3 server.
+ * * <host> [PasswordDatabase.ExtraFields.Host.txt]*: Send login referral to
+   client (if proxy=y field isn't set).
+ * * <nologin> [PasswordDatabase.ExtraFields.NoLogin.txt]*: User isn't actually
+   allowed to log in even if the password matches, with optionally a different
+   reason given as the authentication failure message.
+ * * <nodelay> [PasswordDatabase.ExtraFields.NoDelay.txt]*: Don't delay reply
+   to client in case of an authentication failure.
+ * *nopassword*: If you want to allow all passwords, use an empty password and
+   this field.
+ * *fail*: If set, explicitly fails the passdb lookup. (v2.2.22+)
+ * *k5principals*: if using "auth_mechanisms = gssapi", may contain Kerberos v5
+   principals allowed to map to the current user, bypassing the internal call
+   to krb5_kuserok(). The database must support credentials lookup. (v2.2+)
+ * *delay_until*=<UNIX timestamp>[+<max random secs>]: Delay login until this
+   time. The timestamp must be less than 5 minutes into future or the login
+   will fail with internal error. The extra random seconds can be used to avoid
+   a load spike of everybody getting logged in at exactly the same time.
+   (v2.2.25+)
+ * *noauthenticate*: Do not perform any authentication, just store extra fields
+   if user is found. (v2.2.26+/v2.3)
+ * *forward_<anything>*: In proxy/director, pass the variable to next hop as
+   forward_<anything>. (v2.2.29+/v2.3)
+
+How to return these extra fields depends on the password database you use. See
+the <password database> [PasswordDatabase.txt] pages on how to do it. Some
+passdbs however don't support returning them at all, such as <PAM>
+[PasswordDatabase.PAM.txt].
+
+The password database may also return fields prefixed with 'userdb_'. These
+fields are only saved and used later as if they came from the <user database>
+[UserDatabase.txt]'s extra fields. Typically this is done only when using
+<prefetch userdb> [UserDatabase.Prefetch.txt].
+
+Note that boolean fields are true always if the field exists. So 'nodelay',
+'nodelay=yes', 'nodelay=no' and 'nodelay=0' all mean that the nodelay field is
+true. With SQL the field is considered to be non-existent if its value is NULL.
+
+The following suffixes added to a field name are handled specially:
+
+ * *:protected*: Set this field only if it hasn't been set before.
+ * *:remove*: Remove this field entirely.
+
+Examples
+--------
+
+SQL
+---
+
+*dovecot-sql.conf.ext*:
+
+---%<-------------------------------------------------------------------------
+password_query = SELECT userid as user, password, 'Y' as proxy, host \
+  FROM users WHERE userid = '%u'
+---%<-------------------------------------------------------------------------
+
+LDAP
+----
+
+*dovecot-ldap.conf*:
+
+---%<-------------------------------------------------------------------------
+pass_attrs = \
+  =user=%{ldap:user}, \
+  =password=%{ldap:userPassword},
+  =proxy=%{ldap:proxyEnabled}, \
+  =host=%{ldap:hostName}
+---%<-------------------------------------------------------------------------
+
+Note about the "proxy", "proxy_maybe" and any other boolean type fields: these
+represent an existence test. Currently this translates to "will proxy (or
+proxy_maybe) if this attribute exists".  This allows the proxy behaviour to be
+selectable per user.  To have it "always" on, use a template, e.g.:
+
+---%<-------------------------------------------------------------------------
+pass_attrs = \
+  =user=%{ldap:user}, \
+  =password=%{ldap:userPassword},
+  =proxy=y, \
+  =host=%{ldap:hostName}
+---%<-------------------------------------------------------------------------
+
+passwd-file
+-----------
+
+---%<-------------------------------------------------------------------------
+user:{plain}pass::::::proxy=y host=127.0.0.1
+---%<-------------------------------------------------------------------------
+
+(This file was created from the wiki on 2019-06-19 12:42)