. Update the Copyright year (only) when changing content.
. /////////////////////////////////////////////////////////////////////////////
. Update the Copyright year (only) when changing content.
. /////////////////////////////////////////////////////////////////////////////
.section "Exim documentation" "SECID1"
. Keep this example change bar when updating the documentation!
.section "Exim documentation" "SECID1"
. Keep this example change bar when updating the documentation!
.cindex "documentation"
This edition of the Exim specification applies to version &version() of Exim.
Substantive changes from the &previousversion; edition are marked in some
renditions of this document; this paragraph is so marked if the rendition is
capable of showing a change indicator.
.cindex "documentation"
This edition of the Exim specification applies to version &version() of Exim.
Substantive changes from the &previousversion; edition are marked in some
renditions of this document; this paragraph is so marked if the rendition is
capable of showing a change indicator.
This document is very much a reference manual; it is not a tutorial. The reader
is expected to have some familiarity with the SMTP mail transfer protocol and
This document is very much a reference manual; it is not a tutorial. The reader
is expected to have some familiarity with the SMTP mail transfer protocol and
.cindex debugging "UTF-8 in"
.cindex UTF-8 "in debug output"
The &`noutf8`& selector disables the use of
UTF-8 line-drawing characters to group related information.
When disabled. ascii-art is used instead.
Using the &`+all`& option does not set this modifier,
.cindex debugging "UTF-8 in"
.cindex UTF-8 "in debug output"
The &`noutf8`& selector disables the use of
UTF-8 line-drawing characters to group related information.
When disabled. ascii-art is used instead.
Using the &`+all`& option does not set this modifier,
If the &%debug_print%& option is set in any driver, it produces output whenever
any debugging is selected, or if &%-v%& is used.
If the &%debug_print%& option is set in any driver, it produces output whenever
any debugging is selected, or if &%-v%& is used.
This forces an expansion failure (see section &<<SECTforexpfai>>&);
{<&'string2'&>} must be present for &"fail"& to be recognized.
This forces an expansion failure (see section &<<SECTforexpfai>>&);
{<&'string2'&>} must be present for &"fail"& to be recognized.
.vitem "&*${extract json{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
{*&<&'string3'&>&*}}*&"
.cindex "expansion" "extracting from JSON object"
.vitem "&*${extract json{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
{*&<&'string3'&>&*}}*&"
.cindex "expansion" "extracting from JSON object"
.vitem "&*${extract json{*&<&'number'&>&*}}&&&
{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
.cindex "expansion" "extracting from JSON array"
.vitem "&*${extract json{*&<&'number'&>&*}}&&&
{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
.cindex "expansion" "extracting from JSON array"
The second, tls, controls the use of TLS on the connection. Example:
.code
${readsocket{/socket/name}{request string}{3s:tls=yes}}
.endd
The default is to not use TLS.
If it is enabled, a shutdown as descripbed above is never done.
The second, tls, controls the use of TLS on the connection. Example:
.code
${readsocket{/socket/name}{request string}{3s:tls=yes}}
.endd
The default is to not use TLS.
If it is enabled, a shutdown as descripbed above is never done.
A fourth argument allows you to change any newlines that are in the data
that is read, in the same way as for &%readfile%& (see above). This example
A fourth argument allows you to change any newlines that are in the data
that is read, in the same way as for &%readfile%& (see above). This example
.cindex "expansion" "utf-8 forcing"
.cindex "&%utf8clean%& expansion item"
This replaces any invalid utf-8 sequence in the string by the character &`?`&.
.cindex "expansion" "utf-8 forcing"
.cindex "&%utf8clean%& expansion item"
This replaces any invalid utf-8 sequence in the string by the character &`?`&.
In versions of Exim before 4.92, this did not correctly do so for a truncated
final codepoint's encoding, and the character would be silently dropped.
If you must handle detection of this scenario across both sets of Exim behavior,
In versions of Exim before 4.92, this did not correctly do so for a truncated
final codepoint's encoding, and the character would be silently dropped.
If you must handle detection of this scenario across both sets of Exim behavior,
.vitem "&*${utf8_domain_to_alabel:*&<&'string'&>&*}*&" &&&
"&*${utf8_domain_from_alabel:*&<&'string'&>&*}*&" &&&
.vitem "&*${utf8_domain_to_alabel:*&<&'string'&>&*}*&" &&&
"&*${utf8_domain_from_alabel:*&<&'string'&>&*}*&" &&&
reversed and looked up in the reverse DNS, as described in more detail in
section &<<SECTverifyCSA>>&.
reversed and looked up in the reverse DNS, as described in more detail in
section &<<SECTverifyCSA>>&.
.option dns_cname_loops main integer 1
.cindex DNS "CNAME following"
This option controls the following of CNAME chains, needed if the resolver does
.option dns_cname_loops main integer 1
.cindex DNS "CNAME following"
This option controls the following of CNAME chains, needed if the resolver does
The default value of one CNAME-follow is needed
thanks to the observed return for an MX request,
given no MX presence but a CNAME to an A, of the CNAME.
The default value of one CNAME-follow is needed
thanks to the observed return for an MX request,
given no MX presence but a CNAME to an A, of the CNAME.
Note that at least one Linux distribution has been seen failing
to put &"smtps"& in its &"/etc/services"& file, resulting is such deferrals.
Note that at least one Linux distribution has been seen failing
to put &"smtps"& in its &"/etc/services"& file, resulting is such deferrals.
If this option is set to &"smtps"&, the default value for the &%port%& option
changes to &"smtps"&, and the transport initiates TLS immediately after
connecting, as an outbound SSL-on-connect, instead of using STARTTLS to upgrade.
If this option is set to &"smtps"&, the default value for the &%port%& option
changes to &"smtps"&, and the transport initiates TLS immediately after
connecting, as an outbound SSL-on-connect, instead of using STARTTLS to upgrade.
The Internet standards bodies used to strongly discourage use of this mode,
but as of RFC 8314 it is perferred over STARTTLS for message submission
(as distinct from MTA-MTA communication).
The Internet standards bodies used to strongly discourage use of this mode,
but as of RFC 8314 it is perferred over STARTTLS for message submission
(as distinct from MTA-MTA communication).
If both this option and &%tls_try_verify_hosts%& are unset
operation is as if this option selected all hosts.
If both this option and &%tls_try_verify_hosts%& are unset
operation is as if this option selected all hosts.
.option utf8_downconvert smtp integer!! unset
.cindex utf8 "address downconversion"
.cindex i18n "utf8 address downconversion"
.option utf8_downconvert smtp integer!! unset
.cindex utf8 "address downconversion"
.cindex i18n "utf8 address downconversion"
this option controls conversion of UTF-8 in message addresses
to a-label form.
For details see section &<<SECTi18nMTA>>&.
this option controls conversion of UTF-8 in message addresses
to a-label form.
For details see section &<<SECTi18nMTA>>&.
.oindex "&%tls_require_ciphers%&" "OpenSSL"
There is a function in the OpenSSL library that can be passed a list of cipher
suites before the cipher negotiation takes place. This specifies which ciphers
.oindex "&%tls_require_ciphers%&" "OpenSSL"
There is a function in the OpenSSL library that can be passed a list of cipher
suites before the cipher negotiation takes place. This specifies which ciphers
The list is colon separated and may contain names like
DES-CBC3-SHA. Exim passes the expanded value of &%tls_require_ciphers%&
directly to this function call.
The list is colon separated and may contain names like
DES-CBC3-SHA. Exim passes the expanded value of &%tls_require_ciphers%&
directly to this function call.
For TLS version 1.3 the control available is less fine-grained
and Exim does not provide access to it at present.
The value of the &%tls_require_ciphers%& option is ignored when
For TLS version 1.3 the control available is less fine-grained
and Exim does not provide access to it at present.
The value of the &%tls_require_ciphers%& option is ignored when
Our recommendation is to use DANE with a certificate from a public CA,
because this enables a variety of strategies for remote clients to verify
your certificate.
Our recommendation is to use DANE with a certificate from a public CA,
because this enables a variety of strategies for remote clients to verify
your certificate.
If you're not already using a private CA, or it doesn't meet these
requirements, then we encourage you to avoid all these issues and use a public
CA such as &url(https://letsencrypt.org/,Let's Encrypt) instead.
If you're not already using a private CA, or it doesn't meet these
requirements, then we encourage you to avoid all these issues and use a public
CA such as &url(https://letsencrypt.org/,Let's Encrypt) instead.
The Certificate issued by the CA published in the DANE-TA model should be
issued using a strong hash algorithm.
Exim, and importantly various other MTAs sending to you, will not
The Certificate issued by the CA published in the DANE-TA model should be
issued using a strong hash algorithm.
Exim, and importantly various other MTAs sending to you, will not
libraries.
This means no MD5 and no SHA-1. SHA2-256 is the minimum for reliable
interoperability (and probably the maximum too, in 2018).
libraries.
This means no MD5 and no SHA-1. SHA2-256 is the minimum for reliable
interoperability (and probably the maximum too, in 2018).
The use of OCSP-stapling should be considered, allowing for fast revocation of certificates (which would otherwise
be limited by the DNS TTL on the TLSA records). However, this is likely to only be usable with DANE-TA. NOTE: the
The use of OCSP-stapling should be considered, allowing for fast revocation of certificates (which would otherwise
be limited by the DNS TTL on the TLSA records). However, this is likely to only be usable with DANE-TA. NOTE: the
The &%leaky%& (default) option means that the client's recorded rate is not
updated if it is above the limit. The effect of this is that Exim measures the
client's average rate of successfully sent email,
The &%leaky%& (default) option means that the client's recorded rate is not
updated if it is above the limit. The effect of this is that Exim measures the
client's average rate of successfully sent email,
up to the given limit.
This is appropriate if the countermeasure when the condition is true
consists of refusing the message, and
is generally the better choice if you have clients that retry automatically.
If the action when true is anything more complex then this option is
likely not what is wanted.
up to the given limit.
This is appropriate if the countermeasure when the condition is true
consists of refusing the message, and
is generally the better choice if you have clients that retry automatically.
If the action when true is anything more complex then this option is
likely not what is wanted.
The &%strict%& option means that the client's recorded rate is always
updated. The effect of this is that Exim measures the client's average rate
The &%strict%& option means that the client's recorded rate is always
updated. The effect of this is that Exim measures the client's average rate
The main use of these variables is expected to be to distinguish between
rejections of MAIL and rejections of RCPT in callouts.
The main use of these variables is expected to be to distinguish between
rejections of MAIL and rejections of RCPT in callouts.
The above variables may also be set after a &*successful*&
address verification to:
.ilist
&%random%&: A random local-part callout succeeded
.endlist
The above variables may also be set after a &*successful*&
address verification to:
.ilist
&%random%&: A random local-part callout succeeded
.endlist
.cindex "&[local_scan()]& function" "building Exim to use"
To make use of the local scan function feature, you must tell Exim where your
function is before building Exim, by setting
.cindex "&[local_scan()]& function" "building Exim to use"
To make use of the local scan function feature, you must tell Exim where your
function is before building Exim, by setting
LOCAL_SCAN_SOURCE in your
&_Local/Makefile_&. A recommended place to put it is in the &_Local_&
directory, so you might set
LOCAL_SCAN_SOURCE in your
&_Local/Makefile_&. A recommended place to put it is in the &_Local_&
directory, so you might set
&%pid%&: The current process id is added to every log line, in square brackets,
immediately after the time and date.
.next
&%pid%&: The current process id is added to every log line, in square brackets,
immediately after the time and date.
.next
is insurance against disk crashes where the directory is lost but the files
themselves are recoverable.
is insurance against disk crashes where the directory is lost but the files
themselves are recoverable.
The file formats may be changed, or new formats added, at any release.
Spool files are not intended as an interface to other programs
and should not be used as such.
The file formats may be changed, or new formats added, at any release.
Spool files are not intended as an interface to other programs
and should not be used as such.
Some people are tempted into editing -D files in order to modify messages. You
need to be extremely careful if you do this; it is not recommended and you are
Some people are tempted into editing -D files in order to modify messages. You
need to be extremely careful if you do this; it is not recommended and you are
.option dkim_timestamps smtp integer&!! unset
This option controls the inclusion of timestamp information in the signature.
If not set, no such information will be included.
.option dkim_timestamps smtp integer&!! unset
This option controls the inclusion of timestamp information in the signature.
If not set, no such information will be included.
Verification of DKIM signatures in SMTP incoming email is done for all
messages for which an ACL control &%dkim_disable_verify%& has not been set.
.cindex authentication "expansion item"
Performing verification sets up information used by the
&$authresults$& expansion item.
Verification of DKIM signatures in SMTP incoming email is done for all
messages for which an ACL control &%dkim_disable_verify%& has not been set.
.cindex authentication "expansion item"
Performing verification sets up information used by the
&$authresults$& expansion item.
-.new The results of that verification are then made available to the
-&%acl_smtp_dkim%& ACL, &new(which can examine and modify them).
+The results of that verification are then made available to the
+&%acl_smtp_dkim%& ACL, which can examine and modify them.
By default, this ACL is called once for each
syntactically(!) correct signature in the incoming message.
A missing ACL definition defaults to accept.
By default, this ACL is called once for each
syntactically(!) correct signature in the incoming message.
A missing ACL definition defaults to accept.
If a cutthrough delivery was in progress for the message, that is
summarily dropped (having wasted the transmission effort).
If a cutthrough delivery was in progress for the message, that is
summarily dropped (having wasted the transmission effort).
a large number of expansion variables
containing the signature status and its details are set up during the
runtime of the ACL.
a large number of expansion variables
containing the signature status and its details are set up during the
runtime of the ACL.
The number of signed body bytes. If zero ("0"), the body is unsigned. If no
limit was set by the signer, "9999999999999" is returned. This makes sure
that this variable always expands to an integer value.
The number of signed body bytes. If zero ("0"), the body is unsigned. If no
limit was set by the signer, "9999999999999" is returned. This makes sure
that this variable always expands to an integer value.
&*Note:*& The presence of the signature tag specifying a signing body length
is one possible route to spoofing of valid DKIM signatures.
A paranoid implementation might wish to regard signature where this variable
shows less than the "no limit" return as being invalid.
&*Note:*& The presence of the signature tag specifying a signing body length
is one possible route to spoofing of valid DKIM signatures.
A paranoid implementation might wish to regard signature where this variable
shows less than the "no limit" return as being invalid.
The smtp transport has an option &%utf8_downconvert%&.
If set it must expand to one of the three values described above,
and it overrides any previously set value.
The smtp transport has an option &%utf8_downconvert%&.
If set it must expand to one of the three values described above,
and it overrides any previously set value.
git://git.exim.org / users / jgh / exim.git / blobdiff