Docs: clarify notes on Events
[exim.git] / doc / doc-txt / experimental-spec.txt
index faa64df68685d133acf8e2ea4999c8d7bda10dcd..f0c6d95ba70699ea71f5c1fe508c780b9de5ca39 100644 (file)
@@ -623,10 +623,10 @@ exim will send these forensic emails.  It's also advised that you
 configure a dmarc_forensic_sender because the default sender address
 construction might be inadequate.
 
-  control = dmarc_forensic_enable
+  control = dmarc_enable_forensic
 
 (AGAIN: You can choose not to send these forensic reports by simply
-not putting the dmarc_forensic_enable control line at any point in
+not putting the dmarc_enable_forensic control line at any point in
 your exim config.  If you don't tell it to send them, it will not
 send them.)
 
@@ -755,7 +755,7 @@ b. Configure, somewhere before the DATA ACL, the control option to
 
   deny    dmarc_status   = reject
           !authenticated = *
-          message        = Message from $domain_used_domain failed sender's DMARC policy, REJECT
+          message        = Message from $dmarc_used_domain failed sender's DMARC policy, REJECT
 
 
 
@@ -795,8 +795,10 @@ expansion is done.  The current list of events is:
  smtp:connect          after  transport  per connection
 
 The expansion is called for all event types, and should use the $event_name
-value to decide when to act.  The variable data is a colon-separated
-list, describing an event tree.
+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.
+
 
 There is an auxilary variable, $event_data, for which the
 content is event_dependent:
@@ -821,7 +823,7 @@ The following variables are likely to be useful depending on the event type:
 
 An example might look like:
 
-event_action = ${if = {msg:delivery}{$event_name} \
+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}}', \
@@ -855,7 +857,7 @@ No other use is made of the result string.
 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 thse loaded locally.
+  chain including those loaded locally.
 
 
 Redis Lookup
@@ -1084,82 +1086,39 @@ QUIT
 221 mail.example.net closing connection
 
 
-DSN Support
---------------------------------------------------------------
-
-DSN Support tries to add RFC 3461 support to Exim. It adds support for
-*) the additional parameters for MAIL FROM and RCPT TO
-*) RFC complient MIME DSN messages for all of
-   success, failure and delay notifications
-*) dsn_advertise_hosts main option to select which hosts are able
-   to use the extension
-*) dsn_lasthop router switch to end DSN processing
-
-In case of failure reports this means that the last three parts, the message body
-intro, size info and final text, of the defined template are ignored since there is no
-logical place to put them in the MIME message.
-
-All the other changes are made without changing any defaults
-
-Building exim:
---------------
-
-Define
-EXPERIMENTAL_DSN=YES
-in your Local/Makefile.
-
-Configuration:
---------------
-All DSNs are sent in MIME format if you built exim with EXPERIMENTAL_DSN=YES
-No option needed to activate it, and no way to turn it off.
-
-Failure and delay DSNs are triggered as usual except a sender used NOTIFY=...
-to prevent them.
-
-Support for Success DSNs is added and activated by NOTIFY=SUCCESS by clients.
-
-Add
-dsn_advertise_hosts = *
-or a more restrictive host_list to announce DSN in EHLO answers
 
-Those hosts can then use NOTIFY,ENVID,RET,ORCPT options.
 
-If a message is relayed to a DSN aware host without changing the envelope
-recipient the options are passed along and no success DSN is generated.
-
-A redirect router will always trigger a success DSN if requested and the DSN
-options are not passed any further.
-
-A success DSN always contains the recipient address as submitted by the
-client as required by RFC. Rewritten addresses are never exposed.
+SOCKS
+------------------------------------------------------------
+Support for proxying outbound SMTP via a Socks 5 proxy
+(RFC 1928) is included if Exim is compiled with
+EXPERIMENTAL_SOCKS defined.
 
-If you used DSN patch up to 1.3 before remove all "dsn_process" switches from
-your routers since you don't need them anymore. There is no way to "gag"
-success DSNs anymore. Announcing DSN means answering as requested.
+If an smtp transport has a nonempty socks_proxy option
+defined, this is active.  The option is expanded and
+should 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.
 
-You can prevent Exim from passing DSN options along to other DSN aware hosts by defining
-dsn_lasthop
-in a router. Exim will then send the success DSN himself if requested as if
-the next hop does not support DSN.
-Adding it to a redirect router makes no difference.
+Options are a string <name>=<value>.
+These options are currently defined:
+- "auth", with possible values "none" and "name".
+  Using "name" selects username/password authentication
+  per RFC 1929. Default is "none".
+- "name" sets the authentication username. Default is empty.
+- "pass" sets the authentication password. Default is empty.
+- "port" sets the tcp port number for the proxy. Default is 1080.
+- "tmo" sets a connection timeout in seconds for this proxy. Default is 5.
 
