Fix CVE-2016-1531
[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt
index 44623a5502523e90e3594a25656be4e3290709a5..9d2316937f114a9ab538838786acc4b7335e4bb9 100644 (file)
@@ -3151,6 +3151,11 @@ using one of the words &%router_list%&, &%transport_list%&, or
 settings can be obtained by using &%routers%&, &%transports%&, or
 &%authenticators%&.
 
+.cindex "environment"
+If &%environment%& is given as an argument, the set of environment
+variables is output, line by line. Using the &%-n%& flag supresses the value of the
+variables.
+
 .cindex "options" "macro &-- extracting"
 If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%&
 are available, similarly to the drivers.  Because macros are sometimes used
@@ -3482,6 +3487,8 @@ name, but it can be a colon-separated list of names. In this case, the first
 file that exists is used. Failure to open an existing file stops Exim from
 proceeding any further along the list, and an error is generated.
 
+The file names need to be absolute names.
+
 When this option is used by a caller other than root, and the list is different
 from the compiled-in list, Exim gives up its root privilege immediately, and
 runs with the real and effective uid and gid set to those of the caller.
@@ -7739,7 +7746,7 @@ domain, host, address and local part lists.
 
 
 
-.section "Expansion of lists" "SECID75"
+.section "Expansion of lists" "SECTlistexpand"
 .cindex "expansion" "of lists"
 Each list is expanded as a single string before it is used. The result of
 expansion must be a list, possibly containing empty items, which is split up
@@ -9677,7 +9684,8 @@ ${readsocket{inet:[::1]:1234}{request string}}
 Only a single host name may be given, but if looking it up yields more than
 one IP address, they are each tried in turn until a connection is made. For
 both kinds of socket, Exim makes a connection, writes the request string
-(unless it is an empty string) and reads from the socket until an end-of-file
+unless it is an empty string; and no terminating NUL is ever sent)
+and reads from the socket until an end-of-file
 is read. A timeout of 5 seconds is applied. Additional, optional arguments
 extend what can be done. Firstly, you can vary the timeout. For example:
 .code
@@ -13786,6 +13794,7 @@ See also the &'Policy controls'& section above.
 .row &%bounce_message_file%&         "content of bounce"
 .row &%bounce_message_text%&         "content of bounce"
 .row &%bounce_return_body%&          "include body if returning message"
+.row &%bounce_return_linesize_limit%& "limit on returned message line length"
 .row &%bounce_return_message%&       "include original message in bounce"
 .row &%bounce_return_size_limit%&    "limit on returned message"
 .row &%bounce_sender_authentication%& "send authenticated sender with bounce"
@@ -13945,6 +13954,14 @@ received. See chapter &<<CHAPACL>>& for further details.
 This option defines the ACL that is run when an SMTP VRFY command is
 received. See chapter &<<CHAPACL>>& for further details.
 
+.new
+.option add_environment main "string list" empty
+.cindex "environment" "inherited"
+This option allows to set individual environment variables that the
+currently linked libraries and programs in child processes use. The
+default list is empty,
+.wen
+
 .option admin_groups main "string list&!!" unset
 .cindex "admin user"
 This option is expanded just once, at the start of Exim's processing. If the
@@ -14094,6 +14111,24 @@ error that is detected during reception, only those header lines preceding the
 point at which the error was detected are returned.
 .cindex "bounce message" "including original"
 
+.option bounce_return_linesize_limit main integer 998
+.cindex "size" "of bounce lines, limit"
+.cindex "bounce message" "line length limit"
+.cindex "limit" "bounce message line length"
+This option sets a limit in bytes on the line length of messages
+that are returned to senders due to delivery problems,
+when &%bounce_return_message%& is true.
+The default value corresponds to RFC limits.
+If the message being returned has lines longer than this value it is
+treated as if the &%bounce_return_size_limit%& (below) restriction was exceeded.
+
+The option also applies to bounces returned when an error is detected
+during reception of a messsage.
+In this case lines from the original are truncated.
+
+The option does not apply to messages generated by an &(autoreply)& transport.
+
+
 .option bounce_return_message main boolean true
 If this option is set false, none of the original message is included in
 bounce messages generated by Exim. See also &%bounce_return_size_limit%& and
@@ -15014,6 +15049,30 @@ process rather than a remote host, and is using &%-bs%& to inject the messages,
 .option ignore_fromline_local main boolean false
 See &%ignore_fromline_hosts%& above.
 
+.new
+.option keep_environment main "string list" unset
+.cindex "environment" "inherited"
+This option contains a string list of environment variables to keep.
+You have to trust these variables or you have to be sure that
+these variables do not impose any security risk. Keep in mind that
+during the startup phase Exim is running with an effective UID 0 in most
+installations. As the default value is an empty list, the default
+environment for using libraries, running embedded Perl code, or running
+external binaries is empty, and does not not even contain PATH or HOME.
+
+Actually the list is interpreted as a list of patterns
+(&<<SECTlistexpand>>&), except that it is not expanded first.
+
+WARNING: Macro substitution is still done first, so having a macro
+FOO and having FOO_HOME in your &%keep_environment%& option may have
+unexpected results. You may work around this using a regular expression
+that does not match the macro name: ^[F]OO_HOME$.
+
+Current versions of Exim issue a warning during startupif you do not mention
+&%keep_environment%& or &%add_environment%& in your runtime configuration
+file.
+.wen
+
 
 .option keep_malformed main time 4d
 This option specifies the length of time to keep messages whose spool files
