Documentation for $tls_bits and SASL changes

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index aa4be53323c8739ff79748a663faf8c87cbfad01..5ae4f76498b4c8cd0d37812cff7cc054c2fa990c 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -46,7 +46,7 @@
 . /////////////////////////////////////////////////////////////////////////////
 
 .set previousversion "4.75"
 . /////////////////////////////////////////////////////////////////////////////
 
 .set previousversion "4.75"

-.set version "4.76"
+.set version "4.77"

 
 .set ACL "access control lists (ACLs)"
 .set I   "    "
 
 .set ACL "access control lists (ACLs)"
 .set I   "    "


@@ -174,8 +174,8 @@
 <author><firstname>Exim</firstname><surname>Maintainers</surname></author>
 <authorinitials>EM</authorinitials>
 <revhistory><revision>
 <author><firstname>Exim</firstname><surname>Maintainers</surname></author>
 <authorinitials>EM</authorinitials>
 <revhistory><revision>

-  <revnumber>4.76</revnumber>
-  <date>06 May 2011</date>
+  <revnumber>4.77</revnumber>
+  <date>10 Oct 2011</date>

   <authorinitials>EM</authorinitials>
 </revision></revhistory>
 <copyright><year>2011</year><holder>University of Cambridge</holder></copyright>
   <authorinitials>EM</authorinitials>
 </revision></revhistory>
 <copyright><year>2011</year><holder>University of Cambridge</holder></copyright>


@@ -468,10 +468,10 @@ first to check that you are not duplicating a previous entry.
 The following Exim mailing lists exist:
 
 .table2 140pt
 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-users@exim.org'&      "General discussion list"
 .row &'exim-dev@exim.org'&        "Discussion of bugs, enhancements, etc."

-.row &'exim-announce@exim.org'&   "Moderated, low volume announcements list"
-.row &'exim-future@exim.org'&     "Discussion of long-term development"
+.row &'exim-cvs@exim.org'&        "Automated commit messages from the VCS"

 .endtable
 
 You can subscribe to these lists, change your existing subscriptions, and view
 .endtable
 
 You can subscribe to these lists, change your existing subscriptions, and view


@@ -7779,7 +7779,7 @@ pattern must be an appropriate query for the lookup type, as described in
 chapter &<<CHAPfdlookup>>&. For example:
 .code
 hold_domains = mysql;select domain from holdlist \
 chapter &<<CHAPfdlookup>>&. For example:
 .code
 hold_domains = mysql;select domain from holdlist \

