DANE: fix build under LibreSSL. Bug 2020
[exim.git] / doc / doc-txt / experimental-spec.txt
index aa4cb464d12c40ffe8b45e9b5bdb05b005214d15..2a1901ade14cde281670bc4c28081c4954646eb2 100644 (file)
@@ -6,7 +6,7 @@ about experimental  features, all  of which  are unstable and
 liable to incompatible change.
 
 
 liable to incompatible change.
 
 
-Brightmail AntiSpam (BMI) suppport
+Brightmail AntiSpam (BMI) support
 --------------------------------------------------------------
 
 Brightmail  AntiSpam  is  a  commercial  package.  Please  see
 --------------------------------------------------------------
 
 Brightmail  AntiSpam  is  a  commercial  package.  Please  see
@@ -42,7 +42,7 @@ These four steps are explained in more details below.
 1) Adding support for BMI at compile time
 
   To compile with BMI support,  you need to link Exim  against
 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
   (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
@@ -550,7 +550,7 @@ Then set something like
 mout-xforward.gmx.net           82.165.159.12
 mout.gmx.net                    212.227.15.16
 
 mout-xforward.gmx.net           82.165.159.12
 mout.gmx.net                    212.227.15.16
 
-Use a reasonable IP. eg. one the sending cluster acutally uses.
+Use a reasonable IP. eg. one the sending cluster actually uses.
 
 DMARC Support
 --------------------------------------------------------------
 
 DMARC Support
 --------------------------------------------------------------
@@ -771,208 +771,6 @@ b. Configure, somewhere before the DATA ACL, the control option to
 
 
 
 
 
 
-Event Actions
---------------------------------------------------------------
-
-(Renamed from TPDA, Transport post-delivery actions)
-
-An arbitrary per-transport string can be expanded upon various transport events.
-Additionally a main-section configuration option can be expanded on some
-per-message events.
-This feature may be used, for example, to write exim internal log information
-(not available otherwise) into a database.
-
-In order to use the feature, you must compile with
-
-EXPERIMENTAL_EVENT=yes
-
-in your Local/Makefile
-
-and define one or both of
-- the event_action option in the transport
-- the event_action main option
-to be expanded when the event fires.
-
-A new variable, $event_name, is set to the event type when the
-expansion is done.  The current list of events is:
-
- msg:complete          after  main       per message
- 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 attempt
- msg:fail:delivery     after  main       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
-
-The expansion is called for all event types, and should use the $event_name
-variable to decide when to act.  The value of the variable is a colon-separated
-list, defining a position in the tree of possible events; it may be used as
-a list or just matched on as a whole.  There will be no whitespace.
-
-New event types may be added in the future.
-
-
-There is an auxilary variable, $event_data, for which the
-content is event_dependent:
-
-       msg:delivery            smtp confirmation mssage
-       msg:rcpt:host:defer     error string
-       msg:rcpt:defer          error string
-       msg:host:defer          error string
-       tls:cert                verification chain depth
-       smtp:connect            smtp banner
-
-The :defer events populate one extra variable, $event_defer_errno.
-
-The following variables are likely to be useful depending on the event type:
-
-       router_name, transport_name
-       local_part, domain
-       host, host_address, host_port
-       tls_out_peercert
-       lookup_dnssec_authenticated, tls_out_dane
-       sending_ip_address, sending_port
-       message_exim_id, verify_mode
-
-
-An example might look like:
-
-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}')}} \
-} {}}
-
-The string is expanded when each of the supported events occur
-and any side-effects of the expansion will happen.
-
-Note that for complex operations an ACL expansion can be used,
-however due to the multiple contexts the Exim operates in
-a) variables set in events raised from transports will not
-   be visible outside that transport call.
-b) acl_m variables in a server context are lost on a new connection,
-   and after helo/ehlo/mail/starttls/rset commands
-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:
-
-       msg:delivery    (ignored)
-       msg:host:defer  (ignored)
-       msg:fail:delivery (ignored)
-       tcp:connect     do not connect
-       tcp:close       (ignored)
-       tls:cert        refuse verification
-       smtp:connect    close connection
-
-No other use is made of the result string.
-
-If transport proxying is used, the remote IP/port during a
-tcp:connect event will be that of the proxy.
-
-
-Known issues:
-- the tls:cert event is only called for the cert chain elements
-  received over the wire, with GnuTLS.  OpenSSL gives the entire
-  chain including those loaded locally.
-
-
-Redis Lookup
---------------------------------------------------------------
-
-Redis is open source advanced key-value data store. This document
-does not explain the fundamentals, you should read and understand how
-it works by visiting the website at http://www.redis.io/.
-
-Redis lookup support is added via the hiredis library.  Visit:
-
-  https://github.com/redis/hiredis
-
-to obtain a copy, 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 Redis lookup support add
-
-EXPERIMENTAL_REDIS=yes
-
-to your Local/Makefile. (Re-)build/install exim. exim -d should show
-Experimental_Redis in the line "Support for:".
-
-EXPERIMENTAL_REDIS=yes
-LDFLAGS += -lhiredis
-# 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 hiredis libraries into the
-exim binary.  The commented out lines should be uncommented if you
-built hiredis 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. Use the following global settings to configure Redis lookup support:
-
-Required:
-redis_servers       This option provides a list of Redis servers
-                    and associated connection data, to be used in
-                    conjunction with redis lookups. The option is
-                    only available if Exim is configured with Redis
-                    support.
-
-For example:
-
-redis_servers = 127.0.0.1/10/ - using database 10 with no password
-redis_servers = 127.0.0.1//password - to make use of the default database of 0 with a password
-redis_servers = 127.0.0.1// - for default database of 0 with no password
-
-3. Once you have the Redis servers defined you can then make use of the
-experimental Redis lookup by specifying ${lookup redis{}} in a lookup query.
-
-4. Example usage:
-
-(Host List)
-hostlist relay_from_ips = <\n ${lookup redis{SMEMBERS relay_from_ips}}
-
-Where relay_from_ips is a Redis set which contains entries such as "192.168.0.0/24" "10.0.0.0/8" and so on.
-The result set is returned as
-192.168.0.0/24
-10.0.0.0/8
-..
-.
-
-(Domain list)
-domainlist virtual_domains = ${lookup redis {HGET $domain domain}}
-
-Where $domain is a hash which includes the key 'domain' and the value '$domain'.
-
-(Adding or updating an existing key)
-set acl_c_spammer = ${if eq{${lookup redis{SPAMMER_SET}}}{OK}}
-
-Where SPAMMER_SET is a macro and it is defined as
-
-"SET SPAMMER <some_value>"
-
-(Getting a value from Redis)
-
-set acl_c_spam_host = ${lookup redis{GET...}}
-
-
 DANE
 ------------------------------------------------------------
 DNS-based Authentication of Named Entities, as applied
 DANE
 ------------------------------------------------------------
 DNS-based Authentication of Named Entities, as applied
