X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/04e5caa9a7e84b2afca642d28096d988cb6802e7..d6a5a05b84595e4cdfe8f73672b4dbec5559e8aa:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index fd2b47f22..a2374b187 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,3 +1,4 @@ + . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is . converted into DocBook XML for subsequent conversion into printable and online @@ -443,10 +444,11 @@ Please do not ask for configuration help in the bug-tracker. The following Exim mailing lists exist: .table2 140pt -.row &'exim-announce@exim.org'& "Moderated, low volume announcements list" -.row &'exim-users@exim.org'& "General discussion list" -.row &'exim-dev@exim.org'& "Discussion of bugs, enhancements, etc." -.row &'exim-cvs@exim.org'& "Automated commit messages from the VCS" +.row &'exim-announce@lists.exim.org'& "Moderated, low volume announcements list" +.row &'exim-users@lists.exim.org'& "General discussion list" +.row &'exim-users-de@lists.exim.org'& "General discussion list in German language" +.row &'exim-dev@lists.exim.org'& "Discussion of bugs, enhancements, etc." +.row &'exim-cvs@lists.exim.org'& "Automated commit messages from the VCS" .endtable You can subscribe to these lists, change your existing subscriptions, and view @@ -948,6 +950,7 @@ User filters are run as part of the routing process, described below. .cindex "base36" .cindex "Darwin" .cindex "Cygwin" +.cindex "exim_msgdate" Every message handled by Exim is given a &'message id'& which is sixteen characters long. It is divided into three parts, separated by hyphens, for example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits, @@ -994,6 +997,10 @@ received by the same process, or by another process with the same (re-used) pid, it is guaranteed that the time will be different. In most cases, the clock will already have ticked while the message was being received. +The exim_msgdate utility (see section &<>&) can be +used to display the date, and optionally the process id, of an Exim +Message ID. + .section "Receiving mail" "SECID13" .cindex "receiving mail" @@ -3266,6 +3273,12 @@ to the standard output. It is restricted to admin users, unless &%queue_list_requires_admin%& is set false. +.cmdopt -bpi +.cindex queue "list of message IDs" +This option operates like &%-bp%&, but only outputs message ids +(one per line). + + .cmdopt -bpr This option operates like &%-bp%&, but the output is not sorted into chronological order of message arrival. This can speed it up when there are @@ -3275,6 +3288,9 @@ going to be post-processed in a way that doesn't need the sorting. .cmdopt -bpra This option is a combination of &%-bpr%& and &%-bpa%&. +.cmdopt -bpri +This option is a combination of &%-bpr%& and &%-bpi%&. + .cmdopt -bpru This option is a combination of &%-bpr%& and &%-bpu%&. @@ -4615,6 +4631,15 @@ combined daemon at system boot time is to use a command such as Such a daemon listens for incoming SMTP calls, and also starts a queue runner process every 30 minutes. +.new +.cindex "named queues" "queue runners" +It is possible to set up runners for multiple named queues within one daemon, +For example: +.code +exim -qGhipri/2m -q10m -qqGmailinglist/1h +.endd +.wen + When a daemon is started by &%-q%& with a time value, but without &%-bd%&, no pid file is written unless one is explicitly requested by the &%-oP%& option. @@ -9938,7 +9963,7 @@ leading and trailing quotes are removed from the returned value. 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 place in &$item$&, and then the condition is +in this list, its value is placed in &$item$&, and then the condition is evaluated. .new Any modification of &$value$& by this evaluation is discarded. @@ -10471,6 +10496,11 @@ Defines whether or not a write-shutdown is done on the connection after sending the request. Values are &"yes"& (the default) or &"no"& (preferred, eg. by some webservers). +.next +&*sni*& +Controls the use of Server Name Identification on the connection. +Any nonempty value will be the SNI sent; TLS will be forced. + .next &*tls*& Controls the use of TLS on the connection. @@ -10558,12 +10588,13 @@ expansion items. This item inserts &"raw"& header lines. It is described with the &%header%& expansion item in section &<>& above. -.vitem "&*${run <&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&& +.vitem "&*${run<&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&& {*&<&'string2'&>&*}}*&" .cindex "expansion" "running a command" .cindex "&%run%& expansion item" This item runs an external command, as a subprocess. -One option is supported after the word &'run'&, comma-separated. +One option is supported after the word &'run'&, comma-separated +and without whitespace. If the option &'preexpand'& is not used, the command string is split into individual arguments by spaces @@ -11045,6 +11076,24 @@ abbreviation &%h%& can be used when &%hash%& is used as an operator. +.new +.vitem &*${headerwrap_*&<&'cols'&>&*_*&<&'limit'&>&*:*&<&'string'&>&*}*& +.cindex header "wrapping operator" +.cindex expansion "header wrapping" +This operator line-wraps its argument in a way useful for headers. +The &'cols'& value gives the column number to wrap after, +the &'limit'& gives a limit number of result characters to truncate at. +Either just the &'limit'& and the preceding underbar, or both, can be omitted; +the defaults are 80 and 998. +Wrapping will be inserted at a space if possible before the +column number is reached. +Whitespace at a chosen wrap point is removed. +A line-wrap consists of a newline followed by a tab, +and the tab is counted as 8 columns. +.wen + + + .vitem &*${hex2b64:*&<&'hexstring'&>&*}*& .cindex "base64 encoding" "conversion from hex" .cindex "expansion" "hex to base64" @@ -13403,7 +13452,8 @@ This is an obsolete name for &$bounce_return_size_limit$&. .cindex "router" "name" .cindex "name" "of router" .vindex "&$router_name$&" -During the running of a router this variable contains its name. +During the running of a router, or a transport called, +this variable contains the router name. .vitem &$runrc$& .cindex "return code" "from &%run%& expansion" @@ -22797,7 +22847,17 @@ example: transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}' .endd This runs the command &(/bin/cmd1)& if the host name is &'a.b.c'&, and -&(/bin/cmd2)& otherwise. If double quotes had been used, they would have been +&(/bin/cmd2)& otherwise. + +Option strings in general have any fully-surrounding double quote wrapping +removed early in parsing (see &<>&). +Then, for this option, quotes protect against whitespace being +regarded as a separator while splitting into the command argument vector. +Either double or single quotes can be used here; +the former interprets backlash-quoted charachters +and the latter does not. + +If double quotes had been used in this example, they would have been stripped by Exim when it read the option's value. When the value is used, if the single quotes were missing, the line would be split into two items, &`/bin/cmd${if`& and &`eq{$host}{a.b.c}{1}{2}`&, and an error would occur when @@ -26102,7 +26162,8 @@ This option give a list of hosts for which, while verifying the server certificate, checks will be included on the host name (note that this will generally be the result of a DNS MX lookup) -versus Subject and Subject-Alternate-Name fields. Wildcard names are permitted +versus the Subject-Alternate-Name (or, if none, Subject-Name) fields. +Wildcard names are permitted, limited to being the initial component of a 3-or-more component FQDN. There is no equivalent checking on client certificates. @@ -32087,8 +32148,24 @@ Headers will not be removed from the message if the modifier is used in DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing. More than one header can be removed at the same time by using a colon separated -list of header names. The header matching is case insensitive. Wildcards are -not permitted, nor is list expansion performed, so you cannot use hostlists to +list of header specifiers. +.new +If a specifier does not start with a circumflex (^) +then it is treated as a header name. +The header name matching is case insensitive. +If it does, then it is treated as a (front-anchored) +regular expression applied to the whole header. + +&*Note*&: The colon terminating a header name will need to be doubled +if used in an RE, and there can legitimately be whitepace before it. + +Example: +.code +remove_header = \N^(?i)Authentication-Results\s*::\s*example.org;\N +.endd +.wen + +List expansion is not performed, so you cannot use hostlists to create a list of headers, however both connection and message variable expansion are performed (&%$acl_c_*%& and &%$acl_m_*%&), illustrated in this example: .code @@ -32097,14 +32174,14 @@ warn hosts = +internal_hosts warn message = Remove internal headers remove_header = $acl_c_ihdrs .endd -Header names for removal are accumulated during the MAIL, RCPT, and predata ACLs. +Header specifiers for removal are accumulated during the MAIL, RCPT, and predata ACLs. Matching header lines are removed from the message before processing the DATA and MIME ACLs. 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 lines to be removed may be accumulated -during the DATA and MIME ACLs, after which they are removed from the message, -if present. In the case of non-SMTP messages, headers to be removed are -accumulated during the non-SMTP ACLs, and are removed from the message after +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 +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 would have been removed. @@ -38936,7 +39013,7 @@ logging and the message has a DKIM signature header. .section "Reducing or increasing what is logged" "SECTlogselector" .cindex "log" "selectors" By setting the &%log_selector%& global option, you can disable some of Exim's -default logging, or you can request additional logging. The value of +default logging to the main log, or you can request additional logging. The value of &%log_selector%& is made up of names preceded by plus or minus characters. For example: .code @@ -39466,6 +39543,7 @@ the next chapter. The utilities described here are: .irow &<>& &'exim_tidydb'& "clean up a hints database" .irow &<>& &'exim_fixdb'& "patch a hints database" .irow &<>& &'exim_lock'& "lock a mailbox file" +.irow &<>& &'exim_msgdate'& "Message Ids for humans (exim_msgdate)" .endtable Another utility that might be of use to sites with many MTAs is Tom Kistner's @@ -40189,9 +40267,16 @@ exim_lock -q /var/spool/mail/spqr \ .endd Note that if a command is supplied, it must be entirely contained within the second argument &-- hence the quotes. -.ecindex IIDutils +.section "Message Ids for humans (exim_msgdate)" "SECTexim_msgdate" +.cindex "exim_msgdate" +The &'exim_msgdate'& utility is written by Andrew Aitchison and included in the Exim distribution. +This Perl script converts an Exim Mesage ID back into a human readable form. +For details of &'exim_msgdate'&'s options, run &'exim_msgdate'& with the &%--help%& option. + +Section &<>& (Message identification) describes Exim Mesage IDs. +.ecindex IIDutils . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// @@ -42189,8 +42274,9 @@ Example usage: # one, plus the max_rcpt and return_path options remote_forwarded_smtp: driver = smtp - # modify the envelope from, for mails that we forward + # single-recipient so that $original_domain is valid max_rcpt = 1 + # modify the envelope from, for mails that we forward return_path = ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}} .endd