-$Cambridge: exim/doc/doc-txt/experimental-spec.txt,v 1.12 2009/06/11 14:07:57 tom Exp $
-
From time to time, experimental features may be added to Exim.
While a feature is experimental, there will be a build-time
option whose name starts "EXPERIMENTAL_" that must be set in
order to include the feature. This file contains information
-about experimenatal features, all of which are unstable and
-liable to incompatibile change.
+about experimental features, all of which are unstable and
+liable to incompatible change.
-Brightmail AntiSpam (BMI) suppport
+Brightmail AntiSpam (BMI) support
--------------------------------------------------------------
Brightmail AntiSpam is a commercial package. Please see
1) Adding support for BMI at compile time
To compile with BMI support, you need to link Exim against
- the Brighmail client SDK, consisting of a library
+ the Brightmail client SDK, consisting of a library
(libbmiclient_single.so) and a header file (bmi_api.h).
You'll also need to explicitly set a flag in the Makefile to
include BMI support in the Exim binary. Both can be achieved
-Sender Policy Framework (SPF) support
+DCC Support
--------------------------------------------------------------
+Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/
+
+*) Building exim
+
+In order to build exim with DCC support add
+
+EXPERIMENTAL_DCC=yes
+
+to your Makefile. (Re-)build/install exim. exim -d should show
+EXPERIMENTAL_DCC under "Support for".
+
+
+*) Configuration
+
+In the main section of exim.cf add at least
+ dccifd_address = /usr/local/dcc/var/dccifd
+or
+ dccifd_address = <ip> <port>
+
+In the DATA ACL you can use the new condition
+ dcc = *
+
+After that "$dcc_header" contains the X-DCC-Header.
+
+Return values are:
+ fail for overall "R", "G" from dccifd
+ defer for overall "T" from dccifd
+ accept for overall "A", "S" from dccifd
+
+dcc = */defer_ok works as for spamd.
+
+The "$dcc_result" variable contains the overall result from DCC
+answer. There will an X-DCC: header added to the mail.
+
+Usually you'll use
+ defer !dcc = *
+to greylist with DCC.
+
+If you set, in the main section,
+ dcc_direct_add_header = true
+then the dcc header will be added "in deep" and if the spool
+file was already written it gets removed. This forces Exim to
+write it again if needed. This helps to get the DCC Header
+through to eg. SpamAssassin.
+
+If you want to pass even more headers in the middle of the
+DATA stage you can set
+ $acl_m_dcc_add_header
+to tell the DCC routines to add more information; eg, you might set
+this to some results from ClamAV. Be careful. Header syntax is
+not checked and is added "as is".
+
+In case you've troubles with sites sending the same queue items from several
+hosts and fail to get through greylisting you can use
+$acl_m_dcc_override_client_ip
+
+Setting $acl_m_dcc_override_client_ip to an IP address overrides the default
+of $sender_host_address. eg. use the following ACL in DATA stage:
+
+ warn set acl_m_dcc_override_client_ip = \
+ ${lookup{$sender_helo_name}nwildlsearch{/etc/mail/multipleip_sites}{$value}{}}
+ condition = ${if def:acl_m_dcc_override_client_ip}
+ log_message = dbg: acl_m_dcc_override_client_ip set to \
+ $acl_m_dcc_override_client_ip
+
+Then set something like
+# cat /etc/mail/multipleip_sites
+mout-xforward.gmx.net 82.165.159.12
+mout.gmx.net 212.227.15.16
+
+Use a reasonable IP. eg. one the sending cluster actually uses.
+
+
+
+DSN extra information
+---------------------
+If compiled with EXPERIMENTAL_DSN_INFO extra information will be added
+to DSN fail messages ("bounces"), when available. The intent is to aid
+tracing of specific failing messages, when presented with a "bounce"
+complaint and needing to search logs.
+
+
+The remote MTA IP address, with port number if nonstandard.
+Example:
+ Remote-MTA: X-ip; [127.0.0.1]:587
+Rationale:
+ Several addresses may correspond to the (already available)
+ dns name for the remote MTA.
+
+The remote MTA connect-time greeting.
+Example:
+ X-Remote-MTA-smtp-greeting: X-str; 220 the.local.host.name ESMTP Exim x.yz Tue, 2 Mar 1999 09:44:33 +0000
+Rationale:
+ This string sometimes presents the remote MTA's idea of its
+ own name, and sometimes identifies the MTA software.
+
+The remote MTA response to HELO or EHLO.
+Example:
+ X-Remote-MTA-helo-response: X-str; 250-the.local.host.name Hello localhost [127.0.0.1]
+Limitations:
+ Only the first line of a multiline response is recorded.
+Rationale:
+ This string sometimes presents the remote MTA's view of
+ the peer IP connecting to it.
+
+The reporting MTA detailed diagnostic.
+Example:
+ X-Exim-Diagnostic: X-str; SMTP error from remote mail server after RCPT TO:<d3@myhost.test.ex>: 550 hard error
+Rationale:
+ This string sometimes give extra information over the
+ existing (already available) Diagnostic-Code field.
+
+
+Note that non-RFC-documented field names and data types are used.
+
+
+Queuefile transport
+-------------------
+Queuefile is a pseudo transport which does not perform final delivery.
+It simply copies the exim spool files out of the spool directory into
+an external directory retaining the exim spool format.
+
+The spool files can then be processed by external processes and then
+requeued into exim spool directories for final delivery.
+However, note carefully the warnings in the main documentation on
+qpool file formats.
+
+The motivation/inspiration for the transport is to allow external
+processes to access email queued by exim and have access to all the
+information which would not be available if the messages were delivered
+to the process in the standard email formats.
+
+The mailscanner package is one of the processes that can take advantage
+of this transport to filter email.
+
+The transport can be used in the same way as the other existing transports,
+i.e by configuring a router to route mail to a transport configured with
+the queuefile driver.
+
+The transport only takes one option:
+
+* directory - This is used to specify the directory messages should be
+copied to. Expanded.
+
+The generic transport options (body_only, current_directory, disable_logging,
+debug_print, delivery_date_add, envelope_to_add, event_action, group,
+headers_add, headers_only, headers_remove, headers_rewrite, home_directory,
+initgroups, max_parallel, message_size_limit, rcpt_include_affixes,
+retry_use_local_part, return_path, return_path_add, shadow_condition,
+shadow_transport, transport_filter, transport_filter_timeout, user) are
+ignored.
+
+Sample configuration:
+
+(Router)
+
+scan:
+ driver = accept
+ transport = scan
+
+(Transport)
+
+scan:
+ driver = queuefile
+ directory = /var/spool/baruwa-scanner/input
+
+
+In order to build exim with Queuefile transport support add or uncomment
+
+EXPERIMENTAL_QUEUEFILE=yes
+
+to your Local/Makefile. (Re-)build/install exim. exim -d should show
+Experimental_QUEUEFILE in the line "Support for:".
+
+
+ARC support
+-----------
+Specification: https://tools.ietf.org/html/draft-ietf-dmarc-arc-protocol-11
+Note that this is not an RFC yet, so may change.
-To learn more about SPF, visit http://www.openspf.org. This
-document does not explain the SPF fundamentals, you should
-read and understand the implications of deploying SPF on your
-system before doing so.
-
-SPF support is added via the libspf2 library. Visit
-
- http://www.libspf2.org/
-
-to obtain a copy, then compile and install it. By default,
-this will put headers in /usr/local/include and the static
-library in /usr/local/lib.
-
-To compile Exim with SPF support, set these additional flags in
-Local/Makefile:
-
-EXPERIMENTAL_SPF=yes
-CFLAGS=-DSPF -I/usr/local/include
-EXTRALIBS_EXIM=-L/usr/local/lib -lspf2
-
-This assumes that the libspf2 files are installed in
-their default locations.
-
-You can now run SPF checks in incoming SMTP by using the "spf"
-ACL condition in either the MAIL, RCPT or DATA ACLs. When
-using it in the RCPT ACL, you can make the checks dependend on
-the RCPT address (or domain), so you can check SPF records
-only for certain target domains. This gives you the
-possibility to opt-out certain customers that do not want
-their mail to be subject to SPF checking.
-
-The spf condition takes a list of strings on its right-hand
-side. These strings describe the outcome of the SPF check for
-which the spf condition should succeed. Valid strings are:
-
- o pass The SPF check passed, the sending host
- is positively verified by SPF.
- o fail The SPF check failed, the sending host
- is NOT allowed to send mail for the domain
- in the envelope-from address.
- o softfail The SPF check failed, but the queried
- domain can't absolutely confirm that this
- is a forgery.
- o none The queried domain does not publish SPF
- records.
- o 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.
- o err_perm This indicates a syntax error in the SPF
- record of the queried domain. This should be
- treated like "none".
- o err_temp This indicates a temporary error during all
- processing, including Exim's SPF processing.
- You may defer messages when this occurs.
-
-You can prefix each string with an exclamation mark to invert
-is meaning, for example "!fail" will match all results but
-"fail". The string list is evaluated left-to-right, in a
-short-circuit fashion. When a string matches the outcome of
-the SPF check, the condition succeeds. If none of the listed
-strings matches the outcome of the SPF check, the condition
-fails.
-
-Here is an example to fail forgery attempts from domains that
-publish SPF records:
-
-/* -----------------
-deny 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.openspf.org/Why?scope=${if def:sender_address_domain {mfrom}{helo}};identity=${if def:sender_address_domain {$sender_address}{$sender_helo_name}};ip=$sender_host_address
- spf = fail
---------------------- */
-
-You can also give special treatment to specific domains:
-
-/* -----------------
-deny message = AOL sender, but not from AOL-approved relay.
- sender_domains = aol.com
- spf = fail:neutral
---------------------- */
-
-Explanation: AOL publishes SPF records, but is liberal and
-still allows non-approved relays to send mail from aol.com.
-This will result in a "neutral" state, while mail from genuine
-AOL servers will result in "pass". The example above takes
-this into account and treats "neutral" like "fail", but only
-for aol.com. Please note that this violates the SPF draft.
-
-When the spf condition has run, it sets up several expansion
-variables.
-
- $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.
-
- $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.
-
- $spf_result
- This contains the outcome of the SPF check in string form,
- one of pass, fail, softfail, none, neutral, err_perm or
- err_temp.
-
- $spf_smtp_comment
- This contains a string that can be used in a SMTP response
- to the calling party. Useful for "fail".
-
-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 http://www.openspf.org/FAQ/Best_guess_record
-for a description of what it means.
-
-To access this feature, simply use the spf_guess condition in place
-of the spf one. For example:
-
-/* -----------------
-deny message = $sender_host_address doesn't look trustworthy to me
- spf_guess = fail
---------------------- */
-
-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 standarized, you may redefine
-what "Best-guess" means to you by redefining spf_guess variable in
-global config. For example, the following:
-
-/* -----------------
-spf_guess = v=spf1 a/16 mx/16 ptr ?all
---------------------- */
-
-would relax host matching rules to a broader network range.
-
-
-SRS (Sender Rewriting Scheme) Support
+[RFC 8617 was published 2019/06. Draft 11 was 2018/01. A review of the
+changes has not yet been done]
+
+ARC is intended to support the utility of SPF and DKIM in the presence of
+intermediaries in the transmission path - forwarders and mailinglists -
+by establishing a cryptographically-signed chain in headers.
+
+Normally one would only bother doing ARC-signing when functioning as
+an intermediary. One might do verify for local destinations.
+
+ARC uses the notion of a "ADministrative Management Domain" (ADMD).
+Described in RFC 5598 (section 2.3), this is essentially a set of
+mail-handling systems that mail transits that are all under the control
+of one organisation. A label should be chosen to identify the ADMD.
+Messages should be ARC-verified on entry to the ADMD, and ARC-signed on exit
+from it.
+
+
+Building with ARC Support
+--
+Enable using EXPERIMENTAL_ARC=yes in your Local/Makefile.
+You must also have DKIM present (not disabled), and you very likely
+want to have SPF enabled.
+
+
+Verification
+--
+An ACL condition is provided to perform the "verifier actions" detailed
+in section 6 of the above specification. It may be called from the DATA ACL
+and succeeds if the result matches any of a given list.
+It also records the highest ARC instance number (the chain size)
+and verification result for later use in creating an Authentication-Results:
+standard header.
+
+ verify = arc/<acceptable_list> none:fail:pass
+
+ add_header = :at_start:${authresults {<admd-identifier>}}
+
+ Note that it would be wise to strip incoming messages of A-R headers
+ that claim to be from our own <admd-identifier>. Eg:
+
+ remove_header = \N^(?i)Authentication-Results\s*::\s*example.org;\N
+
+There are four new variables:
+
+ $arc_state One of pass, fail, none
+ $arc_state_reason (if fail, why)
+ $arc_domains colon-sep list of ARC chain domains, in chain order.
+ problematic elements may have empty list elements
+ $arc_oldest_pass lowest passing instance number of chain
+
+Example:
+ logwrite = oldest-p-ams: <${reduce {$lh_ARC-Authentication-Results:} \
+ {} \
+ {${if = {$arc_oldest_pass} \
+ {${extract {i}{${extract {1}{;}{$item}}}}} \
+ {$item} {$value}}} \
+ }>
+
+Receive log lines for an ARC pass will be tagged "ARC".
+
+
+Signing
+--
+arc_sign = <admd-identifier> : <selector> : <privkey> [ : <options> ]
+An option on the smtp transport, which constructs and prepends to the message
+an ARC set of headers. The textually-first Authentication-Results: header
+is used as a basis (you must have added one on entry to the ADMD).
+Expanded as a whole; if unset, empty or forced-failure then no signing is done.
+If it is set, all of the first three elements must be non-empty.
+
+The fourth element is optional, and if present consists of a comma-separated list
+of options. The options implemented are
+
+ timestamps Add a t= tag to the generated AMS and AS headers, with the
+ current time.
+ expire[=<val>] Add an x= tag to the generated AMS header, with an expiry time.
+ If the value <val> is an plain number it is used unchanged.
+ If it starts with a '+' then the following number is added
+ to the current time, as an offset in seconds.
+ If a value is not given it defaults to a one month offset.
+
+[As of writing, gmail insist that a t= tag on the AS is mandatory]
+
+Caveats:
+ * There must be an Authentication-Results header, presumably added by an ACL
+ while receiving the message, for the same ADMD, for arc_sign to succeed.
+ This requires careful coordination between inbound and outbound logic.
+
+ Only one A-R header is taken account of. This is a limitation versus
+ the ARC spec (which says that all A-R headers from within the ADMD must
+ be used).
+
+ * If passing a message to another system, such as a mailing-list manager
+ (MLM), between receipt and sending, be wary of manipulations to headers made
+ by the MLM.
+ + For instance, Mailman with REMOVE_DKIM_HEADERS==3 might improve
+ deliverability in a pre-ARC world, but that option also renames the
+ Authentication-Results header, which breaks signing.
+
+ * Even if you use multiple DKIM keys for different domains, the ARC concept
+ should try to stick to one ADMD, so pick a primary domain and use that for
+ AR headers and outbound signing.
+
+Signing is not compatible with cutthrough delivery; any (before expansion)
+value set for the option will result in cutthrough delivery not being
+used via the transport in question.
+
+
+
+Dovecot authenticator via inet socket
--------------------------------------------------------------
+If Dovecot is configured similar to :-
+
+service auth {
+...
+#SASL
+ inet_listener {
+ name = exim
+ port = 12345
+ }
+...
+}
+
+then an Exim authenticator can be configured :-
+
+ dovecot-plain:
+ driver = dovecot
+ public_name = PLAIN
+ server_socket = dovecot_server_name 12345
+ server_tls = true
+ server_set_id = $auth1
+
+If the server_socket does not start with a / it is taken as a hostname (or IP);
+and a whitespace-separated port number must be given.
+
+
+
+
+Logging protocol unusual states
+---------------------------------------------------------------
+An extra log_selector, "protocol_detail" has been added in the default build.
+The name may change in future, hence the Experimenal status.
+
+Currrently the only effect is to enable logging, under TLS,
+of a TCP RST received directly after a QUIT (in server mode).
+
+Outlook is consistently doing this; not waiting for the SMTP response
+to its QUIT, not properly closing the TLS session and not properly closing
+the TCP connection. Previously this resulted is an error from SSL_write
+being logged.
+
+
+
+Limits ESMTP extension
+---------------------------------------------------------------
+Per https://datatracker.ietf.org/doc/html/draft-freed-smtp-limits-01
+
+If compiled with EXPERIMENTAL_ESMTP_LIMITS=yes :-
+
+As a server, Exim will advertise, in the EHLO response, the limit for RCPT
+commands set by the recipients_max main-section config option (if it is set),
+and the limit for MAIL commands set by the smtp_accept_max_per_connection
+option.
+
+Note that as of writing, smtp_accept_max_per_connection is expanded but
+recipients_max is not.
+
+A new main-section option "limits_advertise_hosts" controls whether
+the limits are advertised; the default for the option is "*".
+
+As a client, Exim will:
+
+ - note an advertised MAILMAX; the lower of the value given and the
+ value from the transport connection_max_messages option is used.
+
+ - note an advertised RCPTMAX; the lower of the
+ value given and the value from the transport max_rcpt option is used.
+ Parallisation of transactions is not done if due to a RCPTMAX, unlike
+ max_rcpt.
+
+ - note an advertised RCPTDOMAINMAX, and behave as if the transport
+ multi_domains option was set to false. The value advertised is ignored.
+
+Values advertised are only noted for TLS connections and ones for which
+the server does not advertise TLS support.
+
-Exiscan currently includes SRS support via Miles Wilton's
-libsrs_alt library. The current version of the supported
-library is 0.5.
-In order to use SRS, you must get a copy of libsrs_alt from
+XCLIENT proxy support
+---------------------------------------------------------------
+Per https://www.postfix.org/XCLIENT_README.html
-http://srs.mirtol.com/
+XCLIENT is an ESMTP extension supporting an inbound proxy.
+The only client immplementation known is in Nginx
+(https://nginx.org/en/docs/mail/ngx_mail_proxy_module.html)
-Unpack the tarball, then refer to MTAs/README.EXIM
-to proceed. You need to set
+If compiled with EXPERIMENTAL_XCLIENT=yes :-
-EXPERIMENTAL_SRS=yes
+As a server, Exim will advertise XCLIENT support (conditional on a new option
+"hosts_xclient") and service XCLIENT commands with parameters
+ ADDR
+ NAME
+ PORT
+ LOGIN
+ DESTADDR
+ DESTPORT
+A fresh HELO/EHLO is required after a succesful XCLIENT, and the usual
+values are derived from that (making the HELO and PROTO paramemters redundant).
-in your Local/Makefile.
+An XCLIENT command must give both ADDR and PORT parameters if no previous
+XCLIENT has succeeded in the SMTP session.
+After a success:
+ $proxy_session variable becomes "yes"
+ $proxy_local_address, $proxy_local_port have the proxy "inside" values
+ $proxy_external_address, $proxy_external_port have the proxy "outside" values
+ $sender_host_address, $sender_host_port have the remot client values
--------------------------------------------------------------
End of file
git://git.exim.org / exim.git / blobdiff