Config Variables

You can use special variables in several places:

Global variables that work everywhere are:

Long name Description
%% ‘%’ character. See SharedMailboxes/Shared for further information about %% variables
env:<name> Environment variable <name>
uid Effective UID of the current process NOTE: This is overridden for mail service user variables.
gid Effective GID of the current process NOTE: This is overridden for mail service user variables.
pid PID of the current process (e.g. login or imap/pop3 process).
hostname Hostname (without domain). Can be overridden with DOVECOT_HOSTNAME environment variable. NOTE: This is overridden for mail user variables.

If var_expand_crypt plugin is loaded (see Plugins/VarExpandCrypt):

Long name Description
encrypt; <parameters>:<field> Encrypt field (v2.2.29+)
decrypt; <parameters<:<field> Decrypt field (v2.2.29+)

Mail service user variables:

Variable Long name Description
%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
%l lip local IP address
%r rip remote IP address
%i uid UNIX user identifier of the user
gid UNIX group identifier of the user
session session ID for this client connection (unique for 9 years)
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> 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+)

Mail user variables include all of the mail service user variables. Additionally there are:

Variable Long name Description
%h home home directory. Use of ~/ is better whenever possible.
hostname Expands to the hostname setting. Overrides the global %{hostname}.

Login variables:

Variable Long name Description
%l lip local IP address
%r rip remote IP address
%s service local_name imap, pop3, smtp, lda (and doveadm, dsync, etc.) TLS SNI hostname, if given (v2.2.26+)

Authentication variables:

Variable Long name Description
%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
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+)
%s service imap, pop3, smtp, lda (and doveadm, dsync, etc.)
local_name TLS SNI hostname, if given (v2.2.26+)
%l lip local IP address
%r rip remote IP address
%a lport local port
%b rport remote port
real_rip Same as %{rip}, except in proxy setups contains the remote proxy’s IP instead of the client’s IP
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+)
%p pid process ID of the authentication client
session_pid For user logins: The PID of the IMAP/POP3 process handling the session. (v2.2.7+)
%m mech authentication mechanism e.g. PLAIN
%w password plaintext password from plaintext authentication mechanism
%c secured “secured” string with SSL, TLS and localhost connections. Otherwise empty.
%k cert “valid” if client had sent a valid client certificate, otherwise empty.
session session ID for this client connection (unique for 9 years)
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+)
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
master_user For master user logins: The master username (v2.2.7+)
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> 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+)
client_id Expands to client ID request as IMAP arglist (v2.2.29+). Needs imap_id_retain=yes
forward_<name> Used by proxies to pass on extra fields to the next hop, see PasswordDatabase/ExtraFields/Proxy (v2.2.29+)
%!
Internal ID number of the current passdb/userdb.

Modifiers

You can apply a modifiers for each variable (e.g. %Us or %U{service} = 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).

New in version 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.

Example:

%{sha256:user} or %{md5;truncate=32:user}.

New in version 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.

Note

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

Note

%0.-2u gives all but the last two characters from the username.

New in version none: v2.2.13

The modifiers are applied from left-to-right order, except the substring is always taken from the final string.

Conditionals

New in version 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)