Docs: clarify notes on .ifdef Bug 1155
[exim.git] / doc / doc-docbook / spec.xfpt
index c1668c7ac472d236c72e4856275ebff858b5244a..09ce793b0be637e7e340452ab05454b2acc25aba 100644 (file)
@@ -52,7 +52,7 @@
 .set I   "    "
 
 .macro copyyear
-2014
+2015
 .endmacro
 
 . /////////////////////////////////////////////////////////////////////////////
@@ -5010,7 +5010,8 @@ message_size_limit = 50M
 message_size_limit = 100M
 .endif
 .endd
-sets a message size limit of 50M if the macro &`AAA`& is defined, and 100M
+sets a message size limit of 50M if the macro &`AAA`& is defined
+(or &`A`& or &`AA`&), and 100M
 otherwise. If there is more than one macro named on the line, the condition
 is true if any of them are defined. That is, it is an &"or"& condition. To
 obtain an &"and"& condition, you need to use nested &`.ifdef`&s.
@@ -5598,6 +5599,13 @@ find that they send unqualified addresses. The two commented-out options:
 show how you can specify hosts that are permitted to send unqualified sender
 and recipient addresses, respectively.
 
+The &%log_selector%& option is used to increase the detail of logging
+over the default:
+.code
+log_selector = +smtp_protocol_error +smtp_syntax_error \
+               +tls_certificate_verified
+.endd
+
 The &%percent_hack_domains%& option is also commented out:
 .code
 # percent_hack_domains =
@@ -9031,6 +9039,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.
 
+
+.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"
@@ -11318,6 +11350,34 @@ This variable is available when Exim is compiled with the
 content-scanning extension and the obsolete &%demime%& condition. For details,
 see section &<<SECTdemimecond>>&.
 
+.vitem &$dkim_cur_signer$& &&&
+       &$dkim_verify_status$& &&&
+       &$dkim_verify_reason$& &&&
+       &$dkim_domain$& &&&
+       &$dkim_identity$& &&&
+       &$dkim_selector$& &&&
+       &$dkim_algo$& &&&
+       &$dkim_canon_body$& &&&
+       &$dkim_canon_headers$& &&&
+       &$dkim_copiedheaders$& &&&
+       &$dkim_bodylength$& &&&
+       &$dkim_created$& &&&
+       &$dkim_expires$& &&&
+       &$dkim_headernames$& &&&
+       &$dkim_key_testing$& &&&
+       &$dkim_key_nosubdomains$& &&&
+       &$dkim_key_srvtype$& &&&
+       &$dkim_key_granularity$& &&&
+       &$dkim_key_notes$&
+These variables are only available within the DKIM ACL.
+For details see chapter &<<CHAPdkim>>&.
+
+.vitem &$dkim_signers$&
+.vindex &$dkim_signers$&
+When a message has been received this variable contains
+a colon-separated list of signer domains and identities for the message.
+For details see chapter &<<CHAPdkim>>&.
+
 .vitem &$dnslist_domain$& &&&
        &$dnslist_matched$& &&&
        &$dnslist_text$& &&&
@@ -11415,7 +11475,7 @@ This variable contains the numerical value of the Exim user id.
 
 .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.
@@ -11681,6 +11741,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.
+.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.
@@ -12198,6 +12259,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.
 
+.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
@@ -12227,6 +12296,7 @@ resolver library states that both
 the reverse and forward DNS were authenticated data.  At all
 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
@@ -13367,6 +13437,7 @@ listed in more than one group.
 .row &%tls_crl%&                     "certificate revocation list"
 .row &%tls_dh_max_bits%&             "clamp D-H bit count suggestion"
 .row &%tls_dhparam%&                 "DH parameters for server"
+.row &%tls_eccurve%&                 "EC curve selection for server"
 .row &%tls_ocsp_file%&               "location of server certificate status proof"
 .row &%tls_on_connect_ports%&        "specify SSMTP (SMTPS) ports"
 .row &%tls_privatekey%&              "location of server private key"
@@ -13421,6 +13492,7 @@ listed in more than one group.
 See also the &'Policy controls'& section above.
 
 .table2
