Add optional authenticated_sender info to A= elements of log lines; bug 1314.

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 632de6ab03faf11aacae1ff937dacc71c33c6c90..6b63062be49440008d5ffc81bfc6e4590ca41d58 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -8791,12 +8791,12 @@ arguments are assigned to the variables &$acl_arg1$& to &$acl_arg9$& in order.
 Any unused are made empty.  The variable &$acl_narg$& is set to the number of
 arguments.  The named ACL (see chapter &<<CHAPACL>>&) is called
 and may use the variables; if another acl expansion is used the values
-are overwritten.  If the ACL sets
+are restored after it returns.  If the ACL sets
 a value using a "message =" modifier and returns accept or deny, the value becomes
 the result of the expansion.
-If no message was set and the ACL returned accept or deny
-the value is an empty string.
-If the ACL returned defer the result is a forced-fail.  Otherwise the expansion fails.
+If no message is set and the ACL returns accept or deny
+the expansion result is an empty string.
+If the ACL returns defer the result is a forced-fail.  Otherwise the expansion fails.
 
 
 .vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&&
@@ -10107,7 +10107,7 @@ arguments are assigned to the variables &$acl_arg1$& to &$acl_arg9$& in order.
 Any unused are made empty.  The variable &$acl_narg$& is set to the number of
 arguments.  The named ACL (see chapter &<<CHAPACL>>&) is called
 and may use the variables; if another acl expansion is used the values
-are overwritten.  If the ACL sets
+are restored after it returns.  If the ACL sets
 a value using a "message =" modifier the variable $value becomes
 the result of the expansion, otherwise it is empty.
 If the ACL returns accept the condition is true; if deny, false.
@@ -24072,6 +24072,12 @@ client_condition = ${if !eq{$tls_out_cipher}{}}
 .endd
 
 
+.option client_set_id authenticators string&!! unset
+When client authentication succeeds, this condition is expanded; the
+result is used in the log lines for outbound messasges.
+Typically it will be the user name used for authentication.
+
+
 .option driver authenticators string unset
 This option must always be set. It specifies which of the available
 authenticators is to be used.
@@ -27525,8 +27531,10 @@ condition false. This means that further processing of the &%warn%& verb
 ceases, but processing of the ACL continues.
 
 If the argument is a named ACL, up to nine space-separated optional values
-can be appended; they appear in $acl_arg1 to $acl_arg9, and $acl_narg is set
-to the count of values.  The name and values are expanded separately.
+can be appended; they appear within the called ACL in $acl_arg1 to $acl_arg9,
+and $acl_narg is set to the count of values.
+Previous values of these variables are restored after the call returns.
+The name and values are expanded separately.
 
 If the nested &%acl%& returns &"drop"& and the outer condition denies access,
 the connection is dropped. If it returns &"discard"&, the verb must be
@@ -33641,6 +33649,11 @@ intermediate address(es) exist between the original and the final address, the
 last of these is given in parentheses after the final address. The R and T
 fields record the router and transport that were used to process the address.
 
+If SMTP AUTH was used for the delivery there is an additional item A=
+followed by the name of the authenticator that was used.
+If an authenticated identification was set up by the authenticator's &%client_set_id%&
+option, this is logged too, separated by a colon from the authenticator name.
+
 If a shadow transport was run after a successful local delivery, the log line
 for the successful delivery has an item added on the end, of the form
 .display
@@ -33754,7 +33767,7 @@ at the end of its processing.
 A summary of the field identifiers that are used in log lines is shown in
 the following table:
 .display
-&`A   `&        authenticator name (and optional id)
+&`A   `&        authenticator name (and optional id and sender)
 &`C   `&        SMTP confirmation on delivery
 &`    `&        command list for &"no mail in SMTP session"&
 &`CV  `&        certificate verification status
@@ -33871,6 +33884,7 @@ selection marked by asterisks:
 &`*smtp_confirmation          `&  SMTP confirmation on => lines
 &` smtp_connection            `&  SMTP connections
 &` smtp_incomplete_transaction`&  incomplete SMTP transactions
+&` smtp_mailauth              `&  AUTH argument to MAIL commands
 &` smtp_no_mail               `&  session with no MAIL commands
 &` smtp_protocol_error        `&  SMTP protocol errors
 &` smtp_syntax_error          `&  SMTP syntax errors
@@ -34139,6 +34153,11 @@ the last 20 are listed, preceded by &"..."&. However, with the default
 setting of 10 for &%smtp_accep_max_nonmail%&, the connection will in any case
 have been aborted before 20 non-mail commands are processed.
 .next
+&%smtp_mailauth%&: A third subfield with the authenticated sender,
+colon-separated, is appended to the A= item for a message arrival or delivery
+log line, if an AUTH argument to the SMTP MAIL command (see &<<SECTauthparamail>>&)
+was accepted or used.
+.next
 .cindex "log" "SMTP protocol error"
 .cindex "SMTP" "logging protocol error"
 &%smtp_protocol_error%&: A log line is written for every SMTP protocol error