Make smtp_receive_timeout main option expanded. Bug 564
[users/heiko/exim.git] / doc / doc-txt / experimental-spec.txt
index e7a0d06682e95e507edf0d8c376bb1b6788e9a65..aae8338f17b55fd0b09a7ec4e80e42b3f4392670 100644 (file)
@@ -759,11 +759,12 @@ b. Configure, somewhere before the DATA ACL, the control option to
 
 
 
-Transport post-delivery actions
+Event Actions
 --------------------------------------------------------------
 
-An arbitrary per-transport string can be expanded upon various transport events
-and (for SMTP transports) a second string on deferrals caused by a host error.
+(Renamed from TPDA, Transport post-delivery actions)
+
+An arbitrary per-transport string can be expanded upon various transport events.
 Additionally a main-section configuration option can be expanded on some
 per-message events.
 This feature may be used, for example, to write exim internal log information
@@ -771,33 +772,33 @@ This feature may be used, for example, to write exim internal log information
 
 In order to use the feature, you must compile with
 
-EXPERIMENTAL_TPDA=yes
+EXPERIMENTAL_EVENT=yes
 
 in your Local/Makefile
 
 and define one or both of
-- the tpda_event_action option in the transport
-- the delivery_event_action
+- the event_action option in the transport
+- the event_action main option
 to be expanded when the event fires.
 
-A new variable, $tpda_event, is set to the event type when the
+A new variable, $event_name, is set to the event type when the
 expansion is done.  The current list of events is:
 
      msg:complete            main            per message
      msg:delivery            transport       per recipient
      msg:host:defer          transport       per attempt
      msg:fail:delivery       main            per recipient
      msg:fail:internal       main            per recipient
      tcp:connect             transport       per connection
      tcp:close               transport       per connection
      tls:cert                transport       per certificate in verification chain
      smtp:connect            transport       per connection
-
-The expansion is called for all event types, and should use the $tpda_event
msg:complete          after  main       per message
msg:delivery          after  transport  per recipient
msg:host:defer                after  transport  per attempt
msg:fail:delivery     after  main       per recipient
msg:fail:internal     after  main       per recipient
tcp:connect           before transport  per connection
tcp:close             after  transport  per connection
tls:cert              before both       per certificate in verification chain
smtp:connect          after  transport  per connection
+
+The expansion is called for all event types, and should use the $event_name
 value to decide when to act.  The variable data is a colon-separated
 list, describing an event tree.
 
-There is an auxilary variable, $tpda_data, for which the
+There is an auxilary variable, $event_data, for which the
 content is event_dependent:
 
        msg:delivery            smtp confirmation mssage
@@ -805,7 +806,7 @@ content is event_dependent:
        tls:cert                verification chain depth
        smtp:connect            smtp banner
 
-The msg:host:defer event populates one extra variable, $tpda_defer_errno.
+The msg:host:defer event populates one extra variable, $event_defer_errno.
 
 The following variables are likely to be useful depending on the event type:
 
@@ -815,12 +816,12 @@ The following variables are likely to be useful depending on the event type:
        tls_out_peercert
        lookup_dnssec_authenticated, tls_out_dane
        sending_ip_address, sending_port
-       message_exim_id
+       message_exim_id, verify_mode
 
 
 An example might look like:
 
