Printable Version of Topic
Click here to view this topic in its original format
XMail Forum > Documentation and Knowledge Base > Xmail's Filter Mechanism


Posted by: hschneider Oct 11 2004, 10:39 AM
One of XMail's ost powerful features are filters. To make things more clear, here the mail flow schemata, when and how messages are filtered:

Receiving or sending mail via SMTP:
- During SMTP conversation: filters.pre-data.tab
- Before ending the SMTP dialog: filters.post-data.tab
- Now the mail's envelope is removed and the spoolfile is generated.
- If the mail contains multiple RCPT_TO or CC and BCC recipients, further spoolfiles are generated for each recipient .

Those spoolfiles take the following routes now:
- If the recipient is local, it runs through filters.in.tab
- Otherwise, it travels through filters.out.tab

Receiving mail via pop3links.tab:
- These mails go directly through filters.in.tab

Sending mail vial local mailer /spool/local:
- Depending on the recipient, these mails go through filters.in.tab (local) or filters.out.tab (external)

For more details about filters read these 2 sections in the manual:

QUOTE

SMTP MESSAGE FILTERS

    Besides having the ability to perform off-line message filtering, XMail
    gives the user the power to run filters during the SMTP session. Two
    files drive the SMTP on-line filtering, and these are
    'FILTERS.PRE-DATA.TAB' and 'FILTERS.POST-DATA.TAB'. The file
    'FILTERS.PRE-DATA.TAB' contains one or more commands to be executed
    after the remote SMTP client sends the DATA command, and before XMail
    sends the response to the command. Using such filters, the user can tell
    XMail if or if not accept the following DATA transaction and, in case of
    rejection, the user is also allowed to specify a custom message to be
    sent to the remote SMTP client. The file 'FILTERS.POST-DATA.TAB'
    contains one or more commands to be executed after XMail received the
    whole client DATA, and before XMail sends the final response to the DATA
    command (final messages ack). The files 'FILTERS.PRE-DATA.TAB' and
    'FILTERS.POST-DATA.TAB' conatins zero or more lines with the following
    format:

    "command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]

    Each file may contain multiple commands, that will be executed in
    strictly sequential order. The first command that will trigger a
    rejection code will make the filtering process to end. Each argument can
    be a macro also:

    @@FILE
        message file path

    @@USERAUTH
        name of the SMTP authenticated user, or "-" if not authentication
        has been granted

    @@REMOTEADDR
        remote IP address and port of the sender

    @@LOCALADDR
        local IP address and port where the message has been accepted

    Filter commands have the ability to inspect and modify the content of
    the message (or info) file. The exit code of commands executed by XMail
    are used to tell XMail the action that has to be performed as a
    cosequence of the filter. The exit code is composed by a raw exit code
    and additional flags. Currently defined flags are:

    '16'
        Stop selected filter list processing.

    Currently defined raw exit codes are:

    '3' Reject the message.

    Any other exit codes will make XMail to accept the message, and can be
    used also when changing the content of the @@FILE file. 'EXTREME' care
    must be used when changing the @@FILE file, since XMail expect the file
    format to be correct. Also, it is important to preserve the <CR><LF>
    line termination of the file itself. When rejecting the message, the
    filter command has the ability to specify the SMTP status code that
    XMail will send to the remote SMTP client, by creating a file named
    @@FILE.rej containing the message in the very first line. Such file will
    be automatically removed by XMail. The data passed to filter commands
    inside @@FILE varies depending if the command is listed inside
    'FILTERS.PRE-DATA.TAB' or inside 'FILTERS.POST-DATA.TAB'. Commands
    listed inside 'FILTERS.PRE-DATA.TAB' will receive the following data
    stored inside @@FILE:

    Info Data          [ 1th line ]
    SmtpDomain          [ 2nd line ]
    SmtpMessageID      [ 3rd line ]
    MAIL FROM:<...>    [ 4th line ]
    RCPT TO:<...> {...} [ 5th line ]
    ...

    The file can have one or more "RCPT TO" lines. The format of the "Info
    Data" line is:

    ClientDomain;ClientIP;ClientPort;ServerDomain;ServerIP;ServerPort;Time;Logo

    Commands listed inside 'FILTERS.POST-DATA.TAB' will receive the
    following data stored inside @@FILE:

    Info Data          [ 1th line ]
    SmtpDomain          [ 2nd line ]
    SmtpMessageID      [ 3rd line ]
    MAIL FROM:<...>    [ 4th line ]
    RCPT TO:<...> {...} [ 5th line ]
    ...
    <<MAIL-DATA>>
    ...

    After the '<<MAIL-DATA>>' tag the message follows. The message is
    composed of a headers section and, after the first empty line, the
    message body. The format of the RCPT line is:

    RCPT TO:<address> {ra=real-address}

    where "real-address" is the "address" after it has been translated (if
    aliases applies) to the real local address. Otherwise it holds the same
    value of "address".




QUOTE

