git://git.exim.org / exim.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Transports: pass back next id for continued-transport
[exim.git] / doc / doc-txt / experimental-spec.txt
diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 3beab4b9c9e86d5192a0f3c995e03272d23c68a6..56ee10f828df594bc868fa2499572d8f03017bc0 100644 (file)
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -292,128 +292,6 @@ These four steps are explained in more details below.
 
 
 
 
 
 
-SRS (Sender Rewriting Scheme) Support (using libsrs_alt)
---------------------------------------------------------------
-See also below, for an alternative native support implementation.
-
-Exim  currently  includes SRS  support  via Miles  Wilton's
-libsrs_alt library. The current version of the supported
-library is 0.5, there are reports of 1.0 working.
-
-In order to  use SRS, you  must get a  copy of libsrs_alt from
-
-https://opsec.eu/src/srs/
-
-(not the original source, which has disappeared.)
-
-Unpack the tarball, then refer to MTAs/README.EXIM
-to proceed. You need to set
-
-EXPERIMENTAL_SRS=yes
-
-in your Local/Makefile.
-
-The following main-section options become available:
-       srs_config              string
-       srs_hashlength          int
-       srs_hashmin             int
-       srs_maxage              int
-       srs_secrets             string
-       srs_usehash             bool
-       srs_usetimestamp        bool
-
-The redirect router gains these options (all of type string, unset by default):
-       srs
-       srs_alias
-       srs_condition
-       srs_dbinsert
-       srs_dbselect
-
-The following variables become available:
-       $srs_db_address
-       $srs_db_key
-       $srs_orig_recipient
-       $srs_orig_sender
-       $srs_recipient
-       $srs_status
-
-The predefined feature-macro _HAVE_SRS will be present.
-Additional delivery log line elements, tagged with "SRS=" will show the srs sender.    
-For configuration information see https://github.com/Exim/exim/wiki/SRS .
-
-
-
-
-SRS (Sender Rewriting Scheme) Support (native)
---------------------------------------------------------------
-This is less full-featured than the libsrs_alt version above.
-
-The Exim build needs to be done with this in Local/Makefile:
-EXPERIMENTAL_SRS_NATIVE=yes
-
-The following are provided:
-- an expansion item "srs_encode"
-  This takes three arguments:
-  - a site SRS secret
-  - the return_path
-  - the pre-forwarding domain
-
-- an expansion condition "inbound_srs"
-  This takes two arguments: the local_part to check, and a site SRS secret.
-  If the secret is zero-length, only the pattern of the local_part is checked.
-  The $srs_recipient variable is set as a side-effect.
-
-- an expansion variable $srs_recipient
-  This gets the original return_path encoded in the SRS'd local_part
-
-- predefined macros _HAVE_SRS and _HAVE_NATIVE_SRS
-
-Sample usage:
-
-  #macro
-  SRS_SECRET = <pick something unique for your site for this>
-  
-  #routers
-
-  outbound:
-    driver =    dnslookup
-    # if outbound, and forwarding has been done, use an alternate transport
-    domains =   ! +my_domains
-    transport = ${if eq {$local_part@$domain} \
-                        {$original_local_part@$original_domain} \
-                     {remote_smtp} {remote_forwarded_smtp}}
-  
-  inbound_srs:
-    driver =    redirect
-    senders =   :
-    domains =   +my_domains
-    # detect inbound bounces which are SRS'd, and decode them
-    condition = ${if inbound_srs {$local_part} {SRS_SECRET}}
-    data =      $srs_recipient
-  
-  inbound_srs_failure:
-    driver =    redirect
-    senders =   :
-    domains =   +my_domains
-    # detect inbound bounces which look SRS'd but are invalid
-    condition = ${if inbound_srs {$local_part} {}}
-    allow_fail
-    data =      :fail: Invalid SRS recipient address
-
-  #... further routers here
-
-  
-  # transport; should look like the non-forward outbound
-  # one, plus the max_rcpt and return_path options
-  remote_forwarded_smtp:
-    driver =              smtp
-    # modify the envelope from, for mails that we forward
-    max_rcpt =            1
-    return_path =         ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}}
-
-
-
-
 DCC Support
 --------------------------------------------------------------
 Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/
 DCC Support
 --------------------------------------------------------------
 Distributed Checksum Clearinghouse; http://www.rhyolite.com/dcc/
@@ -532,52 +410,6 @@ Rationale:
 Note that non-RFC-documented field names and data types are used.
 
 
 Note that non-RFC-documented field names and data types are used.
 
 
-LMDB Lookup support
--------------------
-LMDB is an ultra-fast, ultra-compact, crash-proof key-value embedded data store.
-It is modeled loosely on the BerkeleyDB API. You should read about the feature
-set as well as operation modes at https://symas.com/products/lightning-memory-mapped-database/
-
-LMDB single key lookup support is provided by linking to the LMDB C library.
-The current implementation does not support writing to the LMDB database.
-
-Visit https://github.com/LMDB/lmdb to download the library or find it in your
-operating systems package repository.
-
-If building from source, this description assumes that headers will be in
-/usr/local/include, and that the libraries are in /usr/local/lib.
-
-1. In order to build exim with LMDB lookup support add or uncomment
-
-EXPERIMENTAL_LMDB=yes
-
-to your Local/Makefile. (Re-)build/install exim. exim -d should show
-Experimental_LMDB in the line "Support for:".
-
-EXPERIMENTAL_LMDB=yes
-LDFLAGS += -llmdb
-# CFLAGS += -I/usr/local/include
-# LDFLAGS += -L/usr/local/lib
-
-The first line sets the feature to include the correct code, and
-the second line says to link the LMDB libraries into the
-exim binary.  The commented out lines should be uncommented if you
-built LMDB from source and installed in the default location.
-Adjust the paths if you installed them elsewhere, but you do not
-need to uncomment them if an rpm (or you) installed them in the
-package controlled locations (/usr/include and /usr/lib).
-
-2. Create your LMDB files, you can use the mdb_load utility which is
-part of the LMDB distribution our your favourite language bindings.
-
-3. Add the single key lookups to your exim.conf file, example lookups
-are below.
-
-${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}{$value}}
-${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}{$value}fail}
-${lookup{$sender_address_domain}lmdb{/var/lib/baruwa/data/db/relaydomains.mdb}}
-
-
 Queuefile transport
 -------------------
 Queuefile is a pseudo transport which does not perform final delivery.
 Queuefile transport
 -------------------
 Queuefile is a pseudo transport which does not perform final delivery.
