[exim-cvs] cvs commit: exim/exim-doc/doc-txt experimental-sp…

Αρχική Σελίδα
Delete this message
Reply to this message
Συντάκτης: Philip Hazel
Ημερομηνία:  
Προς: exim-cvs
Αντικείμενο: [exim-cvs] cvs commit: exim/exim-doc/doc-txt experimental-spec.txt
ph10 2005/01/11 10:51:15 GMT

  Added files:
    exim-doc/doc-txt     experimental-spec.txt 
  Log:
  Created new doc file containing specs for the experimental features,
  taken from Tom's original document.


  Revision  Changes    Path
  1.1       +433 -0    exim/exim-doc/doc-txt/experimental-spec.txt (new)


Index: experimental-spec.txt
====================================================================
$Cambridge: exim/exim-doc/doc-txt/experimental-spec.txt,v 1.1 2005/01/11 10:51:15 ph10 Exp $

From time to time, experimental features may be added to Exim.
While a feature is experimental, there will be a build-time
option whose name starts "EXPERIMENTAL_" that must be set in
order to include the feature. This file contains information
about experimenatal features, all of which are unstable and
liable to incompatibile change.


1. Brighmail AntiSpam (BMI) suppport
--------------------------------------------------------------

  Brightmail  AntiSpam  is  a  commercial  package.  Please  see
  http://www.brightmail.com    for    more    information     on
  the product. For  the sake of  clarity, we'll refer  to it  as
  "BMI" from now on.



0) BMI concept and implementation overview

In contrast to how spam-scanning with SpamAssassin is
implemented in exiscan-acl, BMI is more suited for per
-recipient scanning of messages. However, each messages is
scanned only once, but multiple "verdicts" for multiple
recipients can be returned from the BMI server. The exiscan
implementation passes the message to the BMI server just
before accepting it. It then adds the retrieved verdicts to
the messages header file in the spool. These verdicts can then
be queried in routers, where operation is per-recipient
instead of per-message. To use BMI, you need to take the
following steps:

    1) Compile Exim with BMI support
    2) Set up main BMI options (top section of exim config file)
    3) Set up ACL control statement (ACL section of the config
       file)
    4) Set up your routers to use BMI verdicts (routers section
       of the config file).
    5) (Optional) Set up per-recipient opt-in information.


These four steps are explained in more details below.

1) Adding support for BMI at compile time

    To compile with BMI support,  you need to link Exim  against
    the   Brighmail  client   SDK,  consisting   of  a   library
    (libbmiclient_single.so)  and  a  header  file  (bmi_api.h).
    You'll also need to explicitly set a flag in the Makefile to
    include BMI support in the Exim binary. Both can be achieved
    with  these lines in Local/Makefile:


    EXPERIMENTAL_BRIGHTMAIL=yes
    CFLAGS=-DBRIGHTMAIL -I/path/to/the/dir/with/the/includefile
    EXTRALIBS_EXIM=-L/path/to/the/dir/with/the/library -lbmiclient_single


    If  you use  other CFLAGS  or EXTRALIBS_EXIM  settings then
    merge the content of these lines with them.


    Note for BMI6.x users: You'll also have to add -lxml2_single
    to the EXTRALIBS_EXIM line. Users of 5.5x do not need to  do
    this.


    You    should     also    include     the    location     of
    libbmiclient_single.so in your dynamic linker  configuration
    file   (usually   /etc/ld.so.conf)   and   run    "ldconfig"
    afterwards, or  else the  produced Exim  binary will  not be
    able to find the library file.



2) Setting up BMI support in the exim main configuration

    To enable BMI  support in the  main exim configuration,  you
    should set the path to the main BMI configuration file  with
    the "bmi_config_file" option, like this:


    bmi_config_file = /opt/brightmail/etc/brightmail.cfg


    This must go into section 1 of exims configuration file (You
    can  put it  right on  top). If  you omit  this option,  it
    defaults to /opt/brightmail/etc/brightmail.cfg.


    Note for BMI6.x users: This  file is in XML format  in V6.xx
    and its  name is  /opt/brightmail/etc/bmiconfig.xml. So  BMI
    6.x users MUST set the bmi_config_file option.



3) Set up ACL control statement

    To  optimize performance,  it makes  sense only  to process
    messages coming from remote, untrusted sources with the  BMI
    server.  To set  up a  messages for  processing by  the BMI
    server, you MUST set the "bmi_run" control statement in  any
    ACL for an incoming message.  You will typically do this  in
    an "accept"  block in  the "acl_check_rcpt"  ACL. You should
    use the "accept" block(s)  that accept messages from  remote
    servers for your own domain(s). Here is an example that uses
    the "accept" blocks from exims default configuration file:



    accept  domains       = +local_domains
            endpass
            verify        = recipient
            control       = bmi_run


    accept  domains       = +relay_to_domains
            endpass
            verify        = recipient
            control       = bmi_run


    If bmi_run  is not  set in  any ACL  during reception of the
    message, it will NOT be passed to the BMI server.



