Expand docs re. logs dir, and make eximon logs dir match exim's. Bug 1324

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index d4ebf464d7fc7f593bedd4a00a0dc42536bbcf5e..667857a996daf38f6d3a7c90919220ab0eda6013 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9031,6 +9031,30 @@ When compiling a function that is to be used in this way with gcc,
 you need to add &%-shared%& to the gcc command. Also, in the Exim build-time
 configuration, you must add &%-export-dynamic%& to EXTRALIBS.
 
 you need to add &%-shared%& to the gcc command. Also, in the Exim build-time
 configuration, you must add &%-export-dynamic%& to EXTRALIBS.
 

+
+.vitem "&*${env{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&"
+.cindex "expansion" "extracting value from environment"
+.cindex "environment" "value from"
+The key is first expanded separately, and leading and trailing white space
+removed.
+This is then searched for as a name in the environment.
+If a variable is found then its value is placed in &$value$&
+and <&'string1'&> is expanded, otherwise <&'string2'&> is expanded.
+
+Instead of {<&'string2'&>} the word &"fail"& (not in curly brackets) can
+appear, for example:
+.code
+${env{USER}{$value} fail }
+.endd
+This forces an expansion failure (see section &<<SECTforexpfai>>&);
+{<&'string1'&>} must be present for &"fail"& to be recognized.
+
+If {<&'string2'&>} is omitted an empty string is substituted on 
+search failure.
+If {<&'string1'&>} is omitted the search result is substituted on
+search success.
+
+

 .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
        {*&<&'string3'&>&*}}*&"
 .cindex "expansion" "extracting substrings by key"
 .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
        {*&<&'string3'&>&*}}*&"
 .cindex "expansion" "extracting substrings by key"


@@ -11415,7 +11439,7 @@ This variable contains the numerical value of the Exim user id.
 
 .new
 .vitem &$exim_version$&
 
 .new
 .vitem &$exim_version$&

-.vindex "&$exim_uid$&"
+.vindex "&$exim_version$&"

 This variable contains the version string of the Exim build.
 The first character is a major version number, currently 4.
 Then after a dot, the next group of digits is a minor version number.
 This variable contains the version string of the Exim build.
 The first character is a major version number, currently 4.
 Then after a dot, the next group of digits is a minor version number.


@@ -11681,6 +11705,7 @@ the space value is -1. See also the &%check_log_space%& option.
 .vindex "&$lookup_dnssec_authenticated$&"
 This variable is set after a DNS lookup done by
 a dnsdb lookup expansion, dnslookup router or smtp transport.
 .vindex "&$lookup_dnssec_authenticated$&"
 This variable is set after a DNS lookup done by
 a dnsdb lookup expansion, dnslookup router or smtp transport.

+.cindex "DNS" "DNSSEC"

 It will be empty if &(DNSSEC)& was not requested,
 &"no"& if the result was not labelled as authenticated data
 and &"yes"& if it was.
 It will be empty if &(DNSSEC)& was not requested,
 &"no"& if the result was not labelled as authenticated data
 and &"yes"& if it was.


@@ -12198,6 +12223,14 @@ verification either failed or was not requested. A host name in parentheses is
 the argument of a HELO or EHLO command. This is omitted if it is identical to
 the verified host name or to the host's IP address in square brackets.
 
 the argument of a HELO or EHLO command. This is omitted if it is identical to
 the verified host name or to the host's IP address in square brackets.
 

+.new
+.vitem &$sender_helo_dnssec$&
+.vindex "&$sender_helo_dnssec$&"
+This boolean variable is true if a successful HELO verification was
+.cindex "DNS" "DNSSEC"
+done using DNS information the resolver library stated was authenticatied data.
+.wen
+

 .vitem &$sender_helo_name$&
 .vindex "&$sender_helo_name$&"
 When a message is received from a remote host that has issued a HELO or EHLO
 .vitem &$sender_helo_name$&
 .vindex "&$sender_helo_name$&"
 When a message is received from a remote host that has issued a HELO or EHLO


@@ -12223,9 +12256,11 @@ received. It is empty if there was no successful authentication. See also
 If an attempt to populate &$sender_host_name$& has been made
 (by reference, &%hosts_lookup%& or
 otherwise) then this boolean will have been set true if, and only if, the
 If an attempt to populate &$sender_host_name$& has been made
 (by reference, &%hosts_lookup%& or
 otherwise) then this boolean will have been set true if, and only if, the