-  where domain = '$domain';
+  where domain = '${quote_mysql:$domain}';

 .endd
 In most cases, the data that is looked up is not used (so for an SQL query, for
 example, it doesn't matter what field you select). Exim is interested only in
 .endd
 In most cases, the data that is looked up is not used (so for an SQL query, for
 example, it doesn't matter what field you select). Exim is interested only in


@@ -9871,7 +9871,10 @@ zero.
 This condition turns a string holding a true or false representation into
 a boolean state.  It parses &"true"&, &"false"&, &"yes"& and &"no"&
 (case-insensitively); also positive integer numbers map to true if non-zero,
 This condition turns a string holding a true or false representation into
 a boolean state.  It parses &"true"&, &"false"&, &"yes"& and &"no"&
 (case-insensitively); also positive integer numbers map to true if non-zero,

-false if zero.  Leading and trailing whitespace is ignored.
+false if zero.
+An empty string is treated as false.
+Leading and trailing whitespace is ignored;
+thus a string consisting only of whitespace is false.

 All other string values will result in expansion failure.
 
 When combined with ACL variables, this expansion condition will let you
 All other string values will result in expansion failure.
 
 When combined with ACL variables, this expansion condition will let you


@@ -10079,6 +10082,25 @@ string is lexically greater than the second string. For &%gt%& the comparison
 includes the case of letters, whereas for &%gti%& the comparison is
 case-independent.
 
 includes the case of letters, whereas for &%gti%& the comparison is
 case-independent.
 

+.new
+.vitem &*inlist&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
+       &*inlisti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
+.cindex "string" "comparison"
+.cindex "list" "iterative conditions"
+Both strings are expanded; the second string is treated as a list of simple
+strings; if the first string is a member of the second, then the condition
+is true.
+
+These are simpler to use versions of the more powerful &*forany*& condition.
+Examples, and the &*forany*& equivalents:
+.code
+${if inlist{needle}{foo:needle:bar}}
+  ${if forany{foo:needle:bar}{eq{$item}{needle}}}
+${if inlisti{Needle}{fOo:NeeDLE:bAr}}
+  ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
+.endd
+.wen
+

 .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
        &*isip4&~{*&<&'string'&>&*}*& &&&
        &*isip6&~{*&<&'string'&>&*}*&
 .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
        &*isip4&~{*&<&'string'&>&*}*& &&&
        &*isip6&~{*&<&'string'&>&*}*&


@@ -10189,10 +10211,12 @@ See &*match_local_part*&.
 
 .vitem &*match_ip&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
 .cindex "&%match_ip%& expansion condition"
 
 .vitem &*match_ip&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
 .cindex "&%match_ip%& expansion condition"

+.new

 This condition matches an IP address to a list of IP address patterns. It must
 be followed by two argument strings. The first (after expansion) must be an IP
 This condition matches an IP address to a list of IP address patterns. It must
 be followed by two argument strings. The first (after expansion) must be an IP

-address or an empty string. The second (after expansion) is a restricted host
+address or an empty string. The second (not expanded) is a restricted host

 list that can match only an IP address, not a host name. For example:
 list that can match only an IP address, not a host name. For example:

+.wen

 .code
 ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
 .endd
 .code
 ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
 .endd


@@ -10238,6 +10262,11 @@ just as easy to use the fact that a lookup is itself a condition, and write:
 .endd
 .endlist ilist
 
 .endd
 .endlist ilist
 

+.new
+Note that <&'string2'&> is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+.wen
+

 Consult section &<<SECThoslispatip>>& for further details of these patterns.
 
 .vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
 Consult section &<<SECThoslispatip>>& for further details of these patterns.
 
 .vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&


@@ -10265,6 +10294,11 @@ item can be used, as in all address lists, to cause subsequent items to
 have their local parts matched casefully. Domains are always matched
 caselessly.
 
 have their local parts matched casefully. Domains are always matched
 caselessly.
 

+.new
+Note that <&'string2'&> is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+.wen
+

 &*Note*&: Host lists are &'not'& supported in this way. This is because
 hosts have two identities: a name and an IP address, and it is not clear
 how to specify cleanly how such a test would work. However, IP addresses can be
 &*Note*&: Host lists are &'not'& supported in this way. This is because
 hosts have two identities: a name and an IP address, and it is not clear
 how to specify cleanly how such a test would work. However, IP addresses can be


@@ -10632,7 +10666,7 @@ number of lines in the message's body. See also &$message_linecount$&.
 .cindex "binary zero" "in message body"
 .vindex "&$body_zerocount$&"
 When a message is being received or delivered, this variable contains the
 .cindex "binary zero" "in message body"
 .vindex "&$body_zerocount$&"
 When a message is being received or delivered, this variable contains the

-number of binary zero bytes in the message's body.
+number of binary zero bytes (ASCII NULs) in the message's body.

 
 .vitem &$bounce_recipient$&
 .vindex "&$bounce_recipient$&"
 
 .vitem &$bounce_recipient$&
 .vindex "&$bounce_recipient$&"


@@ -11750,6 +11784,16 @@ command in a filter file. Its use is explained in the description of that
 command, which can be found in the separate document entitled &'Exim's
 interfaces to mail filtering'&.
 
 command, which can be found in the separate document entitled &'Exim's
 interfaces to mail filtering'&.
 

+.new
+.vitem &$tls_bits$&
+.vindex "&$tls_bits$&"
+Contains an approximation of the TLS cipher's bit-strength; the meaning of
+this depends upon the TLS implementation used.
+If TLS has not been negotiated, the value will be 0.
+The value of this is automatically fed into the Cyrus SASL authenticator
+when acting as a server, to specify the "external SSF" (a SASL term).
+.wen
+

 .vitem &$tls_certificate_verified$&
 .vindex "&$tls_certificate_verified$&"
 This variable is set to &"1"& if a TLS certificate was verified when the
 .vitem &$tls_certificate_verified$&
 .vindex "&$tls_certificate_verified$&"
 This variable is set to &"1"& if a TLS certificate was verified when the


@@ -13042,7 +13086,7 @@ section &<<SECTcallvercache>>& for details of the caching.
 This option defines the &"random"& local part that can be used as part of
 callout verification. The default value is
 .code
 This option defines the &"random"& local part that can be used as part of
 callout verification. The default value is
 .code

-$primary_host_name-$tod_epoch-testing
+$primary_hostname-$tod_epoch-testing

 .endd
 See section &<<CALLaddparcall>>& for details of how this value is used.
 
 .endd
 See section &<<CALLaddparcall>>& for details of how this value is used.
 


@@ -14169,6 +14213,10 @@ probably safest to just set it to a little larger than this value.  Eg, with a
 default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
 some problems may result.
 
 default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
 some problems may result.
 

+A value of 0 will disable size limit checking; Exim will still advertise the
+SIZE extension in an EHLO response, but without a limit, so as to permit
+SMTP clients to still indicate the message size along with the MAIL verb.
+

 
 .option move_frozen_messages main boolean false
 .cindex "frozen messages" "moving"
 
 .option move_frozen_messages main boolean false
 .cindex "frozen messages" "moving"


@@ -19955,13 +20003,16 @@ This option applies only to deliveries in maildir format, and is described in
 section &<<SECTmaildirdelivery>>& below.
 
 
 section &<<SECTmaildirdelivery>>& below.
 
 

-.option maildir_use_size_file appendfile boolean false
+.new
+.option maildir_use_size_file appendfile&!! boolean false

 .cindex "maildir format" "&_maildirsize_& file"
 .cindex "maildir format" "&_maildirsize_& file"

-Setting this option true enables support for &_maildirsize_& files. Exim
+The result of string expansion for this option must be a valid boolean value.
+If it is true, it enables support for &_maildirsize_& files. Exim

 creates a &_maildirsize_& file in a maildir if one does not exist, taking the
 quota from the &%quota%& option of the transport. If &%quota%& is unset, the
 value is zero. See &%maildir_quota_directory_regex%& above and section
 &<<SECTmaildirdelivery>>& below for further details.
 creates a &_maildirsize_& file in a maildir if one does not exist, taking the
 quota from the &%quota%& option of the transport. If &%quota%& is unset, the
 value is zero. See &%maildir_quota_directory_regex%& above and section
 &<<SECTmaildirdelivery>>& below for further details.

+.wen

 
 .option maildirfolder_create_regex appendfile string unset
 .cindex "maildir format" "&_maildirfolder_& file"
 
 .option maildirfolder_create_regex appendfile string unset
 .cindex "maildir format" "&_maildirfolder_& file"


@@ -24588,8 +24639,14 @@ DHE_DSS). The default list contains RSA, DHE_DSS, DHE_RSA.
 For &%gnutls_require_mac%&, the recognized names are SHA (synonym SHA1), and
 MD5. The default list contains SHA, MD5.
 
 For &%gnutls_require_mac%&, the recognized names are SHA (synonym SHA1), and
 MD5. The default list contains SHA, MD5.
 

-For &%gnutls_require_protocols%&, the recognized names are TLS1 and SSL3.
-The default list contains TLS1, SSL3.
+.new
+For &%gnutls_require_protocols%&, the recognized names are TLS1.2, TLS1.1,
+TLS1.0, (TLS1) and SSL3.
+The default list contains TLS1.2, TLS1.1, TLS1.0, SSL3.
+TLS1 is an alias for TLS1.0, for backwards compatibility.
+For sufficiently old versions of the GnuTLS library, TLS1.2 or TLS1.1 might
+not be supported and will not be recognised by Exim.
+.wen

 
 In a server, the order of items in these lists is unimportant. The server
 advertises the availability of all the relevant cipher suites. However, in a
 
 In a server, the order of items in these lists is unimportant. The server
 advertises the availability of all the relevant cipher suites. However, in a


@@ -27342,7 +27399,7 @@ checks.
 
 The &%per_*%& options described above do not make sense in some ACLs. If you
 use a &%per_*%& option in an ACL where it is not normally permitted then the
 
 The &%per_*%& options described above do not make sense in some ACLs. If you
 use a &%per_*%& option in an ACL where it is not normally permitted then the

-update mode defaults to &%readonly%& and you cannot specify the &%strict&% or
+update mode defaults to &%readonly%& and you cannot specify the &%strict%& or

 &%leaky%& modes. In other ACLs the default update mode is &%leaky%& (see the
 next section) so you must specify the &%readonly%& option explicitly.
 
 &%leaky%& modes. In other ACLs the default update mode is &%leaky%& (see the
 next section) so you must specify the &%readonly%& option explicitly.
 


@@ -27396,7 +27453,7 @@ go over the limit is not added to the set, in the same way that the client's
 recorded rate is not updated in the same situation.
 
 When you combine the &%unique=%& and &%readonly%& options, the specific
 recorded rate is not updated in the same situation.
 
 When you combine the &%unique=%& and &%readonly%& options, the specific

-%&unique=%& value is ignored, and Exim just retrieves the client's stored
+&%unique=%& value is ignored, and Exim just retrieves the client's stored

 rate.
 
 The &%unique=%& mechanism needs more space in the ratelimit database than the
 rate.
 
 The &%unique=%& mechanism needs more space in the ratelimit database than the


@@ -27732,7 +27789,7 @@ check for a &"random"& local part at the same domain. The local part is not
 really random &-- it is defined by the expansion of the option
 &%callout_random_local_part%&, which defaults to
 .code
 really random &-- it is defined by the expansion of the option
 &%callout_random_local_part%&, which defaults to
 .code

-$primary_host_name-$tod_epoch-testing
+$primary_hostname-$tod_epoch-testing

 .endd
 The idea here is to try to determine whether the remote host accepts all local
 parts without checking. If it does, there is no point in doing callouts for
 .endd
 The idea here is to try to determine whether the remote host accepts all local
 parts without checking. If it does, there is no point in doing callouts for


@@ -34992,7 +35049,7 @@ integer size comparisons against this value.
 A colon-separated list of names of headers included in the signature.
 .vitem &%$dkim_key_testing%&
 "1" if the key record has the "testing" flag set, "0" if not.
 A colon-separated list of names of headers included in the signature.
 .vitem &%$dkim_key_testing%&
 "1" if the key record has the "testing" flag set, "0" if not.

-.vitem &%$dkim_key_nosubdomaining%&
+.vitem &%$nosubdomains%&

 "1" if the key record forbids subdomaining, "0" otherwise.
 .vitem &%$dkim_key_srvtype%&
 Service type (tag s=) from the key record. Defaults to "*" if not specified
 "1" if the key record forbids subdomaining, "0" otherwise.
 .vitem &%$dkim_key_srvtype%&
 Service type (tag s=) from the key record. Defaults to "*" if not specified