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:

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

%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.

%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. %3RNu.

This is "New Hash", based on MD5 to give better distribution of values (no need for any string reversing kludges either). (v2.2.3+)

%{<hash algorithm>;rounds=<n>,truncate=<bits>,salt=s>:field} - Generic hash function that outputs a hex 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+)

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.