X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/a612424f526dbe6a0bde0658cf104b41a8458d05..0f06b4f296802e4e13188c740ea09419931a3020:/doc/doc-docbook/spec.xfpt?ds=sidebyside

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index aa9d23ddb..ffe153ae9 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -5556,12 +5556,10 @@ unreachable.
 
 The next two lines are concerned with &'ident'& callbacks, as defined by RFC
 1413 (hence their names):
-.new
 .code
 rfc1413_hosts = *
 rfc1413_query_timeout = 0s
 .endd
-.wen
 These settings cause Exim to avoid ident callbacks for all incoming SMTP calls.
 Few hosts offer RFC1413 service these days; calls have to be
 terminated by a timeout and this needlessly delays the startup
@@ -7268,7 +7266,7 @@ default list of ldap servers, and a single lookup can specify a single ldap
 server to use.  But when you need to do a lookup with a list of servers that is
 different than the default list (maybe different order, maybe a completely
 different set of servers), the SERVERS parameter allows you to specify this
-alternate list.
+alternate list (colon-separated).
 
 Here is an example of an LDAP query in an Exim lookup that uses some of these
 values. This is a single line, folded to fit on the page:
@@ -7340,30 +7338,44 @@ If you specify multiple attributes, the result contains space-separated, quoted
 strings, each preceded by the attribute name and an equals sign. Within the
 quotes, the quote character, backslash, and newline are escaped with
 backslashes, and commas are used to separate multiple values for the attribute.
+.new
+Any commas in attribute values are doubled
+(permitting treatment of the values as a comma-separated list).
+.wen
 Apart from the escaping, the string within quotes takes the same form as the
 output when a single attribute is requested. Specifying no attributes is the
 same as specifying all of an entry's attributes.
 
+.new
 Here are some examples of the output format. The first line of each pair is an
 LDAP query, and the second is the data that is returned. The attribute called
-&%attr1%& has two values, whereas &%attr2%& has only one value:
+&%attr1%& has two values, one of them with an embedded comma, whereas
+&%attr2%& has only one value:
 .code
 ldap:///o=base?attr1?sub?(uid=fred)
-value1.1, value1.2
+value1.1,value1,,2
 
 ldap:///o=base?attr2?sub?(uid=fred)
 value two
 
 ldap:///o=base?attr1,attr2?sub?(uid=fred)
-attr1="value1.1, value1.2" attr2="value two"
+attr1="value1.1,value1,,2" attr2="value two"
 
 ldap:///o=base??sub?(uid=fred)
-objectClass="top" attr1="value1.1, value1.2" attr2="value two"
+objectClass="top" attr1="value1.1,value1,,2" attr2="value two"
 .endd
-The &%extract%& operator in string expansions can be used to pick out
-individual fields from data that consists of &'key'&=&'value'& pairs. You can
+.wen
+You can
 make use of Exim's &%-be%& option to run expansion tests and thereby check the
 results of LDAP lookups.
+The &%extract%& operator in string expansions can be used to pick out
+individual fields from data that consists of &'key'&=&'value'& pairs.
+.new
+The &%listextract%& operator should be used to pick out individual values
+of attributes, even when only a single value is expected.
+The doubling of embedded commas allows you to use the returned data as a
+comma separated list (using the "<," syntax for changing the input list separator).
+.wen
 
 
 
@@ -10999,12 +11011,10 @@ precedes the expansion of the string. For example, the commands available in
 Exim filter files include an &%if%& command with its own regular expression
 matching condition.
 
-.new
 .vitem "&$acl_arg1$&, &$acl_arg2$&, etc"
 Within an acl condition, expansion condition or expansion item
 any arguments are copied to these variables,
 any unused variables being made empty.
-.wen
 
 .vitem "&$acl_c...$&"
 Values can be placed in these variables by the &%set%& modifier in an ACL. They
@@ -11027,11 +11037,9 @@ message is received, the values of these variables are saved with the message,
 and can be accessed by filters, routers, and transports during subsequent
 delivery.
 
-.new
 .vitem &$acl_narg$&
 Within an acl condition, expansion condition or expansion item
 this variable has the number of arguments.
-.wen
 
 .vitem &$acl_verify_message$&
 .vindex "&$acl_verify_message$&"
@@ -11419,6 +11427,11 @@ the result, the name is not accepted, and &$host_lookup_deferred$& is set to
 .vindex "&$host_lookup_failed$&"
 See &$host_lookup_deferred$&.
 
+.vitem &$host_port$&
+.vindex "&$host_port$&"
+This variable is set to the remote host's TCP port whenever &$host$& is set
+for an outbound connection.
+
 
 .vitem &$inode$&
 .vindex "&$inode$&"
@@ -11665,7 +11678,7 @@ This variable is like &$message_headers$& except that no processing of the
 contents of header lines is done.
 
 .vitem &$message_id$&
-This is an old name for &$message_exim_id$&, which is now deprecated.
+This is an old name for &$message_exim_id$&. It is now deprecated.
 
 .vitem &$message_linecount$&
 .vindex "&$message_linecount$&"
