.set drivernamemax "64"
.macro copyyear
-2020
+2021
.endmacro
. /////////////////////////////////////////////////////////////////////////////
</revision></revhistory>
<copyright><year>
.copyyear
- </year><holder>University of Cambridge</holder></copyright>
+ </year><holder>The Exim Maintainers</holder></copyright>
</bookinfo>
.literal off
of independent, short-lived processes, this caching applies only within a
single Exim process. There is no inter-process lookup caching facility.
+.new
+If an option &"cache=no_rd"& is used on the lookup then
+the cache is only written to, cached data is not used for the operation
+and a real lookup is done.
+.wen
+
For single-key lookups, Exim keeps the relevant files open in case there is
another lookup that needs them. In some types of configuration this can lead to
many files being kept open for messages with many recipients. To avoid hitting
.vitem &$acl_verify_message$&
.vindex "&$acl_verify_message$&"
After an address verification has failed, this variable contains the failure
-message. It retains its value for use in subsequent modifiers. The message can
-be preserved by coding like this:
+message. It retains its value for use in subsequent modifiers of the verb.
+The message can be preserved by coding like this:
.code
warn !verify = sender
set acl_m0 = $acl_verify_message
You can use &$acl_verify_message$& during the expansion of the &%message%& or
&%log_message%& modifiers, to include information about the verification
failure.
+.new
+&*Note*&: The variable is cleared at the end of processing the ACL verb.
+.wen
.vitem &$address_data$&
.vindex "&$address_data$&"
of the temporary file which is about to be renamed. It can be used to construct
a unique name for the file.
-.vitem &$interface_address$&
+.vitem &$interface_address$& &&&
+ &$interface_port$&
.vindex "&$interface_address$&"
-This is an obsolete name for &$received_ip_address$&.
-
-.vitem &$interface_port$&
.vindex "&$interface_port$&"
-This is an obsolete name for &$received_port$&.
+These are obsolete names for &$received_ip_address$& and &$received_port$&.
.vitem &$item$&
.vindex "&$item$&"
This variable contains the number of bytes in the longest line that was
received as part of the message, not counting the line termination
character(s).
-It is not valid if the &%spool_files_wireformat%& option is used.
+It is not valid if the &%spool_wireformat%& option is used.
.vitem &$message_age$&
.cindex "message" "age of"
also &$message_size$&, &$body_linecount$&, and &$body_zerocount$&.
If the spool file is wireformat
-(see the &%spool_files_wireformat%& main option)
+(see the &%spool_wireformat%& main option)
the CRLF line-terminators are included in the count.
.vitem &$message_exim_id$&
In the MAIL and RCPT ACLs, the value is zero because at that stage the
message has not yet been received.
-This variable is not valid if the &%spool_files_wireformat%& option is used.
+This variable is not valid if the &%spool_wireformat%& option is used.
.vitem &$message_size$&
.cindex "size" "of message"
contains the size supplied on the MAIL command, or -1 if no size was given. The
value may not, of course, be truthful.
-.vitem &$mime_$&&'xxx'&
+.vitem &$mime_anomaly_level$& &&&
+ &$mime_anomaly_text$& &&&
+ &$mime_boundary$& &&&
+ &$mime_charset$& &&&
+ &$mime_content_description$& &&&
+ &$mime_content_disposition$& &&&
+ &$mime_content_id$& &&&
+ &$mime_content_size$& &&&
+ &$mime_content_transfer_encoding$& &&&
+ &$mime_content_type$& &&&
+ &$mime_decoded_filename$& &&&
+ &$mime_filename$& &&&
+ &$mime_is_coverletter$& &&&
+ &$mime_is_multipart$& &&&
+ &$mime_is_rfc822$& &&&
+ &$mime_part_count$&
A number of variables whose names start with &$mime$& are
available when Exim is compiled with the content-scanning extension. For
details, see section &<<SECTscanmimepart>>&.
This variable is set to &"yes"& if PRDR was requested by the client for the
current message, otherwise &"no"&.
-.vitem &$prvscheck_address$&
-This variable is used in conjunction with the &%prvscheck%& expansion item,
-which is described in sections &<<SECTexpansionitems>>& and
-&<<SECTverifyPRVS>>&.
-
-.vitem &$prvscheck_keynum$&
-This variable is used in conjunction with the &%prvscheck%& expansion item,
-which is described in sections &<<SECTexpansionitems>>& and
-&<<SECTverifyPRVS>>&.
-
-.vitem &$prvscheck_result$&
-This variable is used in conjunction with the &%prvscheck%& expansion item,
+.vitem &$prvscheck_address$& &&&
+ &$prvscheck_keynum$& &&&
+ &$prvscheck_result$&
+These variables are used in conjunction with the &%prvscheck%& expansion item,
which is described in sections &<<SECTexpansionitems>>& and
&<<SECTverifyPRVS>>&.
built. The value is copied after recipient rewriting has happened, but before
the &[local_scan()]& function is run.
-.vitem &$received_ip_address$&
+.vitem &$received_ip_address$& &&&
+ &$received_port$&
.vindex "&$received_ip_address$&"
-As soon as an Exim server starts processing an incoming TCP/IP connection, this
-variable is set to the address of the local IP interface, and &$received_port$&
-is set to the local port number. (The remote IP address and port are in
+.vindex "&$received_port$&"
+As soon as an Exim server starts processing an incoming TCP/IP connection, these
+variables are set to the address and port on the local IP interface.
+(The remote IP address and port are in
&$sender_host_address$& and &$sender_host_port$&.) When testing with &%-bh%&,
the port value is -1 unless it has been set using the &%-oMi%& command line
option.
time.
For outbound connections see &$sending_ip_address$&.
-.vitem &$received_port$&
-.vindex "&$received_port$&"
-See &$received_ip_address$&.
-
.vitem &$received_protocol$&
.vindex "&$received_protocol$&"
When a message is being processed, this variable contains the name of the
.table2
.row &%gnutls_compat_mode%& "use GnuTLS compatibility mode"
.row &%gnutls_allow_auto_pkcs11%& "allow GnuTLS to autoload PKCS11 modules"
+.row &%hosts_require_alpn%& "mandatory ALPN"
.row &%openssl_options%& "adjust OpenSSL compatibility options"
.row &%tls_advertise_hosts%& "advertise TLS to these hosts"
+.row &%tls_alpn%& "acceptable protocol names"
.row &%tls_certificate%& "location of server certificate"
.row &%tls_crl%& "certificate revocation list"
.row &%tls_dh_max_bits%& "clamp D-H bit count suggestion"
If the &%smtp_connection%& log selector is not set, this option has no effect.
+.new
+.option hosts_require_alpn main "host list&!!" unset
+.cindex ALPN "require negotiation in server"
+.cindex TLS ALPN
+.cindex TLS "Application Layer Protocol Names"
+If the TLS library supports ALPN
+then a successful negotiation of ALPN will be required for any client
+matching the list, for TLS to be used.
+See also the &%tls_alpn%& option.
+
+&*Note*&: prevention of fallback to in-clear connection is not
+managed by this option, and should be done separately.
+.wen
+
.option hosts_proxy main "host list&!!" unset
.cindex proxy "proxy protocol"
is not required the &%tls_advertise_hosts%& option should be set empty.
-.option tls_certificate main string list&!! unset
+.new
+.option tls_alpn main "string list&!!" "smtp : esmtp"
+.cindex TLS "Application Layer Protocol Names"
+.cindex TLS ALPN
+.cindex ALPN "set acceptable names for server"
+If this option is set,
+the TLS library supports ALPN,
+and the client offers either more than
+ALPN name or a name which does not match the list,
+the TLS connection is declined.
+.wen
+
+
+.option tls_certificate main "string list&!!" unset
.cindex "TLS" "server certificate; location of"
.cindex "certificate" "server, location of"
The value of this option is expanded, and must then be a list of absolute paths to
-.option tls_privatekey main string list&!! unset
+.option tls_privatekey main "string list&!!" unset
.cindex "TLS" "server private key; location of"
The value of this option is expanded, and must then be a list of absolute paths to
files which contains the server's private keys.
its removal from incoming messages, so that delivered messages can safely be
resent to other recipients.
+.new
+&*Note:*& If used on a transport handling multiple recipients
+(the smtp transport unless &%rcpt_max%& is 1, the appendfile, pipe or lmtp
+transport if &%batch_max%& is greater than 1)
+then information about Bcc recipients will be leaked.
+Doing so is generally not advised.
+.wen
+
.option event_action transports string&!! unset
.cindex events
.option dkim_canon smtp string&!! unset
DKIM signing option. For details see section &<<SECDKIMSIGN>>&.
-.option dkim_domain smtp string list&!! unset
+.option dkim_domain smtp "string list&!!" unset
DKIM signing option. For details see section &<<SECDKIMSIGN>>&.
.option dkim_hash smtp string&!! sha256
DKIM signing option. For details see section &<<SECDKIMSIGN>>&.
TLS session for any host that matches this list.
&%tls_verify_certificates%& should also be set for the transport.
+.new
+.option hosts_require_alpn smtp "host list&!!" unset
+.cindex ALPN "require negotiation in client"
+.cindex TLS ALPN
+.cindex TLS "Application Layer Protocol Names"
+If the TLS library supports ALPN
+then a successful negotiation of ALPN will be required for any host
+matching the list, for TLS to be used.
+See also the &%tls_alpn%& option.
+
+&*Note*&: prevention of fallback to in-clear connection is not
+managed by this option; see &%hosts_require_tls%&.
+.wen
+
.option hosts_require_dane smtp "host list&!!" unset
.cindex DANE "transport options"
.cindex DANE "requiring for certain servers"
transport. For details see section &<<SECTproxySOCKS>>&.
+.new
+.option tls_alpn smtp string&!! unset
+.cindex TLS "Application Layer Protocol Names"
+.cindex TLS ALPN
+.cindex ALPN "set name in client"
+If this option is set
+and the TLS library supports ALPN,
+the value given is used.
+
+As of writing no value has been standardised for email use.
+The authors suggest using &"smtp"&.
+.wen
+
+
+
.option tls_certificate smtp string&!! unset
.cindex "TLS" "client certificate, location of"
.cindex "certificate" "client, location of"
0.5.10. (Its presence predates the current API which Exim uses, so if Exim
built, then you have SNI support).
+.new
+.cindex TLS ALPN
+.cindex ALPN "general information"
+.cindex TLS "Application Layer Protocol Names"
+There is a TLS feature related to SNI
+called Application Layer Protocol Name (ALPN).
+This is intended to declare, or select, what protocol layer will be using a TLS
+connection.
+The client for the connection proposes a set of protocol names, and
+the server responds with a selected one.
+It is not, as of 2021, commonly used for SMTP connections.
+However, to guard against misirected or malicious use of web clients
+(which often do use ALPN) against MTA ports, Exim by default check that
+there is no incompatible ALPN specified by a client for a TLS connection.
+If there is, the connection is rejected.
+
+As a client Exim does not supply ALPN by default.
+The behaviour of both client and server can be configured using the options
+&%tls_alpn%& and &%hosts_require_alpn%&.
+There are no variables providing observability.
+Some feature-specific logging may appear on denied connections, but this
+depends on the behavious of the peer
+(not all peers can send a feature-specific TLS Alert).
+
+This feature is available when Exim is built with
+OpenSSL 1.1.0 or later or GnuTLS 3.2.0 or later;
+the macro _HAVE_TLS_ALPN will be defined when this is so.
+.wen
+
.section "Multiple messages on the same encrypted TCP/IP connection" &&&
response.
.vindex "&$acl_verify_message$&"
-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.
+.new
+While the text is being expanded, the &$acl_verify_message$& variable
+contains any message previously set.
+Afterwards, &$acl_verify_message$& is cleared.
+.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.
If you are writing your own custom rejection message or log message when
denying access, you can use this variable to include information about the
verification failure.
+This variable is cleared at the end of processing the ACL verb.
In addition, &$sender_verify_failure$& or &$recipient_verify_failure$& (as
appropriate) contains one of the following words:
.vlist
.vitem &*int&~body_linecount*&
This variable contains the number of lines in the message's body.
-It is not valid if the &%spool_files_wireformat%& option is used.
+It is not valid if the &%spool_wireformat%& option is used.
.vitem &*int&~body_zerocount*&
This variable contains the number of binary zero bytes in the message's body.
-It is not valid if the &%spool_files_wireformat%& option is used.
+It is not valid if the &%spool_wireformat%& option is used.
.vitem &*unsigned&~int&~debug_selector*&
This variable is set to zero when no debugging is taking place. Otherwise, it
lists_post:
driver = redirect
domains = lists.example
- senders = ${if exists {/usr/lists/$local_part}\
- {lsearch;/usr/lists/$local_part}{*}}
+ local_parts = ${lookup {$local_part} dsearch,filter=file,ret=full {/usr/lists}}
+ senders = ${if exists {$local_part_data} {lsearch;$local_part_data}{*}}
file = ${lookup {$local_part} dsearch,ret=full {/usr/lists}}
forbid_pipe
forbid_file
.vitem &%temperror%&
This indicates a temporary error during all processing, including Exim's
SPF processing. You may defer messages when this occurs.
+
+.vitem &%invalid%&
+There was an error during processing of the SPF lookup
.endlist
You can prefix each string with an exclamation mark to invert
.vitem &$spf_received$&
.vindex &$spf_received$&
- This contains a complete Received-SPF: header that can be
- added to the message. Please note that according to the SPF
- draft, this header must be added at the top of the header
- list. Please see section 10 on how you can do this.
+ This contains a complete Received-SPF: header (name and
+ content) that can be added to the message. Please note that
+ according to the SPF draft, this header must be added at the
+ top of the header list, i.e. with
+.code
+add_header = :at_start:$spf_received
+.endd
+ See section &<<SECTaddheadacl>>& for further details.
Note: in case of "Best-guess" (see below), the convention is
to put this string in a header called X-SPF-Guess: instead.
.vitem &$spf_result$&
.vindex &$spf_result$&
This contains the outcome of the SPF check in string form,
- one of pass, fail, softfail, none, neutral, permerror or
- temperror.
+ currently one of pass, fail, softfail, none, neutral, permerror,
+ temperror, or &"(invalid)"&.
.vitem &$spf_result_guessed$&
.vindex &$spf_result_guessed$&
git://git.exim.org / exim.git / blobdiff