Size: 1169
Comment:
|
← Revision 29 as of 2010-06-02 15:02:14 ⇥
Size: 4593
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 5: | Line 5: |
* default_mail_env setting * namespace locations * static userdb template string * LDAP and SQL userdb query strings |
* [[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 |
Line 10: | Line 9: |
* [[Plugins|Plugin]] settings | |
Line 11: | Line 11: |
The variables are: | The variables that work everywhere are: |
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 * %h - home directory * %p - protocol (IMAP or POP3) (1.0-tests only) * %P - PID of the current process (login or imap/pop3 process) (1.0-tests only) * %l - local IP address (1.0-tests only) * %r - remote IP address (1.0-tests only) |
|| '''Variable''' || '''Long name''' || '''Description''' || || %% || || '%' character || || %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 22: | Line 23: |
You can apply a modifiers for each variable (eg. %Lp = pop3): (1.0-tests only) | 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]], e.g. 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]], e.g. 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_pid || 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 (e.g. %Ls = pop3): |
Line 26: | Line 57: |
* %E - escape '"', "'" and '\' characters by inserting '\' before them. | * %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. * %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 (v1.1.rc6+) |
Line 28: | Line 66: |
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 offset points outside the value, empty string is returned. (The width is only in 1.0-tests) | 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". The modifiers are applied from left-to-right order, except the substring is always taken from the final string. |
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 everywhere are:
Variable
Long name
Description
%%
'%' character
%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 mechanism, e.g. 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 mechanism, e.g. 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_pid
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 (e.g. %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.
- %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.
- %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 (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".
The modifiers are applied from left-to-right order, except the substring is always taken from the final string.