-tpda_event_action = ${if = {msg:delivery}{$tpda_event} \
+event_action = ${if = {msg:delivery}{$event_name} \
 {${lookup pgsql {SELECT * FROM record_Delivery( \
     '${quote_pgsql:$sender_address_domain}',\
     '${quote_pgsql:${lc:$sender_address_local_part}}', \
@@ -831,12 +832,12 @@ tpda_event_action = ${if = {msg:delivery}{$tpda_event} \
     '${quote_pgsql:$message_exim_id}')}} \
 } {}}
 
-The string is expanded for each of the supported events and any
-side-effects will happen.  The result is then discarded.
+The string is expanded when each of the supported events occur
+and any side-effects of the expansion will happen.
 Note that for complex operations an ACL expansion can be used.
 
 
-The expansion of the tpda_event_action option should normally
+The expansion of the event_action option should normally
 return an empty string.  Should it return anything else the
 following will be forced:
 
@@ -848,8 +849,13 @@ following will be forced:
        tls:cert        refuse verification
        smtp:connect    close connection
 
+No other use is made of the result string.
 
 
+Known issues:
+- the tls:cert event is only called for the cert chain elements
+  received over the wire, with GnuTLS.  OpenSSL gives the entire
+  chain including thse loaded locally.
 
 
 Redis Lookup
@@ -1078,82 +1084,6 @@ QUIT
 221 mail.example.net closing connection
 
 
-DSN Support
---------------------------------------------------------------
-
-DSN Support tries to add RFC 3461 support to Exim. It adds support for
-*) the additional parameters for MAIL FROM and RCPT TO
-*) RFC complient MIME DSN messages for all of
-   success, failure and delay notifications
-*) dsn_advertise_hosts main option to select which hosts are able
-   to use the extension
-*) dsn_lasthop router switch to end DSN processing
-
-In case of failure reports this means that the last three parts, the message body
-intro, size info and final text, of the defined template are ignored since there is no
-logical place to put them in the MIME message.
-
-All the other changes are made without changing any defaults
-
-Building exim:
---------------
-
-Define
-EXPERIMENTAL_DSN=YES
-in your Local/Makefile.
-
-Configuration:
---------------
-All DSNs are sent in MIME format if you built exim with EXPERIMENTAL_DSN=YES
-No option needed to activate it, and no way to turn it off.
-
-Failure and delay DSNs are triggered as usual except a sender used NOTIFY=...
-to prevent them.
-
-Support for Success DSNs is added and activated by NOTIFY=SUCCESS by clients.
-
-Add
-dsn_advertise_hosts = *
-or a more restrictive host_list to announce DSN in EHLO answers
-
-Those hosts can then use NOTIFY,ENVID,RET,ORCPT options.
-
-If a message is relayed to a DSN aware host without changing the envelope
-recipient the options are passed along and no success DSN is generated.
-
-A redirect router will always trigger a success DSN if requested and the DSN
-options are not passed any further.
-
-A success DSN always contains the recipient address as submitted by the
-client as required by RFC. Rewritten addresses are never exposed.
-
-If you used DSN patch up to 1.3 before remove all "dsn_process" switches from
-your routers since you don't need them anymore. There is no way to "gag"
-success DSNs anymore. Announcing DSN means answering as requested.
-
-You can prevent Exim from passing DSN options along to other DSN aware hosts by defining
-dsn_lasthop
-in a router. Exim will then send the success DSN himself if requested as if
-the next hop does not support DSN.
-Adding it to a redirect router makes no difference.
-
-
-Certificate name checking
---------------------------------------------------------------
-The X509 certificates used for TLS are supposed be verified
-that they are owned by the expected host.  The coding of TLS
-support to date has not made these checks.
-
-If built with EXPERIMENTAL_CERTNAMES defined, code is
-included to do so, and a new smtp transport option
-"tls_verify_cert_hostname" supported which takes a list of
-names for which the checks must be made.  The host must
-also be in "tls_verify_hosts".
-
-Both Subject and Subject-Alternate-Name certificate fields
-are supported, as are wildcard certificates (limited to
-a single wildcard being the initial component of a 3-or-more
-component FQDN).
 
 
 DANE
@@ -1298,7 +1228,7 @@ in the delivery log line will show as "CV=dane".
 
 There is a new variable $tls_out_dane which will have "yes" if
 verification succeeded using DANE and "no" otherwise (only useful
-in combination with EXPERIMENTAL_TPDA), and a new variable
+in combination with EXPERIMENTAL_EVENT), and a new variable
 $tls_out_tlsa_usage (detailed above).