X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/19849de0dd5a6cf2ec8344a8adef9a433d7e7cf1..43ba45ce62100bc1dbc9b04b5d869f59026783f5:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index ff6a115c5..c55dff0af 100644 --- 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 - file = /var/mail/$local_part_verified + file = /var/mail/$local_part_data 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. -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 @@ -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 -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 @@ -6977,9 +6977,10 @@ be followed by optional colons. lookup types support only literal keys. .next +.cindex "spf lookup type" .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 &<>&. .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" @@ -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. + +.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" @@ -8505,7 +8541,14 @@ in square brackets (as in an email address that contains a domain literal), but 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. +In today's Internet, the use of domain literals is controversial; +see the &%allow_domain_literals%& main option. + +.new +The value for a match will be the string &`@[]`&. +.wen + + .next .cindex "@mx_any" .cindex "@mx_primary" @@ -8554,6 +8597,11 @@ involved, it is easiest to change the delimiter for the main list as well: domains = >&) 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). +Additionally, &$0$& will be set to the string matching the regular expression, +and &$1$& (onwards) to any submatches identified by parentheses. +.wen + + + .next .cindex "lookup" "in domain list" .cindex "domain list" "matching by lookup" @@ -8593,12 +8656,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 -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 -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. +.cindex "tainted data" "de-tainting" +The value will be untainted. + .next Any of the single-key lookup type names may be preceded by @@ -8617,6 +8683,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. + .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 +8693,37 @@ chapter &<>&. For example: 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 -&%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. +.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 -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 + .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 + Here is an example that uses several different kinds of pattern: .code domainlist funny_domains = \ @@ -12550,7 +12629,7 @@ 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 -&$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. @@ -12559,26 +12638,6 @@ 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 -.cindex "tainted data" -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 variable values are tainted. - -If the specification did not include a wildcard then -the affix variable value is not tainted. -.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 @@ -12619,44 +12678,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. +.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. -.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 -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 -.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$& @@ -19202,7 +19250,7 @@ but the user is specified symbolically, the gid associated with the uid is 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. @@ -21833,7 +21881,7 @@ local_users: # 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 @@ -22668,7 +22716,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} \ - {/var/mail/$local_part_verified} \ + {/var/mail/$local_part_data} \ {${if eq{${substr_0_1:$address_file}}{/} \ {$address_file} \ {$home/mail/$address_file} \ @@ -22849,8 +22897,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 -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" @@ -23606,7 +23654,7 @@ and directories in a maildir mailbox, including subdirectories for maildir++ 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 = /\.[^/]+$ @@ -24596,14 +24644,14 @@ configuration for &%procmail%&: # 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 - user = $local_part + user = $local_part_data group = mail # router @@ -35158,7 +35206,7 @@ central_filter: 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 @@ -37028,9 +37076,9 @@ another MTA: userforward: driver = redirect check_local_user - file = $home/.forward$local_part_suffix 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