X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/cb0fd07ce1b3a159c6e1772802b4b7c3e8e0e545..d17c916db7c661aacf65684a5568f8e105e50b3b:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index fd5170198..68d9c056f 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -45,14 +45,16 @@ . Update the Copyright year (only) when changing content. . ///////////////////////////////////////////////////////////////////////////// -.set previousversion "4.93" +.set previousversion "4.94" .include ./local_params .set ACL "access control lists (ACLs)" .set I "    " +.set drivernamemax "64" + .macro copyyear -2019 +2020 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -161,6 +163,13 @@ .macro index .echo "** Don't use .index; use .cindex or .oindex or .vindex" .endmacro + + +. use this for a concept-index entry for a header line +.macro chindex +.cindex "&'$1'& header line" +.cindex "header lines" $1 +.endmacro . //////////////////////////////////////////////////////////////////////////// @@ -193,6 +202,8 @@ . This chunk of literal XML implements index entries of the form "x, see y" and . "x, see also y". However, the DocBook DTD doesn't allow entries . at the top level, so we have to put the .chapter directive first. + +. These do not turn up in the HTML output, unfortunately. The PDF does get them. . ///////////////////////////////////////////////////////////////////////////// .chapter "Introduction" "CHID1" @@ -318,6 +329,10 @@ zero, binary binary zero + + headers + header lines + .literal off @@ -1394,21 +1409,50 @@ Again, cutthrough delivery counts as a verification. .next Individual routers can be explicitly skipped when running the routers to check an address given in the SMTP EXPN command (see the &%expn%& option). + .next If the &%domains%& option is set, the domain of the address must be in the set of domains that it defines. +.new +.cindex "tainted data" "de-tainting" +A match verifies the variable &$domain$& (which carries tainted data) +and assigns an untainted value to the &$domain_data$& variable. +Such an untainted value is often needed in the transport. +For specifics of the matching operation and the resulting untainted value, +refer to section &<>&. + +When an untainted value is wanted, use this option +rather than the generic &%condition%& option. +.wen + .next .vindex "&$local_part_prefix$&" +.vindex "&$local_part_prefix_v$&" .vindex "&$local_part$&" .vindex "&$local_part_suffix$&" +.vindex "&$local_part_suffix_v$&" .cindex affix "router precondition" If the &%local_parts%& option is set, the local part of the address must be in -the set of local parts that it defines. If &%local_part_prefix%& or +the set of local parts that it defines. +.new +A match verifies the variable &$local_part$& (which carries tainted data) +and assigns an untainted value to the &$local_part_data$& variable. +Such an untainted value is often needed in the transport. +For specifics of the matching operation and the resulting untainted value, +refer to section &<>&. + +When an untainted value is wanted, use this option +rather than the generic &%condition%& option. +.wen + +If &%local_part_prefix%& or &%local_part_suffix%& is in use, the prefix or suffix is removed from the local part before this check. If you want to do precondition tests on local parts that include affixes, you can do so by using a &%condition%& option (see below) -that uses the variables &$local_part$&, &$local_part_prefix$&, and -&$local_part_suffix$& as necessary. +that uses the variables &$local_part$&, &$local_part_prefix$&, +&$local_part_prefix_v$&, &$local_part_suffix$& +and &$local_part_suffix_v$& as necessary. + .next .vindex "&$local_user_uid$&" .vindex "&$local_user_gid$&" @@ -1418,23 +1462,37 @@ an account on the local host. If this check succeeds, the uid and gid of the local user are placed in &$local_user_uid$& and &$local_user_gid$& and the user's home directory is placed in &$home$&; these values can be used in the remaining preconditions. + .next If the &%router_home_directory%& option is set, it is expanded at this point, because it overrides the value of &$home$&. If this expansion were left till later, the value of &$home$& as set by &%check_local_user%& would be used in subsequent tests. Having two different values of &$home$& in the same router could lead to confusion. + .next If the &%senders%& option is set, the envelope sender address must be in the set of addresses that it defines. + .next If the &%require_files%& option is set, the existence or non-existence of specified files is tested. + .next .cindex "customizing" "precondition" If the &%condition%& option is set, it is evaluated and tested. This option uses an expanded string to allow you to set up your own custom preconditions. Expanded strings are described in chapter &<>&. + +.new +Note that while using +this option for address matching technically works, +it does not set any de-tainted values. +Such values are often needed, either for router-specific options or +for transport options. +Using the &%domains%& and &%local_parts%& options is usually the most +convenient way to obtain them. +.wen .endlist @@ -2640,10 +2698,8 @@ Exim through the local interface (see the &%-bm%& and &%-f%& options below). See the &%untrusted_set_sender%& option for a way of permitting non-trusted users to set envelope senders. -.cindex "&'From:'& header line" -.cindex "&'Sender:'& header line" -.cindex "header lines" "From:" -.cindex "header lines" "Sender:" +.chindex From: +.chindex Sender: For a trusted user, there is never any check on the contents of the &'From:'& header line, and a &'Sender:'& line is never added. Furthermore, any existing &'Sender:'& line in incoming local (non-TCP/IP) messages is not removed. @@ -3794,9 +3850,11 @@ headers.) .cindex "Solaris" "&'mail'& command" .cindex "dot" "in incoming non-SMTP message" This option, which has the same effect as &%-oi%&, specifies that a dot on a -line by itself should not terminate an incoming, non-SMTP message. I can find -no documentation for this option in Solaris 2.4 Sendmail, but the &'mailx'& -command in Solaris 2.4 uses it. See also &%-ti%&. +line by itself should not terminate an incoming, non-SMTP message. +Solaris 2.4 (SunOS 5.4) Sendmail has a similar &%-i%& processing option +&url(https://docs.oracle.com/cd/E19457-01/801-6680-1M/801-6680-1M.pdf), +p. 1M-529), and therefore a &%-oi%& command line option, which both are used +by its &'mailx'& command. .vitem &%-L%&&~<&'tag'&> .oindex "&%-L%&" @@ -3842,7 +3900,9 @@ id, and the remaining ones must be email addresses. However, if the message is active (in the middle of a delivery attempt), it is not altered. This option can be used only by an admin user. -.vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&~<&'sequence&~number'&>&&& +.vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&&& + &~<&'host&~IP'&>&&& + &~<&'sequence&~number'&>&&& &~<&'message&~id'&>" .oindex "&%-MC%&" .cindex "SMTP" "passed connection" @@ -3866,6 +3926,12 @@ This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option. It signifies that the remote host supports the ESMTP &_DSN_& extension. +.vitem &%-MCd%& +.oindex "&%-MCd%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-d%& option +to pass on an information string on the purpose of the process. + .vitem &%-MCG%&&~<&'queue&~name'&> .oindex "&%-MCG%&" This option is not intended for use by external callers. It is used internally @@ -3878,12 +3944,31 @@ This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option. It signifies that a remote host supports the ESMTP &_CHUNKING_& extension. +.new +.vitem &%-MCL%& +.oindex "&%-MCL%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that the server to +which Exim is connected advertised limits on numbers of mails, recipients or +recipient domains. +The limits are given by the following three arguments. +.wen + .vitem &%-MCP%& .oindex "&%-MCP%&" This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option. It signifies that the server to which Exim is connected supports pipelining. +.new +.vitem &%-MCp%& +.oindex "&%-MCp%&" +This option is not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MC%& option. It signifies that the connection +t a remote server is via a SOCKS proxy, using addresses and ports given by +the following four arguments. +.wen + .vitem &%-MCQ%&&~<&'process&~id'&>&~<&'pipe&~fd'&> .oindex "&%-MCQ%&" This option is not intended for use by external callers. It is used internally @@ -3893,11 +3978,18 @@ together with the file descriptor number of an open pipe. Closure of the pipe signals the final completion of the sequence of processes that are passing messages through the same SMTP connection. +.new +.vitem &%-MCq%&&~<&'recipient&~address'&>&~<&'size'&> +.oindex "&%-MCq%&" +This option is not intended for use by external callers. It is used internally +by Exim to implement quota checking for local users. +.wen + .vitem &%-MCS%& .oindex "&%-MCS%&" This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option, and passes on the fact that the -SMTP SIZE option should be used on messages delivered down the existing +ESMTP SIZE option should be used on messages delivered down the existing connection. .vitem &%-MCT%& @@ -3906,6 +3998,18 @@ This option is not intended for use by external callers. It is used internally by Exim in conjunction with the &%-MC%& option, and passes on the fact that the host to which Exim is connected supports TLS encryption. +.new +.vitem &%-MCr%&&~<&'SNI'&> &&& + &%-MCs%&&~<&'SNI'&> +.oindex "&%-MCs%&" +.oindex "&%-MCr%&" +These options are not intended for use by external callers. It is used internally +by Exim in conjunction with the &%-MCt%& option, and passes on the fact that +a TLS Server Name Indication was sent as part of the channel establishment. +The argument gives the SNI string. +The "r" variant indicates a DANE-verified connection. +.wen + .vitem &%-MCt%&&~<&'IP&~address'&>&~<&'port'&>&~<&'cipher'&> .oindex "&%-MCt%&" This option is not intended for use by external callers. It is used internally @@ -3966,7 +4070,7 @@ user. .vitem &%-MG%&&~<&'queue&~name'&>&~<&'message&~id'&>&~<&'message&~id'&>&~... .oindex "&%-MG%&" .cindex queue named -.cindex "named queues" +.cindex "named queues" "moving messages" .cindex "queue" "moving messages" This option requests that each listed message be moved from its current queue to the given named queue. @@ -4070,8 +4174,9 @@ the standard output. This option can be used only by an admin user. .vitem &%-m%& .oindex "&%-m%&" -This is apparently a synonym for &%-om%& that is accepted by Sendmail, so Exim -treats it that way too. +This is a synonym for &%-om%& that is accepted by Sendmail +(&url(https://docs.oracle.com/cd/E19457-01/801-6680-1M/801-6680-1M.pdf) +p. 1M-258), so Exim treats it that way too. .vitem &%-N%& .oindex "&%-N%&" @@ -4185,6 +4290,7 @@ forces queueing. .vitem &%-odqs%& .oindex "&%-odqs%&" .cindex "SMTP" "delaying delivery" +.cindex "first pass routing" This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&. However, like &%-odb%& and &%-odi%&, this option has no effect if &%queue_only_override%& is false and one of the queueing options in the @@ -4383,7 +4489,6 @@ written. When &%-oX%& is used with &%-bd%&, or when &%-q%& with a time is used without &%-bd%&, this is the only way of causing Exim to write a pid file, because in those cases, the normal pid file is not used. -.new .vitem &%-oPX%& .oindex "&%-oPX%&" .cindex "pid (process id)" "of daemon" @@ -4392,7 +4497,6 @@ This option is not intended for general use. The daemon uses it when terminating due to a SIGTEM, possibly in combination with &%-oP%&&~<&'path'&>. It causes the pid file to be removed. -.wen .vitem &%-or%&&~<&'time'&> .oindex "&%-or%&" @@ -4426,6 +4530,27 @@ of the syntax, and how it interacts with configuration file options, are given in chapter &<>&. When &%-oX%& is used to start a daemon, no pid file is written unless &%-oP%& is also present to specify a pid filename. +.new +.vitem &%-oY%& +.oindex &%-oY%& +.cindex "daemon notifier socket" +This option controls the creation of an inter-process communications endpoint +by the Exim daemon. +It is only relevant when the &%-bd%& (start listening daemon) option is also +given. +Normally the daemon creates this socket, unless a &%-oX%& and &*no*& &%-oP%& +option is also present. +If this option is given then the socket will not be created. This could be +required if the system is running multiple daemons. + +The socket is currently used for +.ilist +fast ramp-up of queue runner processes +.next +obtaining a current queue size +.endlist +.wen + .vitem &%-pd%& .oindex "&%-pd%&" .cindex "Perl" "starting the interpreter" @@ -4503,11 +4628,19 @@ appear in the correct order. Each flag is described in a separate item below. .cindex "queue" "double scanning" .cindex "queue" "routing" .cindex "routing" "whole queue before delivery" +.cindex "first pass routing" +.cindex "queue runner" "two phase" An option starting with &%-qq%& requests a two-stage queue run. In the first stage, the queue is scanned as if the &%queue_smtp_domains%& option matched every domain. Addresses are routed, local deliveries happen, but no remote transports are run. +Performance will be best if the &%queue_run_in_order%& option is false. +If that is so and the &%queue_fast_ramp%& option is true then +in the first phase of the run, +once a threshold number of messages are routed for a given host, +a delivery process is forked in parallel with the rest of the scan. + .cindex "hints database" "remembering routing" The hints database that remembers which messages are waiting for specific hosts is updated, as if delivery to those hosts had been deferred. After this is @@ -4553,7 +4686,7 @@ for later delivery. .vitem &%-q[q][i][f[f]][l][G[/