Created new doc file containing specs for the experimental features,

taken from Tom's original document.

1 files changed, 433 insertions, 0 deletions

diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
new file mode 100644
index 000000000..145fc42da
--- /dev/null
+++ b/doc/doc-txt/experimental-spec.txt
@@ -0,0 +1,433 @@
+$Cambridge: 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@mydomain.com
+      
+  
+  - 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@mydomain.com: <OPTIN STRING1>:<OPTIN STRING2>
+    user2@thatdomain.com: <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
+--------------------------------------------------------------