-resolver library states that the reverse DNS was authenticated data.  At all
+resolver library states that both
+the reverse and forward DNS were authenticated data.  At all

 other times, this variable is false.
 
 other times, this variable is false.
 

+.cindex "DNS" "DNSSEC"

 It is likely that you will need to coerce DNSSEC support on in the resolver
 library, by setting:
 .code
 It is likely that you will need to coerce DNSSEC support on in the resolver
 library, by setting:
 .code


@@ -12235,9 +12270,6 @@ dns_dnssec_ok = 1
 Exim does not perform DNSSEC validation itself, instead leaving that to a
 validating resolver (eg, unbound, or bind with suitable configuration).
 
 Exim does not perform DNSSEC validation itself, instead leaving that to a
 validating resolver (eg, unbound, or bind with suitable configuration).
 

-Exim does not (currently) check to see if the forward DNS was also secured
-with DNSSEC, only the reverse DNS.
-

 If you have changed &%host_lookup_order%& so that &`bydns`& is not the first
 mechanism in the list, then this variable will be false.
 
 If you have changed &%host_lookup_order%& so that &`bydns`& is not the first
 mechanism in the list, then this variable will be false.
 


@@ -14537,14 +14569,17 @@ is an IP literal matching the calling address of the host, or
 matches the host name that Exim obtains by doing a reverse lookup of the
 calling host address, or
 .next
 matches the host name that Exim obtains by doing a reverse lookup of the
 calling host address, or
 .next

-when looked up using &[gethostbyname()]& (or &[getipnodebyname()]& when
-available) yields the calling host address.
+when looked up in DNS yields the calling host address.

 .endlist
 
 However, the EHLO or HELO command is not rejected if any of the checks
 fail. Processing continues, but the result of the check is remembered, and can
 be detected later in an ACL by the &`verify = helo`& condition.
 
 .endlist
 
 However, the EHLO or HELO command is not rejected if any of the checks
 fail. Processing continues, but the result of the check is remembered, and can
 be detected later in an ACL by the &`verify = helo`& condition.
 

+If DNS was used for successful verification, the variable
+.cindex "DNS" "DNSSEC"
+&$helo_verify_dnssec$& records the DNSSEC status of the lookups.
+

 .option helo_verify_hosts main "host list&!!" unset
 .cindex "HELO verifying" "mandatory"
 .cindex "EHLO" "verifying, mandatory"
 .option helo_verify_hosts main "host list&!!" unset
 .cindex "HELO verifying" "mandatory"
 .cindex "EHLO" "verifying, mandatory"


@@ -14918,8 +14953,9 @@ section &<<SECTmessiden>>&.
 This option sets the path which is used to determine the names of Exim's log
 files, or indicates that logging is to be to syslog, or both. It is expanded
 when Exim is entered, so it can, for example, contain a reference to the host
 This option sets the path which is used to determine the names of Exim's log
 files, or indicates that logging is to be to syslog, or both. It is expanded
 when Exim is entered, so it can, for example, contain a reference to the host

-name. If no specific path is set for the log files at compile or run time, they
-are written in a sub-directory called &_log_& in Exim's spool directory.
+name. If no specific path is set for the log files at compile or run time,
+or if the option is unset at run time (i.e.  &`log_file_path = `&)
+they are written in a sub-directory called &_log_& in Exim's spool directory.

 Chapter &<<CHAPlog>>& contains further details about Exim's logging, and
 section &<<SECTwhelogwri>>& describes how the contents of &%log_file_path%& are
 used. If this string is fixed at your installation (contains no expansion
 Chapter &<<CHAPlog>>& contains further details about Exim's logging, and
 section &<<SECTwhelogwri>>& describes how the contents of &%log_file_path%& are
 used. If this string is fixed at your installation (contains no expansion


@@ -34636,8 +34672,9 @@ equivalent to the setting:
 .code
 log_file_path = $spool_directory/log/%slog
 .endd
 .code
 log_file_path = $spool_directory/log/%slog
 .endd

-If you do not specify anything at build time or run time, that is where the
-logs are written.
+If you do not specify anything at build time or run time,
+or if you unset the option at run time (i.e. &`log_file_path = `&),
+that is where the logs are written.

 
 A log file path may also contain &`%D`& or &`%M`& if datestamped log file names
 are in use &-- see section &<<SECTdatlogfil>>& below.
 
 A log file path may also contain &`%D`& or &`%M`& if datestamped log file names
 are in use &-- see section &<<SECTdatlogfil>>& below.