Merge branch 'master' into transp_logging_1031

[users/jgh/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 7fd2bd8ecf015d1383b2bb8362f4dfd76f24688c..565c01851a5bc80acbc663117b70c03cf8bfc1c1 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -844,6 +844,85 @@ b. Configure, somewhere before the DATA ACL, the control option to
 
 
 
+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