Variables
You can use special variables in several places:
mail_location setting and namespace locations
static userdb and passwd-file userdb template strings
- log prefix for imap/pop3 process
Plugin settings
The variables that work (almost) everywhere are:
Variable
Long name
Description
%%
'%' character. See SharedMailboxes/Shared 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+)
These variables work almost everywhere else except in Dovecot-auth (userdb queries/templates):
Variable
Long name
Description
%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, 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)
%{passdb:name}
Expands to extra field "name" returned by passdb (v2.2.19+)
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+)
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".
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.