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 | *Description* |
| | name* | |
+------------+----------+-----------------------------------------------------+
| %% | | '%' 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 there's 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+) |
+------------+----------+-----------------------------------------------------+
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+)|
+----+---------------+--------------------------------------------------------+
| | orig_username | Same as %{username}, except using the original username|
| | | (v2.2.6+) |
+----+---------------+--------------------------------------------------------+
| | orig_domain | Same as %{domain}, except using the original username |
| | | (v2.2.6+) |
+----+---------------+--------------------------------------------------------+
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 |
+------------+----------------+-----------------------------------------------+
| | session_pid | For user logins: The PID of the IMAP/POP3 |
| | | process handling the session. (v2.2.7+) |
+------------+----------------+-----------------------------------------------+
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 |
+------------+--------------+-------------------------------------------------+
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 |
+------------+---------------+----------------------+
| %p | size | Message size |
+------------+---------------+----------------------+
| %w | vsize | Virtual message size |
+------------+---------------+----------------------+
* 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
* %H - take a 32bit hash of the variable and return it as hex. You can also
limit the hash value. For example %256Hu gives values 0..ff. You might want
padding also, so %2.256Hu gives 00..ff. This can be useful for example in
dividing users automatically to multiple partitions.
* %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.
* %N - "New hash" - same as %H, but based on MD5 to give better distribution
of values (no need for any string reversing kludges either). (v2.2.3+)
* %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".
The modifiers are applied from left-to-right order, except the substring is
always taken from the final string.
(This file was created from the wiki on 2013-11-24 04:43)
