X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/66ce3fc9291d13fe8a7d4099942b9101aef1c38c..f0a4098c909b11829a143fb558156c1d7e12c3f9:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 7a28d8107..1f5e29511 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -77,6 +77,16 @@ . --- table with four columns. For cases when the option name is given with . --- a space, so that it can be split, a fifth argument is used for the . --- index entry. +. --- Also one for multiple option def headings be grouped in a single +. --- table (but without the split capability). + +.macro otable +.itable all 0 0 4 8* left 6* center 6* center 6* right +.endmacro + +.macro orow +.row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&" +.endmacro .macro option .arg 5 @@ -85,8 +95,19 @@ .arg -5 .oindex "&%$1%&" .endarg -.itable all 0 0 4 8* left 6* center 6* center 6* right -.row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&" +.otable +.orow "$1" "$2" "$3" "$4" +.endtable +.endmacro + +.macro options +.eacharg +.oindex "&%$+1%&" +.endeach 4 +.otable +.eacharg +.orow "$+1" "$+2" "$+3" "$+4" +.endeach 4 .endtable .endmacro @@ -951,7 +972,7 @@ User filters are run as part of the routing process, described below. .cindex "Darwin" .cindex "Cygwin" .cindex "exim_msgdate" -Every message handled by Exim is given a &'message id'& which is sixteen +Every message handled by Exim is given a &'message id'& which is 23 characters long. It is divided into three parts, separated by hyphens, for example &`16VDhn-000000001bo-D342`&. Each part is a sequence of letters and digits, normally encoding numbers in base 62. However, in the Darwin operating @@ -3999,7 +4020,7 @@ user. This option requests Exim to give up trying to deliver the listed messages, including any that are frozen. However, if any of the messages are active, their status is not altered. For non-bounce messages, a delivery error message -is sent to the sender, containing the text &"cancelled by administrator"&. +is sent to the sender. Bounce messages are just discarded. This option can be used only by an admin user. @@ -7328,6 +7349,11 @@ dot-separated components; a key such as &`*fict.example`& in a database file is useless, because the asterisk in a partial matching subject key is always followed by a dot. +When the lookup is done from a string-expansion, +the variables &$1$& and &$2$& contain the wild and non-wild parts of the key +during the expansion of the replacement text. +They return to their previous values at the end of the lookup item. + @@ -7384,7 +7410,7 @@ For example, the way to write the NIS+ query is .endd .cindex "tainted data" "in lookups" .new -&*All*& tainted data used in a quoery-style lookup must be quoted +&*All*& tainted data used in a query-style lookup must be quoted using a mechanism appropriate for the lookup type. .wen See chapter &<>& for full coverage of string expansions. The quote @@ -10673,6 +10699,7 @@ shell must be invoked directly, such as with: .code ${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}} .endd +Note that &$value$& will not persist beyond the reception of a single message. .vindex "&$runrc$&" The return code from the command is put in the variable &$runrc$&, and this @@ -11802,10 +11829,11 @@ all items in the list, the overall condition is true. .endlist Note that negation of &*forany*& means that the condition must be false for all items for the overall condition to succeed, and negation of &*forall*& means -that the condition must be false for at least one item. In this example, the -list separator is changed to a comma: +that the condition must be false for at least one item. + +Example: .code -${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}} +${if forany{$recipients_list}{match{$item}{^user3@}}{yes}{no}} .endd The value of &$item$& is saved and restored while &%forany%& or &%forall%& is being processed, to enable these expansion items to be nested. @@ -12060,6 +12088,10 @@ Exim was built with the EXPAND_LISTMATCH_RHS option. Consult section &<>& for further details of these patterns. +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. +Any previous &$value$& is restored after the if. + .vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& .cindex "domain list" "in expansion condition" .cindex "address list" "in expansion condition" @@ -13404,10 +13436,20 @@ The main use of this variable is expected to be to distinguish between rejections of MAIL and rejections of RCPT. .tvar &$recipients$& -This variable contains a list of envelope recipients for a message. A comma and -a space separate the addresses in the replacement text. However, the variable -is not generally available, to prevent exposure of Bcc recipients in -unprivileged users' filter files. You can use &$recipients$& only in these +.new +.tvar &$recipients_list$& +These variables both contain the envelope recipients for a message. + +The first uses a comma and a space separate the addresses in the replacement text. +&*Note*&: an address can legitimately contain a comma; +this variable is not intended for further processing. + +The second is a proper Exim list; colon-separated. +.wen + +However, the variables +are not generally available, to prevent exposure of Bcc recipients in +unprivileged users' filter files. You can use either of them only in these cases: .olist @@ -15444,11 +15486,8 @@ $primary_hostname-$tod_epoch-testing See section &<>& for details of how this value is used. -.option check_log_inodes main integer 100 -See &%check_spool_space%& below. - - -.option check_log_space main integer 10M +.options check_log_inodes main integer 100 &&& + check_log_space main integer 10M See &%check_spool_space%& below. .oindex "&%check_rfc2047_length%&" @@ -15463,11 +15502,8 @@ of the RFC, generates overlong encoded words. If &%check_rfc2047_length%& is set false, Exim recognizes encoded words of any length. -.option check_spool_inodes main integer 100 -See &%check_spool_space%& below. - - -.option check_spool_space main integer 10M +.options check_spool_inodes main integer 100 &&& + check_spool_space main integer 10M .cindex "checking disk space" .cindex "disk space, checking" .cindex "spool directory" "checking space" @@ -15546,17 +15582,15 @@ This option specifies one or more default SMTP ports on which the Exim daemon listens. See chapter &<>& for details of how it is used. For backward compatibility, &%daemon_smtp_port%& (singular) is a synonym. -.option daemon_startup_retries main integer 9 +.options daemon_startup_retries main integer 9 &&& + daemon_startup_sleep main time 30s .cindex "daemon startup, retrying" -This option, along with &%daemon_startup_sleep%&, controls the retrying done by +These options control the retrying done by the daemon at startup when it cannot immediately bind a listening socket (typically because the socket is already in use): &%daemon_startup_retries%& defines the number of retries after the first failure, and &%daemon_startup_sleep%& defines the length of time to wait between retries. -.option daemon_startup_sleep main time 30s -See &%daemon_startup_retries%&. - .option delay_warning main "time list" 24h .cindex "warning of delay" .cindex "delay warning, specifying" @@ -16080,7 +16114,8 @@ log. If you configure freezing in a filter or ACL, you must arrange for any logging that you require. -.option gecos_name main string&!! unset +.options gecos_name main string&!! unset &&& + gecos_pattern main string unset .cindex "HP-UX" .cindex "&""gecos""& field, parsing" Some operating systems, notably HP-UX, use the &"gecos"& field in the system @@ -16105,9 +16140,6 @@ gecos_pattern = ([^,]*) gecos_name = $1 .endd -.option gecos_pattern main string unset -See &%gecos_name%& above. - .option gnutls_compat_mode main boolean unset This option controls whether GnuTLS is used in compatibility mode in an Exim @@ -16411,7 +16443,8 @@ dealing with other kinds of frozen message, see &%auto_thaw%& and &%timeout_frozen_after%&. -.option ignore_fromline_hosts main "host list&!!" unset +.options ignore_fromline_hosts main "host list&!!" unset &&& + ignore_fromline_local main boolean false .cindex "&""From""& line" .cindex "UUCP" "&""From""& line" Some broken SMTP clients insist on sending a UUCP-like &"From&~"& line before @@ -16423,8 +16456,6 @@ process rather than a remote host, and is using &%-bs%& to inject the messages, &%ignore_fromline_local%& must be set to achieve this effect. -.option ignore_fromline_local main boolean false -See &%ignore_fromline_hosts%& above. .option keep_environment main "string list" unset .cindex "environment" "values from" @@ -16579,7 +16610,8 @@ has more details about &'Sender:'& processing. -.option local_from_prefix main string unset +.options local_from_prefix main string unset &&& + local_from_suffix main string unset When Exim checks the &'From:'& header line of locally submitted messages for matching the login id (see &%local_from_check%& above), it can be configured to ignore certain prefixes and suffixes in the local part of the address. This is @@ -16599,10 +16631,6 @@ matches the actual sender address that is constructed from the login name and qualify domain. -.option local_from_suffix main string unset -See &%local_from_prefix%& above. - - .option local_interfaces main "string list" "see below" This option controls which network interfaces are used by the daemon for listening; they are also used to identify the local host when routing. Chapter @@ -17042,16 +17070,11 @@ a good idea to reject recipient addresses with percent characters in their local parts. Exim's default configuration does this. -.option perl_at_start main boolean false +.options perl_at_start main boolean false &&& + perl_startup main string unset .cindex "Perl" -This option is available only when Exim is built with an embedded Perl -interpreter. See chapter &<>& for details of its use. - - -.option perl_startup main string unset -.cindex "Perl" -This option is available only when Exim is built with an embedded Perl -interpreter. See chapter &<>& for details of its use. +These options are available only when Exim is built with an embedded Perl +interpreter. See chapter &<>& for details of their use. .option perl_taintmode main boolean false .cindex "Perl" @@ -17263,7 +17286,7 @@ and &%-odi%& command line options override &%queue_only%& unless &%queue_only_load%&, and &%smtp_accept_queue%&. -.option queue_only_file main string unset +.option queue_only_file main "string list" unset .cindex "queueing incoming messages" .cindex "message" "queueing by file existence" This option can be set to a colon-separated list of absolute path names, each @@ -17946,7 +17969,9 @@ non-SMTP command lines are sent first. -.option smtp_ratelimit_hosts main "host list&!!" unset +.options smtp_ratelimit_hosts main "host list&!!" unset &&& + smtp_ratelimit_mail main string unset &&& + smtp_ratelimit_rcpt main string unset .cindex "SMTP" "rate limiting" .cindex "limit" "rate of message arrival" .cindex "RCPT" "rate limiting" @@ -17989,13 +18014,6 @@ seconds, increasing by a factor of 1.05 each time. The second setting applies delays to RCPT commands when more than four occur in a single message. -.option smtp_ratelimit_mail main string unset -See &%smtp_ratelimit_hosts%& above. - - -.option smtp_ratelimit_rcpt main string unset -See &%smtp_ratelimit_hosts%& above. - .option smtp_receive_timeout main time&!! 5m .cindex "timeout" "for SMTP input" @@ -18396,7 +18414,7 @@ is not required the &%tls_advertise_hosts%& option should be set empty. .cindex ALPN "set acceptable names for server" If this option is set, the TLS library supports ALPN, -and the client offers either more than +and the client offers either more than one ALPN name or a name which does not match the list, the TLS connection is declined. @@ -19167,12 +19185,25 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence. .cindex "router" "restricting to specific domains" .vindex "&$domain_data$&" 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 +the list. +The data returned by the list check +is placed in &$domain_data$& for use in string expansions of the driver's private options and in the transport. See section &<>& for a list of the order in which preconditions are evaluated. +A complex example, using a file like: +.code +alice@dom1 +bill@dom1 +maggie@dom1 +.endd +and checking both domain and local_part +.code +domains = ${domain:${lookup {$local_part@$domain} lseach,ret=key {/path/to/accountsfile}}} +local_parts = ${local_part:${lookup {$local_part@$domain} lseach,ret=key {/path/to/accountsfile}}} +.endd + .option driver routers string unset @@ -19536,7 +19567,7 @@ example: 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 +the data returned by the list check for the local part is placed in the variable &$local_part_data$& for use in expansions of the router's private options or in the transport. You might use this option, for @@ -29666,10 +29697,10 @@ A HUP signal is sufficient for this. The value &"system"& results in no caching under GnuTLS. The macro _HAVE_TLS_CA_CACHE will be defined if the suffix for "system" -is acceptable in configurations for the Exim executavble. +is acceptable in configurations for the Exim executable. Caching of the system Certificate Authorities bundle can -save siginificant time and processing on every TLS connection +save significant time and processing on every TLS connection accepted by Exim. @@ -29839,10 +29870,10 @@ A HUP signal is sufficient for this. The value &"system"& results in no caching under GnuTLS. The macro _HAVE_TLS_CA_CACHE will be defined if the suffix for "system" -is acceptable in configurations for the Exim executavble. +is acceptable in configurations for the Exim executable. Caching of the system Certificate Authorities bundle can -save siginificant time and processing on every TLS connection +save significant time and processing on every TLS connection initiated by Exim. @@ -32211,7 +32242,7 @@ If multiple header lines match, all are removed. There is no harm in attempting to remove the same header twice nor in removing a non-existent header. Further header specifiers for removal may be accumulated during the DATA and MIME ACLs, after which matching headers are removed -if present. In the case of non-SMTP messages, remove speifiers are +if present. In the case of non-SMTP messages, remove specifiers are accumulated during the non-SMTP ACLs, and are acted on after all the ACLs have run. If a message is rejected after DATA or by the non-SMTP ACL, there really is no effect because there is no logging of what headers @@ -38956,6 +38987,7 @@ the following table: .display &`A `& authenticator name (and optional id and sender) &`C `& SMTP confirmation on delivery +&`Ci `& connection identifier &` `& command list for &"no mail in SMTP session"& &`CV `& certificate verification status &`D `& duration of &"no mail in SMTP session"& @@ -39058,6 +39090,7 @@ selection marked by asterisks: .irow &`address_rewrite`&   "address rewriting" .irow &`all_parents`&   "all parents in => lines" .irow &`arguments`&   "command line arguments" +.irow &`connection_id`&   "connection identifier" .irow &`connection_reject`& * "connection rejections" .irow &`delay_delivery`& * "immediate delivery delayed" .irow &`deliver_time`&   "time taken to attempt delivery" @@ -39153,6 +39186,14 @@ because the arguments are checked before the configuration file is read. The only way to log such cases is to interpose a script such as &_util/logargs.sh_& between the caller and Exim. .next +.cindex "log" "connection identifier" +.new +&%connection_identifier%&: An identifier for the accepted connection is added to +connection start and end lines and to message accept lines. +The identifier is tagged by Ci=. +The value is PID-based, so will reset on reboot and will wrap. +.wen +.next .cindex "log" "connection rejections" &%connection_reject%&: A log entry is written whenever an incoming SMTP connection is rejected, for whatever reason. @@ -40083,6 +40124,8 @@ Serializing delivery to a specific host (when &%serialize_hosts%& is set in an .next Limiting the concurrency of specific transports (when &%max_parallel%& is set in a transport) +.next +Recording EHLO-time facilities advertised by hosts .endlist @@ -41984,7 +42027,7 @@ option. .endlist -In addition, two ACL conditions are provided: +In addition, two ACL conditions are provided, usable only in a DKIM ACL: .vlist .vitem &%dkim_signers%& @@ -42252,18 +42295,30 @@ encoding operation. If this value is empty the the expansion result will be empty. The third argument should be the recipient domain of the message when it arrived at this system. +All arguments are expanded before use. + +The result of the expansion is the replacement envelope-from (return path) +to be used. .endlist .cindex SRS decoding To decode an address use this expansion condition: .vlist .vitem &*inbound_srs&~{*&<&'local&~part'&>&*}{*&<&'secret'&>&*}*& -The first argument should be the recipient local prt as is was received. +The first argument should be the recipient local part as it was received. The second argument is the site secret. +Both arguments are expanded before use. If the messages is not for an SRS-encoded recipient the condition will -return false. If it is, the condition will return true and the variable +return false. +If it is, the condition will return true and the variable &$srs_recipient$& will be set to the decoded (original) value. + +.new +If the second argument is empty then the condition returns true if +the first argument is in valid SRS formet, else false. +The variable &$srs_recipient$& is not set for this case. +.wen .endlist Example usage: