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
.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$&"
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$&"
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$&
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$&
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"
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
git://git.exim.org / users / jgh / exim.git / blobdiff