-. $Cambridge: exim/doc/doc-src/spec.src,v 1.5 2005/01/27 10:25:35 ph10 Exp $
+. $Cambridge: exim/doc/doc-src/spec.src,v 1.8 2005/02/17 11:58:25 ph10 Exp $
.
.set version "4.50"
.set previousversion "4.40"
.section Mailing lists
.index mailing lists||for Exim users
-The following are the two main Exim mailing lists:
+.em
+The following are the three main Exim mailing lists:
.display rm
.tabs 28
$it{exim-users@@exim.org} $t general discussion list
+$it{exim-dev@@exim.org} $t discussion of bugs, enhancements, etc.
$it{exim-announce@@exim.org} $t moderated, low volume announcements list
.endd
+.nem
You can subscribe to these lists, change your existing subscriptions, and view
or search the archives via the
.if ~~html
.em
As part of its operation, \-bV-\ causes Exim to read and syntax check its
configuration file. However, this is a static check only. It cannot check
-values that to be expanded. You cannot rely on \-bV-\ alone to discover (for
-example) all the typos in the configuration; some realistic testing is needed.
-The \-bh-\ and \-N-\ options provide more dynamic testing facilities.
+values that are to be expanded. For example, although a misspelt ACL verb is
+detected, an error in the verb's arguments is not. You cannot rely on \-bV-\
+alone to discover (for example) all the typos in the configuration; some
+realistic testing is needed. The \-bh-\ and \-N-\ options provide more dynamic
+testing facilities.
.nem
Like \%lsearch%\, the testing is done case-insensitively. The following forms
of wildcard are recognized:
.numberpars "$*$"
-The string may begin with an asterisk to mean `begins with'. For example:
+The string may begin with an asterisk to mean `ends with'. For example:
.display asis
*.a.b.c data for anything.a.b.c
*fish data for anythingfish
.em
.tempindent 0
-\$demime@_$\\*xxx*\: Two variables whose names start with \$demime$\ are
-available when Exim is compiled with the content-scanning extension and the
-obsolete \demime\ condition. For details, see section ~~SECTdemimecond.
+\$demime@_errorlevel$\: This variable is available when Exim is compiled with
+the content-scanning extension and the obsolete \demime\ condition. For
+details, see section ~~SECTdemimecond.
+
+.tempindent 0
+\$demime@_reason$\: This variable is available when Exim is compiled with the
+content-scanning extension and the obsolete \demime\ condition. For details,
+see section ~~SECTdemimecond.
.nem
.index black list (DNS)
.em
.tempindent 0
-\$mime@_$\\*xxx*\:
-A number of variables whose names start with \$mime$\ are available when Exim
-is compiled with the content-scanning extension. For details, see section
-~~SECTscanmimepart.
+\$mime@_$\\*xxx*\: A number of variables whose names start with \$mime$\ are
+available when Exim is compiled with the content-scanning extension. For
+details, see section ~~SECTscanmimepart.
.nem
.tempindent 0
message was received over an encrypted SMTP connection and the client was
successfully authenticated.
-Exim also uses the protocol name `smtps' for the rare situation where the
-client initially used \\EHLO\\, set up an encrypted connection using
-\\STARTTLS\\, and then used \\HELO\\ afterwards to initiate the encrypted
-session.
+Exim uses the protocol name `smtps' for the case when encryption is
+automatically set up on connection without the use of \\STARTTLS\\ (see
+\tls@_on@_connect@_ports\), and the client uses \\HELO\\ to initiate the
+encrypted SMTP session. The name `smtps' is also used for the rare situation
+where the client initially uses \\EHLO\\, sets up an encrypted connection using
+\\STARTTLS\\, and then uses \\HELO\\ afterwards.
The \-oMr-\ option provides a way of specifying a custom protocol name for
messages that are injected locally by trusted callers. This is commonly used to
.em
.section Use of standard output and error by Perl
+.index Perl||standard output and error
You should not write to the standard error or output streams from within your
-Perl code, as it is not defined how these are set up. In versions of Exim up to
-at least 4.50, it is possible for the standard output or error to refer to the
-SMTP connection during message reception. Writing to this stream is likely to
-cause chaos. Something may be done about this in later releases.
-
-Unfortunately, the Perl \warn\ statment writes to the standard error stream,
-and this may be embedded in Perl modules that you use, but over which you have
-no control. One way round this is to ensure that the following Perl magic is
-obeyed before \warn\ is used:
-.display asis
-$SIG{__WARN__} = sub { Exim::log_write($_[0]) };
-.endd
-This causes the output of the \warn\ statement to be written to Exim's log
-file.
+Perl code, as it is not defined how these are set up. In versions of Exim
+before 4.50, it is possible for the standard output or error to refer to the
+SMTP connection during message reception via the daemon. Writing to this stream
+is certain to cause chaos. From Exim 4.50 onwards, the standard output and
+error streams are connected to \(/dev/null)\ in the daemon. The chaos is
+avoided, but the output is lost.
+
+.index Perl||\warn\, use of
+The Perl \warn\ statement writes to the standard error stream by default. Calls
+to \warn\ may be embedded in Perl modules that you use, but over which you have
+no control. When Exim starts up the Perl interpreter, it arranges for output
+from the \warn\ statement to be written to the Exim main log. You can change
+this by including appropriate Perl magic somewhere in your Perl code. For
+example, to discard \warn\ output completely, you need this:
+.display asis
+$SIG{__WARN__} = sub { };
+.endd
+Whenever a \warn\ is obeyed, the anonymous subroutine is called. In this
+example, the code for the subroutine is empty, so it does nothing, but you can
+include any Perl code that you like. The text of the \warn\ message is passed
+as the first subroutine argument.
.nem
.em
-.section Support for the obsolete SSMTP protocol
+.section Support for the obsolete SSMTP (or SMTPS) protocol
.rset SECTsupobssmt "~~chapter.~~section"
.index ssmtp protocol
+.index smtps protocol
.index SMTP||ssmtp protocol
-Exim supports the obsolete SSMTP protocol that was used before the \\STARTTLS\\
-command was standardized for SMTP. Some legacy clients still use this protocol.
-If the \tls@_on@_connect@_ports\ option is set to a list of port numbers,
-connections to those ports must use SSMTP. The most common use of this option
-is expected to be
+.index SMTP||smtps protocol
+Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used
+before the \\STARTTLS\\ command was standardized for SMTP. Some legacy clients
+still use this protocol. If the \tls@_on@_connect@_ports\ option is set to a
+list of port numbers, connections to those ports must use SSMTP. The most
+common use of this option is expected to be
.display asis
tls_on_connect_ports = 465
.endd
\tls@_dhparam\ $t$rm{DH parameters for server}
.newline
.em
-\tls@_on@_connect@_ports\ $t$rm{specify SSMTP ports}
+\tls@_on@_connect@_ports\ $t$rm{specify SSMTP (SMTPS) ports}
.nem
.newline
\tls@_privatekey\ $t$rm{location of server private key}
This option defines the ACL that is run when a non-SMTP message is on the point
of being accepted. See chapter ~~CHAPACL for further details.
-.index ~~ACL||on SMTP connection
-.conf acl@_smtp@_connect string$**$ unset
-This option defines the ACL that is run when an SMTP connection is received.
-See chapter ~~CHAPACL for further details.
-
.index ~~ACL||setting up for SMTP commands
.index \\AUTH\\||ACL for
.conf acl@_smtp@_auth string$**$ unset
This option defines the ACL that is run when an SMTP \\AUTH\\ command is
received. See chapter ~~CHAPACL for further details.
+.index ~~ACL||on SMTP connection
+.conf acl@_smtp@_connect string$**$ unset
+This option defines the ACL that is run when an SMTP connection is received.
+See chapter ~~CHAPACL for further details.
+
.index \\DATA\\, ACL for
.conf acl@_smtp@_data string$**$ unset
This option defines the ACL that is run after an SMTP \\DATA\\ command has been
.index queue runner||processing messages in order
If this option is set, queue runs happen in order of message arrival instead of
in an arbitrary order. For this to happen, a complete list of the entire queue
-must be set up before the deliveries start. When the queue is all in a single
-directory (the default), this happens anyway, but if \split@_spool@_directory\
-is set it does not -- for delivery in random order, the sub-directories are
-processed one at a time (in random order), to avoid setting up one huge list.
-Thus, setting \queue@_run@_in@_order\ with \split@_spool@_directory\ may
-degrade performance when the queue is large. In most situations,
-\queue@_run@_in@_order\ should not be set.
+must be set up before the deliveries start. When the queue is all held in a
+single directory (the default),
+.em
+a single list is created for both the ordered and the non-ordered cases.
+However, if \split@_spool@_directory\ is set, a single list is not created when
+\queue@_run@_in@_order\ is false. In this case, the sub-directories are
+processed one at a time (in a random order), and this avoids setting up one
+huge list for the whole queue. Thus, setting \queue@_run@_in@_order\ with
+\split@_spool@_directory\ may degrade performance when the queue is large,
+because of the extra work in setting up the single, large list. In most
+situations, \queue@_run@_in@_order\ should not be set.
+.nem
.conf queue@_run@_max integer 5
.index queue runner||maximum number of
responses. For example, it is used as domain name in the response to an
incoming \\HELO\\ or \\EHLO\\ command.
.em
+It is also used in \\HELO\\ commands for callout verification.
The active hostname is placed in the \$smtp__active__hostname$\ variable, which
is saved with any messages that are received. It is therefore available for use
in routers and transports when the message is later delivered.
.em
.conf tls@_on@_connect@_ports "string list" unset
-This option specifies a list of incoming SSMTP ports that should operate the
-obsolete SSMTP protocol, where a TLS session is immediately set up without
-waiting for the client to issue a \\STARTTLS\\ command. For further details,
-see section ~~SECTsupobssmt.
+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
+further details, see section ~~SECTsupobssmt.
.nem
.conf tls@_privatekey string$**$ unset
X.Employee: :fail: Gone away, no forwarding address
.endd
In the case of an address that is being verified from an ACL or as the subject
-of a \\VRFY\\ command, the text is included in the SMTP error response by
-default. In an ACL, an explicitly provided message overrides the default, but
-the default message is available in the variable \$acl@_verify@_message$\ and
-can therefore be included in a custom message if this is desired. Exim sends a
-451 SMTP code for a :::defer::, and 550 for :::fail::. In non-SMTP cases the
-text is included in the error message that Exim generates.
+of a
+.index \\VRFY\\||error text, display of
+\\VRFY\\ command, the text is included in the SMTP error response by
+default.
+.em
+.index \\EXPN\\||error text, display of
+The text is not included in the response to an \\EXPN\\ command.
+.nem
+
+In an ACL, an explicitly provided message overrides the default, but the
+default message is available in the variable \$acl@_verify@_message$\ and can
+therefore be included in a custom message if this is desired. Exim sends a 451
+SMTP code for a :::defer::, and 550 for :::fail::. In non-SMTP cases the text
+is included in the error message that Exim generates.
return code that is neither zero nor one of the return codes listed in
\temp@_errors\ (that is, the delivery failed), the first line of output is
written to the main log.
+.em
+This option and \log@_output\ are mutually exclusive. Only one of them may be
+set.
+.nem
.conf log@_output boolean false
If this option is set and the command returns any output, the first line of
output is written to the main log, whatever the return code.
+.em
+This option and \log@_fail@_output\ are mutually exclusive. Only one of them
+may be set.
+.nem
.conf max@_output integer 20K
This specifies the maximum amount of output that the command may produce on its
is, the delivery failed), the output is returned in the bounce message.
However, if the message has a null sender (that is, it is itself a bounce
message), output from the command is discarded.
+.em
+This option and \return@_output\ are mutually exclusive. Only one of them may
+be set.
+.nem
.conf return@_output boolean false
If this option is true, and the command produced any output, the delivery is
However, if the message has a null sender (that is, it is a bounce message),
output from the command is always discarded, whatever the setting of this
option.
+.em
+This option and \return@_fail@_output\ are mutually exclusive. Only one of them
+may be set.
+.nem
.conf temp@_errors "string list" "see below"
.index \%pipe%\ transport||temporary failure
library implementation of the RFC 2222 (`Simple Authentication and Security
Layer'). This library supports a number of authentication mechanisms, including
PLAIN and LOGIN, but also several others that Exim does not support directly.
+In particular, there is support for Kerberos authentication.
+
The \%cyrus@_sasl%\ authenticator provides a gatewaying mechanism directly to
the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5,
then so can the \%cyrus@_sasl%\ authenticator. By default it uses the public
.em
-.section Support for the legacy `ssmtp' protocol
+.section Support for the legacy `ssmtp' (aka `smtps') protocol
.index ssmtp protocol
+.index smtps protocol
.index SMTP||ssmtp protocol
+.index SMTP||smtps protocol
Early implementations of encrypted SMTP used a different TCP port from normal
SMTP, and expected an encryption negotiation to start immediately, instead of
waiting for a \\STARTTLS\\ command from the client using the standard SMTP
-port. The protocol was called `ssmtp' and port 465 was allocated for this
-purpose.
+port. The protocol was called `ssmtp' or `smtps', and port 465 was allocated
+for this purpose.
This approach was abandoned when encrypted SMTP was standardised, but there are
still some legacy clients that use it. Exim supports these clients by means of
~~SECTaddressverification. Exim caches the result of sender verification, to
avoid doing it more than once per message.
-.item "verify = sender=address/<<options>>"
+.item "verify = sender=<<address>>/<<options>>"
.index \verify\, ACL condition
This is a variation of the previous option, in which a modified address is
verified as a sender.
.index virus scanners||command line interface
\cmdline\: This is the keyword for the generic command line scanner interface.
It can be used to attach virus scanners that are invoked from the shell. This
-scanner type takes 3 mantadory options:
+scanner type takes 3 mandatory options:
.numberpars
The full path and name of the scanner binary, with all command line options,
and a placeholder (%s) for the directory to scan.
git://git.exim.org / users / jgh / exim.git / blobdiff