Exim Filter Specification - Expansion conditions

Go to the first, previous, next, last section, table of contents.

## Expansion conditions

The following conditions are available for testing by the ${if construct while expanding strings:

    ______________________________________________________________

    !<condition>

Preceding any condition with an exclamation mark negates the result of the condition.

    <symbolic operator> {<string1>}{<string2>}

There are a number of symbolic operators for doing numeric comparisons. They are:

    =        equal
    ==       equal
    >        greater
    >=       greater or equal
    <        less
    <=       less or equal

For example,

    ${if >{$message_size}{10M} ...

Note that the general negation operator provides for inequality testing. The two strings must take the form of optionally signed decimal integers, optionally followed by one of the letters `K' or `M' (in either upper or lower case), signifying multiplication by 1024 or 1024*1024, respectively.

    ______________________________________________________________

    def:<variable name>

The def condition must be followed by the name of one of the expansion variables defined in section 33. The condition is true if the named expansion variable does not contain the empty string, for example

    ${if def:sender_ident {from $sender_ident}}

Note that the variable name is given without a leading $ character. If the variable does not exist, the expansion fails.

    ______________________________________________________________

    def:header_<header name>:  or  def:h_<header name>:

This condition is true if a message is being processed and the named header exists in the message. For example,

    ${if def:header_reply-to:{$h_reply-to:}{$h_from:}}

Note that no $ appears before header_ or h_ in the condition, and that header names must be terminated by colons if white space does not follow.

    ______________________________________________________________

    exists {<file name>}

The substring is first expanded and then interpreted as an absolute path. The condition is true if the named file (or directory) exists. The existence test is done by calling the stat() function. The use of the exists test in users' filter files may be locked out by the system administrator.

    eq {<string1>}{<string2>}

The two substrings are first expanded. The condition is true if the two resulting strings are identical, including the case of letters.

    ______________________________________________________________

    match {<string1>}{<string2>}

The two substrings are first expanded. The second is then treated as a regular expression and applied to the first. Because of the pre-expansion, if the regular expression contains dollar, or backslash characters, they must be escaped with backslashes. Care must also be taken if the regular expression contains braces (curly brackets). A closing brace must be escaped so that it is not taken as a premature termination of <string2>. It does no harm to escape opening braces, but this is not strictly necessary. For example,

    ${if match {$local_part}{^\\d\{3\}} ...

If the whole expansion string is in double quotes, further escaping of backslashes is also required.

The condition is true if the regular expression match succeeds. At the start of an if expansion the values of the numeric variable substitutions $1 etc. are remembered. Obeying a match condition that succeeds causes them to be reset to the substrings of that condition and they will have these values during the expansion of the success string. At the end of the if expansion, the previous values are restored. After testing a combination of conditions using or, the subsequent values of the numeric variables are those of the condition that succeeded.

    ______________________________________________________________

    pam {<string1>:<string2>:...}

Pluggable Authentication Modules (http://ftp.at.kernel.org/pub/linux/libs/pam/) are a facility which is available in the latest releases of Solaris and in some GNU/Linux distributions. The Exim support, which is intended for use in conjunction with the SMTP AUTH command, is available only if Exim is compiled with

    SUPPORT_PAM=yes

in ``Local/Makefile'`. You probably need to add -lpam to EXTRALIBS, and in some releases of GNU/Linux -ldl is also needed.

The argument string is first expanded, and the result must be a colon-separated list of strings. The PAM module is initialized with the service name `exim' and the user name taken from the first item in the colon-separated data string (i.e. <string1>). The remaining items in the data string are passed over in response to requests from the authentication function. In the simple case there will only be one request, for a password, so the data will consist of two strings only.

There can be problems if any of the strings are permitted to contain colon characters. In the usual way, these have to be doubled to avoid being taken as separators. If the data is being inserted from a variable, the sg expansion item can be used to double any existing colons. For example, the configuration of a LOGIN authenticator might contain this setting:

    server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}}

    ______________________________________________________________

    first_delivery

This condition, which has no data, is true during a message's first delivery attempt. It is false during any subsequent delivery attempts.

    ______________________________________________________________

    queue_running

This condition, which has no data, is true during delivery attempts that are initiated by queue-runner processes, and false otherwise.

    ______________________________________________________________

    or {{<cond1>}{<cond2>}...}

The sub-conditions are evaluated from left to right. The condition is true if any one of the sub-conditions is true. For example,

    ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}...

When a true sub-condition is found, the following ones are parsed but not evaluated. If there are several `match' sub-conditions the values of the numeric variables afterwards are taken from the first one that succeeds.

    ______________________________________________________________

    and {{<cond1>}{<cond2>}...}

The sub-conditions are evaluated from left to right. The condition is true if all of the sub-conditions are true. If there are several `match' sub-conditions, the values of the numeric variables afterwards are taken from the last one. When a false sub-condition is found, the following ones are parsed but not evaluated.

Note that and and or are complete conditions on their own, and precede their lists of sub-conditions. Each sub-condition must be enclosed in braces within the overall braces that contain the list. No repetition of if is used.

Go to the first, previous, next, last section, table of contents.