+.row &%dkim_verify_signers%&         "DKIM domain for which DKIM ACL is run"
 .row &%host_lookup%&                 "host name looked up for these hosts"
 .row &%host_lookup_order%&           "order of DNS and local name lookups"
 .row &%recipient_unqualified_hosts%& "may send unqualified recipients"
@@ -13629,6 +13701,12 @@ is run for each recipient after an SMTP DATA command has been
 processed and the message itself has been received, but before the
 acknowledgment is sent. See chapter &<<CHAPACL>>& for further details.
 
+.option acl_smtp_dkim main string&!! unset
+.cindex DKIM "ACL for"
+This option defines the ACL that is run for each DKIM signature
+of a received message.
+See chapter &<<CHAPdkim>>& for further details.
+
 .option acl_smtp_etrn main string&!! unset
 .cindex "ETRN" "ACL for"
 This option defines the ACL that is run when an SMTP ETRN command is
@@ -14104,6 +14182,14 @@ etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines
 to handle IPv6 literal addresses.
 
 
+.option dkim_verify_signers main "domain list&!!" $dkim_signers
+.cindex DKIM "controlling calls to the ACL"
+This option gives a list of DKIM domains for which the DKIM ACL is run.
+It is expanded after the message is received; by default it runs
+the ACL once for each signature in the message.
+See chapter &<<CHAPdkim>>&.
+
+
 .option dns_again_means_nonexist main "domain list&!!" unset
 .cindex "DNS" "&""try again""& response; overriding"
 DNS lookups give a &"try again"& response for the DNS errors
@@ -14535,14 +14621,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
-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.
 
+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"
@@ -14916,8 +15005,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
-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
@@ -16539,7 +16629,22 @@ prior to the 4.80 release, as Debian used to patch Exim to raise the minimum
 acceptable bound from 1024 to 2048.
 
 
+.option tls_eccurve main string&!! prime256v1
+.cindex TLS "EC cryptography"
+If built with a recent-enough version of OpenSSL,
+this option selects a EC curve for use by Exim.
+
+Curve names of the form &'prime256v1'& are accepted.
+For even more-recent library versions, names of the form &'P-512'&
+are also accepted, plus the special value &'auto'&
+which tell the library to choose.
+
+If the option is set to an empty string, no EC curves will be enabled.
+
+
 .option tls_ocsp_file main string&!! unset
+.cindex TLS "certificate status"
+.cindex TLS "OCSP proof file"
 This option
 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
@@ -16547,6 +16652,8 @@ Certificate Authority.
 
 
 .option tls_on_connect_ports main "string list" unset
+.cindex SSMTP
+.cindex SMTPS
 This option specifies a list of incoming SSMTP (aka SMTPS) ports that should
 operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately
 set up without waiting for the client to issue a STARTTLS command. For
@@ -24828,6 +24935,7 @@ AUTH_GSASL=yes
 AUTH_HEIMDAL_GSSAPI=yes
 AUTH_PLAINTEXT=yes
 AUTH_SPA=yes
+AUTH_TLS=yes
 .endd
 in &_Local/Makefile_&, respectively. The first of these supports the CRAM-MD5
 authentication mechanism (RFC 2195), and the second provides an interface to
@@ -24842,6 +24950,8 @@ The sixth can be configured to support
 the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is
 not formally documented, but used by several MUAs. The seventh authenticator
 supports Microsoft's &'Secure Password Authentication'& mechanism.
+The eighth is an Exim authenticator but not an SMTP one;
+instead it can use information from a TLS negotiation.
 
 The authenticators are configured using the same syntax as other drivers (see
 section &<<SECTfordricon>>&). If no authenticators are required, no
@@ -25561,7 +25671,7 @@ cyrusless_crammd5:
   driver = cram_md5
   public_name = CRAM-MD5
   server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
-                  dbmjz{/etc/sasldb2}}
+                  dbmjz{/etc/sasldb2}{$value}fail}
   server_set_id = $auth1
 .endd
 