4) Setting up routers to use BMI verdicts

    When a message has been  run through the BMI server,  one or
    more "verdicts" are  present. Different recipients  can have
    different verdicts. Each  recipient is treated  individually
    during routing, so you  can query the verdicts  by recipient
    at  that stage.  From Exims  view, a  verdict can  have the
    following outcomes:


    o deliver the message normally
    o deliver the message to an alternate location
    o do not deliver the message


    To query  the verdict  for a  recipient, the  implementation
    offers the following tools:



    - Boolean router  preconditions. These  can be  used in  any
      router. For a simple  implementation of BMI, these  may be
      all  that  you  need.  The  following  preconditions   are
      available:


      o bmi_deliver_default


        This  precondition  is  TRUE  if  the  verdict  for  the
        recipient is  to deliver  the message  normally. If  the
        message has not been  processed by the BMI  server, this
        variable defaults to TRUE.


      o bmi_deliver_alternate


        This  precondition  is  TRUE  if  the  verdict  for  the
        recipient  is to  deliver the  message to  an alternate
        location.  You  can  get the  location  string  from the
        $bmi_alt_location expansion variable if you need it. See
        further below. If the message has not been processed  by
        the BMI server, this variable defaults to FALSE.


      o bmi_dont_deliver


        This  precondition  is  TRUE  if  the  verdict  for  the
        recipient  is  NOT  to   deliver  the  message  to   the
        recipient. You will typically use this precondition in a
        top-level blackhole router, like this:


          # don't deliver messages handled by the BMI server
          bmi_blackhole:
            driver = redirect
            bmi_dont_deliver
            data = :blackhole:


        This router should be on top of all others, so  messages
        that should not be delivered do not reach other  routers
        at all. If   the  message  has  not  been  processed  by
        the  BMI server, this variable defaults to FALSE.



    - A list router  precondition to query  if rules "fired"  on
      the message for the recipient. Its name is "bmi_rule". You
      use  it  by  passing it  a  colon-separated  list of  rule
      numbers. You can use this condition to route messages that
      matched specific rules. Here is an example:


        # special router for BMI rule #5, #8 and #11
        bmi_rule_redirect:
          driver = redirect
          bmi_rule = 5:8:11
          data = postmaster@???



    - Expansion variables. Several  expansion variables are  set
      during  routing.  You  can  use  them  in  custom   router
      conditions,  for  example.  The  following  variables  are
      available:


      o $bmi_base64_verdict


        This variable  will contain  the BASE64  encoded verdict
        for the recipient being routed. You can use it to add  a
        header to messages for tracking purposes, for example:


        localuser:
          driver = accept
          check_local_user
          headers_add = X-Brightmail-Verdict: $bmi_base64_verdict
          transport = local_delivery


        If there is no verdict available for the recipient being
        routed, this variable contains the empty string.


      o $bmi_base64_tracker_verdict


        This variable  will contain  a BASE64  encoded subset of
        the  verdict  information  concerning  the  "rules" that
        fired  on the  message. You  can add  this string  to a
        header, commonly named "X-Brightmail-Tracker". Example:


        localuser:
          driver = accept
          check_local_user
          headers_add = X-Brightmail-Tracker: $bmi_base64_tracker_verdict
          transport = local_delivery


        If there is no verdict available for the recipient being
        routed, this variable contains the empty string.


      o $bmi_alt_location


        If  the  verdict  is  to  redirect  the  message  to  an
        alternate  location,  this  variable  will  contain  the
        alternate location string returned by the BMI server. In
        its default configuration, this is a header-like  string
        that can be added to the message with "headers_add".  If
        there is  no verdict  available for  the recipient being
        routed, or if the  message is to be  delivered normally,
        this variable contains the empty string.


      o $bmi_deliver


        This is an additional integer variable that can be  used
        to query if the message should be delivered at all.  You
        should use router preconditions instead if possible.


        $bmi_deliver is '0': the message should NOT be delivered.
        $bmi_deliver is '1': the message should be delivered.



    IMPORTANT NOTE: Verdict inheritance.
    The  message  is passed  to  the BMI  server  during message
    reception,  using the  target addresses  from the  RCPT TO:
    commands in the SMTP transaction. If recipients get expanded
    or re-written (for example by aliasing), the new address(es)
    inherit the  verdict from  the original  address. This means
    that verdicts also apply to all "child" addresses  generated
    from top-level addresses that were sent to the BMI server.



