Testsuite: Add short help to server
[users/heiko/exim.git] / doc / doc-txt / experimental-spec.txt
index 4bcfecf048e72fdfbb4230e84563b898818d4414..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.
 
 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
 
 (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.)
 
 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 = *
 
   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
  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:
 
 There is an auxilary variable, $event_data, for which the
 content is event_dependent:
@@ -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
 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
 
 
 Redis Lookup
@@ -1084,64 +1086,37 @@ QUIT
 221 mail.example.net closing connection
 
 
 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.
+SOCKS
+------------------------------------------------------------
+Support for proxying outbound SMTP via a Socks 5 proxy
+(RFC 1928) is included if Exim is compiled with
+EXPERIMENTAL_SOCKS defined.
 
 
-A redirect router will always trigger a success DSN if requested and the DSN
-options are not passed any further.
+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.
 
 
-A success DSN always contains the recipient address as submitted by the
-client as required by RFC. Rewritten addresses are never exposed.
+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.
 
 
-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.
+Proxies from the list are tried in order until
+one responds.  The timeout for the overall connection
+applies to the set of proxied attempts.
 
 
-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.
+If events are used, the remote IP/port during a
+tcp:connect event will be that of the proxy.
 
 
 
 
 
 
@@ -1297,6 +1272,104 @@ in combination with EXPERIMENTAL_EVENT), and a new variable
 $tls_out_tlsa_usage (detailed above).
 
 
 $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
 --------------------------------------------------------------
 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------