+
+
+
+.section "SPF (Sender Policy Framework)" SECSPF
+.cindex SPF verification
+
+SPF is a mechanism whereby a domain may assert which IP addresses may transmit
+messages with its domain in the envelope from, documented by RFC 7208.
+For more information on SPF see &url(http://www.open-spf.org), a static copy of
+the &url(http://openspf.org).
+. --- 2019-10-28: still not https, open-spf.org is told to be a
+. --- web-archive copy of the now dead openspf.org site
+. --- See https://www.mail-archive.com/mailop@mailop.org/msg08019.html for a
+. --- discussion.
+
+Messages sent by a system not authorised will fail checking of such assertions.
+This includes retransmissions done by traditional forwarders.
+
+SPF verification support is built into Exim if SUPPORT_SPF=yes is set in
+&_Local/Makefile_&. The support uses the &_libspf2_& library
+&url(https://www.libspf2.org/).
+There is no Exim involvement in the transmission of messages;
+publishing certain DNS records is all that is required.
+
+For verification, an ACL condition and an expansion lookup are provided.
+.cindex authentication "expansion item"
+Performing verification sets up information used by the
+&%authresults%& expansion item.
+
+
+.cindex SPF "ACL condition"
+.cindex ACL "spf condition"
+The ACL condition "spf" can be used at or after the MAIL ACL.
+It takes as an argument a list of strings giving the outcome of the SPF check,
+and will succeed for any matching outcome.
+Valid strings are:
+.vlist
+.vitem &%pass%&
+The SPF check passed, the sending host is positively verified by SPF.
+
+.vitem &%fail%&
+The SPF check failed, the sending host is NOT allowed to send mail for the
+domain in the envelope-from address.
+
+.vitem &%softfail%&
+The SPF check failed, but the queried domain can't absolutely confirm that this
+is a forgery.
+
+.vitem &%none%&
+The queried domain does not publish SPF records.
+
+.vitem &%neutral%&
+The SPF check returned a "neutral" state. This means the queried domain has
+published a SPF record, but wants to allow outside servers to send mail under
+its domain as well. This should be treated like "none".
+
+.vitem &%permerror%&
+This indicates a syntax error in the SPF record of the queried domain.
+You may deny messages when this occurs.
+
+.vitem &%temperror%&
+This indicates a temporary error during all processing, including Exim's
+SPF processing. You may defer messages when this occurs.
+.endlist
+
+You can prefix each string with an exclamation mark to invert
+its meaning, for example "!fail" will match all results but
+"fail". The string list is evaluated left-to-right, in a
+short-circuit fashion.
+
+Example:
+.code
+deny spf = fail
+ message = $sender_host_address is not allowed to send mail from \
+ ${if def:sender_address_domain \
+ {$sender_address_domain}{$sender_helo_name}}. \
+ Please see http://www.open-spf.org/Why;\
+ identity=${if def:sender_address_domain \
+ {$sender_address}{$sender_helo_name}};\
+ ip=$sender_host_address
+.endd
+
+Note: The above mentioned URL may not be as helpful as expected. You are
+encouraged to replace the link with a link to a site with more
+explanations.
+
+When the spf condition has run, it sets up several expansion
+variables:
+
+.cindex SPF "verification variables"
+.vlist
+.vitem &$spf_header_comment$&
+.vindex &$spf_header_comment$&
+ This contains a human-readable string describing the outcome
+ of the SPF check. You can add it to a custom header or use
+ it for logging purposes.
+
+.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.
+
+ 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.
+
+.vitem &$spf_result_guessed$&
+.vindex &$spf_result_guessed$&
+ This boolean is true only if a best-guess operation was used
+ and required in order to obtain a result.
+
+.vitem &$spf_smtp_comment$&
+.vindex &$spf_smtp_comment$&
+.vindex &%spf_smtp_comment_template%&
+ This contains a string that can be used in a SMTP response
+ to the calling party. Useful for "fail".
+.new
+ The string is generated by the SPF library from the template configured in the main config
+ option &%spf_smtp_comment_template%&.
+.wen
+.endlist
+
+
+.cindex SPF "ACL condition"
+.cindex ACL "spf_guess condition"
+.cindex SPF "best guess"
+In addition to SPF, you can also perform checks for so-called
+"Best-guess". Strictly speaking, "Best-guess" is not standard
+SPF, but it is supported by the same framework that enables SPF
+capability.
+Refer to &url(http://www.open-spf.org/FAQ/Best_guess_record)
+for a description of what it means.
+. --- 2019-10-28: still not https:
+
+To access this feature, simply use the spf_guess condition in place
+of the spf one. For example:
+
+.code
+deny spf_guess = fail
+ message = $sender_host_address doesn't look trustworthy to me
+.endd
+
+In case you decide to reject messages based on this check, you
+should note that although it uses the same framework, "Best-guess"
+is not SPF, and therefore you should not mention SPF at all in your
+reject message.
+
+When the spf_guess condition has run, it sets up the same expansion
+variables as when spf condition is run, described above.
+
+Additionally, since Best-guess is not standardized, you may redefine
+what "Best-guess" means to you by redefining the main configuration
+&%spf_guess%& option.
+For example, the following:
+
+.code
+spf_guess = v=spf1 a/16 mx/16 ptr ?all
+.endd
+
+would relax host matching rules to a broader network range.
+
+
+.cindex SPF "lookup expansion"
+.cindex lookup spf
+A lookup expansion is also available. It takes an email
+address as the key and an IP address
+(v4 or v6)
+as the database:
+
+.code
+ ${lookup {username@domain} spf {ip.ip.ip.ip}}
+.endd
+
+The lookup will return the same result strings as can appear in
+&$spf_result$& (pass,fail,softfail,neutral,none,err_perm,err_temp).
+
+
+
+
+
+.section DMARC SECDMARC
+.cindex DMARC verification
+
+DMARC combines feedback from SPF, DKIM, and header From: in order
+to attempt to provide better indicators of the authenticity of an
+email. This document does not explain the fundamentals; you
+should read and understand how it works by visiting the website at
+&url(http://www.dmarc.org/).
+
+If Exim is built with DMARC support,
+the libopendmarc library is used.
+
+For building Exim yourself, obtain the library from
+&url(http://sourceforge.net/projects/opendmarc/)
+to obtain a copy, or find it in your favorite package
+repository. You will need to attend to the local/Makefile feature
+SUPPORT_DMARC and the associated LDFLAGS addition.
+This description assumes
+that headers will be in /usr/local/include, and that the libraries
+are in /usr/local/lib.
+
+. subsection
+
+There are three main-configuration options:
+.cindex DMARC "configuration options"
+
+The &%dmarc_tld_file%& option
+.oindex &%dmarc_tld_file%&
+defines the location of a text file of valid
+top level domains the opendmarc library uses
+during domain parsing. Maintained by Mozilla,
+the most current version can be downloaded
+from a link at &url(https://publicsuffix.org/list/public_suffix_list.dat).
+See also the util/renew-opendmarc-tlds.sh script.
+.new
+The default for the option is unset.
+If not set, DMARC processing is disabled.
+.wen
+
+
+The &%dmarc_history_file%& option, if set
+.oindex &%dmarc_history_file%&
+defines the location of a file to log results
+of dmarc verification on inbound emails. The
+contents are importable by the opendmarc tools
+which will manage the data, send out DMARC
+reports, and expire the data. Make sure the
+directory of this file is writable by the user
+exim runs as.
+The default is unset.
+
+The &%dmarc_forensic_sender%& option
+.oindex &%dmarc_forensic_sender%&
+defines an alternate email address to use when sending a
+forensic report detailing alignment failures
+if a sender domain's dmarc record specifies it
+and you have configured Exim to send them.
+If set, this is expanded and used for the
+From: header line; the address is extracted
+from it and used for the envelope from.
+If not set (the default), the From: header is expanded from
+the dsn_from option, and <> is used for the
+envelope from.
+
+. I wish we had subsections...
+
+.cindex DMARC controls
+By default, the DMARC processing will run for any remote,
+non-authenticated user. It makes sense to only verify DMARC
+status of messages coming from remote, untrusted sources. You can
+use standard conditions such as hosts, senders, etc, to decide that
+DMARC verification should *not* be performed for them and disable
+DMARC with an ACL control modifier:
+.code
+ control = dmarc_disable_verify
+.endd
+A DMARC record can also specify a "forensic address", which gives
+exim an email address to submit reports about failed alignment.
+Exim does not do this by default because in certain conditions it
+results in unintended information leakage (what lists a user might
+be subscribed to, etc). You must configure exim to submit forensic
+reports to the owner of the domain. If the DMARC record contains a
+forensic address and you specify the control statement below, then
+exim will send these forensic emails. It is also advised that you
+configure a &%dmarc_forensic_sender%& because the default sender address
+construction might be inadequate.
+.code
+ control = dmarc_enable_forensic
+.endd
+(AGAIN: You can choose not to send these forensic reports by simply
+not putting the dmarc_enable_forensic control line at any point in
+your exim config. If you don't tell exim to send them, it will not
+send them.)
+
+There are no options to either control. Both must appear before
+the DATA acl.
+
+. subsection
+
+DMARC checks cam be run on incoming SMTP messages by using the
+&"dmarc_status"& ACL condition in the DATA ACL. You are required to
+call the &"spf"& condition first in the ACLs, then the &"dmarc_status"&
+condition. Putting this condition in the ACLs is required in order
+for a DMARC check to actually occur. All of the variables are set
+up before the DATA ACL, but there is no actual DMARC check that
+occurs until a &"dmarc_status"& condition is encountered in the ACLs.
+
+The &"dmarc_status"& condition takes a list of strings on its
+right-hand side. These strings describe recommended action based
+on the DMARC check. To understand what the policy recommendations
+mean, refer to the DMARC website above. Valid strings are:
+.display
+&'accept '& The DMARC check passed and the library recommends accepting the email.
+&'reject '& The DMARC check failed and the library recommends rejecting the email.
+&'quarantine '& The DMARC check failed and the library recommends keeping it for further inspection.
+&'none '& The DMARC check passed and the library recommends no specific action, neutral.
+&'norecord '& No policy section in the DMARC record for this sender domain.
+&'nofrom '& Unable to determine the domain of the sender.
+&'temperror '& Library error or dns error.
+&'off '& The DMARC check was disabled for this email.
+.endd
+You can prefix each string with an exclamation mark to invert its
+meaning, for example "!accept" will match all results but
+"accept". The string list is evaluated left-to-right in a
+short-circuit fashion. When a string matches the outcome of the
+DMARC check, the condition succeeds. If none of the listed
+strings matches the outcome of the DMARC check, the condition
+fails.
+
+Of course, you can also use any other lookup method that Exim
+supports, including LDAP, Postgres, MySQL, etc, as long as the
+result is a list of colon-separated strings.
+
+Performing the check sets up information used by the
+&%authresults%& expansion item.
+
+Several expansion variables are set before the DATA ACL is
+processed, and you can use them in this ACL. The following
+expansion variables are available:
+
+.vlist
+.vitem &$dmarc_status$&
+.vindex &$dmarc_status$&
+.cindex DMARC result
+A one word status indicating what the DMARC library
+thinks of the email. It is a combination of the results of
+DMARC record lookup and the SPF/DKIM/DMARC processing results
+(if a DMARC record was found). The actual policy declared
+in the DMARC record is in a separate expansion variable.
+
+.vitem &$dmarc_status_text$&
+.vindex &$dmarc_status_text$&
+Slightly longer, human readable status.
+
+.vitem &$dmarc_used_domain$&
+.vindex &$dmarc_used_domain$&
+The domain which DMARC used to look up the DMARC policy record.
+
+.vitem &$dmarc_domain_policy$&
+.vindex &$dmarc_domain_policy$&
+The policy declared in the DMARC record. Valid values
+are "none", "reject" and "quarantine". It is blank when there
+is any error, including no DMARC record.
+.endlist
+
+. subsection
+
+By default, Exim's DMARC configuration is intended to be
+non-intrusive and conservative. To facilitate this, Exim will not
+create any type of logging files without explicit configuration by
+you, the admin. Nor will Exim send out any emails/reports about
+DMARC issues without explicit configuration by you, the admin (other
+than typical bounce messages that may come about due to ACL
+processing or failure delivery issues).
+
+In order to log statistics suitable to be imported by the opendmarc
+tools, you need to:
+.ilist
+Configure the global option &%dmarc_history_file%&
+.next
+Configure cron jobs to call the appropriate opendmarc history
+import scripts and truncating the dmarc_history_file
+.endlist
+
+In order to send forensic reports, you need to:
+.ilist
+Configure the global option &%dmarc_forensic_sender%&
+.next
+Configure, somewhere before the DATA ACL, the control option to
+enable sending DMARC forensic reports
+.endlist
+
+. subsection
+
+Example usage:
+.code
+(RCPT ACL)
+ warn domains = +local_domains
+ hosts = +local_hosts
+ control = dmarc_disable_verify
+
+ warn !domains = +screwed_up_dmarc_records
+ control = dmarc_enable_forensic
+
+ warn condition = (lookup if destined to mailing list)
+ set acl_m_mailing_list = 1
+
+(DATA ACL)
+ warn dmarc_status = accept : none : off
+ !authenticated = *
+ log_message = DMARC DEBUG: $dmarc_status $dmarc_used_domain
+
+ warn dmarc_status = !accept
+ !authenticated = *
+ log_message = DMARC DEBUG: '$dmarc_status' for $dmarc_used_domain
+
+ warn dmarc_status = quarantine
+ !authenticated = *
+ set $acl_m_quarantine = 1
+ # Do something in a transport with this flag variable
+
+ deny condition = ${if eq{$dmarc_domain_policy}{reject}}
+ condition = ${if eq{$acl_m_mailing_list}{1}}
+ message = Messages from $dmarc_used_domain break mailing lists
+
+ deny dmarc_status = reject
+ !authenticated = *
+ message = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT
+
+ warn add_header = :at_start:${authresults {$primary_hostname}}
+.endd
+
+
+
+
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Proxies" "CHAPproxies" &&&
+ "Proxy support"
+.cindex "proxy support"
+.cindex "proxy" "access via"
+
+A proxy is an intermediate system through which communication is passed.
+Proxies may provide a security, availability or load-distribution function.
+
+
+.section "Inbound proxies" SECTproxyInbound
+.cindex proxy inbound
+.cindex proxy "server side"
+.cindex proxy "Proxy protocol"
+.cindex "Proxy protocol" proxy
+
+Exim has support for receiving inbound SMTP connections via a proxy
+that uses &"Proxy Protocol"& to speak to it.
+To include this support, include &"SUPPORT_PROXY=yes"&
+in Local/Makefile.
+
+It was built on the HAProxy specification, found at
+&url(https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt).
+
+The purpose of this facility is so that an application load balancer,
+such as HAProxy, can sit in front of several Exim servers
+to distribute load.
+Exim uses the local protocol communication with the proxy to obtain
+the remote SMTP system IP address and port information.
+There is no logging if a host passes or
+fails Proxy Protocol negotiation, but it can easily be determined and
+recorded in an ACL (example is below).
+
+Use of a proxy is enabled by setting the &%hosts_proxy%&
+main configuration option to a hostlist; connections from these
+hosts will use Proxy Protocol.
+Exim supports both version 1 and version 2 of the Proxy Protocol and
+automatically determines which version is in use.
+
+The Proxy Protocol header is the first data received on a TCP connection
+and is inserted before any TLS-on-connect handshake from the client; Exim
+negotiates TLS between Exim-as-server and the remote client, not between
+Exim and the proxy server.
+
+The following expansion variables are usable
+(&"internal"& and &"external"& here refer to the interfaces
+of the proxy):
+.display
+&'proxy_external_address '& IP of host being proxied or IP of remote interface of proxy
+&'proxy_external_port '& Port of host being proxied or Port on remote interface of proxy
+&'proxy_local_address '& IP of proxy server inbound or IP of local interface of proxy
+&'proxy_local_port '& Port of proxy server inbound or Port on local interface of proxy
+&'proxy_session '& boolean: SMTP connection via proxy
+.endd
+If &$proxy_session$& is set but &$proxy_external_address$& is empty
+there was a protocol error.
+The variables &$sender_host_address$& and &$sender_host_port$&
+will have values for the actual client system, not the proxy.
+
+Since the real connections are all coming from the proxy, and the
+per host connection tracking is done before Proxy Protocol is
+evaluated, &%smtp_accept_max_per_host%& must be set high enough to
+handle all of the parallel volume you expect per inbound proxy.
+With the option set so high, you lose the ability
+to protect your server from many connections from one IP.
+In order to prevent your server from overload, you
+need to add a per connection ratelimit to your connect ACL.
+A possible solution is:
+.display
+ # Set max number of connections per host
+ LIMIT = 5
+ # Or do some kind of IP lookup in a flat file or database
+ # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}}
+
+ defer ratelimit = LIMIT / 5s / per_conn / strict
+ message = Too many connections from this IP right now
+.endd
+
+
+
+.section "Outbound proxies" SECTproxySOCKS
+.cindex proxy outbound
+.cindex proxy "client side"
+.cindex proxy SOCKS
+.cindex SOCKS proxy
+Exim has support for sending outbound SMTP via a proxy
+using a protocol called SOCKS5 (defined by RFC1928).
+The support can be optionally included by defining SUPPORT_SOCKS=yes in
+Local/Makefile.
+
+Use of a proxy is enabled by setting the &%socks_proxy%& option
+on an smtp transport.
+The option value is expanded and should then be a list
+(colon-separated by default) of proxy specifiers.
+Each proxy specifier is a list
+(space-separated by default) where the initial element
+is an IP address and any subsequent elements are options.
+
+Options are a string <name>=<value>.
+The list of options is in the following table:
+.display
+&'auth '& authentication method
+&'name '& authentication username
+&'pass '& authentication password
+&'port '& tcp port
+&'tmo '& connection timeout
+&'pri '& priority
+&'weight '& selection bias
+.endd
+
+More details on each of these options follows:
+
+.ilist
+.cindex authentication "to proxy"
+.cindex proxy authentication
+&%auth%&: Either &"none"& (default) or &"name"&.
+Using &"name"& selects username/password authentication per RFC 1929
+for access to the proxy.
+Default is &"none"&.
+.next
+&%name%&: sets the username for the &"name"& authentication method.
+Default is empty.
+.next
+&%pass%&: sets the password for the &"name"& authentication method.
+Default is empty.
+.next
+&%port%&: the TCP port number to use for the connection to the proxy.
+Default is 1080.
+.next
+&%tmo%&: sets a connection timeout in seconds for this proxy.
+Default is 5.
+.next
+&%pri%&: specifies a priority for the proxy within the list,
+higher values being tried first.
+The default priority is 1.
+.next
+&%weight%&: specifies a selection bias.
+Within a priority set servers are queried in a random fashion,
+weighted by this value.
+The default value for selection bias is 1.
+.endlist
+
+Proxies from the list are tried according to their priority
+and weight settings until one responds. The timeout for the
+overall connection applies to the set of proxied attempts.
+
+.section Logging SECTproxyLog
+To log the (local) IP of a proxy in the incoming or delivery logline,
+add &"+proxy"& to the &%log_selector%& option.
+This will add a component tagged with &"PRX="& to the line.
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Internationalisation" "CHAPi18n" &&&
+ "Internationalisation""
+.cindex internationalisation "email address"
+.cindex EAI
+.cindex i18n
+.cindex utf8 "mail name handling"
+
+Exim has support for Internationalised mail names.
+To include this it must be built with SUPPORT_I18N and the libidn library.
+Standards supported are RFCs 2060, 5890, 6530 and 6533.
+
+If Exim is built with SUPPORT_I18N_2008 (in addition to SUPPORT_I18N, not
+instead of it) then IDNA2008 is supported; this adds an extra library
+requirement, upon libidn2.
+
+.section "MTA operations" SECTi18nMTA
+.cindex SMTPUTF8 "ESMTP option"
+.cindex "ESMTP extensions" SMTPUTF8
+The main configuration option &%smtputf8_advertise_hosts%& specifies
+a host list. If this matches the sending host and
+accept_8bitmime is true (the default) then the ESMTP option
+SMTPUTF8 will be advertised.
+
+If the sender specifies the SMTPUTF8 option on a MAIL command
+international handling for the message is enabled and
+the expansion variable &$message_smtputf8$& will have value TRUE.
+
+The option &%allow_utf8_domains%& is set to true for this
+message. All DNS lookups are converted to a-label form
+whatever the setting of &%allow_utf8_domains%&
+when Exim is built with SUPPORT_I18N.
+
+Both localparts and domain are maintained as the original
+UTF-8 form internally; any comparison or regular-expression use will
+require appropriate care. Filenames created, eg. by
+the appendfile transport, will have UTF-8 names.
+
+HELO names sent by the smtp transport will have any UTF-8
+components expanded to a-label form,
+and any certificate name checks will be done using the a-label
+form of the name.
+
+.cindex log protocol
+.cindex SMTPUTF8 logging
+.cindex i18n logging
+Log lines and Received-by: header lines will acquire a "utf8"
+prefix on the protocol element, eg. utf8esmtp.
+
+The following expansion operators can be used:
+.code
+${utf8_domain_to_alabel:str}
+${utf8_domain_from_alabel:str}
+${utf8_localpart_to_alabel:str}
+${utf8_localpart_from_alabel:str}
+.endd
+
+.cindex utf8 "address downconversion"
+.cindex i18n "utf8 address downconversion"
+The RCPT ACL
+may use the following modifier:
+.display
+control = utf8_downconvert
+control = utf8_downconvert/<value>
+.endd
+This sets a flag requiring that envelope addresses are converted to
+a-label form before smtp delivery.
+This is usually for use in a Message Submission Agent context,
+but could be used for any message.
+
+If a value is appended it may be:
+.display
+&`1 `& mandatory downconversion
+&`0 `& no downconversion
+&`-1 `& if SMTPUTF8 not supported by destination host
+.endd
+If no value is given, 1 is used.
+
+If mua_wrapper is set, the utf8_downconvert control
+is initially set to -1.
+
+The smtp transport has an option &%utf8_downconvert%&.
+If set it must expand to one of the three values described above,
+or an empty string.
+If non-empty it overrides value previously set
+(due to mua_wrapper or by an ACL control).
+
+
+There is no explicit support for VRFY and EXPN.
+Configurations supporting these should inspect
+&$smtp_command_argument$& for an SMTPUTF8 argument.
+
+There is no support for LMTP on Unix sockets.
+Using the "lmtp" protocol option on an smtp transport,
+for LMTP over TCP, should work as expected.
+
+There is no support for DSN unitext handling,
+and no provision for converting logging from or to UTF-8.
+
+
+
+.section "MDA operations" SECTi18nMDA
+To aid in constructing names suitable for IMAP folders
+the following expansion operator can be used:
+.code
+${imapfolder {<string>} {<sep>} {<specials>}}
+.endd
+
+The string is converted from the charset specified by
+the "headers charset" command (in a filter file)
+or &%headers_charset%& main configuration option (otherwise),
+to the
+modified UTF-7 encoding specified by RFC 2060,
+with the following exception: All occurrences of <sep>
+(which has to be a single character)
+are replaced with periods ("."), and all periods and slashes that are not
+<sep> and are not in the <specials> string are BASE64 encoded.
+
+The third argument can be omitted, defaulting to an empty string.
+The second argument can be omitted, defaulting to "/".
+
+This is the encoding used by Courier for Maildir names on disk, and followed
+by many other IMAP servers.
+
+Examples:
+.display
+&`${imapfolder {Foo/Bar}} `& yields &`Foo.Bar`&
+&`${imapfolder {Foo/Bar}{.}{/}} `& yields &`Foo&&AC8-Bar`&
+&`${imapfolder {Räksmörgås}} `& yields &`R&&AOQ-ksm&&APY-rg&&AOU-s`&
+.endd
+
+Note that the source charset setting is vital, and also that characters
+must be representable in UTF-16.
+
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.chapter "Events" "CHAPevents" &&&
+ "Events"
+.cindex events
+
+The events mechanism in Exim can be used to intercept processing at a number
+of points. It was originally invented to give a way to do customised logging
+actions (for example, to a database) but can also be used to modify some
+processing actions.
+
+Most installations will never need to use Events.
+The support can be left out of a build by defining DISABLE_EVENT=yes
+in &_Local/Makefile_&.
+
+There are two major classes of events: main and transport.
+The main configuration option &%event_action%& controls reception events;
+a transport option &%event_action%& controls delivery events.
+
+Both options are a string which is expanded when the event fires.
+An example might look like:
+.cindex logging custom
+.code
+event_action = ${if eq {msg:delivery}{$event_name} \
+{${lookup pgsql {SELECT * FROM record_Delivery( \
+ '${quote_pgsql:$sender_address_domain}',\
+ '${quote_pgsql:${lc:$sender_address_local_part}}', \
+ '${quote_pgsql:$domain}', \
+ '${quote_pgsql:${lc:$local_part}}', \
+ '${quote_pgsql:$host_address}', \
+ '${quote_pgsql:${lc:$host}}', \
+ '${quote_pgsql:$message_exim_id}')}} \
+} {}}
+.endd
+
+Events have names which correspond to the point in process at which they fire.
+The name is placed in the variable &$event_name$& and the event action
+expansion must check this, as it will be called for every possible event type.
+
+.new
+The current list of events is:
+.wen
+.display
+&`dane:fail after transport `& per connection
+&`msg:complete after main `& per message
+&`msg:defer after transport `& per message per delivery try
+&`msg:delivery after transport `& per recipient
+&`msg:rcpt:host:defer after transport `& per recipient per host
+&`msg:rcpt:defer after transport `& per recipient
+&`msg:host:defer after transport `& per host per delivery try; host errors
+&`msg:fail:delivery after transport `& per recipient
+&`msg:fail:internal after main `& per recipient
+&`tcp:connect before transport `& per connection
+&`tcp:close after transport `& per connection
+&`tls:cert before both `& per certificate in verification chain
+&`smtp:connect after transport `& per connection
+&`smtp:ehlo after transport `& per connection
+.endd
+New event types may be added in future.
+
+The event name is a colon-separated list, defining the type of
+event in a tree of possibilities. It may be used as a list
+or just matched on as a whole. There will be no spaces in the name.
+
+The second column in the table above describes whether the event fires
+before or after the action is associates with. Those which fire before
+can be used to affect that action (more on this below).
+
+The third column in the table above says what section of the configuration
+should define the event action.
+
+An additional variable, &$event_data$&, is filled with information varying
+with the event type:
+.display
+&`dane:fail `& failure reason
+&`msg:defer `& error string
+&`msg:delivery `& smtp confirmation message
+&`msg:fail:internal `& failure reason
+&`msg:fail:delivery `& smtp error message
+&`msg:host:defer `& error string
+&`msg:rcpt:host:defer `& error string
+&`msg:rcpt:defer `& error string
+&`tls:cert `& verification chain depth
+&`smtp:connect `& smtp banner
+&`smtp:ehlo `& smtp ehlo response
+.endd
+
+The :defer events populate one extra variable: &$event_defer_errno$&.
+
+For complex operations an ACL expansion can be used in &%event_action%&
+however due to the multiple contexts that Exim operates in during
+the course of its processing:
+.ilist
+variables set in transport events will not be visible outside that
+transport call
+.next
+acl_m variables in a server context are lost on a new connection,
+and after smtp helo/ehlo/mail/starttls/rset commands
+.endlist
+Using an ACL expansion with the logwrite modifier can be
+a useful way of writing to the main log.
+
+The expansion of the event_action option should normally
+return an empty string. Should it return anything else the
+following will be forced:
+.display
+&`tcp:connect `& do not connect
+&`tls:cert `& refuse verification
+&`smtp:connect `& close connection
+.endd
+All other message types ignore the result string, and
+no other use is made of it.
+
+For a tcp:connect event, if the connection is being made to a proxy
+then the address and port variables will be that of the proxy and not
+the target system.
+
+For tls:cert events, if GnuTLS is in use this will trigger only per
+chain element received on the connection.
+For OpenSSL it will trigger for every chain element including those
+loaded locally.
+
git://git.exim.org / users / heiko / exim.git / blobdiff