@@ -681,7 +513,9 @@ standard header.
   add_header = :at_start:${authresults {<admd-identifier>}}
 
        Note that it would be wise to strip incoming messages of A-R headers
   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>.
+       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:
 
 
 There are four new variables:
 
@@ -750,67 +584,8 @@ used via the transport in question.
 
 
 
 
 
 
-
-TLS Session Resumption
-----------------------
-TLS Session Resumption for TLS 1.2 and TLS 1.3 connections can be used (defined
-in RFC 5077 for 1.2).  The support for this can be included by building with
-EXPERIMENTAL_TLS_RESUME defined.  This requires GnuTLS 3.6.3 or OpenSSL 1.1.1
-(or later).
-
-Session resumption (this is the "stateless" variant) involves the server sending
-a "session ticket" to the client on one connection, which can be stored by the
-client and used for a later session.  The ticket contains sufficient state for
-the server to reconstruct the TLS session, avoiding some expensive crypto
-calculation and one full packet roundtrip time.
-
-Operational cost/benefit:
- The extra data being transmitted costs a minor amount, and the client has
- extra costs in storing and retrieving the data.
-
- In the Exim/Gnutls implementation the extra cost on an initial connection
- which is TLS1.2 over a loopback path is about 6ms on 2017-laptop class hardware.
- The saved cost on a subsequent connection is about 4ms; three or more
- connections become a net win.  On longer network paths, two or more
- connections will have an average lower startup time thanks to the one
- saved packet roundtrip.  TLS1.3 will save the crypto cpu costs but not any
- packet roundtrips.
-
- Since a new hints DB is used, the hints DB maintenance should be updated
- to additionally handle "tls".
-
-Security aspects:
- The session ticket is encrypted, but is obviously an additional security
- vulnarability surface.  An attacker able to decrypt it would have access
- all connections using the resumed session.
- The session ticket encryption key is not committed to storage by the server
- and is rotated regularly (OpenSSL: 1hr, and one previous key is used for
- overlap; GnuTLS 6hr but does not specify any overlap).
- Tickets have limited lifetime (2hr, and new ones issued after 1hr under
- OpenSSL.  GnuTLS 2hr, appears to not do overlap).
-
- There is a question-mark over the security of the Diffie-Helman parameters
- used for session negotiation. TBD.  q-value; cf bug 1895
-
-Observability:
- New log_selector "tls_resumption", appends an asterisk to the tls_cipher "X="
- element.
-
- Variables $tls_{in,out}_resumption have bits 0-4 indicating respectively
- support built, client requested ticket, client offered session,
- server issued ticket, resume used.  A suitable decode list is provided
- in the builtin macro _RESUME_DECODE for ${listextract {}{}}.
-
-Issues:
- In a resumed session:
-  $tls_{in,out}_cipher will have values different to the original (under GnuTLS)
-  $tls_{in,out}_ocsp will be "not requested" or "no response", and
-   hosts_require_ocsp will fail
-
-
-
 Dovecot authenticator via inet socket
 Dovecot authenticator via inet socket
-------------------------------------
+--------------------------------------------------------------
 If Dovecot is configured similar to :-
 
 service auth {
 If Dovecot is configured similar to :-
 
 service auth {
@@ -837,27 +612,52 @@ and a whitespace-separated port number must be given.
 
 
 
 
 
 
-Twophase queue run fast ramp
-----------------------------
-To include this feature, add to Local/Makefile:
-  EXPERIMENTAL_QUEUE_RAMP=yes
 
 
-If the (added for this feature) main-section option "queue_fast_ramp" (boolean)
-is set, and a two-phase ("-qq") queue run finds, during the first phase, a
-suitably large number of message routed for a given host - then (subject to
-the usual queue-runner resource limits) delivery for that host is initiated
-immediately, overlapping with the remainder of the first phase.
+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 Experimental 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.
+
+
+
+XCLIENT proxy support
+---------------------------------------------------------------
+Per https://www.postfix.org/XCLIENT_README.html
+
+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)
+
+If compiled with EXPERIMENTAL_XCLIENT=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).
 
 
-This is incompatible with queue_run_in_order.
+An XCLIENT command must give both ADDR and PORT parameters if no previous
+XCLIENT has succeeded in the SMTP session.
 
 
-The result should be a faster startup of deliveries when a large queue is
-present and reasonable numbers of messages are routed to common hosts; this
-could be a smarthost case, or delivery onto the Internet where a large proportion
-of recipients hapen to be on a Gorilla-sized provider.
+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
 
 
-As usual, the presence of a configuration option is associated with a
-predefined macro, making it possible to write portable configurations.
-For this one, the macro is _OPT_MAIN_QUEUE_FAST_RAMP.
 
 
 
 
 
 
Master Exim source repository