Fix the PIPE_CONNECT feature control in the template Makefile, the

[users/heiko/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 31c8c5653a573fdc9dc2cd82cd317bd6696955be..302a62312ecc2f10d03d17ddb41109bf51f7229a 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1394,9 +1394,22 @@ Again, cutthrough delivery counts as a verification.
 .next
 Individual routers can be explicitly skipped when running the routers to
 check an address given in the SMTP EXPN command (see the &%expn%& option).
 .next
 Individual routers can be explicitly skipped when running the routers to
 check an address given in the SMTP EXPN command (see the &%expn%& option).

+

 .next
 If the &%domains%& option is set, the domain of the address must be in the set
 of domains that it defines.
 .next
 If the &%domains%& option is set, the domain of the address must be in the set
 of domains that it defines.

+.new
+.cindex "tainted data" "de-tainting"
+A match verifies the variable &$domain$& (which carries tainted data)
+and assigns an untainted value to the &$domain_data$& variable.
+Such an untainted value is often needed in the transport.
+For specifics of the matching operation and the resulting untainted value,
+refer to section &<<SECTdomainlist>>&.
+
+When an untainted value is wanted, use this option
+rather than the generic &%condition%& option.
+.wen
+

 .next
 .vindex "&$local_part_prefix$&"
 .vindex "&$local_part_prefix_v$&"
 .next
 .vindex "&$local_part_prefix$&"
 .vindex "&$local_part_prefix_v$&"


@@ -1405,13 +1418,26 @@ of domains that it defines.
 .vindex "&$local_part_suffix_v$&"
 .cindex affix "router precondition"
 If the &%local_parts%& option is set, the local part of the address must be in
 .vindex "&$local_part_suffix_v$&"
 .cindex affix "router precondition"
 If the &%local_parts%& option is set, the local part of the address must be in

-the set of local parts that it defines. If &%local_part_prefix%& or
+the set of local parts that it defines.
+.new
+A match verifies the variable &$local_part$& (which carries tainted data)
+and assigns an untainted value to the &$local_part_data$& variable.
+Such an untainted value is often needed in the transport.
+For specifics of the matching operation and the resulting untainted value,
+refer to section &<<SECTlocparlis>>&.
+
+When an untainted value is wanted, use this option
+rather than the generic &%condition%& option.
+.wen
+
+If &%local_part_prefix%& or

 &%local_part_suffix%& is in use, the prefix or suffix is removed from the local
 part before this check. If you want to do precondition tests on local parts
 that include affixes, you can do so by using a &%condition%& option (see below)
 that uses the variables &$local_part$&, &$local_part_prefix$&,
 &$local_part_prefix_v$&, &$local_part_suffix$&
 and &$local_part_suffix_v$& as necessary.
 &%local_part_suffix%& is in use, the prefix or suffix is removed from the local
 part before this check. If you want to do precondition tests on local parts
 that include affixes, you can do so by using a &%condition%& option (see below)
 that uses the variables &$local_part$&, &$local_part_prefix$&,
 &$local_part_prefix_v$&, &$local_part_suffix$&
 and &$local_part_suffix_v$& as necessary.

+

 .next
 .vindex "&$local_user_uid$&"
 .vindex "&$local_user_gid$&"
 .next
 .vindex "&$local_user_uid$&"
 .vindex "&$local_user_gid$&"


@@ -1421,23 +1447,37 @@ an account on the local host. If this check succeeds, the uid and gid of the
 local user are placed in &$local_user_uid$& and &$local_user_gid$& and the
 user's home directory is placed in &$home$&; these values can be used in the
 remaining preconditions.
 local user are placed in &$local_user_uid$& and &$local_user_gid$& and the
 user's home directory is placed in &$home$&; these values can be used in the
 remaining preconditions.

+

 .next
 If the &%router_home_directory%& option is set, it is expanded at this point,
 because it overrides the value of &$home$&. If this expansion were left till
 later, the value of &$home$& as set by &%check_local_user%& would be used in
 subsequent tests. Having two different values of &$home$& in the same router
 could lead to confusion.
 .next
 If the &%router_home_directory%& option is set, it is expanded at this point,
 because it overrides the value of &$home$&. If this expansion were left till
 later, the value of &$home$& as set by &%check_local_user%& would be used in
 subsequent tests. Having two different values of &$home$& in the same router
 could lead to confusion.

+

 .next
 If the &%senders%& option is set, the envelope sender address must be in the
 set of addresses that it defines.
 .next
 If the &%senders%& option is set, the envelope sender address must be in the
 set of addresses that it defines.

+

 .next
 If the &%require_files%& option is set, the existence or non-existence of
 specified files is tested.
 .next
 If the &%require_files%& option is set, the existence or non-existence of
 specified files is tested.

+

 .next
 .cindex "customizing" "precondition"
 If the &%condition%& option is set, it is evaluated and tested. This option
 uses an expanded string to allow you to set up your own custom preconditions.
 Expanded strings are described in chapter &<<CHAPexpand>>&.
 .next
 .cindex "customizing" "precondition"
 If the &%condition%& option is set, it is evaluated and tested. This option
 uses an expanded string to allow you to set up your own custom preconditions.
 Expanded strings are described in chapter &<<CHAPexpand>>&.

+
+.new
+Note that while using
+this option for address matching technically works,
+it does not set any de-tainted values.
+Such values are often needed, either for router-specific options or
+for transport options.
+Using the &%domains%& and &%local_parts%& options is usually the most
+convenient way to obtain them.
+.wen

 .endlist
 
 
 .endlist
 
 


@@ -8428,7 +8468,10 @@ will store a result in the &$host_data$& variable.
 A &%local_parts%& router option or &%local_parts%& ACL condition
 will store a result in the &$local_part_data$& variable.
 .vitem domains
 A &%local_parts%& router option or &%local_parts%& ACL condition
 will store a result in the &$local_part_data$& variable.
 .vitem domains

+.new

 A &%domains%& router option or &%domains%& ACL condition
 A &%domains%& router option or &%domains%& ACL condition

+will store a result in the &$domain_data$& variable
+.wen

 .vitem senders
 A &%senders%& router option or &%senders%& ACL condition
 will store a result in the &$sender_data$& variable.
 .vitem senders
 A &%senders%& router option or &%senders%& ACL condition
 will store a result in the &$sender_data$& variable.


@@ -9513,7 +9556,9 @@ reasons,
 .cindex "tainted data" definition
 .cindex expansion "tainted data"
 and expansion of data deriving from the sender (&"tainted data"&)
 .cindex "tainted data" definition
 .cindex expansion "tainted data"
 and expansion of data deriving from the sender (&"tainted data"&)

-is not permitted.
+.new
+is not permitted (including acessing a file using a tainted name).
+.wen

 
 .new
 Common ways of obtaining untainted equivalents of variables with
 
 .new
 Common ways of obtaining untainted equivalents of variables with


@@ -10102,7 +10147,7 @@ newline at the very end. For the &%header%& and &%bheader%& expansion, for
 those headers that contain lists of addresses, a comma is also inserted at the
 junctions between headers. This does not happen for the &%rheader%& expansion.
 
 those headers that contain lists of addresses, a comma is also inserted at the
 junctions between headers. This does not happen for the &%rheader%& expansion.
 

-.cindex "tainted data"
+.cindex "tainted data" "message headers"

 When the headers are from an incoming message,
 the result of expanding any of these variables is tainted.
 
 When the headers are from an incoming message,
 the result of expanding any of these variables is tainted.
 


@@ -13658,7 +13703,11 @@ filter file to set values that can be tested in users' filter files. For
 example, a system filter could set a value indicating how likely it is that a
 message is junk mail.
 
 example, a system filter could set a value indicating how likely it is that a
 message is junk mail.
 

-.vitem &$spam_$&&'xxx'&
+.vitem &$spam_score$& &&&
+       &$spam_score_int$& &&&
+       &$spam_bar$& &&&
+       &$spam_report$& &&&
+       &$spam_action$&

 A number of variables whose names start with &$spam$& are available when Exim
 is compiled with the content-scanning extension. For details, see section
 &<<SECTscanspamass>>&.
 A number of variables whose names start with &$spam$& are available when Exim
 is compiled with the content-scanning extension. For details, see section
 &<<SECTscanspamass>>&.


@@ -14048,6 +14097,10 @@ taint mode of the Perl interpreter. You are encouraged to set this
 option to a true value. To avoid breaking existing installations, it
 defaults to false.
 
 option to a true value. To avoid breaking existing installations, it
 defaults to false.
 

+.new
+&*Note*&: This is entirely separate from Exim's tainted-data tracking.
+.wen
+

 
 .section "Calling Perl subroutines" "SECID86"
 When the configuration file includes a &%perl_startup%& option you can make use
 
 .section "Calling Perl subroutines" "SECID86"
 When the configuration file includes a &%perl_startup%& option you can make use


@@ -16928,7 +16981,7 @@ not count as protocol errors (see &%smtp_max_synprot_errors%&).
 .option pipelining_connect_advertise_hosts main "host list&!!" *
 .cindex "pipelining" "early connection"
 .cindex "pipelining" PIPE_CONNECT
 .option pipelining_connect_advertise_hosts main "host list&!!" *
 .cindex "pipelining" "early connection"
 .cindex "pipelining" PIPE_CONNECT

-.cindex "ESMTP extensions" X_PIPE_CONNECT
+.cindex "ESMTP extensions" PIPE_CONNECT

 If Exim is built with the SUPPORT_PIPE_CONNECT build option
 this option controls which hosts the facility is advertised to
 and from which pipeline early-connection (before MAIL) SMTP
 If Exim is built with the SUPPORT_PIPE_CONNECT build option
 this option controls which hosts the facility is advertised to
 and from which pipeline early-connection (before MAIL) SMTP


@@ -16937,7 +16990,9 @@ When used, the pipelining saves on roundtrip times.
 
 See also the &%hosts_pipe_connect%& smtp transport option.
 
 
 See also the &%hosts_pipe_connect%& smtp transport option.
 

-Currently the option name &"X_PIPE_CONNECT"& is used.
+.new
+The SMTP service extension keyword advertised is &"PIPE_CONNECT"&.
+.wen

 
 
 .option prdr_enable main boolean false
 
 
 .option prdr_enable main boolean false


@@ -18489,7 +18544,9 @@ than the public cert of individual clients.  With both OpenSSL and GnuTLS, if
 the value is a file then the certificates are sent by Exim as a server to
 connecting clients, defining the list of accepted certificate authorities.
 Thus the values defined should be considered public data.  To avoid this,
 the value is a file then the certificates are sent by Exim as a server to
 connecting clients, defining the list of accepted certificate authorities.
 Thus the values defined should be considered public data.  To avoid this,

-use the explicit directory version.
+use the explicit directory version. (If your peer is Exim up to 4.85,
+using GnuTLS, you may need to send the CAs (thus using the file
+variant). Otherwise the peer doesn't send its certificate.)

 
 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
 
 
 See &<<SECTtlssni>>& for discussion of when this option might be re-expanded.
 


@@ -18808,7 +18865,10 @@ address (with affixes removed if relevant) is the name of an account on the
 local system. The check is done by calling the &[getpwnam()]& function rather
 than trying to read &_/etc/passwd_& directly. This means that other methods of
 holding password data (such as NIS) are supported. If the local part is a local
 local system. The check is done by calling the &[getpwnam()]& function rather
 than trying to read &_/etc/passwd_& directly. This means that other methods of
 holding password data (such as NIS) are supported. If the local part is a local

-user, &$home$& is set from the password data, and can be tested in other
+user,
+.cindex "tainted data" "de-tainting"
+&$local_part_data$& is set to an untainted version of the local part and
+&$home$& is set from the password data. The latter can be tested in other

 preconditions that are evaluated after this one (the order of evaluation is
 given in section &<<SECTrouprecon>>&). However, the value of &$home$& can be
 overridden by &%router_home_directory%&. If the local part is not a local user,
 preconditions that are evaluated after this one (the order of evaluation is
 given in section &<<SECTrouprecon>>&). However, the value of &$home$& can be
 overridden by &%router_home_directory%&. If the local part is not a local user,


@@ -18955,7 +19015,8 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence.
 If this option is set, the router is skipped unless the current domain matches
 the list. If the match is achieved by means of a file lookup, the data that the
 lookup returned for the domain is placed in &$domain_data$& for use in string
 If this option is set, the router is skipped unless the current domain matches
 the list. If the match is achieved by means of a file lookup, the data that the
 lookup returned for the domain is placed in &$domain_data$& for use in string

-expansions of the driver's private options. See section &<<SECTrouprecon>>& for
+expansions of the driver's private options and in the transport.
+See section &<<SECTrouprecon>>& for

 a list of the order in which preconditions are evaluated.
 
 
 a list of the order in which preconditions are evaluated.
 
 


@@ -19318,12 +19379,13 @@ section &<<SECTlocparlis>>& for a discussion of local part lists. Because the
 string is expanded, it is possible to make it depend on the domain, for
 example:
 .code
 string is expanded, it is possible to make it depend on the domain, for
 example:
 .code

-local_parts = dbm;/usr/local/specials/$domain
+local_parts = dbm;/usr/local/specials/$domain_data

 .endd
 .vindex "&$local_part_data$&"
 If the match is achieved by a lookup, the data that the lookup returned
 for the local part is placed in the variable &$local_part_data$& for use in
 .endd
 .vindex "&$local_part_data$&"
 If the match is achieved by a lookup, the data that the lookup returned
 for the local part is placed in the variable &$local_part_data$& for use in

-expansions of the router's private options. You might use this option, for
+expansions of the router's private options or in the transport.
+You might use this option, for

 example, if you have a large number of local virtual domains, and you want to
 send all postmaster mail to the same place without having to set up an alias in
 each virtual domain:
 example, if you have a large number of local virtual domains, and you want to
 send all postmaster mail to the same place without having to set up an alias in
 each virtual domain:


@@ -19668,6 +19730,10 @@ Values containing a list-separator should have them doubled.
 When a router runs, the strings are evaluated in order,
 to create variables which are added to the set associated with
 the address.
 When a router runs, the strings are evaluated in order,
 to create variables which are added to the set associated with
 the address.

+.new
+This is done immediately after all the preconditions, before the
+evaluation of the &%address_data%& option.
+.wen

 The variable is set with the expansion of the value.
 The variables can be used by the router options
 (not including any preconditions)
 The variable is set with the expansion of the value.
 The variables can be used by the router options
 (not including any preconditions)


@@ -25043,12 +25109,14 @@ authenticated as a client.
 
 
 .option command_timeout smtp time 5m
 
 
 .option command_timeout smtp time 5m

+.cindex timeout "smtp transport command"

 This sets a timeout for receiving a response to an SMTP command that has been
 sent out. It is also used when waiting for the initial banner line from the
 remote host. Its value must not be zero.
 
 
 .option connect_timeout smtp time 5m
 This sets a timeout for receiving a response to an SMTP command that has been
 sent out. It is also used when waiting for the initial banner line from the
 remote host. Its value must not be zero.
 
 
 .option connect_timeout smtp time 5m

+.cindex timeout "smtp transport connect"

 This sets a timeout for the &[connect()]& function, which sets up a TCP/IP call
 to a remote host. A setting of zero allows the system timeout (typically
 several minutes) to act. To have any effect, the value of this option must be
 This sets a timeout for the &[connect()]& function, which sets up a TCP/IP call
 to a remote host. A setting of zero allows the system timeout (typically
 several minutes) to act. To have any effect, the value of this option must be


@@ -25084,6 +25152,7 @@ be treated as unset and &%tls_require_ciphers%& will be used instead.
 
 
 .option data_timeout smtp time 5m
 
 
 .option data_timeout smtp time 5m

+.cindex timeout "for transmitted SMTP data blocks"

 This sets a timeout for the transmission of each block in the data portion of
 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%&.
 This sets a timeout for the transmission of each block in the data portion of
 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%&.


@@ -25222,6 +25291,7 @@ fails"& facility.
 
 
 .option final_timeout smtp time 10m
 
 
 .option final_timeout smtp time 10m

+.cindex timeout "for transmitted SMTP data accept"

 This is the timeout that applies while waiting for the response to the final
 line containing just &"."& that terminates a message. Its value must not be
 zero.
 This is the timeout that applies while waiting for the response to the final
 line containing just &"."& that terminates a message. Its value must not be
 zero.


@@ -25468,9 +25538,12 @@ incoming messages, use an appropriate ACL.
 .cindex "authentication" "optional in client"
 This option provides a list of servers to which, provided they announce
 authentication support, Exim will attempt to authenticate as a client when it
 .cindex "authentication" "optional in client"
 This option provides a list of servers to which, provided they announce
 authentication support, Exim will attempt to authenticate as a client when it

-connects. If authentication fails, Exim will try to transfer the message
-unauthenticated. See also &%hosts_require_auth%&, and chapter
-&<<CHAPSMTPAUTH>>& for details of authentication.
+connects. If authentication fails
+.new
+and &%hosts_require_auth%& permits,
+.wen
+Exim will try to transfer the message unauthenticated.
+See also chapter &<<CHAPSMTPAUTH>>& for details of authentication.

 
 .option hosts_try_chunking smtp "host list&!!" *
 .cindex CHUNKING "enabling, in client"
 
 .option hosts_try_chunking smtp "host list&!!" *
 .cindex CHUNKING "enabling, in client"


@@ -27299,7 +27372,7 @@ conditions:
 .ilist
 The client host must match &%auth_advertise_hosts%& (default *).
 .next
 .ilist
 The client host must match &%auth_advertise_hosts%& (default *).
 .next

-It the &%server_advertise_condition%& option is set, its expansion must not
+If the &%server_advertise_condition%& option is set, its expansion must not

 yield the empty string, &"0"&, &"no"&, or &"false"&.
 .endlist
 
 yield the empty string, &"0"&, &"no"&, or &"false"&.
 .endlist
 


@@ -27407,7 +27480,7 @@ encode '\0user@domain.com\0pas$$word'
 .endd
 gives an incorrect answer because of the unescaped &"@"& and &"$"& characters.
 
 .endd
 gives an incorrect answer because of the unescaped &"@"& and &"$"& characters.
 

-If you have the &%mimencode%& command installed, another way to do produce
+If you have the &%mimencode%& command installed, another way to produce

 base64-encoded strings is to run the command
 .code
 echo -e -n `\0user\0password' | mimencode
 base64-encoded strings is to run the command
 .code
 echo -e -n `\0user\0password' | mimencode


@@ -29308,7 +29381,7 @@ then the associated information is loaded at daemon startup.
 It is made available
 to child processes forked for handling received SMTP connections.
 
 It is made available
 to child processes forked for handling received SMTP connections.
 

-This caching is currently only supported under Linux.
+This caching is currently only supported under Linux and FreeBSD.

 
 If caching is not possible, for example if an item has to be dependent
 on the peer host so contains a &$sender_host_name$& expansion, the load
 
 If caching is not possible, for example if an item has to be dependent
 on the peer host so contains a &$sender_host_name$& expansion, the load


@@ -29320,7 +29393,7 @@ containing files specified by these options.
 The information specified by the main option &%tls_verify_certificates%&
 is similarly cached so long as it specifies files explicitly
 or (under GnuTLS) is the string &"system,cache"&.
 The information specified by the main option &%tls_verify_certificates%&
 is similarly cached so long as it specifies files explicitly
 or (under GnuTLS) is the string &"system,cache"&.

-The latter case is not automatically invaludated;
+The latter case is not automatically invalidated;

 it is the operator's responsibility to arrange for a daemon restart
 any time the system certificate authority bundle is updated.
 A HUP signal is sufficient for this.
 it is the operator's responsibility to arrange for a daemon restart
 any time the system certificate authority bundle is updated.
 A HUP signal is sufficient for this.


@@ -38605,6 +38678,7 @@ routing email addresses, but it does apply to &"byname"& lookups.
 client's ident port times out.
 .next
 .cindex "log" "incoming interface"
 client's ident port times out.
 .next
 .cindex "log" "incoming interface"

+.cindex "log" "outgoing interface"

 .cindex "log" "local interface"
 .cindex "log" "local address and port"
 .cindex "TCP/IP" "logging local address and port"
 .cindex "log" "local interface"
 .cindex "log" "local address and port"
 .cindex "TCP/IP" "logging local address and port"


@@ -38613,7 +38687,10 @@ client's ident port times out.
 to the &"<="& line as an IP address in square brackets, tagged by I= and
 followed by a colon and the port number. The local interface and port are also
 added to other SMTP log lines, for example, &"SMTP connection from"&, to
 to the &"<="& line as an IP address in square brackets, tagged by I= and
 followed by a colon and the port number. The local interface and port are also
 added to other SMTP log lines, for example, &"SMTP connection from"&, to

-rejection lines, and (despite the name) to outgoing &"=>"& and &"->"& lines.
+rejection lines, and (despite the name) to outgoing
+.new
+&"=>"&, &"->"&, &"=="& and &"**"& lines.
+.wen

 The latter can be disabled by turning off the &%outgoing_interface%& option.
 .next
 .cindex log "incoming proxy address"
 The latter can be disabled by turning off the &%outgoing_interface%& option.
 .next
 .cindex log "incoming proxy address"