Docs: list further ways $domain_data &c may be filled in

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 874ef31cf706e4b8b42b20dcb0e6a549be5c7103..9a49373f35616b6ccf089999ae174ee0575945c7 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -8744,8 +8744,13 @@ The value for a match will be the list element string.
 .cindex "tainted data" "de-tainting"
 Note that this is commonly untainted
 (depending on the way the list was created).
+Specifically, explicit text in the configuration file in not tainted.
 This is a useful way of obtaining an untainted equivalent to
 the domain, for later operations.
+
+However if the list (including one-element lists)
+is created by expanding a variable containing tainted data,
+it is tainted and so will the match value be.
 .endlist
 
 
@@ -12472,7 +12477,8 @@ the complete argument of the ETRN command (see section &<<SECTETRN>>&).
 
 .cindex "tainted data"
 If the origin of the data is an incoming message,
-the result of expanding this variable is tainted.
+the result of expanding this variable is tainted and may not
+be further expanded or used as a filename.
 When an untainted version is needed, one should be obtained from
 looking up the value in a local (therefore trusted) database.
 Often &$domain_data$& is usable in this role.
@@ -12480,17 +12486,23 @@ Often &$domain_data$& is usable in this role.
 
 .vitem &$domain_data$&
 .vindex "&$domain_data$&"
-When the &%domains%& option on a router matches a domain by
-means of a lookup, the data read by the lookup is available during the running
-of the router as &$domain_data$&. In addition, if the driver routes the
+When the &%domains%& condition on a router
+.new
+or an ACL
+matches a domain
+against a list, the match value is copied to &$domain_data$&.
+This is an enhancement over previous versions of Exim, when it only
+applied to the data read by a lookup.
+For details on match values see section &<<SECTlistresults>>& et. al.
+.wen
+
+If the router routes the
 address to a transport, the value is available in that transport. If the
 transport is handling multiple addresses, the value from the first address is
 used.
 
-&$domain_data$& is also set when the &%domains%& condition in an ACL matches a
-domain by means of a lookup. The data read by the lookup is available during
-the rest of the ACL statement. In all other situations, this variable expands
-to nothing.
+&$domain_data$& set in an ACL is available during
+the rest of the ACL statement.
 
 .vitem &$exim_gid$&
 .vindex "&$exim_gid$&"
@@ -12672,7 +12684,8 @@ once.
 
 .cindex "tainted data"
 If the origin of the data is an incoming message,
-the result of expanding this variable is tainted.
+the result of expanding this variable is tainted and
+may not be further expanded or used as a filename.
 
 &*Warning*&: the content of this variable is usually provided by a potential
 attacker.
@@ -12722,19 +12735,17 @@ to process local parts in a case-dependent manner in a router, you can set the
 
 .vitem &$local_part_data$&
 .vindex "&$local_part_data$&"
-When the &%local_parts%& option on a router matches a local part by means of a
-lookup, the data read by the lookup is available during the running of the
-router as &$local_part_data$&. In addition, if the driver routes the address
-to a transport, the value is available in that transport. If the transport is
-handling multiple addresses, the value from the first address is used.
+When the &%local_parts%& condition on a router or ACL
+matches a local part list
+.new
+the match value is copied to &$local_part_data$&.
+This is an enhancement over previous versions of Exim, when it only
+applied to the data read by a lookup.
+For details on match values see section &<<SECTlistresults>>& et. al.
+.wen
 
 The &%check_local_user%& router option also sets this variable.
 
-&$local_part_data$& is also set when the &%local_parts%& condition in an ACL
-matches a local part by means of a lookup. The data read by the lookup is
-available during the rest of the ACL statement. In all other situations, this
-variable expands to nothing.
-
 .vindex &$local_part_prefix$& &&&
        &$local_part_prefix_v$& &&&
        &$local_part_suffix$& &&&
@@ -35474,14 +35485,14 @@ address if its delivery failed.
 
 
 .section "Per-address filtering" "SECTperaddfil"
-.vindex "&$domain$&"
-.vindex "&$local_part$&"
+.vindex "&$domain_data$&"
+.vindex "&$local_part_data$&"
 In contrast to the system filter, which is run just once per message for each
 delivery attempt, it is also possible to set up a system-wide filtering
 operation that runs once for each recipient address. In this case, variables
-such as &$local_part$& and &$domain$& can be used, and indeed, the choice of
-filter file could be made dependent on them. This is an example of a router
-which implements such a filter:
+such as &$local_part_data$& and &$domain_data$& can be used,
+and indeed, the choice of filter file could be made dependent on them.
+This is an example of a router which implements such a filter:
 .code
 central_filter:
   check_local_user
@@ -37302,7 +37313,7 @@ follows:
 .code
 my_mailboxes:
   driver = appendfile
-  file = /var/mail/$domain/$local_part_data
+  file = /var/mail/$domain_data/$local_part_data
   user = mail
 .endd
 This uses a directory of mailboxes for each domain. The &%user%& setting is
@@ -37342,7 +37353,7 @@ It runs a user's &_.forward_& file for all local parts of the form
 cases by testing the variable &$local_part_suffix$&. For example:
 .code
 if $local_part_suffix contains -special then
-save /home/$local_part/Mail/special
+save /home/$local_part_data/Mail/special
 endif
 .endd
 If the filter file does not exist, or does not deal with such addresses, they