@@ -15431,7 +15490,7 @@ harm. This option overrides the &%pipe_as_creator%& option of the &(pipe)&
 transport driver.
 
 
-.option openssl_options main "string list" "+no_sslv2"
+.option openssl_options main "string list" "+no_sslv2 +single_dh_use"
 .cindex "OpenSSL "compatibility options"
 This option allows an administrator to adjust the SSL options applied
 by OpenSSL to connections.  It is given as a space-separated list of items,
@@ -16052,6 +16111,12 @@ it qualifies them only if the message came from a host that matches
 &%sender_unqualified_hosts%&, or if the message was submitted locally (not
 using TCP/IP), and the &%-bnq%& option was not set.
 
+.option set_environment main "string list" empty
+.cindex "environment"
+This option allows to set individual environment variables that the
+currently linked libraries and programs in child processes use. The
+default list is empty,
+
 
 .option slow_lookup_log main integer 0
 .cindex "logging" "slow lookups"
@@ -23398,6 +23463,15 @@ the message. As a result, the overall timeout for a message depends on the size
 of the message. Its value must not be zero. See also &%final_timeout%&.
 
 
+.option dkim_domain smtp string&!! unset
+.option dkim_selector smtp string&!! unset
+.option dkim_private_key smtp string&!! unset
+.option dkim_canon smtp string&!! unset
+.option dkim_strict smtp string&!! unset
+.option dkim_sign_headers smtp string&!! unset
+DKIM signing options.  For details see &<<SECDKIMSIGN>>&.
+
+
 .option delay_after_cutoff smtp boolean true
 This option controls what happens when all remote IP addresses for a given
 domain have been inaccessible for so long that they have passed their retry
@@ -24040,7 +24114,7 @@ and certificate verification fails the TLS connection is closed.
 .option tls_verify_hosts smtp "host list&!!" unset
 .cindex "TLS" "server certificate verification"
 .cindex "certificate" "verification of server"
-This option gives a list of hosts for which. on encrypted connections,
+This option gives a list of hosts for which, on encrypted connections,
 certificate verification must succeed.
 The &%tls_verify_certificates%& option must also be set.
 If both this option and &%tls_try_verify_hosts%& are unset
@@ -28588,6 +28662,14 @@ Note also that headers cannot be
 modified by any of the post-data ACLs (DATA, MIME and DKIM).
 Headers may be modified by routers (subject to the above) and transports.
 
+.new
+All the usual ACLs are called; if one results in the message being
+rejected, all effort spent in delivery (including the costs on
+the ultimate destination) will be wasted.
+Note that in the case of data-time ACLs this includes the entire
+message body.
+.wen
+
 Cutthrough delivery is not supported via transport-filters or when DKIM signing
 of outgoing messages is done, because it sends data to the ultimate destination
 before the entire message has been received from the source.
@@ -34046,13 +34128,20 @@ specific badly-behaved hosts that you have to live with.
 When Exim receives a VRFY or EXPN command on a TCP/IP connection, it
 runs the ACL specified by &%acl_smtp_vrfy%& or &%acl_smtp_expn%& (as
 appropriate) in order to decide whether the command should be accepted or not.
-If no ACL is defined, the command is rejected.
 
+.new
 .cindex "VRFY" "processing"
+When no ACL is defined for VRFY, or if it rejects without
+setting an explicit response code, the command is accepted
+(with a 252 SMTP response code)
+in order to support awkward clients that do a VRFY before every RCPT.
+.wen
 When VRFY is accepted, it runs exactly the same code as when Exim is
-called with the &%-bv%& option.
+called with the &%-bv%& option, and returns 250/451/550
+SMTP response codes.
 
 .cindex "EXPN" "processing"
+If no ACL for EXPN is defined, the command is rejected.
 When EXPN is accepted, a single-level expansion of the address is done.
 EXPN is treated as an &"address test"& (similar to the &%-bt%& option) rather
 than a verification (the &%-bv%& option). If an unqualified local part is given
@@ -35548,7 +35637,7 @@ the following table:
 &`    `&        on &"Completed"& lines: time spent on queue
 &`R   `&        on &`<=`& lines: reference for local bounce
 &`    `&        on &`=>`&  &`**`& and &`==`& lines: router name
-&`S   `&        size of message
+&`S   `&        size of message in bytes
 &`SNI `&        server name indication from TLS client hello
 &`ST  `&        shadow transport name
 &`T   `&        on &`<=`& lines: message subject (topic)
@@ -37979,7 +38068,7 @@ where you accept mail from relay sources (internal hosts or authenticated
 senders).
 
 
-.section "Signing outgoing messages" "SECID513"
+.section "Signing outgoing messages" "SECDKIMSIGN"
 .cindex "DKIM" "signing"
 
 Signing is implemented by setting private options on the SMTP transport.
@@ -37994,7 +38083,7 @@ option is put into the &%$dkim_domain%& expansion variable.
 MANDATORY:
 This sets the key selector string. You can use the &%$dkim_domain%& expansion
 variable to look up a matching selector. The result is put in the expansion
-variable &%$dkim_selector%& which should be used in the &%dkim_private_key%&
+variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
 option along with &%$dkim_domain%&.
 
 .option dkim_private_key smtp string&!! unset