@@ -1086,18 +884,20 @@ with DANE in their OCSP settings.
 
 
 For client-side DANE there are two new smtp transport options,
 
 
 For client-side DANE there are two new smtp transport options,
-hosts_try_dane and hosts_require_dane.  They do the obvious thing.
+hosts_try_dane and hosts_require_dane.
 [ should they be domain-based rather than host-based? ]
 
 [ should they be domain-based rather than host-based? ]
 
+Hosts_require_dane will result in failure if the target host
+is not DNSSEC-secured.
+
 DANE will only be usable if the target host has DNSSEC-secured
 MX, A and TLSA records.
 
 A TLSA lookup will be done if either of the above options match
 DANE will only be usable if the target host has DNSSEC-secured
 MX, A and TLSA records.
 
 A TLSA lookup will be done if either of the above options match
-and the host-lookup succeded using dnssec.
+and the host-lookup succeeded using dnssec.
 If a TLSA lookup is done and succeeds, a DANE-verified TLS connection
 If a TLSA lookup is done and succeeds, a DANE-verified TLS connection
-will be required for the host.
-
-(TODO: specify when fallback happens vs. when the host is not used)
+will be required for the host.  If it does not, the host will not
+be used; there is no fallback to non-DANE or non-TLS.
 
 If DANE is requested and useable (see above) the following transport
 options are ignored:
 
 If DANE is requested and useable (see above) the following transport
 options are ignored:
@@ -1160,13 +960,114 @@ 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:
 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 somtimes give extra information over the
+  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.
 
 
   existing (already available) Diagnostic-Code field.
 
 
 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.
+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.
+
+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
+
+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:".
 
 
 --------------------------------------------------------------
 
 
 --------------------------------------------------------------