docs & more debug

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 828b757bb665f8e86dadc4d3ca28889b3fab39aa..a05ad66500c41b18652aac93a40d759523347763 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6381,7 +6381,7 @@ All other options are defaulted.
 .code
 local_delivery:
   driver = appendfile
 .code
 local_delivery:
   driver = appendfile

-  file = /var/mail/$local_part_verified
+  file = /var/mail/$local_part_data

   delivery_date_add
   envelope_to_add
   return_path_add
   delivery_date_add
   envelope_to_add
   return_path_add


@@ -6394,7 +6394,7 @@ traditional BSD mailbox format.
 .new
 We prefer to avoid using &$local_part$& directly to define the mailbox filename,
 as it is provided by a potential bad actor.
 .new
 We prefer to avoid using &$local_part$& directly to define the mailbox filename,
 as it is provided by a potential bad actor.

-Instead we use &$local_part_verified$&,
+Instead we use &$local_part_data$&,

 the result of looking up &$local_part$& in the user database
 (done by using &%check_local_user%& in the the router).
 .wen
 the result of looking up &$local_part$& in the user database
 (done by using &%check_local_user%& in the the router).
 .wen


@@ -6853,7 +6853,7 @@ If a selector is numeric, it must apply to a JSON array; the (zero-based)
 nunbered array element is selected.
 Otherwise it must apply to a JSON object; the named element is selected.
 The final resulting element can be a simple JSON type or a JSON object
 nunbered array element is selected.
 Otherwise it must apply to a JSON object; the named element is selected.
 The final resulting element can be a simple JSON type or a JSON object

-or array; for the latter two a string-representation os the JSON
+or array; for the latter two a string-representation of the JSON

 is returned.
 For elements of type string, the returned value is de-quoted.
 .next
 is returned.
 For elements of type string, the returned value is de-quoted.
 .next


@@ -6977,9 +6977,10 @@ be followed by optional colons.
 lookup types support only literal keys.
 
 .next
 lookup types support only literal keys.
 
 .next

+.cindex "spf lookup type"

 .cindex "lookup" "spf"
 .cindex "lookup" "spf"

