Testsuite: add command cat2

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index f35ebf675aae45047491fdb05ecf1b273a6af09b..6ff06f3a47f97b39e3936b3bd084de71d51f159d 100644 (file)
--- 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.
 . --- 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
 
 .macro option
 .arg 5


@@ -85,8 +95,19 @@
 .arg -5
 .oindex "&%$1%&"
 .endarg
 .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
 
 .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"
 .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
 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


@@ -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.
 
 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.
+

 
 
 
 
 
 


@@ -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
 .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
 
 .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
 .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
 .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.
 .endd
 The value of &$item$& is saved and restored while &%forany%& or &%forall%& is
 being processed, to enable these expansion items to be nested.


@@ -13404,10 +13432,20 @@ The main use of this variable is expected to be to distinguish between
 rejections of MAIL and rejections of RCPT.
 
 .tvar &$recipients$&
 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
 cases:
 
 .olist


@@ -15444,11 +15482,8 @@ $primary_hostname-$tod_epoch-testing
 See section &<<CALLaddparcall>>& for details of how this value is used.
 
 
 See section &<<CALLaddparcall>>& 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%&"
 See &%check_spool_space%& below.
 
 .oindex "&%check_rfc2047_length%&"


@@ -15463,11 +15498,8 @@ of the RFC, generates overlong encoded words. If &%check_rfc2047_length%& is
 set false, Exim recognizes encoded words of any length.
 
 
 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"
 .cindex "checking disk space"
 .cindex "disk space, checking"
 .cindex "spool directory" "checking space"


@@ -15546,17 +15578,15 @@ This option specifies one or more default SMTP ports on which the Exim daemon
 listens. See chapter &<<CHAPinterfaces>>& for details of how it is used. For
 backward compatibility, &%daemon_smtp_port%& (singular) is a synonym.
 
 listens. See chapter &<<CHAPinterfaces>>& 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"
 .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.
 
 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"
 .option delay_warning main "time list" 24h
 .cindex "warning of delay"
 .cindex "delay warning, specifying"


@@ -16080,7 +16110,8 @@ log. If you configure freezing in a filter or ACL, you must arrange for any
 logging that you require.
 
 
 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
 .cindex "HP-UX"
 .cindex "&""gecos""& field, parsing"
 Some operating systems, notably HP-UX, use the &"gecos"& field in the system


@@ -16105,9 +16136,6 @@ gecos_pattern = ([^,]*)
 gecos_name = $1
 .endd
 
 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
 
 .option gnutls_compat_mode main boolean unset
 This option controls whether GnuTLS is used in compatibility mode in an Exim


@@ -16411,7 +16439,8 @@ dealing with other kinds of frozen message, see &%auto_thaw%& and
 &%timeout_frozen_after%&.
 
 
 &%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
 .cindex "&""From""& line"
 .cindex "UUCP" "&""From""& line"
 Some broken SMTP clients insist on sending a UUCP-like &"From&~"& line before


@@ -16423,8 +16452,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.
 
 
 &%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"
 
 .option keep_environment main "string list" unset
 .cindex "environment" "values from"


@@ -16579,7 +16606,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
 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 +16627,6 @@ matches the actual sender address that is constructed from the login name and
 qualify domain.
 
 
 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
 .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 +17066,11 @@ a good idea to reject recipient addresses with percent characters in their
 local parts. Exim's default configuration does this.
 
 
 local parts. Exim's default configuration does this.
 
 

-.option perl_at_start main boolean false
-.cindex "Perl"
-This option is available only when Exim is built with an embedded Perl
-interpreter. See chapter &<<CHAPperl>>& for details of its use.
-
-
-.option perl_startup main string unset
+.options perl_at_start main boolean false &&&
+        perl_startup main string unset

 .cindex "Perl"
 .cindex "Perl"

-This option is available only when Exim is built with an embedded Perl
-interpreter. See chapter &<<CHAPperl>>& for details of its use.
+These options are available only when Exim is built with an embedded Perl
+interpreter. See chapter &<<CHAPperl>>& for details of their use.

 
 .option perl_taintmode main boolean false
 .cindex "Perl"
 
 .option perl_taintmode main boolean false
 .cindex "Perl"


@@ -17263,7 +17282,7 @@ and &%-odi%& command line options override &%queue_only%& unless
 &%queue_only_load%&, and &%smtp_accept_queue%&.
 
 
 &%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
 .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 +17965,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"
 .cindex "SMTP" "rate limiting"
 .cindex "limit" "rate of message arrival"
 .cindex "RCPT" "rate limiting"


@@ -17989,13 +18010,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.
 
 
 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"
 
 .option smtp_receive_timeout main time&!! 5m
 .cindex "timeout" "for SMTP input"


@@ -18396,7 +18410,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,
 .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.
 
 ALPN name or a name which does not match the list,
 the TLS connection is declined.
 


@@ -19167,12 +19181,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
 .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 &<<SECTrouprecon>>& for
 a list of the order in which preconditions are evaluated.
 
 expansions of the driver's private options and in the transport.
 See section &<<SECTrouprecon>>& 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
 
 
 .option driver routers string unset


@@ -19536,7 +19563,7 @@ example:
 local_parts = dbm;/usr/local/specials/$domain_data
 .endd
 .vindex "&$local_part_data$&"
 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
 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 +29693,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"
 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
 
 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.
 
 
 accepted by Exim.
 
 


@@ -29839,10 +29866,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"
 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
 
 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.
 
 
 initiated by Exim.
 
 


@@ -38956,6 +38983,7 @@ the following table:
 .display
 &`A   `&        authenticator name (and optional id and sender)
 &`C   `&        SMTP confirmation on delivery
 .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"&
 &`    `&        command list for &"no mail in SMTP session"&
 &`CV  `&        certificate verification status
 &`D   `&        duration of &"no mail in SMTP session"&


@@ -39058,6 +39086,7 @@ selection marked by asterisks:
 .irow &`address_rewrite`&              &nbsp; "address rewriting"
 .irow &`all_parents`&                  &nbsp; "all parents in => lines"
 .irow &`arguments`&                    &nbsp; "command line arguments"
 .irow &`address_rewrite`&              &nbsp; "address rewriting"
 .irow &`all_parents`&                  &nbsp; "all parents in => lines"
 .irow &`arguments`&                    &nbsp; "command line arguments"

+.irow &`connection_id`&                        &nbsp;  "connection identifier"

 .irow &`connection_reject`&            *       "connection rejections"
 .irow &`delay_delivery`&               *       "immediate delivery delayed"
 .irow &`deliver_time`&                 &nbsp; "time taken to attempt delivery"
 .irow &`connection_reject`&            *       "connection rejections"
 .irow &`delay_delivery`&               *       "immediate delivery delayed"
 .irow &`deliver_time`&                 &nbsp; "time taken to attempt delivery"


@@ -39153,6 +39182,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
 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.
 .cindex "log" "connection rejections"
 &%connection_reject%&: A log entry is written whenever an incoming SMTP
 connection is rejected, for whatever reason.