This documentation is for Dovecot v1.x, see wiki2 for v2.x documentation.
Differences between revisions 22 and 23
Revision 22 as of 2008-11-21 20:26:11
Size: 3629
Editor: TimoSirainen
Comment:
Revision 23 as of 2008-12-13 16:12:53
Size: 4400
Editor: TimoSirainen
Comment:
Deletions are marked like this. Additions are marked like this.
Line 13: Line 13:
 * %u - username
 * %n - user part in
user@domain, same as %u if there's no domain
 * %d -
domain part in user@domain, empty if user there's no domain
 * %s -
service: imap, pop3, smtp, deliver. (v1.0 uses uppercased IMAP and POP3)
 * %p -
PID of the current process (login or imap/pop3 process)
 * %l -
local IP address
 * %r -
remote IP address
 || '''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 there's no domain ||
 || %s ||
service || imap, pop3, smtp, deliver. (v1.0 uses uppercased IMAP and POP3) ||
 || %p || pid ||
PID of the current process (login or imap/pop3 process) ||
 || %l || lip ||
local IP address ||
 || %r || rip ||
remote IP address ||
Line 23: Line 24:
 * %h - home directory. Use of ~/ is better whenever possible.
 * %i - UNIX UID of the user
 || '''Variable''' || '''Long name''' || '''Description''' ||
 ||
%h || home || home directory. Use of ~/ is better whenever possible. ||
 || %i || uid || UNIX UID of the user ||
Line 28: Line 30:
 * %w - plaintext password from plaintext authentication mechanism
 * %m - authentication method (eg. PLAIN) (v1.0.rc27+)
 * %a - Local port (v1.1+)
 * %b - Remote port (v1.1+)
 * %c - "secured" string with SSL, TLS and localhost connections. Otherwise empty. (v1.0.rc27+)
 * %k - "valid" if client had sent a valid client certificate, otherwise empty. (v1.2.alpha4+)
 || '''Variable''' || '''Long name''' || '''Description''' ||
 ||
%w || password || plaintext password from plaintext authentication mechanism ||
 || %m || mech || [:Authentication/Mechanisms:authentication mechanism] (eg. PLAIN) (v1.0.rc27+) ||
 || %a || lport || Local port (v1.1+) ||
 || %b || rport || Remote port (v1.1+) ||
 || %c || secured || "secured" string with SSL, TLS and localhost connections. Otherwise empty. (v1.0.rc27+) ||
 || %k || cert || "valid" if client had sent a valid client certificate, otherwise empty. (v1.2.alpha4+) ||
Line 37: Line 40:
 * %m - authentication method (eg. PLAIN)
 * %a - Local port
 *
%b - Remote port
 * %c -
SSL, TLS or empty
 *
%k - SSL protocol and cipher information, e.g. "TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)" (v1.1.3+)
 * %e -
Mail process (imap/pop3) PID that handles the post-login connection (v1.2+)
 || '''Variable''' || '''Long name''' || '''Description''' ||
 || %m || mech || [:A
uthentication/Mechanisms:authentication mechanism] (eg. PLAIN) ||
 || %a || lport || Local port (v1.1+) ||
 ||
%b || rport || Remote port (v1.1+) ||
 || %c || secured ||
SSL, TLS or empty ||
 ||
%k || ssl_security || SSL protocol and cipher information, e.g. "TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)" (v1.1.3+) ||
 || %e || mail_uid ||
Mail process (imap/pop3) PID that handles the post-login connection (v1.2+) ||

Long variable names can be used with v1.2.alpha5+ like {{{%{long_name} }}} or with L modifier: {{{%L{long_name} }}}.

Variables

You can use special variables in several places:

  • [:MailLocation:mail_location] setting and [:Namespaces:namespace] locations

  • [:UserDatabase/Static:static userdb] and [:AuthDatabase/PasswdFile:passwd-file userdb] template strings

  • [:AuthDatabase/LDAP:LDAP] and [:AuthDatabase/SQL:SQL] userdb query strings

  • log prefix for imap/pop3 process
  • [:Plugins:Plugin] settings

The variables that work everywhere are:

  • 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 there's no domain

    %s

    service

    imap, pop3, smtp, deliver. (v1.0 uses uppercased IMAP and POP3)

    %p

    pid

    PID of the current process (login or imap/pop3 process)

    %l

    lip

    local IP address

    %r

    rip

    remote IP address

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

These variables work only in Dovecot-auth:

  • Variable

    Long name

    Description

    %w

    password

    plaintext password from plaintext authentication mechanism

    %m

    mech

    [:Authentication/Mechanisms:authentication mechanism] (eg. PLAIN) (v1.0.rc27+)

    %a

    lport

    Local port (v1.1+)

    %b

    rport

    Remote port (v1.1+)

    %c

    secured

    "secured" string with SSL, TLS and localhost connections. Otherwise empty. (v1.0.rc27+)

    %k

    cert

    "valid" if client had sent a valid client certificate, otherwise empty. (v1.2.alpha4+)

These variables work only in login_log_format_elements setting:

  • Variable

    Long name

    Description

    %m

    mech

    [:Authentication/Mechanisms:authentication mechanism] (eg. PLAIN)

    %a

    lport

    Local port (v1.1+)

    %b

    rport

    Remote port (v1.1+)

    %c

    secured

    SSL, TLS or empty

    %k

    ssl_security

    SSL protocol and cipher information, e.g. "TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)" (v1.1.3+)

    %e

    mail_uid

    Mail process (imap/pop3) PID that handles the post-login connection (v1.2+)

Long variable names can be used with v1.2.alpha5+ like %{long_name}  or with L modifier: %L{long_name} .

Modifiers

You can apply a modifiers for each variable (eg. %Ls = 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. Note that if you're hashing usernames being in user@domain form, you probably want to reverse the string to get better hash value variety, eg. %3RHu.
  • %M - return the string's MD5 sum
  • %D - return "sub.domain.org" as "sub,dc=domain,dc=org" (for LDAP queries)
  • %T - Trim trailing whitespace (v1.1.rc6+)

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

Type in %% to get a literal percent sign.

None: Variables (last edited 2010-06-02 15:02:14 by TimoSirainen)