Transport: permit an empty string for the transport_filter option. Bug 1714
[exim.git] / doc / doc-docbook / spec.xfpt
index 238598229812472de4dc2dbc414c82bb7b2a2dd2..af57d9b8566f516dd782e00c0ab72853618a556c 100644 (file)
@@ -1575,7 +1575,7 @@ If a host is unreachable for a period of time, a number of messages may be
 waiting for it by the time it recovers, and sending them in a single SMTP
 connection is clearly beneficial. Whenever a delivery to a remote host is
 deferred,
-.cindex "hints database"
+.cindex "hints database" "deferred deliveries"
 Exim makes a note in its hints database, and whenever a successful
 SMTP delivery has happened, it looks to see if any other messages are waiting
 for the same host. If any are found, they are sent over the same SMTP
@@ -4800,8 +4800,8 @@ help with this. See the comments in &_src/EDITME_& for details.
 Exim's configuration file is divided into a number of different parts. General
 option settings must always appear at the start of the file. The other parts
 are all optional, and may appear in any order. Each part other than the first
-is introduced by the word &"begin"& followed by the name of the part. The
-optional parts are:
+is introduced by the word &"begin"& followed by at least one literal
+space, and the name of the part. The optional parts are:
 
 .ilist
 &'ACL'&: Access control lists for controlling incoming SMTP mail (see chapter
@@ -6060,7 +6060,7 @@ address_pipe:
 .endd
 This transport is used for handling deliveries to pipes that are generated by
 redirection (aliasing or users' &_.forward_& files). The &%return_output%&
-option specifies that any output on stdout or stderr generated by the pipe is to 
+option specifies that any output on stdout or stderr generated by the pipe is to
 be returned to the sender.
 .code
 address_file:
@@ -6993,6 +6993,15 @@ Retries for the dnsdb lookup can be controlled by a retry modifier.
 The form if &"retry_VAL"& where VAL is an integer.
 The default count is set by the main configuration option &%dns_retry%&.
 
+.new
+.cindex cacheing "of dns lookup"
+.cindex TTL "of dns lookup"
+.cindex DNS TTL
+Dnsdb lookup results are cached within a single process (and its children).
+The cache entry lifetime is limited to the smallest time-to-live (TTL)
+value of the set of returned DNS records.
+.wen
+
 
 .section "Pseudo dnsdb record types" "SECID66"
 .cindex "MX record" "in &(dnsdb)& lookup"
@@ -7312,7 +7321,7 @@ The TIME parameter (also a number of seconds) is passed to the server to
 set a server-side limit on the time taken to complete a search.
 
 The SERVERS parameter allows you to specify an alternate list of ldap servers
-to use for an individual lookup.  The global ldap_servers option provides a
+to use for an individual lookup.  The global &%ldap_default_servers%& option provides a
 default list of ldap servers, and a single lookup can specify a single ldap
 server to use.  But when you need to do a lookup with a list of servers that is
 different than the default list (maybe different order, maybe a completely
@@ -7528,13 +7537,12 @@ a query is successfully processed. The result of a query may be that no data is
 found, but that is still a successful query. In other words, the list of
 servers provides a backup facility, not a list of different places to look.
 
+.new
 The &%quote_mysql%&, &%quote_pgsql%&, and &%quote_oracle%& expansion operators
 convert newline, tab, carriage return, and backspace to \n, \t, \r, and \b
 respectively, and the characters single-quote, double-quote, and backslash
-itself are escaped with backslashes. The &%quote_pgsql%& expansion operator, in
-addition, escapes the percent and underscore characters. This cannot be done
-for MySQL because these escapes are not recognized in contexts where these
-characters are not special.
+itself are escaped with backslashes.
+.wen
 
 .section "Specifying the server in the query" "SECTspeserque"
 For MySQL and PostgreSQL lookups (but not currently for Oracle and InterBase),
@@ -9264,10 +9272,11 @@ by earlier ACLs are visible.
 Upper case and lower case letters are synonymous in header names. If the
 following character is white space, the terminating colon may be omitted, but
 this is not recommended, because you may then forget it when it is needed. When
-white space terminates the header name, it is included in the expanded string.
-If the message does not contain the given header, the expansion item is
-replaced by an empty string. (See the &%def%& condition in section
-&<<SECTexpcond>>& for a means of testing for the existence of a header.)
+white space terminates the header name, this white space is included in the
+expanded string.  If the message does not contain the given header, the
+expansion item is replaced by an empty string. (See the &%def%& condition in
+section &<<SECTexpcond>>& for a means of testing for the existence of a
+header.)
 
 If there is more than one header with the same name, they are all concatenated
 to form the substitution string, up to a maximum length of 64K. Unless
@@ -9389,7 +9398,7 @@ yields &"42"&, and
 .code
 ${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}}
 .endd
-yields &"result: 99"&.
+yields &"result: 42"&.
 
 If {<&'string3'&>} is omitted, an empty string is used for string3.
 If {<&'string2'&>} is also omitted, the value that was
@@ -11109,7 +11118,8 @@ support for TLS or the content scanning extension.
 When a &%match%& expansion condition succeeds, these variables contain the
 captured substrings identified by the regular expression during subsequent
 processing of the success string of the containing &%if%& expansion item.
-However, they do not retain their values afterwards; in fact, their previous
+In the expansion condition case
+they do not retain their values afterwards; in fact, their previous
 values are restored at the end of processing an &%if%& item. The numerical
 variables may also be set externally by some other matching process which
 precedes the expansion of the string. For example, the commands available in
@@ -11317,9 +11327,10 @@ not the same as the user id of the originator of a message (see
 &$originator_uid$&). If Exim re-execs itself, this variable in the new
 incarnation normally contains the Exim uid.
 
-.vitem &$compile_date$&
-.vindex "&$compile_date$&"
-The date on which the Exim binary was compiled.
+.vitem &$callout_address$&
+.vindex "&$callout_address$&"
+After a callout for verification, spamd or malware daemon service, the
+address that was connected to.
 
 .vitem &$compile_number$&
 .vindex "&$compile_number$&"
@@ -11978,6 +11989,13 @@ a single-component name, Exim calls &[gethostbyname()]& (or
 qualified host name. See also &$smtp_active_hostname$&.
 
 
+.new
+.vitem &$prdr_requested$&
+.cindex "PRDR" "variable for"
+This variable is set to &"yes"& if PRDR was requested by the client for the
+current message, otherwise &"no"&.
+.wen
+
 .vitem &$prvscheck_address$&
 This variable is used in conjunction with the &%prvscheck%& expansion item,
 which is described in sections &<<SECTexpansionitems>>& and
@@ -12156,6 +12174,12 @@ increases for each accepted recipient. It can be referenced in an ACL.
 This variable is set to contain the matching regular expression after a
 &%regex%& ACL condition has matched (see section &<<SECTscanregex>>&).
 
+.vitem "&$regex1$&, &$regex2$&, etc"
+.cindex "regex submatch variables (&$1regex$& &$2regex$& etc)"
+When a &%regex%& or &%mime_regex%& ACL condition succeeds,
+these variables contain the
+captured substrings identified by the regular expression.
+
 
 .vitem &$reply_address$&
 .vindex "&$reply_address$&"
@@ -14459,7 +14483,7 @@ routing, but which are not used for listening by the daemon. See section
 . Allow this long option name to split; give it unsplit as a fifth argument
 . for the automatic .oindex that is generated by .option.
 
-.option "extract_addresses_remove_ &~&~arguments" main boolean true &&&
+.option "extract_addresses_remove_arguments" main boolean true &&&
          extract_addresses_remove_arguments
 .oindex "&%-t%&"
 .cindex "command line" "addresses with &%-t%&"
@@ -16668,6 +16692,10 @@ must if set expand to the absolute path to a file which contains a current
 status proof for the server's certificate, as obtained from the
 Certificate Authority.
 
+.new
+Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later).
+.wen
+
 
 .option tls_on_connect_ports main "string list" unset
 .cindex SSMTP
@@ -20517,6 +20545,32 @@ transport, the &[initgroups()]& function is called when running the transport
 to ensure that any additional groups associated with the uid are set up.
 
 
+.new
+.option max_parallel transports integer&!! unset
+.cindex limit "transport parallelism"
+.cindex transport "parallel processes"
+.cindex transport "concurrency limit"
+.cindex "delivery" "parallelism for transport"
+If this option is set and expands to an integer greater than zero
+it limits the number of concurrent runs of the transport.
+The control does not apply to shadow transports.
+
+.cindex "hints database" "transport concurrency control"
+Exim implements this control by means of a hints database in which a record is
+incremented whenever a transport process is beaing created. The record
+is decremented and possibly removed when the process terminates.
+Obviously there is scope for
+records to get left lying around if there is a system or program crash. To
+guard against this, Exim ignores any records that are more than six hours old.
+
+If you use this option, you should also arrange to delete the
+relevant hints database whenever your system reboots. The names of the files
+start with &_misc_& and they are kept in the &_spool/db_& directory. There
+may be one or two files, depending on the type of DBM in use. The same files
+are used for ETRN and smtp transport serialization.
+.wen
+
+
 .option message_size_limit transports string&!! 0
 .cindex "limit" "message size per transport"
 .cindex "size" "of message, limit"
@@ -20663,6 +20717,9 @@ headers that some sites insist on.
 This option sets up a filtering (in the Unix shell sense) process for messages
 at transport time. It should not be confused with mail filtering as set up by
 individual users or via a system filter.
+.new
+If unset, or expanding to an empty string, no filtering is done.
+.wen
 
 When the message is about to be written out, the command specified by
 &%transport_filter%& is started up in a separate, parallel process, and
@@ -22414,6 +22471,10 @@ If two messages arrive at almost the same time, and both are routed to a pipe
 delivery, the two pipe transports may be run concurrently. You must ensure that
 any pipe commands you set up are robust against this happening. If the commands
 write to a file, the &%exim_lock%& utility might be of use.
+.new
+Alternatively the &%max_parallel%& option could be used with a value
+of "1" to enforce serialization.
+.wen
 
 
 
@@ -22694,7 +22755,7 @@ See the &%timeout_defer%& option for how timeouts are handled.
 .cindex "&(pipe)& transport" "logging output"
 If this option is set, and the status returned by the command is
 one of the codes listed in &%temp_errors%& (that is, delivery was deferred),
-and any output was produced on stdout or stderr, the first line of it is 
+and any output was produced on stdout or stderr, the first line of it is
 written to the main log.
 
 
@@ -23596,6 +23657,10 @@ start with &_misc_& and they are kept in the &_spool/db_& directory. There
 may be one or two files, depending on the type of DBM in use. The same files
 are used for ETRN serialization.
 
+.new
+See also the &%max_parallel%& generic transport option.
+.wen
+
 
 .option size_addition smtp integer 1024
 .cindex "SMTP" "SIZE"
@@ -26754,7 +26819,9 @@ starts retrying to fetch an OCSP proof some time before its current
 proof expires.  The downside is that it requires server support.
 
 Unless Exim is built with the support disabled,
-or with GnuTLS earlier than version 3.1.3,
+.new
+or with GnuTLS earlier than version 3.3.16 / 3.4.8
+.wen
 support for OCSP stapling is included.
 
 There is a global option called &%tls_ocsp_file%&.
@@ -27336,8 +27403,12 @@ for some or all recipients.
 PRDR may be used to support per-user content filtering.  Without it
 one must defer any recipient after the first that has a different
 content-filter configuration.  With PRDR, the RCPT-time check
-for this can be disabled when the MAIL-time $smtp_command included
-"PRDR".  Any required difference in behaviour of the main DATA-time
+.new
+.cindex "PRDR" "variable for"
+for this can be disabled when the variable &$prdr_requested$&
+is &"yes"&.
+.wen
+Any required difference in behaviour of the main DATA-time
 ACL should however depend on the PRDR-time ACL having run, as Exim
 will avoid doing so in some situations (e.g.  single-recipient mails).
 
@@ -29030,7 +29101,8 @@ This condition is relevant only in an ACL that is run after a message has been
 received, that is, in an ACL specified by &%acl_smtp_data%& or
 &%acl_not_smtp%&. It checks the syntax of all header lines that can contain
 lists of addresses (&'Sender:'&, &'From:'&, &'Reply-To:'&, &'To:'&, &'Cc:'&,
-and &'Bcc:'&). Unqualified addresses (local parts without domains) are
+and &'Bcc:'&), returning true if there are no problems.
+Unqualified addresses (local parts without domains) are
 permitted only in locally generated messages and from hosts that match
 &%sender_unqualified_hosts%& or &%recipient_unqualified_hosts%&, as
 appropriate.
@@ -29192,9 +29264,15 @@ deny  dnslists = blackholes.mail-abuse.org
 warn  message  = X-Warn: sending host is on dialups list
       dnslists = dialups.mail-abuse.org
 .endd
-DNS list lookups are cached by Exim for the duration of the SMTP session,
+.cindex cacheing "of dns lookup"
+.cindex DNS TTL
+DNS list lookups are cached by Exim for the duration of the SMTP session
+.new
+(but limited by the DNS return TTL value),
+.wen
 so a lookup based on the IP address is done at most once for any incoming
-connection. Exim does not share information between multiple incoming
+connection (assuming long-enough TTL).
+Exim does not share information between multiple incoming
 connections (but your local name server cache should be active).
 
 
@@ -30947,6 +31025,10 @@ malware = * / defer_ok / tmo=10s
 .endd
 A timeout causes the ACL to defer.
 
+.vindex "&$callout_address$&"
+When a connection is made to the scanner the expansion variable &$callout_address$&
+is set to record the actual address used.
+
 .vindex "&$malware_name$&"
 When a virus is found, the condition sets up an expansion variable called
 &$malware_name$& that contains the name of the virus. You can use it in a
@@ -31058,7 +31140,7 @@ In the latter case, the range is tried in strict order.
 
 Elements after the first for Unix sockets, or second for TCP socket,
 are options.
-The supported option are:
+The supported options are:
 .code
 pri=<priority>      Selection priority
 weight=<value>      Selection bias
@@ -31097,6 +31179,10 @@ a dollar sign. In this case, the expansion may return a string that is
 used as the list so that multiple spamd servers can be the result of an
 expansion.
 
+.vindex "&$callout_address$&"
+When a connection is made to the server the expansion variable &$callout_address$&
+is set to record the actual address used.
+
 .section "Calling SpamAssassin from an Exim ACL" "SECID206"
 Here is a simple example of the use of the &%spam%& condition in a DATA ACL:
 .code
@@ -31165,7 +31251,8 @@ The integer value is useful for numeric comparisons in conditions.
 A string consisting of a number of &"+"& or &"-"& characters, representing the
 integer part of the spam score value. A spam score of 4.4 would have a
 &$spam_bar$& value of &"++++"&. This is useful for inclusion in warning
-headers, since MUAs can match on such strings.
+headers, since MUAs can match on such strings. The maximum length of the
+spam bar is 50 characters.
 
 .vitem &$spam_report$&
 A multiline text table, containing the full SpamAssassin report for the
@@ -31454,6 +31541,8 @@ deny message = contains blacklisted regex ($regex_match_string)
 The conditions returns true if any one of the regular expressions matches. The
 &$regex_match_string$& expansion variable is then set up and contains the
 matching regular expression.
+The expansion variables &$regex1$& &$regex2$& etc
+are set to any substrings captured by the regular expression.
 
 &*Warning*&: With large messages, these conditions can be fairly
 CPU-intensive.
@@ -35306,6 +35395,9 @@ selection marked by asterisks:
 &` incoming_interface         `&  local interface on <= and => lines
 &` incoming_port              `&  remote port on <= lines
 &`*lost_incoming_connection   `&  as it says (includes timeouts)
+.new
+&` outgoing_interface         `&  local interface on => lines
+.wen
 &` outgoing_port              `&  add remote port to => lines
 &`*queue_run                  `&  start and end queue runs
 &` queue_time                 `&  time on queue for one recipient
@@ -35431,9 +35523,11 @@ client's ident port times out.
 &%incoming_interface%&: The interface on which a message was received is added
 to the &"<="& line as an IP address in square brackets, tagged by I= and
 followed by a colon and the port number. The local interface and port are also
-added to other SMTP log lines, for example &"SMTP connection from"& and to
-rejection lines
-and (despite the name) the local interface is added to &"=>"& lines..
+added to other SMTP log lines, for example &"SMTP connection from"&, to
+rejection lines, and (despite the name) to outgoing &"=>"& and &"->"& lines.
+.new
+The latter can be disabled by turning off the &%outgoing_interface%& option.
+.wen
 .next
 .cindex "log" "incoming remote port"
 .cindex "port" "logging remote"
@@ -35451,13 +35545,30 @@ important with the widening use of NAT (see RFC 2505).
 &%lost_incoming_connection%&: A log line is written when an incoming SMTP
 connection is unexpectedly dropped.
 .next
+.cindex "log" "outgoing interface"
+.cindex "log" "local interface"
+.cindex "log" "local address and port"
+.cindex "TCP/IP" "logging local address and port"
+.cindex "interface" "logging"
+.new
+&%outgoing_interface%&: If &%incoming_interface%& is turned on, then the
+interface on which a message was sent is added to delivery lines as an I= tag
+followed by IP address in square brackets. You can disable this by turning
+off the &%outgoing_interface%& option.
+.wen
+.next
 .cindex "log" "outgoing remote port"
 .cindex "port" "logging outgoint remote"
 .cindex "TCP/IP" "logging ougtoing remote port"
 &%outgoing_port%&: The remote port number is added to delivery log lines (those
-containing => tags) following the IP address. This option is not included in
-the default setting, because for most ordinary configurations, the remote port
-number is always 25 (the SMTP port).
+containing => tags) following the IP address.
+.new
+The local port is also added if &%incoming_interface%& and
+&%outgoing_interface%& are both enabled.
+.wen
+This option is not included in the default setting, because for most ordinary
+configurations, the remote port number is always 25 (the SMTP port), and the
+local port is a random ephemeral port.
 .next
 .cindex "log" "process ids in"
 .cindex "pid (process id)" "in log lines"
@@ -36201,6 +36312,9 @@ Serializing ETRN runs (when &%smtp_etrn_serialize%& is set)
 .next
 Serializing delivery to a specific host (when &%serialize_hosts%& is set in an
 &(smtp)& transport)
+.next
+Limiting the concurrency of specific transports (when &%max_parallel%& is set
+in a transport)
 .endlist