X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/4bb69ec417e3c679b85641d232cb29a64f6a77ee..982854f86c4acc7779b6b65094ba557a9fcd50d6:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 6ad009316..c8f765905 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -8261,12 +8261,21 @@ An option group name for MySQL option files can be specified in square brackets; the default value is &"exim"&. The full syntax of each item in &%mysql_servers%& is: .display -<&'hostname'&>::<&'port'&>(<&'socket name'&>)[<&'option group'&>]/&&& - <&'database'&>/<&'user'&>/<&'password'&> +<&'hostspec'&><&'portspec'&>(<&'socket name'&>)[<&'option group'&>]/&&& + <&'database'&>/<&'user'&>/<&'password'&> .endd Any of the four sub-parts of the first field can be omitted. For normal use on the local host it can be left blank or set to just &"localhost"&. +.new +A &'hostspec'& can be a hostname, an IPv4 address or an IPv6 address. +For the latter, a &'portspec'& is a dot followed by a port number; +for the other two a &'portspec'& is a colon followed by a port number. +.wen + +Note that the default list-separator for the list of servers is a colon so +(unless that is changed) all colons in list items must be doubled. + No database need be supplied &-- but if it is absent here, it must be given in the queries. @@ -8282,6 +8291,10 @@ parameters for the connection. .subsection "Special PostgreSQL features" SECID74 +.new +The &'hostspec'& for PostgreSQL follows the same rules as for MySQL above. +.wen + PostgreSQL lookups can also use Unix domain socket connections to the database. This is usually faster and costs less CPU time than a TCP/IP connection. However it can be used only if the mail server runs on the same machine as the @@ -8428,10 +8441,18 @@ type of match and is given below as the &*value*& information. .section "Expansion of lists" "SECTlistexpand" .cindex "expansion" "of lists" -Each list is expanded as a single string before it is used. +.new +Each list, after any leading change-of-separator specification +(see &<>&) is expanded as a single string, .cindex "tainted data" tracking -&*Note*&: As a result, if any componend was tainted then the -entire result string becomes tainted. +&*Note*&: As a result, if any component was tainted then the +entire expansion result string becomes tainted. + +Splitting out a leading explicit change-of-separator permits +one being safely used on a list that has tainted components +while still detecting the use of a tainted setting. +The latter is not permitted. +.wen &'Exception: the router headers_remove option, where list-item splitting is done before string-expansion.'& @@ -8614,6 +8635,11 @@ domainlist dom2 = !a.b : *.b where &'x.y'& does not match. It's best to avoid negation altogether in referenced lists if you can. +.new +The list item which references a named list (&"+"&) +may not be tainted. +.wen + .cindex "hiding named list values" .cindex "named lists" "hiding value of" Some named list definitions may contain sensitive data, for example, passwords for @@ -8718,6 +8744,9 @@ possible to use the same configuration file on several different hosts that differ only in their names. The value for a match will be the primary host name. +.new +The pattern may not be tainted. +.wen .next @@ -8733,6 +8762,9 @@ In today's Internet, the use of domain literals is controversial; see the &%allow_domain_literals%& main option. The value for a match will be the string &`@[]`&. +.new +The pattern may not be tainted. +.wen .next @@ -8749,6 +8781,10 @@ local host, and the second only when no primary MX target is the local host, but a secondary MX target is. &"Primary"& means an MX record with the lowest preference value &-- there may of course be more than one of them. +.new +The pattern may not be tainted. +.wen + The MX lookup that takes place when matching a pattern of this type is performed with the resolver options for widening names turned off. Thus, for example, a single-component domain will &'not'& be expanded by adding the @@ -9584,6 +9620,12 @@ lower case. However, although independent matches on the domain alone are still performed caselessly, regular expressions that match against an entire address become case-sensitive after &"+caseful"& has been seen. +.new +This string may not be tainted. +To do caseful matching on list elements whic are tainted, +place them in a named list. +.wen + .section "Local part lists" "SECTlocparlis" @@ -9601,6 +9643,12 @@ matching in the local part list, but not elsewhere in the router. If &%caseful_local_part%& is set true in a router, matching in the &%local_parts%& option is case-sensitive from the start. +.new +This string may not be tainted. +To do caseful matching on list elements whic are tainted, +place them in a named list. +.wen + If a local part list is indirected to a file (see section &<>&), comments are handled in the same way as address lists &-- they are recognized only if the # is preceded by white space or the start of the line. @@ -10083,11 +10131,15 @@ leading and trailing quotes are removed from the returned value. .cindex "list" "selecting by condition" .cindex "expansion" "selecting from list by condition" .vindex "&$item$&" -After expansion, <&'string'&> is interpreted as a list, colon-separated by -default, but the separator can be changed in the usual way (&<>&). -For each item -in this list, its value is placed in &$item$&, and then the condition is -evaluated. +.new +<&'string1'&> first has the part after any change-of-list-separator +(see &<>&) expanded, +then the whole is taken as a list. +.wen +The default separator for the list is a colon. + +For each item in this list, +its value is placed in &$item$&, and then the condition is evaluated. Any modification of &$value$& by this evaluation is discarded. If the condition is true, &$item$& is added to the output as an item in a new list; if the condition is false, the item is discarded. The @@ -10351,8 +10403,12 @@ The <&'number'&> argument must consist entirely of decimal digits, apart from an optional leading minus, and leading and trailing white space (which is ignored). -After expansion, <&'string1'&> is interpreted as a list, colon-separated by -default, but the separator can be changed in the usual way (&<>&). +.new +The <&'string1'&> argument, after any leading change-of-separator +(see &<>&), +is expanded and the whole forms the list. +.wen +By default, the list separator is a colon. The first field of the list is numbered one. If the number is negative, the fields are @@ -10452,10 +10508,15 @@ ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ .vitem &*${map{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*& .cindex "expansion" "list creation" .vindex "&$item$&" -After expansion, <&'string1'&> is interpreted as a list, colon-separated by -default, but the separator can be changed in the usual way (&<>&). -For each item -in this list, its value is place in &$item$&, and then <&'string2'&> is +.new +<&'string1'&> first has the part after any change-of-list-separator +(see &<>&) expanded, +then the whole is taken as a list. +.wen +The default separator for the list is a colon. + +For each item in this list, +its value is place in &$item$&, and then <&'string2'&> is expanded and added to the output as an item in a new list. The separator used for the output list is the same as the one used for the input, but a separator setting is not included in the output. For example: @@ -10675,9 +10736,15 @@ locks out the use of this expansion item in filter files. .cindex "list" "reducing to a scalar" .vindex "&$value$&" .vindex "&$item$&" -This operation reduces a list to a single, scalar string. After expansion, -<&'string1'&> is interpreted as a list, colon-separated by default, but the -separator can be changed in the usual way (&<>&). +This operation reduces a list to a single, scalar string. + +.new +<&'string1'&> first has the part after any change-of-list-separator +(see &<>&) expanded, +then the whole is taken as a list. +.wen +The default separator for the list is a colon. + Then <&'string2'&> is expanded and assigned to the &$value$& variable. After this, each item in the <&'string1'&> list is assigned to &$item$&, in turn, and <&'string3'&> is expanded for each of @@ -10834,8 +10901,13 @@ rather than any Unicode-aware character handling. .cindex sorting "a list" .cindex list sorting .cindex expansion "list sorting" -After expansion, <&'string'&> is interpreted as a list, colon-separated by -default, but the separator can be changed in the usual way (&<>&). +.new +<&'string'&> first has the part after any change-of-list-separator +(see &<>&) expanded, +then the whole is taken as a list. +.wen +The default separator for the list is a colon. + The <&'comparator'&> argument is interpreted as the operator of a two-argument expansion condition. The numeric operators plus ge, gt, le, lt (and ~i variants) are supported. @@ -11291,7 +11363,8 @@ All measurement is done in bytes and is not UTF-8 aware. .cindex "list" "item count" .cindex "list" "count of items" .cindex "&%listcount%& expansion item" -The string is interpreted as a list and the number of items is returned. +The part of the string after any leading change-of-separator is expanded, +then the whole is interpreted as a list and the number of items is returned. .vitem &*${listnamed:*&<&'name'&>&*}*&&~and&~&*${listnamed_*&<&'type'&>&*:*&<&'name'&>&*}*& @@ -11912,9 +11985,14 @@ attempt. It is false during any subsequent delivery attempts. .cindex "expansion" "&*forall*& condition" .cindex "expansion" "&*forany*& condition" .vindex "&$item$&" -These conditions iterate over a list. The first argument is expanded to form -the list. By default, the list separator is a colon, but it can be changed by -the normal method (&<>&). +These conditions iterate over a list. +.new +The first argument, after any leading change-of-separator +(see &<>&), +is expanded and the whole forms the list. +.wen +By default, the list separator is a colon. + The second argument is interpreted as a condition that is to be applied to each item in the list in turn. During the interpretation of the condition, the current list item is placed in a variable called &$item$&. @@ -11991,9 +12069,14 @@ SRS decode. See SECT &<>& for details. &*inlisti&~{*&<&'subject'&>&*}{*&<&'list'&>&*}*& .cindex "string" "comparison" .cindex "list" "iterative conditions" -Both strings are expanded; the second string is treated as a list of simple -strings; if the first string is a member of the second, then the condition -is true. +The <&'subject'&> string is expanded. +.new +The <&'list'&> first has any change-of-list-separator ++(see &<>&) retained verbatim, ++then the remainder is expanded. ++.wen +The whole is treated as a list of simple strings; +if the subject string is a member of that list, then the condition is true. For the case-independent &%inlisti%& condition, case is defined per the system C locale. These are simpler to use versions of the more powerful &*forany*& condition. @@ -12186,6 +12269,10 @@ just as easy to use the fact that a lookup is itself a condition, and write: Note that <&'string2'&> is not itself subject to string expansion, unless Exim was built with the EXPAND_LISTMATCH_RHS option. +.new +For the latter case, only the part after any leading +change-of-separator specification is expanded. +.wen Consult section &<>& for further details of these patterns. @@ -12214,9 +12301,10 @@ ${if match_domain{$domain}{+local_domains}{... .endd .cindex "&`+caseful`&" For address lists, the matching starts off caselessly, but the &`+caseful`& -item can be used, as in all address lists, to cause subsequent items to -have their local parts matched casefully. Domains are always matched -caselessly. +item can be used, as in all address lists, to cause subsequent items +(including those of referenced named lists) +to have their local parts matched casefully. +Domains are always matched caselessly. The variable &$value$& will be set for a successful match and can be used in the success clause of an &%if%& expansion item using the condition. @@ -12231,6 +12319,10 @@ Any previous &$value$& is restored after the if. Note that <&'string2'&> is not itself subject to string expansion, unless Exim was built with the EXPAND_LISTMATCH_RHS option. +.new +For the latter case, only the part after any leading +change-of-separator specification is expanded. +.wen &*Note*&: Host lists are &'not'& supported in this way. This is because hosts have two identities: a name and an IP address, and it is not clear @@ -15076,7 +15168,6 @@ See also the &'Policy controls'& section above. connection" .row &%smtp_accept_reserve%& "only reserve hosts if more connections" .row &%smtp_active_hostname%& "host name to use in messages" -.row &%smtp_atrn_command%& "what to run for ATRN" .row &%smtp_banner%& "text for welcome banner" .row &%smtp_check_spool_space%& "from SIZE on MAIL command" .row &%smtp_connect_backlog%& "passed to TCP/IP stack" @@ -19712,8 +19803,8 @@ real_localuser: For security, it would probably be a good idea to restrict the use of this router to locally-generated messages, using a condition such as this: .code - condition = ${if match {$sender_host_address}\ - {\N^(|127\.0\.0\.1)$\N}} + condition = ${if match_ip {$sender_host_address} \ + {<; ; 127.0.0.1 ; ::1}} .endd If both &%local_part_prefix%& and &%local_part_suffix%& are set for a router, @@ -22455,8 +22546,8 @@ real_localuser: For security, it would probably be a good idea to restrict the use of this router to locally-generated messages, using a condition such as this: .code - condition = ${if match {$sender_host_address}\ - {\N^(|127\.0\.0\.1)$\N}} + condition = ${if match_ip {$sender_host_address} \ + {<; ; 127.0.0.1 ; ::1}} .endd @@ -28026,17 +28117,17 @@ Successful authentication sets up information used by the .cindex authentication "failure event, server" If an authenticator is run and does not succeed, -an event (see &<>&) of type "auth:fail" is raised. +an event of type "auth:fail" is raised. While the event is being processed the variables &$sender_host_authenticated$& (with the authenticator name) and &$authenticated_fail_id$& (as set by the authenticator &%server_set_id%& option) will be valid. If the event is serviced and a string is returned then the string will be logged instead of the default log line. -See <> for details on events. +See &<>& for details on events. -.section "Testing server authentication" "SECID169" +.subsection "Testing server authentication" "SECID169" .cindex "authentication" "testing a server" .cindex "AUTH" "testing a server" .cindex "base64 encoding" "creating authentication test data" @@ -28115,12 +28206,12 @@ usual way. .next .cindex authentication "failure event, client" If the response to authentication is a permanent error (5&'xx'& code), -an event (see &<>&) of type "auth:fail" is raised. +an event of type "auth:fail" is raised. While the event is being processed the variable &$sender_host_authenticated$& (with the authenticator name) will be valid. If the event is serviced and a string is returned then the string will be logged. -See <> for details on events. +See &<>& for details on events. .next If the response to authentication is a permanent error (5&'xx'& code), Exim