@@ -12361,7 +12374,9 @@ If TLS has not been negotiated, the value will be 0.
 This variable refers to the certificate presented to the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
-&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+.new
+&%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
+.wen
 or a &%def%& condition.
 
 .vitem &$tls_in_peercert$&
@@ -12369,21 +12384,27 @@ or a &%def%& condition.
 This variable refers to the certificate presented by the peer of an
 inbound connection when the message was received.
 It is only useful as the argument of a
-&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+.new
+&%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
+.wen
 or a &%def%& condition.
 
 .vitem &$tls_out_ourcert$&
 .vindex "&$tls_out_ourcert$&"
 This variable refers to the certificate presented to the peer of an
 outbound connection.  It is only useful as the argument of a
-&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+.new
+&%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
+.wen
 or a &%def%& condition.
 
 .vitem &$tls_out_peercert$&
 .vindex "&$tls_out_peercert$&"
 This variable refers to the certificate presented by the peer of an
 outbound connection.  It is only useful as the argument of a
-&%certextract%& expansion item, &%md5%& or &%sha1%& operator,
+.new
+&%certextract%& expansion item, &%md5%&, &%sha1%& or &%sha256%& operator,
+.wen
 or a &%def%& condition.
 
 .vitem &$tls_in_certificate_verified$&
@@ -12423,7 +12444,6 @@ and then set to the outgoing cipher suite if one is negotiated. See chapter
 &<<CHAPTLS>>& for details of TLS support and chapter &<<CHAPsmtptrans>>& for
 details of the &(smtp)& transport.
 
-.new
 .vitem &$tls_in_ocsp$&
 .vindex "&$tls_in_ocsp$&"
 When a message is received from a remote client connection
@@ -12441,7 +12461,6 @@ the result of any OCSP request from the client is encoded in this variable:
 When a message is sent to a remote host connection
 the result of any OCSP request made is encoded in this variable.
 See &$tls_in_ocsp$& for values.
-.wen
 
 .vitem &$tls_in_peerdn$&
 .vindex "&$tls_in_peerdn$&"
@@ -16808,6 +16827,39 @@ If the expansion fails (other than forced failure) delivery is deferred. Some
 of the other precondition options are common special cases that could in fact
 be specified using &%condition%&.
 
+.new
+When originally designed, Exim's ACL system enforced very strict parsing
+of the &%condition%& expansion everywhere it was being processed.
+Through the 4.7x release cycle, the &%condition%& processing while in a
+router became more loose, internally adopting the use of &%bool_lax%&
+instead of the more rigid &%bool%&.  This is best illustrated in an
+example:
+.code
+# This used to fail with a syntax error, now it
+# treats any extra characters as a string
+
+$ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}'
+true {yes} {no}}
+
+$ exim -be '${if eq {${lc:WHOIS.com}} {google.com}} {yes} {no}}'
+ {yes} {no}}
+.endd
+In each example above, the &%if%& statement actually ends after
+&"{google.com}}"&.  Since no true or false braces were defined, the
+default &%if%& behavior is to return a boolean true or a null answer
+(which evaluates to false). The rest of the line is then treated as a
+string. So the first example resulted in the boolean answer &"true"&
+with the string &" {yes} {no}}"& appended to it. The second example
+resulted in the null output (indicating false) with the string
+&" {yes} {no}}"& appended to it.
+
+In fact you can put excess forward braces in too.  In the router
+&%condition%&, Exim's ACL parser only looks for &"{"& symbols when they
+mean something, like after a &"$"& or when required as part of a
+conditional.  But otherwise &"{"& and &"}"& are treated as ordinary
+string characters.
+.wen
+
 
 .option debug_print routers string&!! unset
 .cindex "testing" "variables in drivers"
@@ -25398,9 +25450,7 @@ but it is present in many binary distributions.
 .scindex IIDdcotauth2 "authenticators" "&(dovecot)&"
 This authenticator is an interface to the authentication facility of the
 Dovecot POP/IMAP server, which can support a number of authentication methods.
-.new
 Note that Dovecot must be configured to use auth-client not auth-userdb.
-.wen
 If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful
 to use the same mechanisms for SMTP authentication. This is a server
 authenticator only. There is only one option:
@@ -26269,9 +26319,7 @@ file named by &%tls_ocsp_file%&.
 Note that the proof only covers the terminal server certificate,
 not any of the chain from CA to it.
 
-.new
 There is no current way to staple a proof for a client certificate.
-.wen
 
 .code
   A helper script "ocsp_fetch.pl" for fetching a proof from a CA
@@ -27636,6 +27684,11 @@ anyway. If the message contains newlines, this gives rise to a multi-line SMTP
 response.
 
 .vindex "&$acl_verify_message$&"
+.new
+For ACLs that are called by an &%acl =%& ACL condition, the message is
+stored in &$acl_verify_message$&, from which the calling ACL may use it.
+.wen
+
 If &%message%& is used on a statement that verifies an address, the message
 specified overrides any message that is generated by the verification process.
 However, the original message is available in the variable