MESSAGE FILTERS

    This feature offers a way to filter messages by providing the ability to
    execute external programs, such as scripts or real executables. These
    'filters' may examine and/or modify messages and inform XMail of their
    actions with a return value.

    This feature offers the ability to inspect and modify messages, giving a
    way to reject messages based on content, alter messages (address
    rewriting) and so on.

    If this filters returns '4, 5 or 6' the message is rejected and is
    stopped in its travel. If the filter modifies the message it must return
    '7'.

    Additional flags are allowed to be returned to XMail as a result of
    filter processing by adding the flags value to the exits code above
    listed. The currently defined flags are :

    '16'
        Stop selected filter list processing.

    Filter flags are additive and if more than one flag need to be
    specified, their values must be added together. If a filter "raw" exit
    code is RC and the filter needs to return extra flags FILTER-SUM, the
    final return code FRC must be :

    FRC = RC + FILTER-SUM

    Example. Suppose a filter modified the message and hence needs to return
    7 as return code. Suppose also that a filter wants to block the filter
    selection list processing by specifying a flags value of 16, the value
    to be returned will be :

    FRC = 7 + 16 = 23

    Filter selection is driven by two files 'FILTERS.IN.TAB' and
    'FILTERS.OUT.TAB' located inside the $MAIL_ROOT/ directory and that have
    the following format:

    "sender"[TAB]"recipient"[TAB]"remote-addr"[TAB]"local-addr"[TAB]"filename"[NEWLINE]

    For example:

    "*@bad-domain.com" "*" "0.0.0.0/0" "0.0.0.0/0" "av-filter.tab"
    "*" "clean@purified.net" "0.0.0.0/0" "0.0.0.0/0" "spam-block.tab"
    "*" "*" "192.168.1.0/24" "0.0.0.0/0" "archive.tab"

    where the file "av-filter.tab" must be present inside the
    $MAIL_ROOT/filters directory. The "sender" and the "recipient" are
    resolved to the real account when possible. Address selection mask are
    formed by an IP address (network) plus the number of valid bits inside
    the network mask. The file 'FILTERS.IN.TAB' lists filters that have to
    be applied to inbound messages (going to local mailboxes) while the file
    'FILTERS.OUT.TAB' lists filters that have to be applied to outbound
    messages (delivered remotely). All four
    (sender+recipient+remote-addr+local-addr) selection fields must have a
    match in order "filename" to be evaluated. The syntax of the filter file
    is:

    "command"[TAB]"arg-or-macro"[TAB]...[NEWLINE]

    Each file may contain multiple commands, that will be executed in
    strictly sequential order. The first command that will trigger a
    rejection code will make the filtering process to end. Each argument can
    be a macro also:

    @@FROM
        the sender of the message

    @@RFROM
        the sender of the message resolved to the real account, when
        possible (alias resolution)

    @@RCPT
        the target of the message

    @@RRCPT
        the target of the message resolved to the real account, when
        possible (alias resolution)

    @@REMOTEADDR
        remote IP address and port of the sender

    @@LOCALADDR
        local IP address and port where the message has been accepted

    @@FILE
        the message file path (the external command may modify the file if
        it returns '7' as command exit value.)

    @@MSGID
        with the (XMail unique) message id

    @@MSGREF
        the reference SMTP message id

    Here 'command' is the name of an external program that processes the
    message and returns its processing result. If it returns '6' the message
    is rejected and a notification message is sent to the sender. By
    returning '5' the message is rejected without notification. While
    returning '4' the message is rejected without notification and without
    being frozen (a '5' response could lead to a frozen message if the
    "SERVER.TAB" configuration enables this). If all filters return values
    different from '6, 5 and 4' the message continues its trip. The filter
    command may also modify the file (AV scanning, content filter, message
    rewriting, etc) by returning '7'. The filter 'MUST' return '7' in case
    it modifies the message. If the filter changes the message file it
    'MUST' keep the message structure and it 'MUST' terminate all line with
    <CR><LF>. The filter has also the ability to return a one-line custom
    return message by creating a file named @@FILE.rej holding the message
    in the very first line. This file should be created 'ONLY' when the
    filter returns a rejection code ('6, 5 and 4')and 'NEVER' in case of
    passthru code ('7') or modify code.

    The spool files has this structure:

    Info Data          [ 1th line ]
    SmtpDomain          [ 2nd line ]
    SmtpMessageID      [ 3rd line ]
    MAIL FROM:<...>    [ 4th line ]
    RCPT TO:<...>      [ 5th line ]
    <<MAIL-DATA>>      [ 6th line ]
    ...

    After the '<<MAIL-DATA>>' tag (5th line) the message follows. The
    message is composed of a headers section and, after the first empty
    line, the message body. The format of the "Info Data" line is:

    ClientDomain;ClientIP;ClientPort;ServerDomain;ServerIP;ServerPort;Time;Logo

    'EXTREME' care must be used when modifying the message because the
    filter will be working on the real message, and a badly reformatted file
    will lead to message loss. The spool file header (any data before
    <<MAIL-DATA>>) 'MUST' be preserved as is by the filter in case of
    message rewrite happens.


Powered by Invision Power Board (http://www.invisionboard.com)
© Invision Power Services (http://www.invisionpower.com)