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, 355 insertions, 0 deletions

diff --git a/doc/wiki/Variables.txt b/doc/wiki/Variables.txt
new file mode 100644
index 0000000..9051220
--- /dev/null
+++ b/doc/wiki/Variables.txt
@@ -0,0 +1,355 @@
+Variables
+=========
+
+You can use special variables in several places:
+
+ * <mail_location> [MailLocation.txt] setting and <namespace> [Namespaces.txt]
+   locations
+ * <static userdb> [UserDatabase.Static.txt] and <passwd-file userdb>
+   [AuthDatabase.PasswdFile.txt] template strings
+ * <LDAP> [AuthDatabase.LDAP.txt] and <SQL> [AuthDatabase.SQL.txt] userdb query
+   strings
+ * log prefix for imap/pop3 process
+ * <Plugin> [Plugins.txt] settings
+
+The variables that work (almost) everywhere are:
+
+ *
++------------+------------------------------+---------------------------------+
+| *Variable* | *Long name*                  | *Description*                   |
++------------+------------------------------+---------------------------------+
+| %%         |                              | '%' character. See              |
+|            |                              | <SharedMailboxes.Shared.txt> for|
+|            |                              | further information about %%    |
+|            |                              | variables                       |
++------------+------------------------------+---------------------------------+
+| %u         | user                         | full username (e.g. user@domain)|
++------------+------------------------------+---------------------------------+
+| %n         | username                     | user part in user@domain, same  |
+|            |                              | as %u if there's no domain      |
++------------+------------------------------+---------------------------------+
+| %d         | domain                       | domain part in user@domain,     |
+|            |                              | empty if user with no domain    |
++------------+------------------------------+---------------------------------+
+| %s         | service                      | imap, pop3, smtp, lda (and      |
+|            |                              | doveadm, dsync, etc.)           |
++------------+------------------------------+---------------------------------+
+| %p         | pid                          | PID of the current process      |
+|            |                              | (login or imap/pop3 process)    |
++------------+------------------------------+---------------------------------+
+| %l         | lip                          | local IP address                |
++------------+------------------------------+---------------------------------+
+| %r         | rip                          | remote IP address               |
++------------+------------------------------+---------------------------------+
+|            | session                      | session ID for this client      |
+|            |                              | connection (unique for 9 years) |
+|            |                              | (v2.1.6+)                       |
++------------+------------------------------+---------------------------------+
+|            | auth_user                    | SASL authentication ID (e.g. if |
+|            |                              | master user login is done, this |
+|            |                              | contains the master username).  |
+|            |                              | If username changes during      |
+|            |                              | authentication, this value      |
+|            |                              | contains the original username. |
+|            |                              | Otherwise the same as %{user}.  |
+|            |                              | (v2.2.11+)                      |
++------------+------------------------------+---------------------------------+
+|            | auth_username                | user part in %{auth_user}       |
+|            |                              | (v2.2.11+)                      |
++------------+------------------------------+---------------------------------+
+|            | auth_domain                  | domain part in %{auth_user}     |
+|            |                              | (v2.2.11+)                      |
++------------+------------------------------+---------------------------------+
+|            | userdb:<name>                | Expands to extra field "name"   |
+|            |                              | returned by userdb (v2.2.19+)   |
++------------+------------------------------+---------------------------------+
+|            | encrypt;<parameters>:<field> | Encrypt field (v2.2.29+) (see   |
+|            |                              | <Plugins.VarExpandCrypt.txt>)   |
++------------+------------------------------+---------------------------------+
+|            | decrypt;<parameters<:<field> | Decrypt field (v2.2.29+) (see   |
+|            |                              | <Plugins.VarExpandCrypt.txt>)   |
++------------+------------------------------+---------------------------------+
+
+These variables work almost everywhere else except in Dovecot-auth (userdb
+queries/templates):
+
+ *
++------------+----------+-----------------------------------------------------+
+| *Variable* | *Long    | *Description*                                       |
+|            | name*    |                                                     |
++------------+----------+-----------------------------------------------------+
+| %h         | home     | home directory. Use of ~/ is better whenever        |
+|            |          | possible.                                           |
++------------+----------+-----------------------------------------------------+
+| %i         | uid      | UNIX UID of the user                                |
++------------+----------+-----------------------------------------------------+
+|            | gid      | UNIX group identifier of the user (v2.0.17+)        |
++------------+----------+-----------------------------------------------------+
+
+These variables work only in Dovecot-auth and 'login_log_format_elements'
+setting:
+
+ *
++----+--------------------+---------------------------------------------------+
+| %m | mech               | <authentication mechanism>                        |
+|    |                    | [Authentication.Mechanisms.txt], e.g. PLAIN       |
++----+--------------------+---------------------------------------------------+
+| %a | lport              | Local port                                        |
++----+--------------------+---------------------------------------------------+
+| %b | rport              | Remote port                                       |
++----+--------------------+---------------------------------------------------+
+| %c | secured            | "secured" string with SSL, TLS and localhost      |
+|    |                    | connections. Otherwise empty.                     |
++----+--------------------+---------------------------------------------------+
+|    | real_rip           | Same as %{rip}, except in proxy setups contains   |
+|    |                    | the remote proxy's IP instead of the client's IP  |
+|    |                    | (v2.1.10+)                                        |
++----+--------------------+---------------------------------------------------+
+|    | real_lip           | Same as %{lip}, except in proxy setups contains   |
+|    |                    | the local proxy's IP instead of the remote proxy's|
+|    |                    | IP (v2.2+)                                        |
++----+--------------------+---------------------------------------------------+
+|    | real_rport         | Similar to %{real_rip} except for port instead of |
+|    |                    | IP (v2.2+)                                        |
++----+--------------------+---------------------------------------------------+
+|    | real_lport         | Similar to %{real_lip} except for port instead of |
+|    |                    | IP (v2.2+)                                        |
++----+--------------------+---------------------------------------------------+
+|    | orig_user          | Same as %{user}, except using the original        |
+|    |                    | username the client sent before any changes by    |
+|    |                    | auth process (v2.2.6+, v2.2.13+ for auth)         |
++----+--------------------+---------------------------------------------------+
+|    | orig_username      | Same as %{username}, except using the original    |
+|    |                    | username (v2.2.6+, v2.2.13+ for auth)             |
++----+--------------------+---------------------------------------------------+
+|    | orig_domain        | Same as %{domain}, except using the original      |
+|    |                    | username (v2.2.6+, v2.2.13+ for auth)             |
++----+--------------------+---------------------------------------------------+
+|    | local_name         | Expands to TLS SNI hostname, if given (v2.2.26+)  |
++----+--------------------+---------------------------------------------------+
+|    | client_id          | Expands to client ID request as IMAP arglist      |
+|    |                    | (v2.2.29+/v2.3+). Needs imap_id_retain=yes        |
++----+--------------------+---------------------------------------------------+
+|    | passdb:<name>      | Expands to extra field "name" returned by passdb  |
+|    |                    | (v2.2.19+)                                        |
++----+--------------------+---------------------------------------------------+
+|    | forward_<variable> | Used by proxies to pass on values to next hop, see|
+|    |                    | <PasswordDatabase.ExtraFields.Proxy.txt>          |
+|    |                    | (v2.2.29+/v2.3+)                                  |
++----+--------------------+---------------------------------------------------+
+
+These variables work only in Dovecot-auth:
+
+ *
++------------+----------------+-----------------------------------------------+
+| *Variable* | *Long name*    | *Description*                                 |
++------------+----------------+-----------------------------------------------+
+| %w         | password       | plaintext password from plaintext             |
+|            |                | authentication mechanism                      |
++------------+----------------+-----------------------------------------------+
+| %k         | cert           | "valid" if client had sent a valid client     |
+|            |                | certificate, otherwise empty.                 |
++------------+----------------+-----------------------------------------------+
+|            | login_user     | For master user logins: Logged in user@domain |
++------------+----------------+-----------------------------------------------+
+|            | login_username | For master user logins: Logged in user        |
++------------+----------------+-----------------------------------------------+
+|            | login_domain   | For master user logins: Logged in domain      |
++------------+----------------+-----------------------------------------------+
+|            | domain_first   | For "username@domain_first@domain_last" style |
+|            |                | usernames (v2.2.6+)                           |
++------------+----------------+-----------------------------------------------+
+|            | domain_last    | For "username@domain_first@domain_last" style |
+|            |                | usernames (v2.2.6+)                           |
++------------+----------------+-----------------------------------------------+
+|            | master_user    | For master user logins: The master username   |
+|            |                | (v2.2.7+)                                     |
++------------+----------------+-----------------------------------------------+
+|            | session_pid    | For user logins: The PID of the IMAP/POP3     |
+|            |                | process handling the session. (v2.2.7+)       |
++------------+----------------+-----------------------------------------------+
+|            | passdb:<name>  | Return passdb extra field "name".             |
+|            |                | %{passdb:name:default} returns "default" if   |
+|            |                | "name" doesn't exist (not returned if name    |
+|            |                | exists but is empty) (v2.2.19+)               |
++------------+----------------+-----------------------------------------------+
+|            | userdb:<name>  | Return userdb extra field "name".             |
+|            |                | %{userdb:name:default} returns "default" if   |
+|            |                | "name" doesn't exist (not returned if name    |
+|            |                | exists but is empty) (v2.2.19+)               |
++------------+----------------+-----------------------------------------------+
+
+These variables work only in 'login_log_format_elements' setting:
+
+ *
++------------+--------------+-------------------------------------------------+
+| *Variable* | *Long name*  | *Description*                                   |
++------------+--------------+-------------------------------------------------+
+| %k         | ssl_security | SSL protocol and cipher information, e.g. "TLSv1|
+|            |              | with cipher DHE-RSA-AES256-SHA (256/256 bits)"  |
++------------+--------------+-------------------------------------------------+
+| %e         | mail_pid     | Mail process (imap/pop3) PID that handles the   |
+|            |              | post-login connection                           |
++------------+--------------+-------------------------------------------------+
+|            | listener     | Expands to the socket listener name as specified|
+|            |              | in config file (v2.2.19+)                       |
++------------+--------------+-------------------------------------------------+
+
+These variables work only in 'deliver_log_format' setting:
+
+ *
++------------+---------------+------------------------------------------------+
+| *Variable* | *Long name*   | *Description*                                  |
++------------+---------------+------------------------------------------------+
+| %$         |               | Log entry                                      |
++------------+---------------+------------------------------------------------+
+| %m         | msgid         | Message-ID                                     |
++------------+---------------+------------------------------------------------+
+| %s         | subject       | Subject                                        |
++------------+---------------+------------------------------------------------+
+| %f         | from          | From address                                   |
++------------+---------------+------------------------------------------------+
+| %e         | from_envelope | Envelope sender                                |
++------------+---------------+------------------------------------------------+
+|            | to_envelope   | Envelope recipient (v2.2.19+)                  |
++------------+---------------+------------------------------------------------+
+| %p         | size          | Message size                                   |
++------------+---------------+------------------------------------------------+
+| %w         | vsize         | Virtual message size                           |
++------------+---------------+------------------------------------------------+
+|            | delivery_time | How many milliseconds was spent actually       |
+|            |               | delivering the mail (v2.2.18+)                 |
++------------+---------------+------------------------------------------------+
+|            | session_time  | How many milliseconds the LMTP session took in |
+|            |               | total, including network waits (v2.2.18+)      |
++------------+---------------+------------------------------------------------+
+
+These variables work only in 'auth_policy_request_attributes' setting:
+
+ *
++------------+--------------------+-------------------------------------------+
+| *Variable* | *Long name*        | *Description*                             |
++------------+--------------------+-------------------------------------------+
+|            | hashed_password    | Truncated auth policy hash of username and|
+|            |                    | password                                  |
++------------+--------------------+-------------------------------------------+
+|            | requested_username | Since v2.2.34, contains correct username  |
++------------+--------------------+-------------------------------------------+
+
+ * Long variable names can be used like '%{long_name} ' or with L modifier:
+   '%L{long_name}'.
+ * Environment variables can be accessed with '%{env:ENVIRONMENT_VARIABLE} '.
+ * Additionally, the (self-explanatory) variables '%{pid} ' and '%{hostname} '
+   are available.
+
+Modifiers
+---------
+
+You can apply a modifiers for each variable (e.g. %Us = POP3):
+
+ * %L - lowercase
+ * %U - uppercase
+ * %E - escape '"', "'" and '\' characters by inserting '\' before them. Note
+   that variables in SQL queries are automatically escaped, you don't need to
+   use this modifier for them.
+ * %X - parse the variable as a base-10 number, and convert it to base-16
+   (hexadecimal)
+ * %R - reverse the string
+ * %N - take a 32bit hash of the variable and return it as hex. You can also
+   limit the hash value. For example %256Nu gives values 0..ff. You might want
+   padding also, so %2.256Nu gives 00..ff. This can be useful for example in
+   dividing users automatically to multiple partitions.
+    * This is "New Hash", based on MD5 to give better distribution of values
+      (no need for any string reversing kludges either). (v2.2.3+)
+    * %H - Same as %N, but use "old hash" (not recommended anymore)
+       * %H hash function is a bit bad if all the strings end with the same
+         text, so if you're hashing usernames being in user@domain form, you
+         probably want to reverse the username to get better hash value
+         variety, e.g. %3RHu.
+ * %{<hash
+   algorithm>;rounds=<n>,truncate=<bits>,salt=s,format=<hex|hexuc|base64>:field}
+   - Generic hash function that outputs a hex (by default) or base64 value.
+   Hash algorithm is any of the supported ones, e.g. md5, sha1, sha256. Also
+   "pkcs5" is supported using SHA256. For example: %{sha256:user} or
+   %{md5;truncate=32:user}. (v2.2.27+)
+ * %M - return the string's MD5 sum as hex.
+ * %D - return "sub.domain.org" as "sub,dc=domain,dc=org" (for LDAP queries)
+ * %T - Trim trailing whitespace
+
+You can take a substring of the variable by giving optional offset followed by
+'.' and width after the '%' character. For example %2u gives first two
+characters of the username. %2.1u gives third character of the username.
+
+If the offset is negative, it counts from the end, for example %-2.2i gives the
+UID mod 100 (last two characters of the UID printed in a string). If a positive
+offset points outside the value, empty string is returned, if a negative offset
+does then the string is taken from the start.
+
+If the width is prefixed with zero, the string isn't truncated, but only padded
+with '0' character if the string is shorter. For example %04i may return
+"0001", "1000" and "12345". %1.04i for the same string would return "001",
+"000" and "2345".
+
+If the width is negative, it counts from the end, for example %0.-2u gives all
+but the last two characters from the username. (v2.2.13+)
+
+The modifiers are applied from left-to-right order, except the substring is
+always taken from the final string.
+
+Conditionals
+------------
+
+Since v2.2.33 it's possible to use conditionals in variable expansion. The
+generic syntax is
+
+---%<-------------------------------------------------------------------------
+  %{if;value1;operator;value2;value-if-true;value-if-false}
+---%<-------------------------------------------------------------------------
+
+Each field can contain another variable expansion, facilitating for nested ifs.
+If some field refers to another field, it must use either %v or %{value}
+syntax.
+
+Escaping is supported, so one can have values like \%{value} that will not get
+expanded, or literal : and ; in the expression.
+
+Spaces and quotes are fully supported.
+
+Following operators are supported
++------------+--------------------------------------------------------------+
+| *operator* | *explanation*                                                |
++------------+--------------------------------------------------------------+
+| ==         | NUMERIC equality                                             |
++------------+--------------------------------------------------------------+
+| !=         | NUMERIC inequality                                           |
++------------+--------------------------------------------------------------+
+| <          | NUMERIC less than                                            |
++------------+--------------------------------------------------------------+
+| <=         | NUMERIC less or equal                                        |
++------------+--------------------------------------------------------------+
+| >          | NUMERIC greater than                                         |
++------------+--------------------------------------------------------------+
+| >=         | NUMERIC greater or equal                                     |
++------------+--------------------------------------------------------------+
+| eq         | String equality                                              |
++------------+--------------------------------------------------------------+
+| ne         | String inequality                                            |
++------------+--------------------------------------------------------------+
+| lt         | String inequality                                            |
++------------+--------------------------------------------------------------+
+| le         | String inequality                                            |
++------------+--------------------------------------------------------------+
+| gt         | String inequality                                            |
++------------+--------------------------------------------------------------+
+| ge         | String inequality                                            |
++------------+--------------------------------------------------------------+
+| *          | Wildcard match (mask on value2)                              |
++------------+--------------------------------------------------------------+
+| !*         | Wildcard non-match (mask on value2)                          |
++------------+--------------------------------------------------------------+
+| ~          | Regular expression match (pattern on value2, extended POSIX) |
++------------+--------------------------------------------------------------+
+| !~         | String inequality (pattern on value2, extended POSIX)        |
++------------+--------------------------------------------------------------+
+
+(This file was created from the wiki on 2019-06-19 12:42)