-If Exim is built with SPF support, manual lookups can be done
-(as opposed to the standard ACL condition method.
+&(spf)&: If Exim is built with SPF support, manual lookups can be done
+(as opposed to the standard ACL condition method).

 For details see section &<<SECSPF>>&.
 .endlist ilist
 
 For details see section &<<SECSPF>>&.
 .endlist ilist
 


@@ -8334,6 +8335,35 @@ in the previous section. You could also use the &(wildlsearch)& or
 
 
 
 
 
 

+.new
+.section "Results of list checking" SECTlistresults
+The primary result of doing a list check is a truth value.
+In some contexts additional information is stored
+about the list element that matched:
+.vlist
+.vitem hosts
+A &%hosts%& ACL condition
+will store a result in the &$host_data$& variable.
+.vitem local_parts
+A &%local_parts%& router option or &%local_parts%& ACL condition
+will store a result in the &$local_part_data$& variable.
+.vitem domains
+A &%domains%& router option or &%domains%& ACL condition
+.vitem senders
+A &%senders%& router option or &%senders%& ACL condition
+will store a result in the &$sender_data$& variable.
+.vitem recipients
+A &%recipients%& ACL condition
+will store a result in the &$recipient_data$& variable.
+.endlist
+
+The detail of the additional information depends on the
+type of match and is given below as the &*value*& information.
+.wen
+
+
+
+

 .section "Named lists" "SECTnamedlists"
 .cindex "named lists"
 .cindex "list" "named"
 .section "Named lists" "SECTnamedlists"
 .cindex "named lists"
 .cindex "list" "named"


@@ -8496,6 +8526,12 @@ If a pattern consists of a single @ character, it matches the local host name,
 as set by the &%primary_hostname%& option (or defaulted). This makes it
 possible to use the same configuration file on several different hosts that
 differ only in their names.
 as set by the &%primary_hostname%& option (or defaulted). This makes it
 possible to use the same configuration file on several different hosts that
 differ only in their names.

+
+.new
+The value for a match will be the primary host name/
+.wen
+
+

 .next
 .cindex "@[] in a domain list"
 .cindex "domain list" "matching local IP interfaces"
 .next
 .cindex "@[] in a domain list"
 .cindex "domain list" "matching local IP interfaces"


@@ -8506,6 +8542,12 @@ only if that IP address is recognized as local for email routing purposes. The
 &%local_interfaces%& and &%extra_local_interfaces%& options can be used to
 control which of a host's several IP addresses are treated as local.
 In today's Internet, the use of domain literals is controversial.
 &%local_interfaces%& and &%extra_local_interfaces%& options can be used to
 control which of a host's several IP addresses are treated as local.
 In today's Internet, the use of domain literals is controversial.

+
+.new
+The value for a match will be the &`@[]`& string.
+.wen
+
+

 .next
 .cindex "@mx_any"
 .cindex "@mx_primary"
 .next
 .cindex "@mx_any"
 .cindex "@mx_primary"


@@ -8554,6 +8596,11 @@ involved, it is easiest to change the delimiter for the main list as well:
 domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
           an.other.domain ? ...
 .endd
 domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
           an.other.domain ? ...
 .endd

+.new
+The value for a match will be the list element string (starting &`@mx_`&).
+.wen
+
+

 .next
 .cindex "asterisk" "in domain list"
 .cindex "domain list" "asterisk in"
 .next
 .cindex "asterisk" "in domain list"
 .cindex "domain list" "asterisk in"


@@ -8566,6 +8613,10 @@ matching works only in terms of dot-separated components. For example, a domain
 list item such as &`*key.ex`& matches &'donkey.ex'& as well as
 &'cipher.key.ex'&.
 
 list item such as &`*key.ex`& matches &'donkey.ex'& as well as
 &'cipher.key.ex'&.
 

+.new
+The value for a match will be the list element string (starting with the asterisk).
+.wen
+

 .next
 .cindex "regular expressions" "in domain list"
 .cindex "domain list" "matching regular expression"
 .next
 .cindex "regular expressions" "in domain list"
 .cindex "domain list" "matching regular expression"


@@ -8582,6 +8633,13 @@ must escape any backslash and dollar characters in the regular expression, or
 use the special &`\N`& sequence (see chapter &<<CHAPexpand>>&) to specify that
 it is not to be expanded (unless you really do want to build a regular
 expression by expansion, of course).
 use the special &`\N`& sequence (see chapter &<<CHAPexpand>>&) to specify that
 it is not to be expanded (unless you really do want to build a regular
 expression by expansion, of course).

+
+.new
+The value for a match will be the list element string (starting with the circumflex).
+.wen
+
+
+

 .next
 .cindex "lookup" "in domain list"
 .cindex "domain list" "matching by lookup"
 .next
 .cindex "lookup" "in domain list"
 .cindex "domain list" "matching by lookup"


@@ -8593,12 +8651,15 @@ must be a filename in a suitable format for the lookup type. For example, for
 domains = cdb;/etc/mail/local_domains.cdb
 .endd
 The appropriate type of lookup is done on the file using the domain name as the
 domains = cdb;/etc/mail/local_domains.cdb
 .endd
 The appropriate type of lookup is done on the file using the domain name as the

-key. In most cases, the data that is looked up is not used; Exim is interested
+key. In most cases, the value resulting from the lookup is not used; Exim is interested

 only in whether or not the key is present in the file. However, when a lookup
 is used for the &%domains%& option on a router
 only in whether or not the key is present in the file. However, when a lookup
 is used for the &%domains%& option on a router

-or a &%domains%& condition in an ACL statement, the data is preserved in the
+or a &%domains%& condition in an ACL statement, the value is preserved in the

 &$domain_data$& variable and can be referred to in other router options or
 other statements in the same ACL.
 &$domain_data$& variable and can be referred to in other router options or
 other statements in the same ACL.

+.cindex "tainted data" "de-tainting"
+The value will be untainted.
+

 
 .next
 Any of the single-key lookup type names may be preceded by
 
 .next
 Any of the single-key lookup type names may be preceded by


@@ -8617,6 +8678,7 @@ original lookup fails. This is not a useful feature when using a domain list to
 select particular domains (because any domain would match), but it might have
 value if the result of the lookup is being used via the &$domain_data$&
 expansion variable.
 select particular domains (because any domain would match), but it might have
 value if the result of the lookup is being used via the &$domain_data$&
 expansion variable.

+

 .next
 If the pattern starts with the name of a query-style lookup type followed by a
 semicolon (for example, &"nisplus;"& or &"ldap;"&), the remainder of the
 .next
 If the pattern starts with the name of a query-style lookup type followed by a
 semicolon (for example, &"nisplus;"& or &"ldap;"&), the remainder of the


@@ -8626,25 +8688,37 @@ chapter &<<CHAPfdlookup>>&. For example:
 hold_domains = mysql;select domain from holdlist \
   where domain = '${quote_mysql:$domain}';
 .endd
 hold_domains = mysql;select domain from holdlist \
   where domain = '${quote_mysql:$domain}';
 .endd

-In most cases, the data that is looked up is not used (so for an SQL query, for
+In most cases, the value resulting from the lookup is not used (so for an SQL query, for

 example, it doesn't matter what field you select). Exim is interested only in
 whether or not the query succeeds. However, when a lookup is used for the
 example, it doesn't matter what field you select). Exim is interested only in
 whether or not the query succeeds. However, when a lookup is used for the

-&%domains%& option on a router, the data is preserved in the &$domain_data$&
+&%domains%& option on a router, the value is preserved in the &$domain_data$&

 variable and can be referred to in other options.
 variable and can be referred to in other options.

+.cindex "tainted data" "de-tainting"
+The value will be untainted.
+

 .next
 .new
 If the pattern starts with the name of a lookup type
 of either kind (single-key or query-style) it may be
 .next
 .new
 If the pattern starts with the name of a lookup type
 of either kind (single-key or query-style) it may be

-followed by a command and options,
+followed by a comma and options,

 The options are lookup-type specific and consist of a comma-separated list.
 Each item starts with a tag and and equals "=".
 .wen
 The options are lookup-type specific and consist of a comma-separated list.
 Each item starts with a tag and and equals "=".
 .wen

+

 .next
 .cindex "domain list" "matching literal domain name"
 If none of the above cases apply, a caseless textual comparison is made
 between the pattern and the domain.
 .next
 .cindex "domain list" "matching literal domain name"
 If none of the above cases apply, a caseless textual comparison is made
 between the pattern and the domain.

+
+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).
+This is a useful way of obtaining an untainted equivalent to
+the domain, for later operations.

 .endlist
 
 .endlist
 

+

 Here is an example that uses several different kinds of pattern:
 .code
 domainlist funny_domains = \
 Here is an example that uses several different kinds of pattern:
 .code
 domainlist funny_domains = \


@@ -12343,7 +12417,7 @@ If the origin of the data is an incoming message,
 the result of expanding this variable is tainted.
 When un untainted version is needed, one should be obtained from
 looking up the value in a local (therefore trusted) database.
 the result of expanding this variable is tainted.
 When un untainted version is needed, one should be obtained from
 looking up the value in a local (therefore trusted) database.

-See also &$domain_data$&.
+Often &$domain_data$& is usable in this role.

 .wen
 
 
 .wen
 
 


@@ -12550,29 +12624,15 @@ Consider carefully the implications of using it unvalidated as a name
 for file access.
 This presents issues for users' &_.forward_& and filter files.
 For traditional full user accounts, use &%check_local_users%& and the
 for file access.
 This presents issues for users' &_.forward_& and filter files.
 For traditional full user accounts, use &%check_local_users%& and the

-&$local_part_verified$& variable rather than this one.
+&$local_part_data$& variable rather than this one.

 For virtual users, store a suitable pathname component in the database
 which is used for account name validation, and use that retrieved value
 rather than this variable.
 For virtual users, store a suitable pathname component in the database
 which is used for account name validation, and use that retrieved value
 rather than this variable.

+Often &$local_part_data$& is usable in this role.

 If needed, use a router &%address_data%& or &%set%& option for
 the retrieved data.
 .wen
 
 If needed, use a router &%address_data%& or &%set%& option for
 the retrieved data.
 .wen
 

-.vindex "&$local_part_prefix$&"
-.vindex "&$local_part_prefix_v$&"
-.vindex "&$local_part_suffix$&"
-.vindex "&$local_part_suffix_v$&"
-.cindex affix variables
-If a local part prefix or suffix has been recognized, it is not included in the
-value of &$local_part$& during routing and subsequent delivery. The values of
-any prefix or suffix are in &$local_part_prefix$& and
-&$local_part_suffix$&, respectively.
-.new
-If the affix specification included a wildcard then the portion of
-the affix matched by the wildcard is in
-&$local_part_prefix_v$& or &$local_part_suffix_v$& as appropriate.
-.wen
-

 When a message is being delivered to a file, pipe, or autoreply transport as a
 result of aliasing or forwarding, &$local_part$& is set to the local part of
 the parent address, not to the filename or command (see &$address_file$& and
 When a message is being delivered to a file, pipe, or autoreply transport as a
 result of aliasing or forwarding, &$local_part$& is set to the local part of
 the parent address, not to the filename or command (see &$address_file$& and


@@ -12613,44 +12673,33 @@ 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.
 
 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.
 

+.new
+The &%check_local_user%& router option also sets this variable.
+.wen
+

 &$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.
 
 &$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.
 

-.vitem &$local_part_prefix$&
-.vindex "&$local_part_prefix$&"
+.vindex &$local_part_prefix$& &&&
+       &$local_part_prefix_v$& &&&
+       &$local_part_suffix$& &&&
+       &$local_part_suffix_v$&

 .cindex affix variables
 .cindex affix variables

-When an address is being routed or delivered, and a
-specific prefix for the local part was recognized, it is available in this
-variable, having been removed from &$local_part$&.
-
-.new
-.vitem &$local_part_prefix_v$&
-.vindex "&$local_part_prefix_v$&"
-When &$local_part_prefix$& is valid and the prefix match used a wildcard,
-the portion matching the wildcard is available in this variable.
-.wen
-
-.vitem &$local_part_suffix$&
-.vindex "&$local_part_suffix$&"
-When an address is being routed or delivered, and a
-specific suffix for the local part was recognized, it is available in this
-variable, having been removed from &$local_part$&.
-
+If a local part prefix or suffix has been recognized, it is not included in the
+value of &$local_part$& during routing and subsequent delivery. The values of
+any prefix or suffix are in &$local_part_prefix$& and
+&$local_part_suffix$&, respectively.

 .new
 .new

-.vitem &$local_part_suffix_v$&
-.vindex "&$local_part_suffix_v$&"
-When &$local_part_suffix$& is valid and the suffix match used a wildcard,
-the portion matching the wildcard is available in this variable.
-.wen
+.cindex "tainted data"
+If the specification did not include a wildcard then
+the affix variable value is not tainted.

 
 

-.new
-.vitem &$local_part_verified$&
-.vindex "&$local_part_verified$&"
-If the router generic option &%check_local_part%& has run successfully,
-this variable has the user database version of &$local_part$&.
-Such values are not tainted and hence usable for building file names.
+If the affix specification included a wildcard then the portion of
+the affix matched by the wildcard is in
+&$local_part_prefix_v$& or &$local_part_suffix_v$& as appropriate,
+and both the whole and varying values are tainted.

 .wen
 
 .vitem &$local_scan_data$&
 .wen
 
 .vitem &$local_scan_data$&


@@ -19196,7 +19245,7 @@ but the user is specified symbolically, the gid associated with the uid is
 used. For example:
 .code
 require_files = mail:/some/file
 used. For example:
 .code
 require_files = mail:/some/file

-require_files = $local_part_verified:$home/.procmailrc
+require_files = $local_part_data:$home/.procmailrc

 .endd
 If a user or group name in a &%require_files%& list does not exist, the
 &%require_files%& condition fails.
 .endd
 If a user or group name in a &%require_files%& list does not exist, the
 &%require_files%& condition fails.


@@ -21827,7 +21876,7 @@ local_users:
 # This transport overrides the group
 group_delivery:
   driver = appendfile
 # This transport overrides the group
 group_delivery:
   driver = appendfile

-  file = /var/spool/mail/$local_part_verified
+  file = /var/spool/mail/$local_part_data

   group = mail
 .endd
 If &%user%& is set for a transport, its value overrides what is set in the
   group = mail
 .endd
 If &%user%& is set for a transport, its value overrides what is set in the


@@ -22662,7 +22711,7 @@ is used as a result of a &"keep"& action in the filter. This example shows one
 way of handling this requirement:
 .code
 file = ${if eq{$address_file}{inbox} \
 way of handling this requirement:
 .code
 file = ${if eq{$address_file}{inbox} \

-            {/var/mail/$local_part_verified} \
+            {/var/mail/$local_part_data} \

             {${if eq{${substr_0_1:$address_file}}{/} \
                   {$address_file} \
                   {$home/mail/$address_file} \
             {${if eq{${substr_0_1:$address_file}}{/} \
                   {$address_file} \
                   {$home/mail/$address_file} \


@@ -22843,8 +22892,8 @@ The string value is expanded for each delivery, and must yield an absolute
 path. The most common settings of this option are variations on one of these
 examples:
 .code
 path. The most common settings of this option are variations on one of these
 examples:
 .code

-file = /var/spool/mail/$local_part_verified
-file = /home/$local_part_verified/inbox
+file = /var/spool/mail/$local_part_data
+file = /home/$local_part_data/inbox

 file = $home/inbox
 .endd
 .cindex "&""sticky""& bit"
 file = $home/inbox
 .endd
 .cindex "&""sticky""& bit"


@@ -23600,7 +23649,7 @@ and directories in a maildir mailbox, including subdirectories for maildir++
 folders. Consider this example:
 .code
 maildir_format = true
 folders. Consider this example:
 .code
 maildir_format = true

-directory = /var/mail/$local_part_verified\
+directory = /var/mail/$local_part_data\

            ${if eq{$local_part_suffix}{}{}\
            {/.${substr_1:$local_part_suffix}}}
 maildirfolder_create_regex = /\.[^/]+$
            ${if eq{$local_part_suffix}{}{}\
            {/.${substr_1:$local_part_suffix}}}
 maildirfolder_create_regex = /\.[^/]+$


@@ -24590,14 +24639,14 @@ configuration for &%procmail%&:
 # transport
 procmail_pipe:
   driver = pipe
 # transport
 procmail_pipe:
   driver = pipe

-  command = /usr/local/bin/procmail -d $local_part
+  command = /usr/local/bin/procmail -d $local_part_data

   return_path_add
   delivery_date_add
   envelope_to_add
   check_string = "From "
   escape_string = ">From "
   umask = 077
   return_path_add
   delivery_date_add
   envelope_to_add
   check_string = "From "
   escape_string = ">From "
   umask = 077

-  user = $local_part
+  user = $local_part_data

   group = mail
 
 # router
   group = mail
 
 # router


@@ -35152,7 +35201,7 @@ central_filter:
   check_local_user
   driver = redirect
   domains = +local_domains
   check_local_user
   driver = redirect
   domains = +local_domains

-  file = /central/filters/$local_part_verified
+  file = /central/filters/$local_part_data

   no_verify
   allow_filter
   allow_freeze
   no_verify
   allow_filter
   allow_freeze


@@ -37022,9 +37071,9 @@ another MTA:
 userforward:
   driver = redirect
   check_local_user
 userforward:
   driver = redirect
   check_local_user

-  file = $home/.forward$local_part_suffix

   local_part_suffix = -*
   local_part_suffix_optional
   local_part_suffix = -*
   local_part_suffix_optional

+  file = ${lookup {.forward$local_part_suffix} dsearch,ret=full {$home} {$value}fail}

   allow_filter
 .endd
 If there is no suffix, &_.forward_& is used; if the suffix is &'-special'&, for
   allow_filter
 .endd
 If there is no suffix, &_.forward_& is used; if the suffix is &'-special'&, for