using the same syntax as for &%-oMa%&. The interface address is placed in
&$received_ip_address$& and the port number, if present, in &$received_port$&.
+.vitem &%-oMm%&&~<&'message&~reference'&>
+.oindex "&%-oMm%&"
+.cindex "message reference" "message reference, specifying for local message"
+See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMm%&
+option sets the message reference, e.g. message-id, and is logged during
+delivery. This is useful when some kind of audit trail is required to tie
+messages together. The format of the message reference is checked and will
+abort if the format is invalid. The option will only be accepted if exim is
+running in trusted mode, not as any regular user.
+
+The best example of a message reference is when Exim sends a bounce message.
+The message reference is the message-id of the original message for which Exim
+is sending the bounce.
+
.vitem &%-oMr%&&~<&'protocol&~name'&>
.oindex "&%-oMr%&"
.cindex "protocol, specifying for local message"
in the same way that multiple DNS records for a single item are handled. A
different separator can be specified, as described above.
+Modifiers for &(dnsdb)& lookups are givien by optional keywords,
+each followed by a comma,
+that may appear before the record type.
+
The &(dnsdb)& lookup fails only if all the DNS lookups fail. If there is a
temporary DNS error for any of them, the behaviour is controlled by
-an optional keyword followed by a comma that may appear before the record
-type. The possible keywords are &"defer_strict"&, &"defer_never"&, and
-&"defer_lax"&. With &"strict"& behaviour, any temporary DNS error causes the
+a defer-option modifier.
+The possible keywords are
+&"defer_strict"&, &"defer_never"&, and &"defer_lax"&.
+With &"strict"& behaviour, any temporary DNS error causes the
whole lookup to defer. With &"never"& behaviour, a temporary DNS error is
ignored, and the behaviour is as if the DNS lookup failed to find anything.
With &"lax"& behaviour, all the queries are attempted, but a temporary DNS
Thus, in the default case, as long as at least one of the DNS lookups
yields some data, the lookup succeeds.
+.new
+.cindex "DNSSEC" "dns lookup"
+Use of &(DNSSEC)& is controlled by a dnssec modifier.
+The possible keywords are
+&"dnssec_strict"&, &"dnssec_lax"&, and &"dnssec_never"&.
+With &"strict"& or &"lax"& DNSSEC information is requested
+with the lookup.
+With &"strict"& a response from the DNS resolver that
+is not labelled as authenticated data
+is treated as equivalent to a temporary DNS error.
+The default is &"never"&.
+
+See also the &$lookup_dnssec_authenticated$& variable.
+.wen
+
&`USER `& set the DN, for authenticating the LDAP bind
&`PASS `& set the password, likewise
&`REFERRALS `& set the referrals parameter
+.new
&`SERVERS `& set alternate server list for this query only
+.wen
&`SIZE `& set the limit for the number of entries returned
&`TIME `& set the maximum waiting time for a query
.endd
The TIME parameter (also a number of seconds) is passed to the server to
set a server-side limit on the time taken to complete a search.
+.new
The SERVERS parameter allows you to specify an alternate list of ldap servers
to use for an individual lookup. The global ldap_servers option provides a
default list of ldap servers, and a single lookup can specify a single ldap
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.
-
+.wen
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:
If the ACL returns defer the result is a forced-fail. Otherwise the expansion fails.
+.new
+.vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&
+ {*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
+.cindex "expansion" "extracting cerificate fields"
+.cindex "&%certextract%&" "certificate fields"
+.cindex "certificate" "extracting fields"
+The <&'certificate'&> must be a variable of type certificate.
+The field name is expanded and used to retrive the relevant field from
+the certificate. Supported fields are:
+.display
+&`version `&
+&`serial_number `&
+&`subject `&
+&`issuer `&
+&`notbefore `&
+&`notafter `&
+&`sig_algorithm `&
+&`signature `&
+&`subj_altname `& tagged list
+&`ocsp_uri `& list
+&`crl_uri `& list
+.endd
+If the field is found,
+<&'string2'&> is expanded, and replaces the whole item;
+otherwise <&'string3'&> is used. During the expansion of <&'string2'&> the
+variable &$value$& contains the value that has been extracted. Afterwards, it
+is restored to any previous value it might have had.
+
+If {<&'string3'&>} is omitted, the item is replaced by an empty string if the
+key is not found. If {<&'string2'&>} is also omitted, the value that was
+extracted is used.
+
+Some field names take optional modifiers, appended and separated by commas.
+
+The field selectors marked as "list" above return a list,
+newline-separated by default,
+(embedded separator characters in elements are doubled).
+The separator may be changed by a modifier of
+a right angle-bracket followed immediately by the new separator.
+
+The field selectors marked as "tagged" above
+prefix each list element with a type string and an equals sign.
+Elements of only one type may be selected by a modifier
+which is one of "dns", "uri" or "mail";
+if so the elenment tags are omitted.
+
+Field values are generally presented in human-readable form.
+.wen
+
.vitem "&*${dlfunc{*&<&'file'&>&*}{*&<&'function'&>&*}{*&<&'arg'&>&*}&&&
{*&<&'arg'&>&*}...}*&"
.cindex &%dlfunc%&
.vitem &*${md5:*&<&'string'&>&*}*&
.cindex "MD5 hash"
.cindex "expansion" "MD5 hash"
+.cindex "certificate fingerprint"
.cindex "&%md5%& expansion item"
The &%md5%& operator computes the MD5 hash value of the string, and returns it
as a 32-digit hexadecimal number, in which any letters are in lower case.
.vitem &*${sha1:*&<&'string'&>&*}*&
.cindex "SHA-1 hash"
.cindex "expansion" "SHA-1 hashing"
+.cindex "certificate fingerprint"
.cindex "&%sha2%& expansion item"
The &%sha1%& operator computes the SHA-1 hash value of the string, and returns
it as a 40-digit hexadecimal number, in which any letters are in upper case.
+.vitem &*${sha256:*&<&'certificate'&>&*}*&
+.cindex "SHA-256 hash"
+.cindex "certificate fingerprint"
+.cindex "expansion" "SHA-256 hashing"
+.cindex "&%sha256%& expansion item"
+The &%sha256%& operator computes the SHA-256 hash fingerprint of the
+certificate,
+and returns
+it as a 64-digit hexadecimal number, in which any letters are in upper case.
+Only arguments which are a single variable of certificate type are supported.
+
+
.vitem &*${stat:*&<&'string'&>&*}*&
.cindex "expansion" "statting a file"
.cindex "file" "extracting characteristics"
the space value is -1. See also the &%check_log_space%& option.
+.new
+.vitem &$lookup_dnssec_authenticated$&
+.vindex "&$lookup_dnssec_authenticated$&"
+This variable is set after a DNS lookup done by
+a dnsdb lookup expansion, dnslookup router or smtp transport.
+It will be empty if &(DNSSEC)& was not requested,
+&"no"& if the result was not labelled as authenticated data
+and &"yes"& if it was.
+.wen
+
.vitem &$mailstore_basename$&
.vindex "&$mailstore_basename$&"
This variable is set only when doing deliveries in &"mailstore"& format in the
this depends upon the TLS implementation used.
If TLS has not been negotiated, the value will be 0.
+.new
+.vitem &$tls_in_ourcert$&
+.vindex "&$tls_in_ourcert$&"
+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,
+or a &%def%& condition.
+.wen
+
+.new
+.vitem &$tls_in_peercert$&
+.vindex "&$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,
+or a &%def%& condition.
+.wen
+
+.new
+.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,
+or a &%def%& condition.
+.wen
+
+.new
+.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,
+or a &%def%& condition.
+.wen
+
.vitem &$tls_in_certificate_verified$&
.vindex "&$tls_in_certificate_verified$&"
This variable is set to &"1"& if a TLS certificate was verified when the
+.new
.option dnssec_request_domains dnslookup "domain list&!!" unset
.cindex "MX record" "security"
.cindex "DNSSEC" "MX lookup"
DNS lookups for domains matching &%dnssec_request_domains%& will be done with
the dnssec request bit set.
This applies to all of the SRV, MX A6, AAAA, A lookup sequence.
+.wen
+.new
.option dnssec_require_domains dnslookup "domain list&!!" unset
.cindex "MX record" "security"
.cindex "DNSSEC" "MX lookup"
the dnssec request bit set. Any returns not having the Authenticated Data bit
(AD bit) set wil be ignored and logged as a host-lookup failure.
This applies to all of the SRV, MX A6, AAAA, A lookup sequence.
+.wen
details.
+.new
+.option dnssec_request_domains smtp "domain list&!!" unset
+.cindex "MX record" "security"
+.cindex "DNSSEC" "MX lookup"
+.cindex "security" "MX lookup"
+.cindex "DNS" "DNSSEC"
+DNS lookups for domains matching &%dnssec_request_domains%& will be done with
+the dnssec request bit set.
+This applies to all of the SRV, MX A6, AAAA, A lookup sequence.
+.wen
+
+
+
+.new
+.option dnssec_require_domains smtp "domain list&!!" unset
+.cindex "MX record" "security"
+.cindex "DNSSEC" "MX lookup"
+.cindex "security" "MX lookup"
+.cindex "DNS" "DNSSEC"
+DNS lookups for domains matching &%dnssec_request_domains%& will be done with
+the dnssec request bit set. Any returns not having the Authenticated Data bit
+(AD bit) set wil be ignored and logged as a host-lookup failure.
+This applies to all of the SRV, MX A6, AAAA, A lookup sequence.
+.wen
+
+
+
.option dscp smtp string&!! unset
.cindex "DCSP" "outbound"
This option causes the DSCP value associated with a socket to be set to one
or (in case &*-a*& switch is specified)
.code
exim -bp
-.endd
+.endd
+.new
+The &*-C*& option is used to specify an alternate &_exim.conf_& which might
+contain alternate exim configuration the queue management might be using.
+.wen
to obtain a queue listing, and then greps the output to select messages
that match given criteria. The following selection options are available:
git://git.exim.org / users / jgh / exim.git / blobdiff