Add expansion for DMARC policy

[users/heiko/exim.git] / doc / doc-txt / experimental-spec.txt

diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 92790ae33a158bfd05fc748c0aafc0b32f16bb55..d0503d9e847e9fa61a5ed3f351c48fca9310515d 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -452,12 +452,14 @@ which the spf condition should succeed. Valid strings are:
               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
+              This should be treated like "none".
+  o permerror This indicates a syntax error in the SPF
+              record of the queried domain. You may deny
+              messages when this occurs. (Changed in 4.83)
+  o temperror This indicates a temporary error during all
               processing, including Exim's SPF processing.
               You may defer messages when this occurs.
+              (Changed in 4.83)
 
 You can prefix each string with an exclamation mark to  invert
 is meaning,  for example  "!fail" will  match all  results but
@@ -510,8 +512,8 @@ variables.
 
   $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.
+  one of pass, fail, softfail, none, neutral, permerror or
+  temperror.
 
   $spf_smtp_comment
   This contains a string that can be used in a SMTP response
@@ -773,7 +775,7 @@ fails.
 
 Of course, you can also use any other lookup method that Exim
 supports, including LDAP, Postgres, MySQL, etc, as long as the
-result is a list of colon-separated strings;
+result is a list of colon-separated strings.
 
 Several expansion variables are set before the DATA ACL is
 processed, and you can use them in this ACL.  The following
@@ -781,7 +783,10 @@ expansion variables are available:
 
   o $dmarc_status
     This is a one word status indicating what the DMARC library
-    thinks of the email.
+    thinks of the email.  It is a combination of the results of
+    DMARC record lookup and the SPF/DKIM/DMARC processing results
+    (if a DMARC record was found).  The actual policy declared
+    in the DMARC record is in a separate expansion variable.
 
   o $dmarc_status_text
     This is a slightly longer, human readable status.
@@ -790,6 +795,11 @@ expansion variables are available:
     This is the domain which DMARC used to look up the DMARC
     policy record.
 
+  o $dmarc_domain_policy
+    This is the policy declared in the DMARC record.  Valid values
+    are "none", "reject" and "quarantine".  It is blank when there
+    is any error, including no DMARC record.
+
   o $dmarc_ar_header
     This is the entire Authentication-Results header which you can
     add using an add_header modifier.
@@ -825,6 +835,9 @@ b. Configure, somewhere before the DATA ACL, the control option to
   warn    !domains       = +screwed_up_dmarc_records
           control        = dmarc_enable_forensic
 
+  warn    condition      = (lookup if destined to mailing list)
+          set acl_m_mailing_list = 1
+
 (DATA ACL)
   warn    dmarc_status   = accept : none : off
           !authenticated = *
@@ -840,6 +853,10 @@ b. Configure, somewhere before the DATA ACL, the control option to
           set $acl_m_quarantine = 1
           # Do something in a transport with this flag variable
 
+  deny    condition      = ${if eq{$dmarc_domain_policy}{reject}}
+          condition      = ${if eq{$acl_m_mailing_list}{1}}
+          message        = Messages from $dmarc_used_domain break mailing lists
+
   deny    dmarc_status   = reject
           !authenticated = *
           message        = Message from $domain_used_domain failed sender's DMARC policy, REJECT
@@ -1066,28 +1083,28 @@ Proxy Protocol server at 192.168.1.2 will look like this:
 
 3. In the ACL's the following expansion variables are available.
 
-proxy_host     The src IP of the proxy server making the connection
-proxy_port     The src port the proxy server is using
-proxy_session  Boolean, yes/no, the connected host is required to use
-               Proxy Protocol.
+proxy_host_address  The src IP of the proxy server making the connection
+proxy_host_port     The src port the proxy server is using
+proxy_session       Boolean, yes/no, the connected host is required to use
+                    Proxy Protocol.
 
 There is no expansion for a failed proxy session, however you can detect
 it by checking if $proxy_session is true but $proxy_host is empty.  As
 an example, in my connect ACL, I have:
 
   warn    condition      = ${if and{ {bool{$proxy_session}} \
-                                     {eq{$proxy_host}{}} } }
+                                     {eq{$proxy_host_address}{}} } }
           log_message    = Failed required proxy protocol negotiation \
                            from $sender_host_name [$sender_host_address]
 
   warn    condition      = ${if and{ {bool{$proxy_session}} \
-                                     {!eq{$proxy_host}{}} } }
+                                     {!eq{$proxy_host_address}{}} } }
           # But don't log health probes from the proxy itself
-          condition      = ${if eq{$proxy_host}{$sender_host_address} \
+          condition      = ${if eq{$proxy_host_address}{$sender_host_address} \
                                 {false}{true}}
           log_message    = Successfully proxied from $sender_host_name \
                            [$sender_host_address] through proxy protocol \
-                           host $proxy_host
+                           host $proxy_host_address
 
 4. Runtime issues to be aware of:
    - Since the real connections are all coming from your proxy, and the