Events: move from Experimental to mainline

3 files changed, 135 insertions, 120 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index aabf85865..13a426c00 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -13369,6 +13369,7 @@ listed in more than one group.
 
 .section "Logging" "SECID99"
 .table2
+.row &%event_action%&                "custom logging"
 .row &%hosts_connection_nolog%&      "exemption from connect logging"
 .row &%log_file_path%&               "override compiled-in value"
 .row &%log_selector%&                "set/unset optional logging"
@@ -14522,6 +14523,14 @@ own &'Reply-To:'& header line, the value of the &%errors_reply_to%& option is
 not used.
 
 
+.new
+.option event_action main string&!! unset
+.cindex events
+This option declares a string to be expanded for Exim's events mechanism.
+For details see &<<CHAPevents>>&.
+.wen
+
+
 .option exim_group main string "compile-time configured"
 .cindex "gid (group id)" "Exim's own"
 .cindex "Exim group"
@@ -20556,6 +20565,13 @@ its removal from incoming messages, so that delivered messages can safely be
 resent to other recipients.
 
 
+.option event_action transports string&!! unset
+.cindex events
+This option declares a string to be expanded for Exim's events mechanism.
+For details see &<<CHAPevents>>&.
+.wen
+
+
 .option group transports string&!! "Exim group"
 .cindex "transport" "group; specifying"
 This option specifies a gid for running the transport process, overriding any
@@ -37834,7 +37850,7 @@ be tracked on a per-domain basis, rather than merely upon source IP address.
 DKIM is documented in RFC 4871.
 
 Since version 4.70, DKIM support is compiled into Exim by default. It can be
-disabled by setting DISABLE_DKIM=yes in Local/Makefile.
+disabled by setting DISABLE_DKIM=yes in &_Local/Makefile_&.
 
 Exim's DKIM implementation allows to
 .olist