5) Using per-recipient opt-in information (Optional)

    The  BMI server  features multiple  scanning "profiles"  for
    individual recipients.  These are  usually stored  in a LDAP
    server and are  queried by the  BMI server itself.  However,
    you can also  pass opt-in data  for each recipient  from the
    MTA to the  BMI server. This  is particularly useful  if you
    already look  up recipient  data in  exim anyway  (which can
    also be  stored in  a SQL  database or  other source).  This
    implementation enables you  to pass opt-in  data to the  BMI
    server  in  the  RCPT   ACL.  This  works  by   setting  the
    'bmi_optin' modifier in  a block of  that ACL. If  should be
    set to a list  of comma-separated strings that  identify the
    features which the BMI server should use for that particular
    recipient. Ideally, you  would use the  'bmi_optin' modifier
    in the same  ACL block where  you set the  'bmi_run' control
    flag. Here is an example that will pull opt-in data for each
    recipient      from       a      flat       file      called
    '/etc/exim/bmi_optin_data'.


    The file format:


      user1@???: <OPTIN STRING1>:<OPTIN STRING2>
      user2@???: <OPTIN STRING3>



    The example:


      accept  domains       = +relay_to_domains
              endpass
              verify        = recipient
              bmi_optin     = ${lookup{$local_part@$domain}lsearch{/etc/exim/bmi_optin_data}}
              control       = bmi_run  


    Of course,  you can  also use  any other  lookup method that
    exim supports, including LDAP, Postgres, MySQL, Oracle etc.,
    as long as  the result is  a list of  colon-separated opt-in
    strings.


    For a list of available opt-in strings, please contact  your
    Brightmail representative.





2. Sender Policy Framework (SPF) support
--------------------------------------------------------------

To learn more about SPF, visit http://spf.pobox.com. This
document does not explain the SPF fundamentals, you should
read and understand the implications of deploying SPF on your
system before doing so.

SPF support is added via the libspf2 library. Visit

    http://www.libspf2.org/


to obtain a copy, then compile and install it. By default,
this will put headers in /usr/local/include and the static
library in /usr/local/lib.

To compile exim with SPF support, set these additional flags in
Local/Makefile:

EXPERIMENTAL_SPF=yes
CFLAGS=-DSPF -I/usr/local/include
EXTRALIBS_EXIM=-L/usr/local/lib -lspf2

This assumes that the libspf2 files are installed in
their default locations.

You can now run SPF checks in incoming SMTP by using the "spf"
ACL condition in either the MAIL, RCPT or DATA ACLs. When
using it in the RCPT ACL, you can make the checks dependend on
the RCPT address (or domain), so you can check SPF records
only for certain target domains. This gives you the
possibility to opt-out certain customers that do not want
their mail to be subject to SPF checking.

The spf condition takes a list of strings on its right-hand
side. These strings describe the outcome of the SPF check for
which the spf condition should succeed. Valid strings are:

    o pass      The SPF check passed, the sending host
                is positively verified by SPF.
    o fail      The SPF check failed, the sending host
                is NOT allowed to send mail for the domain
                in the envelope-from address.
    o softfail  The SPF check failed, but the queried
                domain can't absolutely confirm that this
                is a forgery.
    o none      The queried domain does not publish SPF
                records.
    o neutral   The SPF check returned a "neutral" state.
                This means the queried domain has published
                a SPF record, but wants to allow outside
                servers to send mail under its domain as well.
    o err_perm  This indicates a syntax error in the SPF
                record of the queried domain. This should be
                treated like "none".
    o err_temp  This indicates a temporary error during all
                processing, including exim's SPF processing.
                You may defer messages when this occurs.


You can prefix each string with an exclamation mark to invert
is meaning, for example "!fail" will match all results but
"fail". The string list is evaluated left-to-right, in a
short-circuit fashion. When a string matches the outcome of
the SPF check, the condition succeeds. If none of the listed
strings matches the outcome of the SPF check, the condition
fails.

Here is a simple example to fail forgery attempts from domains
that publish SPF records:

  /* -----------------
  deny message = $sender_host_address is not allowed to send mail from $sender_address_domain
       spf = fail
  --------------------- */


You can also give special treatment to specific domains:

  /* -----------------
  deny message = AOL sender, but not from AOL-approved relay.
       sender_domains = aol.com
       spf = fail:neutral
  --------------------- */


Explanation: AOL publishes SPF records, but is liberal and
still allows non-approved relays to send mail from aol.com.
This will result in a "neutral" state, while mail from genuine
AOL servers will result in "pass". The example above takes
this into account and treats "neutral" like "fail", but only
for aol.com. Please note that this violates the SPF draft.

When the spf condition has run, it sets up several expansion
variables.

    $spf_header_comment
    This contains a human-readable string describing the outcome
    of the SPF check. You can add it to a custom header or use
    it for logging purposes.


    $spf_received
    This contains a complete SPF-Received: header that can be
    added to the message. Please note that according to the SPF
    draft, this header must be added at the top of the header
    list. Please see section 10 on how you can do this.


    $spf_result
    This contains the outcome of the SPF check in string form,
    one of pass, fail, softfail, none, neutral, err_perm or
    err_temp.


    $spf_smtp_comment
    This contains a string that can be used in a SMTP response
    to the calling party. Useful for "fail".




3. SRS (Sender Rewriting Scheme) Support
--------------------------------------------------------------

Exiscan currently includes SRS support via Miles Wilton's
libsrs_alt library. The current version of the supported
library is 0.5.

In order to use SRS, you must get a copy of libsrs_alt from

http://srs.mirtol.com/

Unpack the tarball, then refer to MTAs/README.EXIM
to proceed. You need to set

EXPERIMENTAL_SRS=yes

in your Local/Makefile.


--------------------------------------------------------------
End of file
--------------------------------------------------------------