@@ -26048,6 +26158,81 @@ msn:
 
 
 
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.new
+.chapter "The tls authenticator" "CHAPtlsauth"
+.scindex IIDtlsauth1 "&(tls)& authenticator"
+.scindex IIDtlsauth2 "authenticators" "&(tls)&"
+.cindex "authentication" "Client Certificate"
+.cindex "authentication" "X509"
+.cindex "Certificate-based authentication"
+The &(tls)& authenticator provides server support for
+authentication based on client certificates.
+
+It is not an SMTP authentication mechanism and is not
+advertised by the server as part of the SMTP EHLO response.
+It is an Exim authenticator in the sense that it affects
+the protocol element of the log line, can be tested for
+by the &%authenticated%& ACL condition, and can set
+the &$authenticated_id$& variable.
+
+The client must present a verifiable certificate,
+for which it must have been requested via the
+&%tls_verify_hosts%& or &%tls_try_verify_hosts%& main options
+(see &<<CHAPTLS>>&).
+
+If an authenticator of this type is configured it is
+run before any SMTP-level communication is done,
+and can authenticate the connection.
+If it does, SMTP suthentication is not offered.
+
+A maximum of one authenticator of this type may be present.
+
+
+.cindex "options" "&(tls)& authenticator (server)"
+The &(tls)& authenticator has three server options:
+
+.option server_param1 tls string&!! unset
+.cindex "variables (&$auth1$& &$auth2$& etc)" "in &(tls)& authenticator"
+This option is expanded after the TLS negotiation and
+the result is placed in &$auth1$&.
+If the expansion is forced to fail, authentication fails. Any other expansion
+failure causes a temporary error code to be returned.
+
+.option server_param2 tls string&!! unset
+.option server_param3 tls string&!! unset
+As above, for &$auth2$& and &$auth3$&.
+
+&%server_param1%& may also be spelled &%server_param%&.
+
+
+Example:
+.code
+tls:
+  driver = tls
+  server_param1 =     ${certextract {subj_altname,mail,>:} \
+                                    {$tls_in_peercert}}
+  server_condition =  ${if forany {$auth1} \
+                            {!= {0} \
+                                {${lookup ldap{ldap:///\
+                         mailname=${quote_ldap_dn:${lc:$item}},\
+                         ou=users,LDAP_DC?mailid} {$value}{0} \
+                       }    }   } }
+  server_set_id =     ${if = {1}{${listcount:$auth1}} {$auth1}{}}
+.endd
+.ecindex IIDtlsauth1
+.ecindex IIDtlsauth2
+.wen
+
+
+Note that because authentication is traditionally an SMTP operation,
+the &%authenticated%& ACL condition cannot be used in
+a connect- or helo-ACL.
+
+
+
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
@@ -26976,6 +27161,7 @@ options in the main part of the configuration. These options are:
 .cindex "EXPN" "ACL for"
 .cindex "HELO" "ACL for"
 .cindex "EHLO" "ACL for"
+.cindex "DKIM" "ACL for"
 .cindex "MAIL" "ACL for"
 .cindex "QUIT, ACL for"
 .cindex "RCPT" "ACL for"
@@ -26994,6 +27180,7 @@ options in the main part of the configuration. These options are:
 .irow &%acl_smtp_connect%&     "ACL for start of SMTP connection"
 .irow &%acl_smtp_data%&        "ACL after DATA is complete"
 .irow &%acl_smtp_data_prdr%&   "ACL for each recipient, after DATA is complete"
+.irow &%acl_smtp_dkim%&        "ACL for each DKIM signer"
 .irow &%acl_smtp_etrn%&        "ACL for ETRN"
 .irow &%acl_smtp_expn%&        "ACL for EXPN"
 .irow &%acl_smtp_helo%&        "ACL for HELO or EHLO"
@@ -29523,7 +29710,7 @@ The &%per_rcpt%& option causes Exim to limit the rate at which recipients are
 accepted. It can be used in the &%acl_smtp_rcpt%&, &%acl_smtp_predata%&,
 &%acl_smtp_mime%&, &%acl_smtp_data%&, or &%acl_smtp_rcpt%& ACLs. In
 &%acl_smtp_rcpt%& the rate is updated one recipient at a time; in the other
-ACLs the rate is updated with the total recipient count in one go. Note that
+ACLs the rate is updated with the total (accepted) recipient count in one go. Note that
 in either case the rate limiting engine will see a message with many
 recipients as a large high-speed burst.
 
@@ -34634,8 +34821,9 @@ equivalent to the setting:
 .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.