@@ -38370,6 +38386,121 @@ must be representable in UTF-16.
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
+.chapter "Events" "CHAPevents" &&&
+         "Events"
+.cindex events
+
+.new
+The events mechanism in Exim can be used to intercept processing at a number
+of points.  It was originally invented to giave a way to do customised logging
+actions (for example, to a database) but can also be used to modify some
+processing actions.
+
+Most installations will never need to use Events.
+The support can be left out of a build by defining DISABLE_EVENT=yes
+in &_Local/Makefile_&.
+
+There are two major classes of events: main and transport.
+The main configuration option &%event_action%& controls reception events;
+a transport option &%event_action%& controls delivery events.
+
+Both options are a string which is expanded when the event fires.
+An example might look like:
+.cindex logging custom
+.code
+event_action = ${if eq {msg:delivery}{$event_name} \
+{${lookup pgsql {SELECT * FROM record_Delivery( \
+    '${quote_pgsql:$sender_address_domain}',\
+    '${quote_pgsql:${lc:$sender_address_local_part}}', \
+    '${quote_pgsql:$domain}', \
+    '${quote_pgsql:${lc:$local_part}}', \
+    '${quote_pgsql:$host_address}', \
+    '${quote_pgsql:${lc:$host}}', \
+    '${quote_pgsql:$message_exim_id}')}} \
+} {}}
+.endd
+
+Events have names which correspond to the point in process at which they fire.
+The name is placed in the variable &$event_name$& and the event action
+expansion must check this, as it will be called for every possible event type.
+
+The current list of events is:
+.display
+&`msg:complete           after    main       `& per message
+&`msg:delivery           after    transport  `& per recipient
+&`msg:rcpt:host:defer    after    transport  `& per recipient per host
+&`msg:rcpt:defer         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
+.endd
+New event types may be added in future.
+
+The event name is a colon-separated list, defining the type of
+event in a tree of possibilities.  It may be used as a list
+or just matched on as a whole.  There will be no spaces in the name.
+
+The second column in the table above describes whether the event fires
+before or after the action is associates with.  Those which fire before
+can be used to affect that action (more on this below).
+
+An additional variable, &$event_data$&, is filled with information varying
+with the event type:
+.display
+&`msg:delivery         `& smtp confirmation mssage
+&`msg:rcpt:host:defer  `& error string
+&`msg:rcpt:defer       `& error string
+&`msg:host:defer       `& error string
+&`tls:cert             `& verification chain depth
+&`smtp:connect         `& smtp banner
+.endd
+
+The :defer events populate one extra variable: &$event_defer_errno$&.
+
+For complex operations an ACL expansion can be used in &%event_action%&
+however due to the multiple contextx that Exim operates in during
+the course of its processing:
+.ilist
+variables set in transport events will not be visible outside that
+transport call
+.next
+acl_m variables in a server context are lost on a new connection,
+and after smtp helo/ehlo/mail/starttls/rset commands
+.endlist
+Using an ACL expansion with the logwrite modifier can be
+a useful way of writing to the main log.
+
+The expansion of the event_action option should normally
+return an empty string.  Should it return anything else the
+following will be forced:
+.display
+&`msg:delivery     `&  (ignored)
+&`msg:host:defer   `&  (ignored)
+&`msg:fail:delivery`&  (ignored)
+&`tcp:connect      `&  do not connect
+&`tcp:close        `&  (ignored)
+&`tls:cert         `&  refuse verification
+&`smtp:connect     `&  close connection
+.endd
+No other use is made of the result string.
+
+For a tcp:connect event, if the connection is being made to a proxy
+then the address and port variables will be that of the proxy and not
+the target system.
+
+For tls:cert events, if GnuTLS is in use this will trigger only per
+chain element received on the connection.
+For OpenSSL it will trigger for every chain element including those
+loaded locally.
+.wen
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
 .chapter "Adding new drivers or lookup types" "CHID13" &&&
          "Adding drivers or lookups"
 .cindex "adding drivers"
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index 98755b60a..052495150 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -126,6 +126,9 @@ JH/27 Move Internationalisation support from Experimental to mainline, enabled
 JH/28 Bug 1745: Fix redis lookups to handle (quoted) spaces embedded in parts
       of the query string, and make ${quote_redis:} do that quoting.
 
+JH/29 Move Events support from Experimental to mainline, enabled by default
+      and removable for a build by defining DISABLE_EVENT.
+
 
 Exim version 4.86
 -----------------
diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index aa4cb464d..81acfda5e 100644
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -771,125 +771,6 @@ b. Configure, somewhere before the DATA ACL, the control option to
 
 
 
-Event Actions
---------------------------------------------------------------
-
-(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
-(not available otherwise) into a database.
-
-In order to use the feature, you must compile with
-
-EXPERIMENTAL_EVENT=yes
-
-in your Local/Makefile
-
-and define one or both of
-- the event_action option in the transport
-- the event_action main option
-to be expanded when the event fires.
-
-A new variable, $event_name, is set to the event type when the
-expansion is done.  The current list of events is:
-
- msg:complete		after  main	  per message
- msg:delivery		after  transport  per recipient
- msg:rcpt:host:defer 	after  transport  per recipient per host
- msg:rcpt:defer 	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
-variable to decide when to act.  The value of the variable is a colon-separated
-list, defining a position in the tree of possible events; it may be used as
-a list or just matched on as a whole.  There will be no whitespace.
-
-New event types may be added in the future.
-
-
-There is an auxilary variable, $event_data, for which the
-content is event_dependent:
-
-	msg:delivery		smtp confirmation mssage
-	msg:rcpt:host:defer	error string
-	msg:rcpt:defer		error string
-	msg:host:defer		error string
-	tls:cert		verification chain depth
-	smtp:connect		smtp banner
-
-The :defer events populate one extra variable, $event_defer_errno.
-
-The following variables are likely to be useful depending on the event type:
-
-	router_name, transport_name
-	local_part, domain
-	host, host_address, host_port
-	tls_out_peercert
-	lookup_dnssec_authenticated, tls_out_dane
-	sending_ip_address, sending_port
-	message_exim_id, verify_mode
-
-
-An example might look like:
-
-event_action = ${if eq {msg:delivery}{$event_name} \
-{${lookup pgsql {SELECT * FROM record_Delivery( \
-    '${quote_pgsql:$sender_address_domain}',\
-    '${quote_pgsql:${lc:$sender_address_local_part}}', \
-    '${quote_pgsql:$domain}', \
-    '${quote_pgsql:${lc:$local_part}}', \
-    '${quote_pgsql:$host_address}', \
-    '${quote_pgsql:${lc:$host}}', \
-    '${quote_pgsql:$message_exim_id}')}} \
-} {}}
-
-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,
-however due to the multiple contexts the Exim operates in
-a) variables set in events raised from transports will not
-   be visible outside that transport call.
-b) acl_m variables in a server context are lost on a new connection,
-   and after helo/ehlo/mail/starttls/rset commands
-Using an ACL expansion with the logwrite modifier can be a
-useful way of writing to the main log.
-
-
-
-The expansion of the event_action option should normally
-return an empty string.  Should it return anything else the
-following will be forced:
-
-	msg:delivery	(ignored)
-	msg:host:defer	(ignored)
-	msg:fail:delivery (ignored)
-	tcp:connect	do not connect
-	tcp:close	(ignored)
-	tls:cert	refuse verification
-	smtp:connect	close connection
-
-No other use is made of the result string.
-
-If transport proxying is used, the remote IP/port during a
-tcp:connect event will be that of the proxy.
-
-
-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 those loaded locally.
-
-
 Redis Lookup
 --------------------------------------------------------------