Patch imported from bugzilla 1031. Axel Rau.
[users/jgh/exim.git] / doc / doc-txt / experimental-spec.txt
index 0073b07afccee53f9be7d22ff52ad521b190ca5a..047440611d0047c1436009393cc77b46f28f9533 100644 (file)
@@ -55,12 +55,13 @@ contents are always valid.  Exim will expand the "tls_ocsp_file" option
 on each connection, so a new file will be handled transparently on the
 next connection.
 
-Exim will check for a validity next update timestamp in the OCSP proof;
+Exim will check for a valid next update timestamp in the OCSP proof;
 if not present, or if the proof has expired, it will be ignored.
 
 At this point in time, we're gathering feedback on use, to determine if
 it's worth adding complexity to the Exim daemon to periodically re-fetch
-OCSP files and somehow handling multiple files.
+OCSP files and somehow handling multiple files.  There is no client support
+for OCSP in Exim, this is feature expected to be used by mail clients.
 
 
 
@@ -520,6 +521,139 @@ EXPERIMENTAL_SRS=yes
 in your Local/Makefile.
 
 
+DCC Support
+--------------------------------------------------------------
+
+*) Building exim
+
+In order to build exim with DCC support add
+
+EXPERIMENTAL_DCC=yes
+
+to your Makefile. (Re-)build/install exim. exim -d should show
+EXPERIMENTAL_DCC under "Support for".
+
+
+*) Configuration
+
+In the main section of exim.cf add at least
+  dccifd_address = /usr/local/dcc/var/dccifd
+or
+  dccifd_address = <ip> <port>
+
+In the DATA ACL you can use the new condition
+        dcc = *
+
+After that "$dcc_header" contains the X-DCC-Header.
+
+Returnvalues are:
+  fail    for overall "R", "G" from dccifd
+  defer   for overall "T" from dccifd
+  accept  for overall "A", "S" from dccifd
+
+dcc = */defer_ok works as for spamd.
+
+The "$dcc_result" variable contains the overall result from DCC
+answer.  There will an X-DCC: header added to the mail.
+
+Usually you'll use
+  defer   !dcc = *
+to greylist with DCC.
+
+If you set, in the main section,
+  dcc_direct_add_header = true
+then the dcc header will be added "in deep" and if the spool
+file was already written it gets removed. This forces Exim to
+write it again if needed.  This helps to get the DCC Header
+through to eg. SpamAssassin.
+
+If you want to pass even more headers in the middle of the
+DATA stage you can set
+  $acl_m_dcc_add_header
+to tell the DCC routines add more information; eg, you might set
+this to some results from ClamAV.  Be careful.  Header syntax is
+not checked and is added "as is".
+
+DBL (Database Logging)
+--------------------------------------------------------------
+
+This feature allows to write exim internal log information
+(not available otherwise) into a database. 
+Initially implemented is logging of details about successfully
+completed remote deliveries, which are needed for reputation
+systems, and deferrals caused by a host error.
+
+In order to use DBL, you must set
+
+EXPERIMENTAL_DBL=yes
+
+in your Local/Makefile
+
+and define the database queries in the runtime config file, to
+be executed at end of delivery.
+
+Additionally, there are 8 more variables, available at end of
+delivery:
+
+dbl_delivery_ip             IP of host, which has accepted delivery
+dbl_delivery_port           Port of remote host which has accepted delivery
+dbl_delivery_fqdn           FQDN of host, which has accepted delivery
+dbl_delivery_local_part     local part of address being delivered
+dbl_delivery_domain         domain part of address being delivered
+dbl_delivery_confirmation   SMTP confirmation message
+
+In case of a deferral caused by a host-error:
+dbl_defer_errno             Error number
+dbl_defer_errstr            Error string possibly containing more details
+
+
+To log successful deliveries, set the following option in the main
+option part of runtime config.
+
+dbl_delivery_query
+
+An example might look like:
+
+dbl_delivery_query = \
+${lookup pgsql {SELECT * FROM record_Delivery( \
+    '${quote_pgsql:$sender_address_domain}',\
+    '${quote_pgsql:${lc:$sender_address_local_part}}', \
+    '${quote_pgsql:$dbl_delivery_domain}', \
+    '${quote_pgsql:${lc:$dbl_delivery_local_part}}', \
+    '${quote_pgsql:$dbl_delivery_ip}', \
+    '${quote_pgsql:${lc:$dbl_delivery_fqdn}}', \
+    '${quote_pgsql:$message_exim_id}')}}
+
+
+In order to log host deferrals, add the following option to an SMTP
+transport:
+
+dbl_host_defer_query
+
+This is a private option of the SMTP transport. It is intended to
+log failures of remote hosts. It is executed only when exim has
+attempted to deliver a message to a remote host and failed due to
+an error which doesn't seem to be related to the individual
+message, sender, or recipient address.
+See section 45.2 of the exim documentation for more details on how
+this is determined.
+
+Example:
+
+dbl_host_defer_query = \
+${lookup mysql {insert into delivlog set \
+    msgid = '${quote_mysql:$message_exim_id}', \
+    senderlp = '${quote_mysql:${lc:$sender_address_local_part}}', \
+    senderdom = '${quote_mysql:$sender_address_domain}', \
+    delivlp = '${quote_mysql:${lc:$dbl_delivery_local_part}}', \
+    delivdom = '${quote_mysql:$dbl_delivery_domain}', \
+    delivip = '${quote_mysql:$dbl_delivery_ip}', \
+    delivport = '${quote_mysql:$dbl_delivery_port}', \
+    delivfqdn = '${quote_mysql:$dbl_delivery_fqdn}', \
+    deliverrno = '${quote_mysql:$dbl_defer_errno}', \
+    deliverrstr = '${quote_mysql:$dbl_defer_errstr}' \
+    }}
+
 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------