Make success expansion a per-transport option

[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 565c01851a5bc80acbc663117b70c03cf8bfc1c1..a7651f6c0b27665d0c00ab3c7e6e21567a6061bc 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -847,11 +847,10 @@ b. Configure, somewhere before the DATA ACL, the control option to
 DBL (Database Logging)
 --------------------------------------------------------------
 
-This feature allows to write exim internal log information
+An arbitrary per-transport string can be expanded on successful delivery,
+and (for SMTP transports) a second string on deferrals caused by a host error.
+This feature allows the writing of 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
 
@@ -859,7 +858,7 @@ EXPERIMENTAL_DBL=yes
 
 in your Local/Makefile
 
-and define the database queries in the runtime config file, to
+and define the expandable strings in the runtime config file, to
 be executed at end of delivery.
 
 Additionally, there are 8 more variables, available at end of
@@ -871,14 +870,17 @@ 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
+router_name                 name of router
+transport_name              name of transport
 
 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.
+
+To log successful deliveries, set the following option
+on any transport of interest.
 
 dbl_delivery_query
 
@@ -894,6 +896,10 @@ ${lookup pgsql {SELECT * FROM record_Delivery( \
     '${quote_pgsql:${lc:$dbl_delivery_fqdn}}', \
     '${quote_pgsql:$message_exim_id}')}}
 
+The string is expanded after the delivery completes and any
+side-effects will happen.  The result is then discarded.
+Note that for complex operations an ACL expansion can be used.
+
 
 In order to log host deferrals, add the following option to an SMTP
 transport: