1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
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)
|