+Proxies from the list are tried in order until
+one responds.  The timeout for the overall connection
+applies to the set of proxied attempts.
 
-Certificate name checking
---------------------------------------------------------------
-The X509 certificates used for TLS are supposed be verified
-that they are owned by the expected host.  The coding of TLS
-support to date has not made these checks.
+If events are used, the remote IP/port during a
+tcp:connect event will be that of the proxy.
 
-If built with EXPERIMENTAL_CERTNAMES defined, code is
-included to do so, and a new smtp transport option
-"tls_verify_cert_hostname" supported which takes a list of
-names for which the checks must be made.  The host must
-also be in "tls_verify_hosts".
 
-Both Subject and Subject-Alternate-Name certificate fields
-are supported, as are wildcard certificates (limited to
-a single wildcard being the initial component of a 3-or-more
-component FQDN).
 
 
 DANE
@@ -1283,12 +1242,13 @@ 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.
-If the TLSA lookup succeeds, a TLS connection will be required
-for the host.
+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)
 
-If dane is in use the following transport options are ignored:
+If DANE is requested and useable (see above) the following transport
+options are ignored:
   hosts_require_tls
   tls_verify_hosts
   tls_try_verify_hosts
@@ -1296,6 +1256,10 @@ If dane is in use the following transport options are ignored:
   tls_crl
   tls_verify_cert_hostnames
 
+If DANE is not usable, whether requested or not, and CA-anchored
+verification evaluation is wanted, the above variables should be set
+appropriately.
+
 Currently dnssec_request_domains must be active (need to think about that)
 and dnssec_require_domains is ignored.
 
@@ -1304,10 +1268,108 @@ in the delivery log line will show as "CV=dane".
 
 There is a new variable $tls_out_dane which will have "yes" if
 verification succeeded using DANE and "no" otherwise (only useful
-in combination with EXPERIMENTAL_TPDA), and a new variable
+in combination with EXPERIMENTAL_EVENT), and a new variable
 $tls_out_tlsa_usage (detailed above).
 
 
+
+INTERNATIONAL
+------------------------------------------------------------
+SMTPUTF8
+Internationalised mail name handling.
+RFCs 6530, 6533, 5890
+
+Compile with EXPERIMENTAL_INTERNATIONAL and libidn.
+
+New main config option smtputf8_advertise_hosts, default '*',
+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.
+
+Both localparts and domain are maintained as the original
+utf8 form internally; any matching or regex use will
+require appropriate care.  Filenames created, eg. by
+the appendfile transport, will have utf8 name.
+
+Helo names sent by the smtp transport will have any utf8
+components expanded to a-label form.
+
+Any certificate name checks will be done using the a-label
+form of the name.
+
+Log lines and Received-by: header lines will aquire a "utf8"
+prefix on the protocol element, eg. utf8esmtp.
+
+New expansion operators:
+       ${utf8_domain_to_alabel:str}
+       ${utf8_domain_from_alabel:str}
+       ${utf8_localpart_to_alabel:str}
+       ${utf8_localpart_from_alabel:str}
+
+New "control = utf8_downconvert" ACL modifier,
+sets a flag requiring that addresses are converted to
+a-label form before smtp delivery, for use in a
+Message Submission Agent context.  Can also be
+phrased as "control = utf8_downconvert/1" and is
+mandatory.  The flag defaults to zero and can be cleared
+by "control = utf8_downconvert/0".  The value "-1"
+may also be used, to use a-label for only if the
+destination host does not support SMTPUTF8.
+
+If mua_wrapper is set, the utf8_downconvert control
+defaults to -1 (convert if needed).
+
+
+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.
+
+Known issues:
+ - DSN unitext handling is not present
+ - no provision for converting logging from or to UTF-8
+
+----
+IMAP folder names
+
+New expansion operator:
+
+${imapfolder {<string>} {<sep>} {<specials>}}
+
+The string is converted from the charset specified by the headers charset 
+command (in a filter file) or headers_charset global option, to the
+modified UTF-7 encoding specified by RFC 2060, with the following
+exception: All occurences of <sep> (which has to be a single character)
+are replaced with periods ("."), and all periods and slashes that aren't
+<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.
+
+   Example 1: ${imapfolder {Foo/Bar}}       yields "Foo.Bar".
+   Example 2: ${imapfolder {Foo/Bar}{.}{/}} yields "Foo&AC8-Bar".
+   Example 3: ${imapfolder {Räksmörgås}}    yields "R&AOQ-ksm&APY-rg&AOU-s".
+
+Note that the source charset setting is vital, and also that characters
+must be representable in UTF-16.
+
+
+
+
 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------