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+)

New in version v2.2.29.

decrypt; <parameters>:<field>

Decrypt field

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

New in version v2.2.11.

auth_username

user part in %{auth_user}

New in version v2.2.11.

auth_domain

domain part in %{auth_user}

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

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

imap, pop3, smtp, lda (and doveadm, dsync, etc.)

local_name | TLS SNI hostname, if given

.. versionadded:: v2.2.26

%k

ssl_security

TLS session security string. If HAProxy is configured and it terminated the TLS connection, contains “(proxied)”.

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

New in version v2.2.6.

domain_last

For “username@domain_first@domain_last” style usernames

New in version v2.2.6.

%s

service

imap, pop3, smtp, lda (and doveadm, dsync, etc.)

local_name

TLS SNI hostname, if given

New in version v2.2.26.

%l

local_ip

local IP address

New in version v2.3.12: For older versions use %{lip}

%r

remote_ip

remote IP address

New in version v2.3.12: For older versions use %{rip}

%a

local_port

local port

New in version v2.3.12: For older versions use %{lport}

%b

remote_port

remote port

New in version v2.3.12: For older versions use %{rport}

real_remote_ip

Same as %{remote_ip}, except in proxy setups contains the remote proxy’s IP instead of the client’s IP

New in version v2.3.12: For older versions use %{real_rip}

real_local_ip

Same as %{local_ip}, except in proxy setups contains the local proxy’s IP instead of the remote proxy’s IP

New in version v2.3.12: For older versions use %{real_lip}

real_remote_port

Similar to %{real_rip} except for port instead of IP

New in version v2.3.12: For older versions use %{real_rport}

real_local_port

Similar to %{real_lip} except for port instead of IP

New in version v2.3.12: For older versions use %{real_lport}

rip

Deprecated version of %{remote_ip}

Deprecated since version v2.3.12.

lip

Deprecated version of %{local_ip}

Deprecated since version v2.3.12.

rport

Deprecated version of %{remote_port}

Deprecated since version v2.3.12.

lport

Deprecated version of %{local_port}

Deprecated since version v2.3.12.

real_rip

Deprecated version of %{real_remote_ip}

Deprecated since version v2.3.12.

real_lip

Deprecated version of %{real_local_ip}

New in version v2.2.0.

Deprecated since version v2.3.12.

real_rport

Deprecated version of %{real_remote_port}

New in version v2.2.0.

Deprecated since version v2.3.12.

real_lport

Deprecated version of %{real_local_port}

New in version v2.2.0.

Deprecated since version v2.3.12.

%p

pid

process ID of the authentication client

session_pid

For user logins: The PID of the IMAP/POP3 process handling the session.

New in version v2.2.7.

%m

mechanism

authentication_mechanisms e.g. PLAIN

New in version v2.3.12.

mech

Deprecated version of %{mechanism}

Deprecated since version v2.3.12.

%w

password

plaintext password from plaintext authentication mechanism

%c

secured

“TLS” with established SSL/TLS connections, “TLS handshaking”, or “TLS [handshaking]: error text” if disconnecting due to TLS error. “secured” with 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}.

New in version v2.2.11.

auth_username

user part in %{auth_user}

New in version v2.2.11.

auth_domain

domain part in %{auth_user}

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

New in version v2.2.7.

original_user

Same as %{user}, except using the original username the client sent before any changes by auth process

New in version v2.3.12.

original_username

Same as %{username}, except using the original username

New in version v2.3.12.

original_domain

Same as %{domain}, except using the original username

New in version v2.3.12.

orig_user

Deprecated version of %{original_user}

New in version v2.2.6.

New in version v2.2.13: Works in auth process.

Deprecated since version v2.3.12.

orig_username

Deprecated version of %{original_username}

New in version v2.2.6.

New in version v2.2.13: Works in auth process.

Deprecated since version v2.3.12.

orig_username

Deprecated version of %{original_domain}

New in version v2.2.6.

New in version v2.2.13: Works in auth process.

Deprecated since version v2.3.12.

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). Note that this doesn’t work in passdb/userdb ldap’s pass_attrs or user_attrs.

New in version v2.2.19.

userdb:<name>

Return userdb extra field “name”. Note that this can also be used in passdbs to access any userdb_* extra fields added by previous passdb lookups. %{userdb:name:default} returns “default” if “name” doesn’t exist (not returned if name exists but is empty). Note that this doesn’t work in passdb/userdb ldap’s pass_attrs or user_attrs.

New in version v2.2.19.

client_id

Expands to client ID request as IMAP arglist. Needs imap_id_retain=yes

New in version v2.2.29.

forward_<name>

Used by proxies to pass on extra fields to the next hop, see Proxy PasswordDatabase

New in version 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 of the value fields can contain another variable expansion, facilitating for nested ifs. Both %f and %{field} syntaxes work.

Escaping is supported, so it’s possible to use values like %, : or ; that expand to the literal %, : or ; characters. Values can have spaces and quotes without any special escaping.

Note that currently unescaped : cuts off the if statement and ignores everything after it.

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)

Examples:

# If %u is "testuser", return "INVALID". Otherwise return %u uppercased.
%{if;%u;eq;testuser;INVALID;%Uu}

# Same as above, but for use nested IF just for showing how they work:
%{if;%{if;%u;eq;testuser;a;b};eq;a;INVALID;%Uu}