-. $Cambridge: exim/doc/doc-src/spec.src,v 1.1 2004/10/07 15:04:35 ph10 Exp $
+. $Cambridge: exim/doc/doc-src/spec.src,v 1.2 2005/01/11 15:17:51 ph10 Exp $
.
-.set version "4.40"
-.set previousversion "4.30"
-.set versionmonth "July"
-.set versionyear "2004"
+.set version "4.50"
+.set previousversion "4.40"
+.set versionmonth "January"
+.set versionyear "2005"
.set ACL "ACL"
. The last of those is to make ACL index entries easier to type. It is put
.index CRL $it{see certificate revocation list}
.index delivery||failure report $it{see bounce message}
.index dialup $it{see intermittently connected hosts}
+.index exiscan $it{see content scanning}
.index failover $it{see fallback}
.index fallover $it{see fallback}
.index filter||Sieve $it{see Sieve filter}
.index RBL $it{see DNS list}
.index redirection $it{see address redirection}
.index return path||$it{see also envelope sender}
+.index scanning $it{see content scanning}
.index SSL $it{see TLS}
.index string||expansion $it{see expansion}
.index top bit $it{see 8-bit characters}
BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, FreeBSD, GNU/Hurd, GNU/Linux,
HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, QNX, SCO, SCO
SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly
-Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. Some of these operating
-systems are no longer current and cannot easily be tested, so the configuration
-files may no longer work in practice.
+Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. Some of these operating
+systems are no longer current and cannot easily be tested, so the configuration
+files may no longer work in practice.
There are also configuration files for compiling Exim in the Cygwin environment
that can be installed on systems running Windows. However, this document does
.section Exim documentation
.index documentation
-.em
This edition of the Exim specification applies to version ~~version of Exim.
Substantive changes from the ~~previousversion edition are marked by bars in
the right-hand margin in the PostScript, PDF, and plain text versions of the
document, and by green text in the HTML version, as shown by this paragraph.
Changes are not marked in the Texinfo version, because Texinfo doesn't support
change bars. Minor corrections and rewordings are not marked.
-.nem
This document is very much a reference manual; it is not a tutorial. The reader
is expected to have some familiarity with the SMTP mail transfer protocol and
[(A HREF="http://www.uit.co.uk/exim-book/")]
$it{The Exim SMTP Mail Server},
[(/A)]
-published by UIT Cambridge.
+published by UIT Cambridge.
.else
$it{The Exim SMTP Mail Server}, published by UIT Cambridge
(\?http://www.uit.co.uk/exim-book/?\).
.section FTP and web sites, and mailing list
.index web site
.index FTP site
-The primary distribution site for Exim is an FTP site, whose contents are
+The primary distribution site for Exim is an FTP site, whose contents are
described in \*Where to find the Exim distribution*\ below. In addition,
there is a web site at \?http://www.exim.org?\ by courtesy of Energis Squared,
formerly Planet Online Ltd, who are situated in the UK. The site is mirrored in
(that is, off Exim's queue) and subsequently passed on to the dial-in hosts by
other means.
.nextp
-Although Exim does have some facilities for scanning incoming messages, these
-are not comprehensive enough to do full virus or spam scanning. Such operations
+Although Exim does have some facilities for scanning incoming messages, these
+are not comprehensive enough to do full virus or spam scanning. Such operations
are best carried out using additional specialized software packages.
.endp
.index Samba project
.index Microsoft Secure Password Authentication
Client support for Microsoft's \*Secure Password Authentication*\ is provided
-by code contributed by Marc Prud'hommeaux. Server support was contributed by
+by code contributed by Marc Prud'hommeaux. Server support was contributed by
Tom Kistner. This includes code taken from the Samba project, which is released
under the Gnu GPL.
at Carnegie Mellon University (\?http://www.cmu.edu/computing/?\).}
.newline
.pop
-.endp
+.endp
.if ~~sgcal
.cancelflag $npbracket
.flag $npbracket "(" ")"
individual recipients or the entire message, respectively, at these two points
(see chapter ~~CHAPACL). Denial of access results in an SMTP error code.
.nextp
-An ACL is also available for locally generated, non-SMTP messages. In this
+An ACL is also available for locally generated, non-SMTP messages. In this
case, the only available actions are to accept or deny the entire message.
.nextp
When a message has been received, either from a remote host or from the local
.section User filters
.index filter||introduction
.index Sieve filter
-In a conventional Exim configuration, users are able to run private filters by
-setting up appropriate \(.forward)\ files in their home directories. See
-chapter ~~CHAPredirect (about the \%redirect%\ router) for the configuration
-needed to support this, and the separate document entitled
+In a conventional Exim configuration, users are able to run private filters by
+setting up appropriate \(.forward)\ files in their home directories. See
+chapter ~~CHAPredirect (about the \%redirect%\ router) for the configuration
+needed to support this, and the separate document entitled
.if ~~html
[(A HREF="filter_toc.html")]
.fi
.fi
for user details. Two different kinds of filtering are available:
.numberpars $.
-Sieve filters are written in the standard filtering language that is defined by
+Sieve filters are written in the standard filtering language that is defined by
RFC 3028.
.nextp
-Exim filters are written in a syntax that is unique to Exim, but which is more
+Exim filters are written in a syntax that is unique to Exim, but which is more
powerful than Sieve, which it pre-dates.
.endp
User filters are run as part of the routing process, described below.
characters long. It is divided into three parts, separated by hyphens, for
example \"16VDhn-0001bo-D3"\. Each part is a sequence of letters and digits,
normally encoding numbers in base 62. However, in the Darwin operating
-system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
-(avoiding the use of lower case letters) is used instead, because the message
+system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
+(avoiding the use of lower case letters) is used instead, because the message
id is used to construct file names, and the names of files in those systems are
not case-sensitive.
The detail of the contents of the message id have changed as Exim has evolved.
Earlier versions relied on the operating system not re-using a process id (pid)
within one second. On modern operating systems, this assumption can no longer
-be made, so the algorithm had to be changed. To retain backward compatibility,
-the format of the message id was retained, which is why the following rules are
+be made, so the algorithm had to be changed. To retain backward compatibility,
+the format of the message id was retained, which is why the following rules are
somewhat eccentric:
.numberpars $.
The first six characters of the message id are the time at which the message
users, and the \untrusted@_set@_sender\ option for a way of allowing untrusted
users to change sender addresses.
-Messages received by either of the non-interactive mechanisms are subject to
-checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
-(either over TCP/IP, or interacting with a local process) can be checked by a
-number of ACLs that operate at different times during the SMTP session. Either
-individual recipients, or the entire message, can be rejected if local policy
+Messages received by either of the non-interactive mechanisms are subject to
+checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
+(either over TCP/IP, or interacting with a local process) can be checked by a
+number of ACLs that operate at different times during the SMTP session. Either
+individual recipients, or the entire message, can be rejected if local policy
requirements are not met. The \*local@_scan()*\ function (see chapter
~~CHAPlocalscan) is run for all incoming messages.
are also written to a separate $it{message log} file for each message. These
logs are solely for the benefit of the administrator, and are normally deleted
along with the spool files when processing of a message is complete.
-The use of individual message logs can be disabled by setting
+The use of individual message logs can be disabled by setting
\no@_message@_logs\; this might give an improvement in performance on very
busy systems.
ones are actually used for delivering messages.
.index drivers||instance definition
-Each driver that is specified in the run time configuration is an \*instance*\
-of that particular driver type. Multiple instances are allowed; for example,
-you can set up several different \%smtp%\ transports, each with different
+Each driver that is specified in the run time configuration is an \*instance*\
+of that particular driver type. Multiple instances are allowed; for example,
+you can set up several different \%smtp%\ transports, each with different
option values that might specify different ports or different timeouts. Each
instance has its own identifying name. In what follows we will normally use the
-instance name when discussing one particular instance (that is, one specific
+instance name when discussing one particular instance (that is, one specific
configuration of the driver), and the generic driver name when discussing
the driver's features in general.
.if ~~sys.fancy
.figure "Routing an address" rm
.indent 0
-.call aspic
+.call aspic -sgcal -nv
centre ~~sys.linelength;
magnify 0.8;
boundingbox 30;
The second router does redirection -- also known as aliasing and forwarding.
When it generates one or more new addresses from the original, each of them is
routed independently from the start. Otherwise, the router may cause an address
-to fail, or it may simply decline to handle the address, in which case the
+to fail, or it may simply decline to handle the address, in which case the
address is passed to the next router.
The final router in many configurations is one that checks to see if the
.section Processing an address for verification
.index router||for verification
.index verifying||address, overview
-As well as being used to decide how to deliver to an address, Exim's routers
-are also used for \*address verification*\. Verification can be requested as
-one of the checks to be performed in an ACL for incoming messages, on both
-sender and recipient addresses, and it can be tested using the \-bv-\ and
+As well as being used to decide how to deliver to an address, Exim's routers
+are also used for \*address verification*\. Verification can be requested as
+one of the checks to be performed in an ACL for incoming messages, on both
+sender and recipient addresses, and it can be tested using the \-bv-\ and
\-bvs-\ command line options.
-When an address is being verified, the routers are run in `verify mode'. This
-does not affect the way the routers work, but it is a state that can be
+When an address is being verified, the routers are run in `verify mode'. This
+does not affect the way the routers work, but it is a state that can be
detected. By this means, a router can be skipped or made to behave differently
when verifying. A common example is a configuration in which the first router
sends all messages to a message-scanning program, unless they have been
previously scanned. Thus, the first router accepts all addresses without any
-checking, making it useless for verifying. Normally, the \no@_verify\ option
+checking, making it useless for verifying. Normally, the \no@_verify\ option
would be set for such a router, causing it to be skipped in verify mode.
.numberpars $.
\*accept*\: The router accepts the address, and either queues it for a
transport, or generates one or more `child' addresses. Processing the original
-address ceases,
+address ceases,
.index \unseen\ option
unless the \unseen\ option is set on the router. This option
can be used to set up multiple deliveries with different routing (for example,
.endp
If an address reaches the end of the routers without having been accepted by
any of them, it is bounced as unrouteable.
-The default error message in this situation is `unrouteable address', but you
-can set your own message by making use of the \cannot@_route@_message\ option.
-This can be set for any router; the value from the last router that `saw'
+The default error message in this situation is `unrouteable address', but you
+can set your own message by making use of the \cannot@_route@_message\ option.
+This can be set for any router; the value from the last router that `saw'
the address is used.
Sometimes while routing you want to fail a delivery when some conditions are
met but others are not, instead of passing the address on for further routing.
You can do this by having a second router that explicitly fails the delivery
-when the relevant conditions are met. The \%redirect%\ router has a `fail'
+when the relevant conditions are met. The \%redirect%\ router has a `fail'
facility for this purpose.
removed from the local part before further processing, including the evaluation
of any other conditions.
.nextp
-Routers can be designated for use only when not verifying an address, that is,
-only when routing it for delivery (or testing its delivery routing). If the
-\verify\ option is set false, the router is skipped when Exim is verifying an
+Routers can be designated for use only when not verifying an address, that is,
+only when routing it for delivery (or testing its delivery routing). If the
+\verify\ option is set false, the router is skipped when Exim is verifying an
address.
-Setting the \verify\ option actually sets two options, \verify@_sender\ and
-\verify@_recipient\, which independently control the use of the router for
-sender and recipient verification. You can set these options directly if
+Setting the \verify\ option actually sets two options, \verify@_sender\ and
+\verify@_recipient\, which independently control the use of the router for
+sender and recipient verification. You can set these options directly if
you want a router to be used for only one type of verification.
.nextp
-If the \address@_test\ option is set false, the router is skipped when Exim is
-run with the \-bt-\ option to test an address routing. This can be helpful when
-the first router sends all new messages to a scanner of some sort; it makes it
+If the \address@_test\ option is set false, the router is skipped when Exim is
+run with the \-bt-\ option to test an address routing. This can be helpful when
+the first router sends all new messages to a scanner of some sort; it makes it
possible to use \-bt-\ to test subsequent delivery routing without having to
simulate the effect of the scanner.
.nextp
.nextp
If the \check@_local@_user\ option is set, the local part must be the name of
an account on the local host.
-If this check succeeds, the uid and gid of the local user are placed in
+If this check succeeds, the uid and gid of the local user are placed in
\$local@_user@_uid$\ and \$local@_user@_gid$\; these values can be used in the
remaining preconditions.
.nextp
If the \router@_home@_directory\ option is set, it is expanded at this point,
-because it overrides the value of \$home$\. If this expansion were left till
-later, the value of \$home$\ as set by \check@_local@_user\ would be used in
-subsequent tests. Having two different values of \$home$\ in the same router
+because it overrides the value of \$home$\. If this expansion were left till
+later, the value of \$home$\ as set by \check@_local@_user\ would be used in
+subsequent tests. Having two different values of \$home$\ in the same router
could lead to confusion.
.nextp
If the \senders\ option is set, the envelope sender address must be in the set
to Exim (`the Exim user'), but in this case, several remote deliveries can be
run in parallel. The maximum number of simultaneous remote deliveries for any
one message is set by the \remote@_max@_parallel\ option.
-.em
-The order in which deliveries are done is not defined, except that all local
+The order in which deliveries are done is not defined, except that all local
deliveries happen before any remote deliveries.
-.nem
.nextp
.index queue runner
When it encounters a local delivery during a queue run, Exim checks its retry
If a host is unreachable for a period of time, a number of messages may be
waiting for it by the time it recovers, and sending them in a single SMTP
connection is clearly beneficial. Whenever a delivery to a remote host is
-deferred,
+deferred,
.index hints database
Exim makes a note in its hints database, and whenever a successful
SMTP delivery has happened, it looks to see if any other messages are waiting
.if !~~sys.fancy && ~~sgcal
.tabs 16
.else
-.tabs 22
+.tabs 22
.fi
\(ACKNOWLEDGMENTS)\ $t contains some acknowledgments
.newline
DBMLIB = -ldb
DBMLIB = -ltdb
.endd
-Settings like that will work if the DBM library is installed in the standard
+Settings like that will work if the DBM library is installed in the standard
place. Sometimes it is not, and the library's header file may also not be in
the default path. You may need to set \\INCLUDE\\ to specify where the header
-file is, and to specify the path to the library more fully in \\DBMLIB\\, as in
+file is, and to specify the path to the library more fully in \\DBMLIB\\, as in
this example:
.display asis
INCLUDE=-I/usr/local/include/db-4.1
.section Support for iconv()
.index \*iconv()*\ support
-The contents of header lines in messages may be encoded according to the rules
-described RFC 2047. This makes it possible to transmit characters that are not
-in the ASCII character set, and to label them as being in a particular
-character set. When Exim is inspecting header lines by means of the \@$h@_\
-mechanism, it decodes them, and translates them into a specified character set
+The contents of header lines in messages may be encoded according to the rules
+described RFC 2047. This makes it possible to transmit characters that are not
+in the ASCII character set, and to label them as being in a particular
+character set. When Exim is inspecting header lines by means of the \@$h@_\
+mechanism, it decodes them, and translates them into a specified character set
(default ISO-8859-1). The translation is possible only if the operating system
supports the \*iconv()*\ function.
very many conversions. The GNU \libiconv\ library (available from
\?http:/@/www.gnu.org/software/libiconv/?\) can be installed on such systems to
remedy this deficiency, as well as on systems that do not supply \*iconv()*\ at
-all. After installing \libiconv\, you should add
+all. After installing \libiconv\, you should add
.display asis
-HAVE_ICONV=yes
-.endd
+HAVE_ICONV=yes
+.endd
to your \(Local/Makefile)\ and rebuild Exim.
.index OpenSSL||building Exim with
.index GnuTLS||building Exim with
Exim can be built to support encrypted SMTP connections, using the \\STARTTLS\\
-command as per RFC 2487. It can also support legacy clients that expect to
-start a TLS session immediately on connection to a non-standard port (see the
+command as per RFC 2487. It can also support legacy clients that expect to
+start a TLS session immediately on connection to a non-standard port (see the
\-tls-on-connect-\ command line option).
-If you want to build Exim with TLS support, you must first install either the
+If you want to build Exim with TLS support, you must first install either the
OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
implementing SSL.
library and include files. For example:
.display asis
SUPPORT_TLS=yes
-USE_GNUTLS=yes
+USE_GNUTLS=yes
TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
TLS_INCLUDE=-I/usr/gnu/include
.endd
You do not need to set \\TLS@_INCLUDE\\ if the relevant directory is already
-specified in \\INCLUDE\\. Details of how to configure Exim to make use of TLS
+specified in \\INCLUDE\\. Details of how to configure Exim to make use of TLS
are given in chapter ~~CHAPTLS.
.index symbolic link||to source files
Symbolic links to relevant source files are installed in the build directory.
-.em
-\**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the
+\**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the
building process fails if it is set.
-.nem
If this is the first time \*make*\ has been run, it calls a script that builds
a make file inside the build directory, using the configuration files from the
.index building Exim||overriding default settings
If you need to change any of the values that are set in \(OS/Makefile-Default)\
-or in \(OS/Makefile-<<ostype>>)\, or to add any new definitions, you do not
+or in \(OS/Makefile-<<ostype>>)\, or to add any new definitions, you do not
need to change the original files. Instead, you should make the changes by
putting the new values in an appropriate \(Local)\ file. For example,
.index Tru64-Unix build-time settings
when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX,
formerly DEC-OSF1) operating system, it is necessary to specify that the C
-compiler is called \*cc*\ rather than \*gcc*\. Also, the compiler must be
+compiler is called \*cc*\ rather than \*gcc*\. Also, the compiler must be
called with the option \-std1-\, to make it recognize some of the features of
-Standard C that Exim uses. (Most other compilers recognize Standard C by
+Standard C that Exim uses. (Most other compilers recognize Standard C by
default.) To do this, you should create a file called \(Local/Makefile-OSF1)\
containing the lines
.display
CC=cc
CFLAGS=-std1
.endd
-If you are compiling for just one operating system, it may be easier to put
+If you are compiling for just one operating system, it may be easier to put
these lines directly into \(Local/Makefile)\.
Keeping all your local configuration settings separate from the distributed
The command \*make install*\ runs the \*exim@_install*\ script with no
arguments. The script copies binaries and utility scripts into the directory
whose name is specified by the \\BIN@_DIRECTORY\\ setting in
-\(Local/Makefile)\.
+\(Local/Makefile)\.
Exim's run time configuration file is named by the \\CONFIGURE@_FILE\\ setting
.index \\CONFIGURE@_FILE\\
.display asis
make DESTDIR=/some/directory/ install
.endd
-This has the effect of pre-pending the specified directory to all the file
-paths, except the name of the system aliases file that appears in the default
+This has the effect of pre-pending the specified directory to all the file
+paths, except the name of the system aliases file that appears in the default
configuration. (If a default alias file is created, its name \*is*\ modified.)
-For backwards compatibility, \\ROOT\\ is used if \\DESTDIR\\ is not set,
+For backwards compatibility, \\ROOT\\ is used if \\DESTDIR\\ is not set,
but this usage is deprecated.
.index installing Exim||what is not installed
make INSTALL_ARG=-no_symlink install
.endd
-The installation script can also be given arguments specifying which files are
-to be copied. For example, to install just the Exim binary, and nothing else,
+The installation script can also be given arguments specifying which files are
+to be copied. For example, to install just the Exim binary, and nothing else,
without creating the symbolic link, you could use:
.display asis
make INSTALL_ARG='-no_symlink exim' install
.endd
If there are any errors in the configuration file, Exim outputs error messages.
Otherwise it outputs the version number and build date,
-the DBM library that is being used, and information about which drivers and
+the DBM library that is being used, and information about which drivers and
other optional code modules are included in the binary.
Some simple routing tests can be done by using the address testing option. For
example,
.endd
to obtain the daemon's pid directly from the file that Exim saves it in.
-Note, however, that stopping the daemon does not `stop Exim'. Messages can
-still be received from local processes, and if automatic delivery is configured
+Note, however, that stopping the daemon does not `stop Exim'. Messages can
+still be received from local processes, and if automatic delivery is configured
(the normal case), deliveries will still occur.
.section Setting options by program name
.index \*mailq*\
If Exim is called under the name \*mailq*\, it behaves as if the option \-bp-\
-were present before any other options.
-The \-bp-\ option requests a listing of the contents of the mail queue on the
+were present before any other options.
+The \-bp-\ option requests a listing of the contents of the mail queue on the
standard output.
This feature is for compatibility with some systems that contain a command of
that name in one of the standard libraries, symbolically linked to
false.
.endp
-\**Warning**\: If you configure your system so that admin users are able to
-edit Exim's configuration file, you are giving those users an easy way of
-getting root. There is further discussion of this issue at the start of chapter
+\**Warning**\: If you configure your system so that admin users are able to
+edit Exim's configuration file, you are giving those users an easy way of
+getting root. There is further discussion of this issue at the start of chapter
~~CHAPconf.
.option -help
This option causes Exim to output a few sentences stating what it is.
-The same output is generated if the Exim binary is called with no options and
+The same output is generated if the Exim binary is called with no options and
no arguments.
.option B <<type>>
.index \\SIGHUP\\
The \\SIGHUP\\ signal can be used to cause the daemon to re-exec itself. This
should be done whenever Exim's configuration file, or any file that is
-incorporated into it by means of the \.include\ facility, is changed, and also
+incorporated into it by means of the \.include\ facility, is changed, and also
whenever a new version of Exim is installed. It is not necessary to do this
when other files that are referenced from the configuration (for example, alias
files) are changed, because these are reread each time they are used.
prevent ordinary users from using this mode to read otherwise inaccessible
files. If no arguments are given, Exim runs interactively, prompting for lines
of data. Long expressions can be split over several lines by using backslash
-continuations.
+continuations.
As in Exim's run time configuration, whitespace at the start of continuation
lines is ignored.
tested, and a test message must be supplied on the standard input. If there are
no message-dependent tests in the filter, an empty file can be supplied. If a
system filter file is being tested, \-bF-\ should be used instead of \-bf-\. If
-the test file does not begin with
+the test file does not begin with
one of the special lines
.display asis
# Exim filter
# Sieve filter
.endd
it is taken to be a normal \(.forward)\ file, and is tested for validity under
-that interpretation. See sections ~~SECTitenonfilred to ~~SECTspecitredli for a
+that interpretation. See sections ~~SECTitenonfilred to ~~SECTspecitredli for a
description of the possible contents of non-filter redirection lists.
The result of an Exim command that uses \-bf-\, provided no errors are
.endd
Comments as to what is going on are written to the standard error file. These
include lines beginning with `LOG' for anything that would have been logged.
-This facility is provided for testing configuration options for incoming
-messages, to make sure they implement the required policy. For example, you can
+This facility is provided for testing configuration options for incoming
+messages, to make sure they implement the required policy. For example, you can
test your relay controls using \-bh-\.
.index RFC 1413
\-bh-\ because there is no incoming SMTP connection.
\**Warning 2**\: Address verification callouts (see section ~~SECTcallver) are
-also skipped when testing using \-bh-\. If you want these callouts to occur,
+also skipped when testing using \-bh-\. If you want these callouts to occur,
use \-bhc-\ instead.
Messages supplied during the testing session are discarded, and nothing is
acceptable or not. See section ~~SECTcheckaccess.
.option bhc #<<IP address>>
-This option operates in the same way as \-bh-\, except that address
-verification callouts are performed if required. This includes consulting and
-updating the callout cache database.
+This option operates in the same way as \-bh-\, except that address
+verification callouts are performed if required. This includes consulting and
+updating the callout cache database.
.option bi
.index alias file||building
options, as appropriate. The \-bnq-\ option (see below) provides a way of
suppressing this for special cases.
-Policy checks on the contents of local messages can be enforced by means of the
+Policy checks on the contents of local messages can be enforced by means of the
non-SMTP ACL. See chapter ~~CHAPACL for details.
.index return code||for \-bm-\
The return code is zero if the message is successfully accepted. Otherwise, the
is permitted to appear at the start of the message. There appears to be no
authoritative specification of the format of this line. Exim recognizes it by
matching against the regular expression defined by the \uucp@_from@_pattern\
-option, which can be changed if necessary.
+option, which can be changed if necessary.
.index \-f-\ option||overriding `From' line
The specified sender is treated as if it were given as the argument to the
\-f-\ option, but if a \-f-\ option is also present, its argument is used in
By default, Exim automatically qualifies unqualified addresses (those
without domains) that appear in messages that are submitted locally (that
is, not over TCP/IP). This qualification applies both to addresses in
-envelopes, and addresses in header lines. Sender addresses are qualified using
-\qualify@_domain\, and recipient addresses using \qualify@_recipient\ (which
+envelopes, and addresses in header lines. Sender addresses are qualified using
+\qualify@_domain\, and recipient addresses using \qualify@_recipient\ (which
defaults to the value of \qualify@_domain\).
Sometimes, qualification is not wanted. For example, if \-bS-\ (batch SMTP) is
.endd
If \configure@_file\ is given as an argument, the name of the run time
configuration file is output.
-If a list of configuration files was supplied, the value that is output here
+If a list of configuration files was supplied, the value that is output here
is the name of the file that was actually used.
.index daemon||process id (pid)
.index local SMTP input
This option causes Exim to accept one or more messages by reading SMTP commands
on the standard input, and producing SMTP replies on the standard output. SMTP
-policy controls, as defined in ACLs (see chapter ~~CHAPACL) are applied.
+policy controls, as defined in ACLs (see chapter ~~CHAPACL) are applied.
Some user agents use this interface as a way of passing locally-generated
messages to the MTA.
.index inetd
The \-bs-\ option is also used to run Exim from \*inetd*\, as an alternative to
using a listening daemon. Exim can distinguish the two cases by checking
-whether the standard input is a TCP/IP socket. When Exim is called from
-\*inetd*\, the source of the mail is assumed to be remote, and the comments
-above concerning senders and qualification do not apply. In this situation,
-Exim behaves in exactly the same way as it does when receiving a message via
+whether the standard input is a TCP/IP socket. When Exim is called from
+\*inetd*\, the source of the mail is assumed to be remote, and the comments
+above concerning senders and qualification do not apply. In this situation,
+Exim behaves in exactly the same way as it does when receiving a message via
the listening daemon.
.option bt
.index address||testing
This option runs Exim in address testing mode, in which each argument is taken
as an address to be tested for deliverability. The results are written to the
-standard output.
-If a test fails, and the caller is not an admin user, no details of the
-failure are output, because these might contain sensitive information such as
+standard output.
+If a test fails, and the caller is not an admin user, no details of the
+failure are output, because these might contain sensitive information such as
usernames and passwords for database lookups.
If no arguments are given, Exim runs in an interactive manner, prompting with a
right angle bracket for addresses to be tested. Each address is handled as if
it were the recipient address of a message (compare the \-bv-\ option). It is
passed to the routers and the result is written to the standard output.
-However, any router that has \no@_address@_test\ set is bypassed. This can
+However, any router that has \no@_address@_test\ set is bypassed. This can
make \-bt-\ easier to use for genuine routing tests if your first router passes
everything to a scanner program.
\**Warning**\: \-bt-\ can only do relatively simple testing. If any of the
routers in the configuration makes any tests on the sender address of a
-message,
+message,
.index \-f-\ option||for address testing
you can use the \-f-\ option to set an appropriate sender when running
\-bt-\ tests. Without it, the sender is assumed to be the calling user at the
the caller is root. The reception works, but by that time, Exim is running as
the Exim user, so when it re-execs to regain privilege for the delivery, the
use of \-C-\ causes privilege to be lost. However, root can test reception and
-delivery using two separate commands (one to put a message on the queue, using
+delivery using two separate commands (one to put a message on the queue, using
\-odq-\, and another to do the delivery, using \-M-\).
If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a
must start. In addition, the file name must not contain the sequence \"/../"\.
However, if the value of the \-C-\ option is identical to the value of
\\CONFIGURE@_FILE\\ in \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as
-usual. There is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is
+usual. There is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is
unset, any file name can be used with \-C-\.
\\ALT@_CONFIG@_PREFIX\\ can be used to confine alternative configuration files
.index macro||setting on command line
This option can be used to override macro definitions in the configuration file
(see section ~~SECTmacrodefs). However, like \-C-\, if it is used by an
-unprivileged caller, it causes Exim to give up its root privilege.
+unprivileged caller, it causes Exim to give up its root privilege.
If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is
completely disabled, and its use causes an immediate error exit.
The entire option (including equals sign if present) must all be within one
-command line item. \-D-\ can be used to set the value of a macro to the empty
-string, in which case the equals sign is optional. These two commands are
+command line item. \-D-\ can be used to set the value of a macro to the empty
+string, in which case the equals sign is optional. These two commands are
synonymous:
.display asis
exim -DABC ...
exim -DABC= ...
.endd
-To include spaces in a macro definition item, quotes must be used. If you use
-quotes, spaces are permitted around the macro name and the equals sign. For
+To include spaces in a macro definition item, quotes must be used. If you use
+quotes, spaces are permitted around the macro name and the equals sign. For
example:
.display asis
exim '-D ABC = something' ...
interface $t $rm{lists of local interfaces}
lists $t $rm{matching things in lists}
load $t $rm{system load checks}
-local@_scan $t $rm{can be used by \*local@_scan()*\ (see chapter ~~CHAPlocalscan)}
+local@_scan $t $rm{can be used by \*local@_scan()*\ (see chapter ~~CHAPlocalscan)}
lookup $t $rm{general lookup code and all lookups}
memory $t $rm{memory handling}
pid $t $rm{add pid to debug output lines}
all $t $rm{all of the above, and also \-v-\}
.endd
-.em
.index resolver, debugging output
.index DNS||resolver, debugging output
-The \"resolver"\ option produces output only if the DNS resolver was compiled
+The \"resolver"\ option produces output only if the DNS resolver was compiled
with \\DEBUG\\ enabled. This is not the case in some operating systems. Also,
unfortunately, debugging output from the DNS resolver is written to stdout
rather than stderr.
-.nem
The default (\-d-\ with no argument) omits \"expand"\, \"filter"\,
\"interface"\, \"load"\, \"memory"\, \"pid"\, \"resolver"\, and \"timestamp"\.
any debugging is selected, or if \-v-\ is used.
.option dropcr
-This is an obsolete option that is now a no-op. It used to affect the way Exim
-handled CR and LF characters in incoming messages. What happens now is
+This is an obsolete option that is now a no-op. It used to affect the way Exim
+handled CR and LF characters in incoming messages. What happens now is
described in section ~~SECTlineendings.
use it, the sender of a local message is set to the caller's login name at the
default qualify domain.
-There is one exception to the restriction on the use of \-f-\: an empty sender
+There is one exception to the restriction on the use of \-f-\: an empty sender
can be specified by any user, to create a message that can never provoke a
bounce. An empty sender can be specified either as an empty string, or as a
-pair of angle brackets with nothing between them, as in these examples of shell
+pair of angle brackets with nothing between them, as in these examples of shell
commands:
.display asis
exim -f '<>' user@domain
This option requests Exim to run a delivery attempt on each message in turn. If
any of the messages are frozen, they are automatically thawed before the
delivery attempt. The settings of \queue@_domains\, \queue@_smtp@_domains\, and
-\hold@_domains\ are ignored.
+\hold@_domains\ are ignored.
.index hints database||overriding retry hints
Retry hints for any of the addresses are
overridden -- Exim tries to deliver even if the normal retry time has not yet
to the remote host has been authenticated.
.option MCP
-This option is not intended for use by external callers. It is used internally
-by Exim in conjunction with the \-MC-\ option. It signifies that the server to
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the \-MC-\ option. It signifies that the server to
which Exim is connected supports pipelining.
.option MCQ #<<process id>> <<pipe fd>>
.index delivery||abandoning further attempts
This option requests Exim to give up trying to deliver the listed messages,
including any that are frozen. However, if any of the messages are active,
-their status is not altered.
+their status is not altered.
For non-bounce messages, a delivery error message is sent to the sender,
containing the text `cancelled by administrator'. Bounce messages are just
discarded.
Exim.
.option O #<<data>>
-This option is interpreted by Sendmail to mean `set option`. It is ignored by
+This option is interpreted by Sendmail to mean `set option`. It is ignored by
Exim.
.option oA #<<file name>>
messages, which means that the accepting process automatically starts delivery
process for each message received, but does not wait for the delivery process
to complete. This is the default action if none of the \-od-\ options are
-present.
+present.
If one of the queueing options in the configuration file
(\queue@_only\ or \queue@_only@_file\, for example) is in effect, \-odb-\
a locally-generated message. (For the daemon it is exactly the same as
\-odb-\.) A delivery process is automatically started to deliver the
message, and Exim waits for it to complete before proceeding.
-However, like \-odb-\, this option has no effect if \queue@_only@_override\ is
+However, like \-odb-\, this option has no effect if \queue@_only@_override\ is
false and one of the queueing options in the configuration file is in effect.
.option odi
.option odqs
.index SMTP||delaying delivery
-This option is a hybrid between \-odb-\/\-odi-\ and \-odq-\.
+This option is a hybrid between \-odb-\/\-odi-\ and \-odq-\.
However, like \-odb-\ and \-odi-\, this option has no effect if
\queue@_only@_override\ is false and one of the queueing options in the
configuration file is in effect.
.index dot||in incoming, non-SMTP message
This option, which has the same effect as \-i-\, specifies that a dot on a line
by itself should not terminate an incoming, non-SMTP message.
-.em
-Otherwise, a single dot does terminate, though Exim does no special processing
+Otherwise, a single dot does terminate, though Exim does no special processing
for other lines that start with a dot.
-.nem
This option is set by default if Exim is called as \*rmail*\. See also \-ti-\.
.option oitrue
A number of options starting with \-oM-\ can be used to set values associated
with remote hosts on locally-submitted messages (that is, messages not received
over TCP/IP). These options can be used by any caller in conjunction with the
-\-bh-\,
+\-bh-\,
\-be-\,
\-bf-\, \-bF-\, \-bt-\, or \-bv-\ testing options. In other circumstances, they
are ignored unless the caller is trusted.
.option oMai #<<string>>
.index authentication||id, specifying for local message
See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMai-\
-option sets the
+option sets the
value of \$authenticated@_id$\ (the id that was authenticated).
This overrides the default value (the caller's login id) for messages from
local sources. See chapter ~~CHAPSMTPAUTH for a discussion of authenticated
.index authentication||sender, specifying for local message
See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMas-\
option sets the authenticated sender value
-in \$authenticated@_sender$\.
+in \$authenticated@_sender$\.
It overrides the sender address that is created from the caller's login id for
messages from local sources. See chapter ~~CHAPSMTPAUTH for a discussion of
authenticated senders.
See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMi-\
option sets the IP interface address value. A port number may be included,
using the same syntax as for \-oMa-\.
-The interface address is placed in \$interface@_address$\ and the port number,
+The interface address is placed in \$interface@_address$\ and the port number,
if present, in \$interface@_port$\.
.option oMr #<<protocol name>>
.index protocol||incoming, specifying for local message
See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMr-\
option sets the received protocol value
-in \$received@_protocol$\.
+in \$received@_protocol$\.
However, this applies only when \-bs-\ is not used. For interactive SMTP input,
the protocol is determined by whether \\EHLO\\ or \\HELO\\ is used, and is
always either `local-esmtp' or `local-smtp'. For \-bS-\ (batch SMTP) however,
.option oMs #<<host name>>
.index sender||host name, specifying for local message
See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMs-\
-option sets the sender host name
-in \$sender@_host@_name$\. When this option is present, Exim does not attempt
+option sets the sender host name
+in \$sender@_host@_name$\. When this option is present, Exim does not attempt
to look up a host name from an IP address; it uses the name it is given.
.option oMt #<<ident string>>
.index sender||ident string, specifying for local message
See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMt-\
option sets the sender ident value
-in \$sender@_ident$\.
+in \$sender@_ident$\.
The default setting for local callers is the login id of the calling process.
.option om
.option oP #<<path>>
.index pid (process id)||of daemon
.index daemon||process id (pid)
-This option is useful only in conjunction with \-bd-\ or \-q-\ with a time
+This option is useful only in conjunction with \-bd-\ or \-q-\ with a time
value. The option specifies the file to which the process id of the daemon is
written. When \-oX-\ is used with \-bd-\, or when \-q-\ with a time is used
without \-bd-\, this is the only way of causing Exim to write a pid file,
chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option,
forcing the starting of the interpreter to occur as soon as Exim is started.
-.em
.option p<<rval>>:<<sval>>
For compatibility with Sendmail, this option
is equivalent to
-.display
+.display
-oMr <<rval>> -oMs <<sval>>
.endd
It sets the incoming protocol and host name (for trusted callers). The
Note the Exim already has two private options, \-pd-\ and \-ps-\, that refer to
embedded Perl. It is therefore impossible to set a protocol value of \"p"\ or
\"s"\ using this option (but that does not seem a real limitation).
-.nem
.option q
.index queue runner||starting manually
An option starting with \-qq-\ requests a two-stage queue run. In the first
stage, the queue is scanned as if the \queue@_smtp@_domains\ option matched
every domain. Addresses are routed, local deliveries happen, but no remote
-transports are run.
+transports are run.
.index hints database||remembering routing
The hints database that remembers which messages are
waiting for specific hosts is updated, as if delivery to those hosts had been
\-odq-\ and want a queue runner just to process the new messages.
.option q[q][i]f...
-.index queue||forcing delivery
+.index queue||forcing delivery
.index delivery||forcing in queue run
If one \*f*\ flag is present, a delivery attempt is forced for each non-frozen
message, whereas without \f\ only those non-frozen addresses that have passed
Such a daemon listens for incoming SMTP calls, and also starts a queue runner
process every 30 minutes.
-When a daemon is started by \-q-\ with a time value, but without \-bd-\, no pid
+When a daemon is started by \-q-\ with a time value, but without \-bd-\, no pid
file is written unless one is explicitly requested by the \-oP-\ option.
.option qR <<rsflags>>#<<string>>
conditions must be met for a message to be selected. If either of the options
has \*f*\ or \*ff*\ in its flags, the associated action is taken.
-.em
.option Tqt#<<times>>
This an option that is exclusively for use by the Exim testing suite.
It is not recognized when Exim is run normally. It allows for the setting up
-of explicit `queue times' so that various warning/retry features can be
-tested.
-.nem
+of explicit `queue times' so that various warning/retry features can be
+tested.
.option t
.index recipient||extracting from header lines
the requirement has been removed in RFC 2822, but that is still very new.
.index \Resent@-\ header lines||with \-t-\
-If there are any \Resent@-\ header lines in the message, Exim extracts
+If there are any \Resent@-\ header lines in the message, Exim extracts
recipients from all ::Resent-To::, ::Resent-Cc::, and ::Resent-Bcc:: header
-lines instead of from ::To::, ::Cc::, and ::Bcc::. This is for compatibility
-with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if
+lines instead of from ::To::, ::Cc::, and ::Bcc::. This is for compatibility
+with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if
\-t-\ was used in conjunction with \Resent@-\ header lines.)
RFC 2822 talks about different sets of \Resent@-\ header lines (for when a
\X-Resent@-\ when a new set is added. This removes any possible ambiguity.
.option ti
-This option is exactly equivalent to \-t-\ \-i-\. It is provided for
+This option is exactly equivalent to \-t-\ \-i-\. It is provided for
compatibility with Sendmail.
.option tls-on-connect
.index \\CONFIGURE@_FILE\\
Exim uses a single run time configuration file that is read whenever an Exim
binary is executed. Note that in normal operation, this happens frequently,
-because Exim is designed to operate in a distributed manner, without central
+because Exim is designed to operate in a distributed manner, without central
control.
The name of the configuration file is compiled into the binary for security
.index configuration file||ownership
.index ownership||configuration file
The run time configuration file must be owned by root or by the user that
-is specified at compile time by the \\EXIM@_USER\\ option,
-.em
-or by the user that is specified at compile time by the \\CONFIGURE@_OWNER\\
+is specified at compile time by the \\EXIM@_USER\\ option,
+or by the user that is specified at compile time by the \\CONFIGURE@_OWNER\\
option (if set).
-.nem
The configuration file must not be world-writeable or group-writeable, unless
its group is the one specified at compile time by the \\EXIM@_GROUP\\ option.
-\**Warning**\: In a conventional configuration, where the Exim binary is setuid
-to root, anybody who is able to edit the run time configuration file has an
-easy way to run commands as root. If you make your mail administrators members
-of the Exim group, but do not trust them with root, make sure that the run time
+\**Warning**\: In a conventional configuration, where the Exim binary is setuid
+to root, anybody who is able to edit the run time configuration file has an
+easy way to run commands as root. If you make your mail administrators members
+of the Exim group, but do not trust them with root, make sure that the run time
configuration is not group writeable.
A default configuration file, which will work correctly in simple situations,
-is provided in the file \(src/configure.default)\.
+is provided in the file \(src/configure.default)\.
If \\CONFIGURE@_FILE\\ defines just one file name, the installation process
copies the default configuration to a new file of that name if it did not
previously exist. If \\CONFIGURE@_FILE\\ is a list, no default is automatically
A one-off alternate configuration can be specified by the \-C-\ command line
option, which may specify a single file or a list of files. However, when \-C-\
is used, Exim gives up its root privilege, unless called by root or the Exim
-user (or unless the argument for \-C-\ is identical to the built-in value from
+user (or unless the argument for \-C-\ is identical to the built-in value from
\\CONFIGURE@_FILE\\). \-C-\ is useful mainly for checking the syntax of
configuration files before installing them. No owner or group checks are done
on a configuration file specified by \-C-\.
the caller is root. The reception works, but by that time, Exim is running as
the Exim user, so when it re-execs to regain privilege for the delivery, the
use of \-C-\ causes privilege to be lost. However, root can test reception and
-delivery using two separate commands (one to put a message on the queue, using
+delivery using two separate commands (one to put a message on the queue, using
\-odq-\, and another to do the delivery, using \-M-\).
If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a
name can be used with \-C-\.
One-off changes to a configuration can be specified by the \-D-\ command line
-option, which defines and overrides values for macros used inside the
+option, which defines and overrides values for macros used inside the
configuration file. However, like \-C-\, the use of this option by a
non-privileged user causes Exim to discard its root privilege.
If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is
If \\CONFIGURE@_FILE@_USE@_NODE\\ is defined in \(Local/Makefile)\, Exim first
looks for a file whose name is the configuration file name followed by a dot
and the machine's node name, as obtained from the \*uname()*\ function. If this
-file does not exist, the standard name is tried. This processing occurs for
+file does not exist, the standard name is tried. This processing occurs for
each file name in the list given by \\CONFIGURE@_FILE\\ or \-C-\.
In some esoteric situations different versions of Exim may be run under
.display asis
LOCAL_SCAN_HAS_OPTIONS=yes
.endd
-in \(Local/Makefile)\ before building Exim. Full details of the
+in \(Local/Makefile)\ before building Exim. Full details of the
\*local@_scan()*\ facility are given in chapter ~~CHAPlocalscan.
.endp
Blank lines in the file, and lines starting with a @# character (ignoring
Any non-comment line can be continued by ending it with a backslash. Trailing
white space after the backslash is ignored, and leading white space at the
-start of continuation lines is also ignored.
+start of continuation lines is also ignored.
Comment lines beginning with @# (but not empty lines) may appear in the middle
of a sequence of continuation lines.
.display
@.include@_if@_exists <<file name>>
.endd
-on a line by itself. Double quotes round the file name are optional. If you use
-the first form, a configuration error occurs if the file does not exist; the
+on a line by itself. Double quotes round the file name are optional. If you use
+the first form, a configuration error occurs if the file does not exist; the
second form does nothing for non-existent files.
Includes may be nested to any depth, but remember that Exim reads its
hosts_lookup = a.b.c \
.include /some/file
.endd
-Include processing happens
-after
+Include processing happens
+after
macro processing (see below). Its effect is to process the lines of the file as
if they occurred inline where the inclusion appears.
.index configuration file||conditional skips
.index .ifdef
You can use the directives \".ifdef"\, \".ifndef"\, \".elifdef"\,
-\".elifndef"\, \".else"\, and \".endif"\ to dynamically include or exclude
-portions of the configuration file. The processing happens whenever the file is
-read (that is, when an Exim binary starts to run).
+\".elifndef"\, \".else"\, and \".endif"\ to dynamically include or exclude
+portions of the configuration file. The processing happens whenever the file is
+read (that is, when an Exim binary starts to run).
The implementation is very simple. Instances of the first four directives must
be followed by text that includes the names of one or macros. The condition
is multiplied by 1024x1024.
When the values of integer option settings are output, values which are an
-exact multiple of 1024 or 1024x1024 are
+exact multiple of 1024 or 1024x1024 are
sometimes, but not always,
printed using the letters K and M. The printing style is independent of the
actual input format that was used.
.endd
For example, `3h50m' specifies 3 hours and 50 minutes. The values of time
intervals are output in the same format.
-Exim does not restrict the values; it is perfectly acceptable, for example, to
+Exim does not restrict the values; it is perfectly acceptable, for example, to
specify `90m' instead of `1h30m'.
.index format||list item in configuration
.index string list, definition
.rset SECTlistconstruct "~~chapter.~~section"
-The data for some configuration options is a colon-separated list of items.
+The data for some configuration options is a colon-separated list of items.
Many of these options are shown with type `string list' in the descriptions
-later in this document. Others are listed as `domain list', `host list',
-`address list', or `local part list'. Syntactically, they are all the same;
+later in this document. Others are listed as `domain list', `host list',
+`address list', or `local part list'. Syntactically, they are all the same;
however, those other than `string list' are subject to particular kinds of
interpretation, as described in chapter ~~CHAPdomhosaddlists.
check_local_user
transport = local_delivery
.endd
-For each driver instance, you specify which Exim code module it uses -- by the
+For each driver instance, you specify which Exim code module it uses -- by the
setting of the \driver\ option -- and (optionally) some configuration settings.
For example, in the case of transports, if you want a transport to deliver with
SMTP you would use the \%smtp%\ driver; if you want to deliver to a local file
The first line defines a domain list called \*local@_domains*\; this is used
later in the configuration to identify domains that are to be delivered
-on the local host.
+on the local host.
.index @@ in a domain list
There is just one item in this list, the string `@@'. This is a special form of
entry which means `the name of the local host'. Thus, if the local host is
acl_smtp_rcpt = acl_check_rcpt
.endd
This option specifies an \*Access Control List*\ (ACL) which is to be used
-during an incoming SMTP session for every recipient of a message (every
+during an incoming SMTP session for every recipient of a message (every
\\RCPT\\ command). The name of the list is \*acl@_check@_rcpt*\, and we will
come to its definition below, in the ACL section of the configuration. ACLs
control which recipients are accepted for an incoming message -- if a
.display asis
# allow_domain_literals
.endd
-.em
The RFCs still require this form, but many people think that in the modern
Internet it makes little sense to permit mail to be sent to specific hosts by
quoting their IP addresses. This ancient format has been used by people who
try to abuse hosts by using them for unwanted relaying. However, some
-people believe there are circumstances (for example, messages addressed to
+people believe there are circumstances (for example, messages addressed to
\*postmaster*\) where domain literals are still useful.
-.nem
The next configuration line is a kind of trigger guard:
.display asis
The list of users specified by \never@_users\ is not, however, the complete
list; the build-time configuration in \(Local/Makefile)\ has an option called
\\FIXED@_NEVER@_USERS\\ specifying a list that cannot be overridden. The
-contents of \never@_users\ are added to this list. By default
+contents of \never@_users\ are added to this list. By default
\\FIXED@_NEVER@_USERS\\ also specifies root.
When a remote host connects to Exim in order to send mail, the only information
in order to get a host name. This improves the quality of the logging
information, but if you feel it is too expensive, you can remove it entirely,
or restrict the lookup to hosts on `nearby' networks.
-Note that it is not always possible to find a host name from an IP address,
+Note that it is not always possible to find a host name from an IP address,
because not all DNS reverse zones are maintained, and sometimes DNS servers are
unreachable.
deny domains = !+local_domains
local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
-.endd
-These statements are concerned with local parts that contain any of the
+.endd
+These statements are concerned with local parts that contain any of the
characters `@@', `%', `!', `/', `|', or dots in unusual places. Although these
characters are entirely legal in local parts (in the case of `@@' and leading
dots, only if correctly quoted), they do not commonly occur in Internet mail
This statement requires the sender address to be verified before any subsequent
ACL statement can be used. If verification fails, the incoming recipient
address is refused. Verification consists of trying to route the address, to
-see if a
-bounce
+see if a
+bounce
message could be delivered to it. In the case of remote addresses, basic
verification checks only the domain, but \*callouts*\ can be used for more
verification if required. Section ~~SECTaddressverification discusses the
The name of the router driver is \%dnslookup%\,
and is specified by the \driver\ option. Do not be confused by the fact that
-the name of this router instance is the same as the name of the driver. The
-instance name is arbitrary, but the name set in the \driver\ option must be one
+the name of this router instance is the same as the name of the driver. The
+instance name is arbitrary, but the name set in the \driver\ option must be one
of the driver modules that is in the Exim binary.
The \%dnslookup%\ router routes addresses by looking up their domains in the
The \ignore@_target@_hosts\ option specifies a list of IP addresses that are to
be entirely ignored. This option is present because a number of cases have been
-encountered where MX records in the DNS point to host names
+encountered where MX records in the DNS point to host names
whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1).
Completely ignoring these IP addresses causes Exim to fail to route the
email address, so it bounces. Otherwise, Exim would log a routing problem, and
the value of the \data\ option is empty, causing the address to be passed to
the next router.
-\(/etc/aliases)\ is a conventional name for the system aliases file that is
-often used. That is why it is referenced by from the default configuration
+\(/etc/aliases)\ is a conventional name for the system aliases file that is
+often used. That is why it is referenced by from the default configuration
file. However, you can change this by setting \\SYSTEM@_ALIASES@_FILE\\ in
\(Local/Makefile)\ before building Exim.
local user. If it is not, the router is skipped. When a local user is found,
the file called \(.forward)\ in the user's home directory is consulted. If it
does not exist, or is empty, the router declines. Otherwise, the contents of
-\(.forward)\ are interpreted as redirection data (see chapter ~~CHAPredirect
+\(.forward)\ are interpreted as redirection data (see chapter ~~CHAPredirect
for more details).
.index Sieve filter||enabling in default router
The \no@_verify\ and \no@_expn\ options mean that this router is skipped when
verifying addresses, or when running as a consequence of an SMTP \\EXPN\\
-command.
+command.
There are two reasons for doing this:
.numberpars
-Whether or not a local user has a \(.forward)\ file is not really relevant when
+Whether or not a local user has a \(.forward)\ file is not really relevant when
checking an address for validity; it makes sense not to waste resources doing
unnecessary work.
.nextp
-More importantly, when Exim is verifying addresses or handling an \\EXPN\\
-command during an SMTP session, it is running as the Exim user, not as root.
+More importantly, when Exim is verifying addresses or handling an \\EXPN\\
+command during an SMTP session, it is running as the Exim user, not as root.
The group is the Exim group, and no additional groups are set up.
It may therefore not be possible for Exim to read users' \(.forward)\ files at
this time.
.fi
(O'Reilly, ISBN 0-596-00289-0).
-The documentation for the syntax and semantics of the regular expressions that
+The documentation for the syntax and semantics of the regular expressions that
are supported by PCRE is included in plain text in the file
\(doc/pcrepattern.txt)\ in the Exim distribution, and also in the HTML
tarbundle of Exim documentation, and as an appendix to the
options set), except that the \\PCRE@_CASELESS\\ option is set when the
matching is required to be case-insensitive.
-.em
-In most cases, when a regular expression is required in an Exim configuration,
-it has to start with a circumflex, in order to distinguish it from plain text
+In most cases, when a regular expression is required in an Exim configuration,
+it has to start with a circumflex, in order to distinguish it from plain text
or an `ends with' wildcard. In this example of a configuration setting, the
second item in the colon-separated list is a regular expression.
.display asis
normal effect of `anchoring' it to the start of the string that is being
matched.
-There are, however, two cases where a circumflex is not required for the
+There are, however, two cases where a circumflex is not required for the
recognition of a regular expression: these are the \match\ condition in a
string expansion, and the \matches\ condition in an Exim filter file. In these
cases, the relevant string is always treated as a regular expression; if it
does not start with a circumflex, the expression is not anchored, and can match
anywhere in the subject string.
-In all cases, if you want a regular expression to match at the end of a string,
+In all cases, if you want a regular expression to match at the end of a string,
you must code the @$ metacharacter to indicate this. For example:
.display asis
domains = ^\\d{3}\\.example
.endd
-matches the domain \*123.example*\, but it also matches \*123.example.com*\.
+matches the domain \*123.example*\, but it also matches \*123.example.com*\.
You need to use:
.display asis
domains = ^\\d{3}\\.example\$
.endd
if you want \*example*\ to be the top-level domain. (The backslash before the
@$ is another artefact of string expansion.)
-.nem
.section Testing regular expressions
messages. Two different kinds of syntax are used:
.numberpars
A string that is to be expanded may contain explicit lookup requests. These
-cause parts of the string to be replaced by data that is obtained from the
-lookup.
+cause parts of the string to be replaced by data that is obtained from the
+lookup.
.nextp
Lists of domains, hosts, and email addresses can contain lookup requests as a
way of avoiding excessively long linear lists. In this case, the data that is
.endp
It is easy to confuse the two different kinds of lookup, especially as the
lists that may contain the second kind are always expanded before being
-processed as lists. Therefore, they may also contain lookups of the first kind.
+processed as lists. Therefore, they may also contain lookups of the first kind.
Be careful to distinguish between the following two examples:
.display asis
domains = ${lookup{$sender_host_address}lsearch{/some/file}}
192.168.3.4: domain1 : domain2 : ...
192.168.1.9: domain3 : domain4 : ...
.endd
-Thus, the result of the expansion is a list of domains (and possibly other
+Thus, the result of the expansion is a list of domains (and possibly other
types of item that are allowed in domain lists).
-In the second case, the lookup is a single item in a domain list. It causes
+In the second case, the lookup is a single item in a domain list. It causes
Exim to use a lookup to see if the domain that is being processed can be found
in the file. The file could contains lines like this:
.display asis
-domain1:
+domain1:
domain2:
.endd
-Any data that follows the keys is not relevant when checking that the domain
+Any data that follows the keys is not relevant when checking that the domain
matches the list item.
-It is possible to use both kinds of lookup at once. Consider a file containing
+It is possible to use both kinds of lookup at once. Consider a file containing
lines like this:
.display asis
192.168.5.6: lsearch;/another/file
.endd
-If the value of \$sender@_host@_address$\ is 192.168.5.6, expansion of the
-first \domains\ setting above generates the second setting, which therefore
+If the value of \$sender@_host@_address$\ is 192.168.5.6, expansion of the
+first \domains\ setting above generates the second setting, which therefore
causes a second lookup to occur.
The rest of this chapter describes the different lookup types that are
available. Any of them can be used in either of the circumstances described
-above. The syntax requirements for the two cases are described in chapters
+above. The syntax requirements for the two cases are described in chapters
~~CHAPexpand and ~~CHAPdomhosaddlists, respectively.
.section Lookup types
zero is included in the key that is passed to the DBM library. See section
~~SECTdb for a discussion of DBM libraries.
.index Berkeley DB library||file format
-For all versions of Berkeley DB, Exim uses the \\DB@_HASH\\ style of database
-when building DBM files using the \exim@_dbmbuild\ utility. However, when using
+For all versions of Berkeley DB, Exim uses the \\DB@_HASH\\ style of database
+when building DBM files using the \exim@_dbmbuild\ utility. However, when using
Berkeley DB versions 3 or 4, it opens existing databases for reading with the
\\DB@_UNKNOWN\\ option. This enables it to handle any of the types of database
-that the library supports, and can be useful for accessing DBM files created by
+that the library supports, and can be useful for accessing DBM files created by
other applications. (For earlier DB versions, \\DB@_HASH\\ is always used.)
.nextp
.nextp
.index lookup||iplsearch
.index iplsearch lookup type
-.em
\%iplsearch%\: The given file is a text file containing keys and data. A key is
terminated by a colon or white space or the end of the line. The keys in the
file must be IP addresses, or IP addresses with CIDR masks. Keys that involve
The key for an \%iplsearch%\ lookup must be an IP address (without a mask). The
file is searched linearly, using the CIDR masks where present, until a matching
key is found. The first key that matches is used; there is no attempt to find a
-`best' match. Apart from the way the keys are matched, the processing for
+`best' match. Apart from the way the keys are matched, the processing for
\%iplsearch%\ is the same as for \%lsearch%\.
\**Warning 1**\: Unlike most other single-key lookup types, a file of data for
\%iplsearch%\ can \*not*\ be turned into a DBM or cdb file, because those
lookup types support only literal keys.
-\**Warning 2**\: In a host list, you must always use \%net-iplsearch%\ so that
+\**Warning 2**\: In a host list, you must always use \%net-iplsearch%\ so that
the implicit key is the host's IP address rather than its name (see section
~~SECThoslispatsikey).
-.nem
.nextp
.index linear search
wildcarding of any kind.
.index lookup||lsearch, colons in keys
-In most \%lsearch%\ files, keys are not required to contain colons
-.em
+In most \%lsearch%\ files, keys are not required to contain colons
or @# characters, or
-.nem
whitespace. However, if you need this feature, it is available. If a key begins
with a doublequote character, it is terminated only by a matching quote (or end
of line), and the normal escaping rules apply to its contents (see section
\%wildlsearch%\ or \%nwildlsearch%\: These search a file linearly, like
\%lsearch%\, but instead of being interpreted as a literal string, each key may
be wildcarded. The difference between these two lookup types is that for
-\%wildlsearch%\, each key in the file is string-expanded before being used,
+\%wildlsearch%\, each key in the file is string-expanded before being used,
whereas for \%nwildlsearch%\, no expansion takes place.
Like \%lsearch%\, the testing is done case-insensitively. The following forms
.display asis
^\N\d+\.a\.b\N data for <digits>.a.b
.endd
-Note the use of \"@\N"\ to disable expansion of the contents of the regular
-expression. If you are using \%nwildlsearch%\, where the keys are not
+Note the use of \"@\N"\ to disable expansion of the contents of the regular
+expression. If you are using \%nwildlsearch%\, where the keys are not
string-expanded, the equivalent entry is:
.display asis
^\d+\.a\.b data for <digits>.a.b
escape all the backslashes inside the quotes.
.nextp
Although I cannot see it being of much use, the general matching function
-that is used to implement
-\%(n)wildlsearch%\
+that is used to implement
+\%(n)wildlsearch%\
means that the string may begin with a lookup name terminated by a semicolon,
and followed by lookup data. For example:
.display asis
.section Query-style lookup types
.index lookup||query-style types
.index query-style lookup||list of types
-The supported query-style lookup types are listed below. Further details about
+The supported query-style lookup types are listed below. Further details about
many of them are given in later sections.
.numberpars $.
.index DNS||as a lookup type
.display asis
data = ${lookup{$local_part@$domain}lsearch*@{/etc/mixed-aliases}}
.endd
-Suppose the address that is being processed is \*jane@@eyre.example*\. Exim
+Suppose the address that is being processed is \*jane@@eyre.example*\. Exim
looks up these keys, in this order:
.display asis
jane@eyre.example
*@eyre.example
*
.endd
-The data is taken from whichever key it finds first. \**Note**\: in an
-\%lsearch%\ file, this does not mean the first of these keys in the file. A
-complete scan is done for each key, and only if it is not found at all does
+The data is taken from whichever key it finds first. \**Note**\: in an
+\%lsearch%\ file, this does not mean the first of these keys in the file. A
+complete scan is done for each key, and only if it is not found at all does
Exim move on to try the next key.
by \*dates.fict.example*\, if that does not appear as a separate key in the
file.
-\**Note**\: Partial matching is not available for query-style lookups. It is
+\**Note**\: Partial matching is not available for query-style lookups. It is
also not available for any lookup items in address lists (see section
~~SECTaddresslist).
Partial matching is implemented by doing a series of separate lookups using
keys constructed by modifying the original subject key. This means that it can
be used with any of the single-key lookup types, provided that
-partial matching keys
+partial matching keys
beginning with a special prefix (default `$*$.') are included in the data file.
Keys in the file that do not begin with the prefix are matched only by
unmodified subject keys when partial matching is in use.
*.fict.example
.endd
As soon as one key in the sequence is successfully looked up, the lookup
-finishes.
+finishes.
.index lookup||partial matching, changing prefix
.index prefix||for partial matching
-The use of `$*$.' as the partial matching prefix is a default that can be
+The use of `$*$.' as the partial matching prefix is a default that can be
changed. The motivation for this feature is to allow Exim to operate with file
formats that are used by other MTAs. A different prefix can be supplied in
parentheses instead of the hyphen after `partial'. For example:
domains = partial(.)lsearch;/some/file
.endd
In this example, if the domain is \*a.b.c*\, the sequence of lookups is
-\"a.b.c"\, \".a.b.c"\, and \".b.c"\ (the default minimum of 2 non-wild
+\"a.b.c"\, \".a.b.c"\, and \".b.c"\ (the default minimum of 2 non-wild
components is unchanged). The prefix may consist of any punctuation characters
other than a closing parenthesis. It may be empty, for example:
.display asis
example, the final lookup for `partial0(.)' is for \"."\ alone.
.nextp
Otherwise, if the prefix ends in a dot, the dot is removed, and the
-remainder is looked up. With the default prefix, therefore, the final lookup is
+remainder is looked up. With the default prefix, therefore, the final lookup is
for `$*$' on its own.
.nextp
Otherwise, the whole prefix is looked up.
.section Lookup caching
-.index lookup||caching
+.index lookup||caching
.index caching||lookup data
An Exim process
caches the most recent lookup result on a per-file basis for single-key
.display asis
${lookup dnsdb{mx=a.b.example}{$value}fail}
.endd
-.em
-The supported record types are A, CNAME, MX, NS, PTR, SRV, and TXT,
-.nem
+The supported record types are A, CNAME, MX, NS, PTR, SRV, and TXT,
and, when Exim is compiled with IPv6 support, AAAA (and A6 if that is also
configured). If no type is given, TXT is assumed. When the type is PTR, the
address should be given as normal; it is converted to the necessary inverted
.index MX record||in \%dnsdb%\ lookup
For MX records, both the preference value and the host name are returned,
-separated by a space.
-.em
+separated by a space.
.index SRV record||in \%dnsdb%\ lookup
-For SRV records, the priority, weight, port, and host name are returned,
+For SRV records, the priority, weight, port, and host name are returned,
separated by spaces. For any record type,
-.nem
if multiple records are found (or, for A6 lookups, if a single record leads to
multiple addresses), the data is returned as a concatenation, separated by
newlines. The order, of course, depends on the DNS resolver.
.index LDAP||quoting
Two levels of quoting are required in LDAP queries, the first for LDAP itself
and the second because the LDAP query is represented as a URL. Furthermore,
-within an LDAP query, two different kinds of quoting are required. For this
+within an LDAP query, two different kinds of quoting are required. For this
reason, there are two different LDAP-specific quoting operators.
The \quote@_ldap\ operator is designed for use on strings that are part of
before any trailing spaces. (These rules are in RFC 2253.) The resulting string
is then quoted according to the rules for URLs. For example:
.display asis
-${quote_ldap_dn: a(bc)*, a<yz>; }
+${quote_ldap_dn: a(bc)*, a<yz>; }
.endd
yields
.display asis
.display asis
\ a(bc)*\, a\<yz\>\;\
.endd
-There are some further comments about quoting in the section on LDAP
+There are some further comments about quoting in the section on LDAP
authentication below.
.section LDAP connections
Using a pathname with \"ldap"\ or \"ldaps"\ forces the use of the Unix domain
interface.
.nextp
-Using \"ldapi"\ with a host name causes an error.
+Using \"ldapi"\ with a host name causes an error.
.endp
Using \"ldapi"\ with no host or path in the query, and no setting of
be preceded by any number of `<<name>>=<<value>>' settings, separated by
spaces. If a value contains spaces it must be enclosed in double quotes, and
when double quotes are used, backslash is interpreted in the usual way inside
-them.
+them.
The following names are recognized:
.display
SIZE $rm{set the limit for the number of entries returned}
TIME $rm{set the maximum waiting time for a query}
.endd
-The value of the \\DEREFERENCE\\ parameter must be one of the words `never',
+The value of the \\DEREFERENCE\\ parameter must be one of the words `never',
`searching', `finding', or `always'.
Here is an example of an LDAP query in an Exim lookup that uses some of these
It makes it possible to use the same \quote@_ldap@_dn\ expansion for \\USER=\\
DNs as with DNs inside actual queries.
.nextp
-It permits spaces inside \\USER=\\ DNs.
+It permits spaces inside \\USER=\\ DNs.
.endp
For example, a setting such as
.display asis
.endd
should work even if \$1$\ contains spaces.
-Expanded data for the \\PASS=\\ value should be quoted using the \quote\
-expansion operator, rather than the LDAP quote operators. The only reason this
-field needs quoting is to ensure that it conforms to the Exim syntax, which
+Expanded data for the \\PASS=\\ value should be quoted using the \quote\
+expansion operator, rather than the LDAP quote operators. The only reason this
+field needs quoting is to ensure that it conforms to the Exim syntax, which
does not allow unquoted spaces. For example:
.display asis
PASS=${quote:$3}
list is negative. In other words, a list that ends with a negative item behaves
as if it had an extra item \":*"\ on the end.
-Another way of thinking about positive and negative items in lists is to read
-the connector as `or' after a positive item and as `and' after a negative
-item.
+Another way of thinking about positive and negative items in lists is to read
+the connector as `or' after a positive item and as `and' after a negative
+item.
.section File names in lists
non-constant pattern. This is not the case. The keys in an \%lsearch%\ file are
always fixed strings, just as for any other single-key lookup type.
-If you want to use a file to contain wild-card patterns that form part of a
+If you want to use a file to contain wild-card patterns that form part of a
list, just give the file name on its own, without a search type, as described
in the previous section.
.display asis
domainlist dom2 = !a.b : *.b
.endd
-where \*x.y*\ does not match. It's best to avoid negation altogether in
+where \*x.y*\ does not match. It's best to avoid negation altogether in
referenced lists if you can.
Named lists may have a performance advantage. When Exim is routing an
domains = +local_domains
.endd
on several of your routers
-or in several ACL statements,
+or in several ACL statements,
the actual test is done only for the first one. However, the caching works only
if there are no expansions within the list itself or any sublists that it
references. In other words, caching happens only for lists that are known to be
.endd
-.em
.section Named list caching
.index list||caching of named
.index caching||named lists
.endd
If you do this, you should be absolutely sure that caching is going to do
the right thing in all cases. When in doubt, leave it out.
-.nem
.section Domain lists
The following types of item may appear in domain lists:
.numberpars $.
.index primary host name
-.index host||name, matched in domain list
+.index host||name, matched in domain list
.index \primary@_hostname\
.index domain list||matching primary host name
.index @@ in a domain list
.index domain literal
If a pattern consists of the string \"@@[]"\ it matches any local IP interface
address, enclosed in square brackets, as in an email address that contains a
-domain literal.
-.em
+domain literal.
In today's Internet, the use of domain literals is controversial.
-.nem
.nextp
.index @@mx@_any
.index @@mx@_primary
but a secondary MX target is. `Primary' means an MX record with the lowest
preference value -- there may of course be more than one of them.
-.em
-The MX lookup that takes place when matching a pattern of this type is
-performed with the resolver options for widening names turned off. Thus, for
-example, a single-component domain will \*not*\ be expanded by adding the
-resolver's default domain. See the \qualify@_single\ and \search@_parents\
+The MX lookup that takes place when matching a pattern of this type is
+performed with the resolver options for widening names turned off. Thus, for
+example, a single-component domain will \*not*\ be expanded by adding the
+resolver's default domain. See the \qualify@_single\ and \search@_parents\
options of the \%dnslookup%\ router for a discussion of domain widening.
Sometimes you may want to ignore certain IP addresses when using one of these
patterns. You can specify this by following the pattern with \"/ignore=<<ip
list>>"\, where <<ip list>> is a list of IP addresses. These addresses are
-ignored when processing the pattern (compare the \ignore@_target@_hosts\ option
+ignored when processing the pattern (compare the \ignore@_target@_hosts\ option
on a router). For example:
.display asis
domains = @mx_any/ignore=127.0.0.1
This example matches any domain that has an MX record pointing to one of
the local host's IP addresses other than 127.0.0.1.
-The list of IP addresses is in fact processed by the same code that processes
-host lists, so it may contain CIDR-coded network specifications and it may also
+The list of IP addresses is in fact processed by the same code that processes
+host lists, so it may contain CIDR-coded network specifications and it may also
contain negative items.
Because the list of IP addresses is a sublist within a domain list, you have to
domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
an.other.domain ? ...
.endd
-.nem
.nextp
.index asterisk||in domain list
This typically causes a forward DNS lookup of the name. The result is compared
with the IP address of the subject host.
-.em
If there is a temporary problem (such as a DNS timeout) with the host name
-lookup, a temporary error occurs. For example, if the list is being used in an
+lookup, a temporary error occurs. For example, if the list is being used in an
ACL condition, the ACL gives a `defer' response, usually leading to a temporary
SMTP error code. If no IP address can be found for the host name, what happens
is described in section ~~SECTbehipnot below.
-.nem
.nextp
.index @@ in a host list
host under the given mask.
This allows, an entire network of hosts to be included (or excluded) by a
single item.
-.index CIDR notation
+.index CIDR notation
The mask uses CIDR notation; it specifies the number of address bits that must
match, starting from the most significant end of the address.
.display asis
192.168.23.236/31
.endd
-matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of
-32 for an IPv4 address is the same as no mask at all; just a single address
+matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of
+32 for an IPv4 address is the same as no mask at all; just a single address
matches.
Here is another example which shows an IPv4 and an IPv6 network:
.rset SECThoslispatnam "~~chapter.~~section"
.index host||lookup failures
.index unknown host name
-.index host list||matching host name
+.index host list||matching host name
There are several types of pattern that require Exim to know the name of the
remote host. These are either wildcard patterns or lookups by name. (If a
complete hostname is given without any wildcarding, it is used to find an IP
address to match against, as described in the section ~~SECThoslispatip above.)
If the remote host name is not already known when Exim encounters one of these
-patterns, it has to be found from the IP address.
-.em
+patterns, it has to be found from the IP address.
Although many sites on the Internet are conscientious about maintaining reverse
DNS data for their hosts, there are also many that do not do this.
Consequently, a name cannot always be found, and this may lead to unwanted
There are some options that control what happens if a host name cannot be
found. These are described in section ~~SECTbehipnot below.
-.nem
.index host||alias for
.display asis
sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : ....
.endd
-.em
-\**Warning**\: If you want to match a complete host name, you must include the
-\"@$"\ terminating metacharacter in the regular expression, as in the above
-example. Without it, a match at the start of the host name is all that is
+\**Warning**\: If you want to match a complete host name, you must include the
+\"@$"\ terminating metacharacter in the regular expression, as in the above
+example. Without it, a match at the start of the host name is all that is
required.
-.nem
.endp
-.em
.section Behaviour when an IP address or name cannot be found
.rset SECTbehipnot "~~chapter.~~section"
.index host||lookup failures
-While processing a host list, Exim may need to look up an IP address from a
-name (see section ~~SECThoslispatip), or it may need to look up a host name
-from an IP address (see section ~~SECThoslispatnam). In either case, the
+While processing a host list, Exim may need to look up an IP address from a
+name (see section ~~SECThoslispatip), or it may need to look up a host name
+from an IP address (see section ~~SECThoslispatnam). In either case, the
behaviour when it fails to find the information it is seeking is the same.
.index \"+include@_unknown"\
rejects connections from any host whose name matches \"*.enemy.ex"\, and also
any hosts whose name it cannot find.
.nextp
-If any item that follows \"+ignore@_unknown"\ requires information that cannot
-be found, Exim ignores that item and proceeds to the rest of the list. For
+If any item that follows \"+ignore@_unknown"\ requires information that cannot
+be found, Exim ignores that item and proceeds to the rest of the list. For
example:
.display asis
accept hosts = +ignore_unknown : friend.example : \
192.168.4.5
.endd
-accepts from any host whose name is \*friend.example*\ and from 192.168.4.5,
-whether or not its host name can be found. Without \"+ignore@_unknown"\, if no
+accepts from any host whose name is \*friend.example*\ and from 192.168.4.5,
+whether or not its host name can be found. Without \"+ignore@_unknown"\, if no
name can be found for 192.168.4.5, it is rejected.
.endp
Both \"+include@_unknown"\ and \"+ignore@_unknown"\ may appear in the same
-list. The effect of each one lasts until the next, or until the end of the
+list. The effect of each one lasts until the next, or until the end of the
list.
\**Note**\: This section applies to permanent lookup failures. It does \*not*\
apply to temporary DNS errors. They always cause a defer action.
-.nem
.section Host list patterns for single-key lookups by host name
If you want to use masked IP addresses in database queries, you can use the
\mask\ expansion operator.
-If the query contains a reference to \$sender@_host@_name$\, Exim automatically
+If the query contains a reference to \$sender@_host@_name$\, Exim automatically
looks up the host name if has not already done so. (See section
~~SECThoslispatnam for comments on finding host names.)
-Historical note: prior to release 4.30, Exim would always attempt to find a
+Historical note: prior to release 4.30, Exim would always attempt to find a
host name before running the query, unless the search type was preceded by
-\"net-"\. This is no longer the case. For backwards compatibility, \"net-"\ is
+\"net-"\. This is no longer the case. For backwards compatibility, \"net-"\ is
still recognized for query-style lookups, but its presence or absence has no
effect. (Of course, for single-key lookups, \"net-"\ $it{is} important.)
.index @@@@ with single-key lookup
.index address list||@@@@ lookup type
.index address list||split local part and domain
-If a pattern starts with `@@@@' followed by a single-key lookup item
+If a pattern starts with `@@@@' followed by a single-key lookup item
(for example, \"@@@@lsearch;/some/file"\), the address that is being checked is
split into a local part and a domain. The domain is looked up in the file. If
it is not found, there is no match. If it is found, the data that is looked up
It is possible to construct loops using this facility, and in order to catch
them, the chains may be no more than fifty items long.
.nextp
-The @@@@<<lookup>> style of item can also be used with a query-style
-lookup, but in this case, the chaining facility is not available. The lookup
+The @@@@<<lookup>> style of item can also be used with a query-style
+lookup, but in this case, the chaining facility is not available. The lookup
can only return a single list of local parts.
.nextp
.index address list||lookup for complete address
-Complete addresses can be looked up by using a pattern that
+Complete addresses can be looked up by using a pattern that
starts with a lookup type terminated by a semicolon, follwed by the data for
the lookup.
For example:
.endd
For a single-key lookup type, Exim uses the complete address as the key.
Partial matching (section ~~SECTpartiallookup) cannot be used, and is ignored
-if specified, with an entry being written to the panic log.
+if specified, with an entry being written to the panic log.
.index @*@@ with single-key lookup
You can configure lookup defaults, as described in section
-~~SECTdefaultvaluelookups, but this is useful only for the `$*$@@' type of
+~~SECTdefaultvaluelookups, but this is useful only for the `$*$@@' type of
default. For example, with this lookup:
.display asis
accept senders = lsearch*@;/some/file
*@jaeger.example
*
.endd
-\**Warning 1**\: Do not include a line keyed by `$*$' in the file, because that
+\**Warning 1**\: Do not include a line keyed by `$*$' in the file, because that
would mean that every address matches, thus rendering the test useless.
\**Warning 2**\: Do not confuse these two kinds of item:
deny recipients = dbm*@;/some/file
deny recipients = *@dbm;/some/file
.endd
-The first does a whole address lookup, with defaulting, as just described,
+The first does a whole address lookup, with defaulting, as just described,
because it starts with a lookup type. The second matches the local part and
domain independently, as described in the next paragraph.
.nextp
When a string is being expanded it is copied verbatim from left to right except
when a dollar or backslash character is encountered. A dollar specifies the
start of a portion of the string which is interpreted and replaced as described
-below in section ~~SECTexpansionitems onwards. Backslash is used as an escape
+below in section ~~SECTexpansionitems onwards. Backslash is used as an escape
character, as described in the following section.
.item "@$@{extract@{<<key>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
.index expansion||extracting substrings by key
-The key and <<string1>> are first expanded separately.
-Leading and trailing whitespace is removed from the key (but not from any of
+The key and <<string1>> are first expanded separately.
+Leading and trailing whitespace is removed from the key (but not from any of
the strings).
The key must not consist entirely of digits. The expanded <<string1>> must be
of the form:
.item "@$@{extract@{<<number>>@}@{<<separators>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
.index expansion||extracting substrings by number
The <<number>> argument must consist entirely of decimal digits,
-apart from leading and trailing whitespace, which is ignored.
+apart from leading and trailing whitespace, which is ignored.
This is what distinguishes this form of \extract\ from the previous kind. It
behaves in the same way, except that, instead of extracting a named field, it
extracts from <<string1>> the field whose number is given as the first
.item "@$@{hash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
.index hash function||textual
.index expansion||textual hash
-This is a textual hashing function, and was the first to be implemented in
-early versions of Exim. In current releases, there are other hashing functions
+This is a textual hashing function, and was the first to be implemented in
+early versions of Exim. In current releases, there are other hashing functions
(numeric, MD5, and SHA-1), which are described below.
-The first two strings, after expansion, must be numbers. Call them <<m>> and
-<<n>>. If you are using fixed values for these numbers, that is, if <<string1>>
+The first two strings, after expansion, must be numbers. Call them <<m>> and
+<<n>>. If you are using fixed values for these numbers, that is, if <<string1>>
and <<string2>> do not change when they are expanded, you can use the
simpler operator notation that avoids some of the braces:
.display
.endd
The second number is optional (in both notations).
-If <<n>> is greater than or equal to the length of the string, the expansion
+If <<n>> is greater than or equal to the length of the string, the expansion
item returns the string. Otherwise it computes a new string of length <<n>> by
applying a hashing function to the string. The new string consists of
characters taken from the first <<m>> characters of the string
If <<m>> is not present the value 26 is used, so that only lower case
letters appear. For example:
.display
-@$@{hash@{3@}@{monty@}@} $rm{yields} \"jmg"\
-@$@{hash@{5@}@{monty@}@} $rm{yields} \"monty"\
-@$@{hash@{4@}@{62@}@{monty python@}@} $rm{yields} \"fbWx"\
+@$@{hash@{3@}@{monty@}@} $rm{yields} \"jmg"\
+@$@{hash@{5@}@{monty@}@} $rm{yields} \"monty"\
+@$@{hash@{4@}@{62@}@{monty python@}@} $rm{yields} \"fbWx"\
.endd
.endd
The newline that terminates a header line is not included in the expansion, but
internal newlines (caused by splitting the header line over several physical
-lines) may be present.
+lines) may be present.
-The difference between \rheader\, \bheader\, and \header\ is in the way the
-data in the header line is interpreted.
+The difference between \rheader\, \bheader\, and \header\ is in the way the
+data in the header line is interpreted.
.numberpars $.
\rheader\ gives the original `raw' content of the header line, with no
processing at all, and without the removal of leading and trailing whitespace.
\bheader\ removes leading and trailing whitespace, and then decodes base64 or
quoted-printable MIME `words' within the header text, but does no character
set translation. If decoding of what looks superficially like a MIME `word'
-fails, the raw string is returned.
+fails, the raw string is returned.
.index binary zero||in header line
If decoding produces a binary zero character, it is replaced by a question mark
-- this is what Exim does for binary zeros that are actually received in header
Only header lines that are common to all copies of a message are visible to
this mechanism. These are the original header lines that are received with the
-message, and any that are added by
+message, and any that are added by
an ACL \warn\ statement or by
a system filter. Header lines that are added to a particular copy of a message
by a router or transport are not accessible.
white space terminates the header name, it is included in the expanded string.
If the message does not contain the given header, the expansion item is
replaced by an empty string. (See the \def\ condition in section ~~SECTexpcond
-for a means of testing for the existence of a header.)
+for a means of testing for the existence of a header.)
If there is more than one header with the same name, they are all concatenated
to form the substitution string, up to a maximum length of 64K. A newline
.index expansion||hmac hashing
This function uses cryptographic hashing (either MD5 or SHA-1) to convert a
shared secret and some text into a message authentication code, as specified in
-RFC 2104.
+RFC 2104.
This differs from \"@$@{md5:secret@_text...@}"\ or
-\"@$@{sha1:secret@_text...@}"\ in that the hmac step adds a signature to the
-cryptographic hash, allowing for authentication that is not possible with MD5
+\"@$@{sha1:secret@_text...@}"\ in that the hmac step adds a signature to the
+cryptographic hash, allowing for authentication that is not possible with MD5
or SHA-1 alone.
The hash name must expand to either \"md5"\ or \"sha1"\ at present. For
example:
{${primary_hostname},${message_id},$h_message-id:}}
.endd
Then given a message, you can check where it was scanned by looking at the
-::X-Spam-Scanned:: header line. If you know the secret, you can check that this
-header line is authentic by recomputing the authentication code from the host
+::X-Spam-Scanned:: header line. If you know the secret, you can check that this
+header line is authentic by recomputing the authentication code from the host
name, message ID and the ::Message-id:: header line. This can be done using
Exim's \-be-\ option, or by other means, for example by using the
\*hmac@_md5@_hex()*\ function in Perl.
.item "@$@{length@{<<string1>>@}@{<<string2>>@}@}"
.index expansion||string truncation
-The \length\ item is used to extract the initial portion of a string. Both
+The \length\ item is used to extract the initial portion of a string. Both
strings are expanded, and the first one must yield a number, <<n>>, say. If you
are using a fixed value for the number, that is, if <<string1>> does not change
when expanded, you can use the simpler operator notation that avoids some of
@$@{length@_<<n>>:<<string>>@}
.endd
The result of this item is either the first <<n>> characters or the whole
-of <<string2>>, whichever is the shorter. Do not confuse \length\ with
+of <<string2>>, whichever is the shorter. Do not confuse \length\ with
\strlen\, which gives the length of a string.
This item is available only if Exim has been built to include an embedded Perl
interpreter. The subroutine name and the arguments are first separately
expanded, and then the Perl subroutine is called with those arguments. No
-additional arguments need be given; the maximum number permitted, including the
+additional arguments need be given; the maximum number permitted, including the
name of the subroutine, is nine.
The return value of the subroutine is inserted into the expanded string, unless
the return value is \undef\. In that case, the expansion fails in the same way
-as an explicit `fail' on a lookup item.
-The return value is a scalar. Whatever you return is evaluated in a scalar
+as an explicit `fail' on a lookup item.
+The return value is a scalar. Whatever you return is evaluated in a scalar
context. For example, if you return the name of a Perl vector, the
return value is the size of the vector, not its contents.
then read, and its contents replace the entire item. All newline characters in
the file are replaced by the end-of-line string if it is present. Otherwise,
newlines are left in the string.
-String expansion is not applied to the contents of the file. If you want this,
-you must wrap the item in an \expand\ operator. If the file cannot be read, the
+String expansion is not applied to the contents of the file. If you want this,
+you must wrap the item in an \expand\ operator. If the file cannot be read, the
string expansion fails.
The \%redirect%\ router has an option called \forbid@_filter@_readfile\ which
locks out the use of this expansion item in filter files.
.item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:"
-This item inserts `raw' header lines. It is described with the \header\
+This item inserts `raw' header lines. It is described with the \header\
expansion item above.
endif
.endd
If execution of the command fails (for example, the command does not exist),
-the return code is 127 -- the same code that shells use for non-existent
+the return code is 127 -- the same code that shells use for non-existent
commands.
-\**Warning**\: In a router or transport, you cannot assume the order in which
-option values are expanded, except for those pre-conditions whose order of
-testing is documented. Therefore, you cannot reliably expect to set \$runrc$\
+\**Warning**\: In a router or transport, you cannot assume the order in which
+option values are expanded, except for those pre-conditions whose order of
+testing is documented. Therefore, you cannot reliably expect to set \$runrc$\
by the expansion of one option, and use it in another.
The \%redirect%\ router has an option called \forbid@_filter@_run\ which locks
${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}}
.endd
yields `K1=A K4=D K3=C'.
-Note the use of \"@\N"\ to protect the contents of the regular expression from
+Note the use of \"@\N"\ to protect the contents of the regular expression from
string expansion.
zeros. \**Note**\: Just to be absolutely clear: this is \*not*\ base64
encoding.
-.em
.item "@$@{base62d:<<base-62 digits>>@}"
.index base62
.index expansion||conversion to base 62
The string must consist entirely of base-62 digits. The number is converted to
decimal and output as a string.
-.nem
.item "@$@{domain:<<string>>@}"
controlled by the \print@_topbitchars\ option.
-.em
.item "@$@{eval:<<string>>@}"
.item "@$@{eval10:<<string>>@}"
.index expansion||expression evaluation
the four basic operators (plus, minus, times, divide) and parentheses. All
operations are carried out using integer arithmetic. Plus and minus have a
lower priority than times and divide; operators with the same priority are
-evaluated from left to right.
+evaluated from left to right.
For \eval\, numbers may be decimal, octal (starting with `0') or hexadecimal
(starting with `0x'). For \eval10\, all numbers are taken as decimal, even if
they start with a leading zero. This can be useful when processing numbers
extracted from dates or times, which often do have leading zeros.
-.nem
A number may be followed by `K' or `M' to multiply it by 1024 or 1024$*$1024,
respectively. Negative numbers are supported. The result of the computation is
Unicode code points with values less than 256 are compatible with ASCII and
ISO-8859-1 (also known as Latin-1).
-For example, character 169 is the copyright symbol in both cases, though the
+For example, character 169 is the copyright symbol in both cases, though the
way it is encoded is different. In UTF-8, more than one byte is needed for
characters with code values greater than 127, whereas ISO-8859-1 is a
-single-byte encoding (but thereby limited to 256 characters). This makes
+single-byte encoding (but thereby limited to 256 characters). This makes
translation from UTF-8 to ISO-8859-1 straightforward.
.item "@$@{hash@_<<n>>@_<<m>>:<<string>>@}"
.index hash function||textual
.index expansion||textual hash
-The \hash\ operator is a simpler interface to the hashing function that can be
-used when the two parameters are fixed numbers (as opposed to strings that
+The \hash\ operator is a simpler interface to the hashing function that can be
+used when the two parameters are fixed numbers (as opposed to strings that
change when expanded). The effect is the same as
.display
@$@{hash@{<<n>>@}@{<<m>>@}@{<<string>>@}@}
.item "@$@{hex2b64:<<hexstring>>@}"
.index base64 encoding||conversion from hex
.index expansion||hex to base64
-This operator converts a hex string into one that is base64 encoded. This can
+This operator converts a hex string into one that is base64 encoded. This can
be useful for processing the output of the MD5 and SHA-1 hashing functions.
.display
@$@{length@{<<number>>@}@{<<string>>@}@}
.endd
-See the description of the general \length\ item above for details. Note that
+See the description of the general \length\ item above for details. Note that
\length\ is not the same as \strlen\. The abbreviation \l\ can be used when
\length\ is used as an operator.
.item "@$@{quote:<<string>>@}"
.index quoting||in string expansions
.index expansion||quoting
-The \quote\ operator puts its argument into double quotes if it
+The \quote\ operator puts its argument into double quotes if it
is an empty string or
contains anything other than letters, digits, underscores, dots, and hyphens.
Any occurrences of double quotes and backslashes are escaped with a backslash.
variable or a message header.
.item "@$@{quote@_local@_part:<<string>>@}"
-This operator is like \quote\, except that it quotes the string only if
-required to do so by the rules of RFC 2822 for quoting local parts. For
+This operator is like \quote\, except that it quotes the string only if
+required to do so by the rules of RFC 2822 for quoting local parts. For
example, a plus sign would not cause quoting (but it would for \quote\).
If you are creating a new email address from the contents of \$local@_part$\
(or any other unknown data), you should always use this operator.
.display asis
${quote_ldap:two * two}
.endd
-returns
+returns
.display asis
two%20%5C2A%20two
.endd
If the string contains only characters in the range 33--126, and no instances
of the characters
.display asis
-? = ( ) < > @ , ; : \ " . [ ] _
+? = ( ) < > @ , ; : \ " . [ ] _
.endd
it is not modified. Otherwise, the result is the RFC 2047 encoding, as a single
`coded word'.
The string, after expansion, must be a file path. A call to the \*stat()*\
function is made for this path. If \*stat()*\ fails, an error occurs and the
expansion fails. If it succeeds, the data from the stat replaces the item, as a
-series of <<name>>=<<value>> pairs, where the values are all numerical,
+series of <<name>>=<<value>> pairs, where the values are all numerical,
except for the value of `smode'. The names are: `mode' (giving the mode as a
4-digit octal number), `smode' (giving the mode in symbolic format as a
10-character string, as for the \*ls*\ command), `inode', `device', `links',
.item "@$@{strlen:<<string>>@}"
.index expansion||string length
.index string||length in expansion
-The item is replace by the length of the expanded string, expressed as a
+The item is replace by the length of the expanded string, expressed as a
decimal number. \**Note**\: Do not confuse \strlen\ with \length\.
See the description of the general \substr\ item above for details. The
abbreviation \s\ can be used when \substr\ is used as an operator.
-.em
.item "@$@{time@_interval:<<string>>@}"
.index \time@_interval\
.index time interval||formatting
represents an interval of time as a number of seconds. It is converted into a
number of larger units and output in Exim's normal time format, for example,
\"1w3d4h2m6s"\.
-.nem
.item "@$@{uc:<<string>>@}"
.index case forcing in strings
.display asis
${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}}
.endd
-The following encryption types
+The following encryption types
(whose names are matched case-independently)
are supported:
.numberpars $.
comparison fails.
.nextp
.index SHA-1 hash
-\@{sha1@}\ computes the SHA-1 digest of the first string, and expresses this as
-printable characters to compare with the remainder of the second string. If the
-length of the comparison string is 28, Exim assumes that it is base64 encoded.
-If the length is 40, Exim assumes that it is a hexadecimal encoding of the
+\@{sha1@}\ computes the SHA-1 digest of the first string, and expresses this as
+printable characters to compare with the remainder of the second string. If the
+length of the comparison string is 28, Exim assumes that it is base64 encoded.
+If the length is 40, Exim assumes that it is a hexadecimal encoding of the
SHA-1 digest. If the length is not 28 or 40, the comparison fails.
.nextp
.index \*crypt()*\
-\@{crypt@}\ calls the \*crypt()*\ function, which uses only the first eight
+\@{crypt@}\ calls the \*crypt()*\ function, which uses only the first eight
characters of the password.
.nextp
.index \*crypt16()*\
Exim has its own version of \*crypt16()*\ (which is just a double call to
\*crypt()*\). For operating systems that have their own version, setting
\\HAVE@_CRYPT16\\ in \(Local/Makefile)\ when building Exim causes it to use the
-operating system version instead of its own. This option is set by default in
-the OS-dependent \(Makefile)\ for those operating systems that are known to
+operating system version instead of its own. This option is set by default in
+the OS-dependent \(Makefile)\ for those operating systems that are known to
support \*crypt16()*\.
If you do not put any curly bracket encryption type in a \crypteq\ comparison,
.index string||comparison
.index expansion||string comparison
The two substrings are first expanded. The condition is true if the two
-resulting strings are identical: for \eq\ the comparison includes the case of
+resulting strings are identical: for \eq\ the comparison includes the case of
letters, whereas for \eqi\ the comparison is case-independent.
.item "exists @{<<file name>>@}"
This condition, which has no data, is true during a message's first delivery
attempt. It is false during any subsequent delivery attempts.
-.em
.item "ge @{<<string1>>@}@{<<string2>>@}"
.item "gei @{<<string1>>@}@{<<string2>>@}"
.index string||comparison
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.
-.nem
.item "isip @{<<string>>@}" 8
.item "isip4 @{<<string>>@}"
.item "isip6 @{<<string>>@}"
.index IP address||testing string format
.index string||testing for IP address
-The substring is first expanded, and then tested to see if it has the form of
-an IP address. Both IPv4 and IPv6 addresses are valid for \isip\, whereas
-\isip4\ and \isip6\ test just for IPv4 or IPv6 addresses, respectively. For
+The substring is first expanded, and then tested to see if it has the form of
+an IP address. Both IPv4 and IPv6 addresses are valid for \isip\, whereas
+\isip4\ and \isip6\ test just for IPv4 or IPv6 addresses, respectively. For
example, you could use
-.display asis
+.display asis
${if isip4{$sender_host_address}...
.endd
to test which version of IP an incoming SMTP connection is using.
use, the query must contain a user name and password. The query itself is not
used, and can be empty. The condition is true if
the password is not empty, and the user name and password are accepted by the
-LDAP server. An empty password is rejected without calling LDAP because LDAP
+LDAP server. An empty password is rejected without calling LDAP because LDAP
binds with an empty password are considered anonymous regardless of
the username, and will succeed in most configurations.
See chapter ~~CHAPSMTPAUTH for details of SMTP authentication, and chapter
~~CHAPplaintext for an example of how this can be used.
-.em
.item "le @{<<string1>>@}@{<<string2>>@}"
.item "lei @{<<string1>>@}@{<<string2>>@}"
.index string||comparison
string is lexically less than the second string: for \lt\ the comparison
includes the case of letters, whereas for \lti\ the comparison is
case-independent.
-.nem
.item "match @{<<string1>>@}@{<<string2>>@}"
If the whole expansion string is in double quotes, further escaping of
backslashes is also required.
-The condition is true if the regular expression match succeeds.
-.em
-The regular expression is not required to begin with a circumflex
+The condition is true if the regular expression match succeeds.
+The regular expression is not required to begin with a circumflex
metacharacter, but if there is no circumflex, the expression is not anchored,
-and it may match anywhere in the subject, not just at the start. If you want
-the pattern to match at the end of the subject, you must include the \"@$"\
+and it may match anywhere in the subject, not just at the start. If you want
+the pattern to match at the end of the subject, you must include the \"@$"\
metacharacter at an appropriate point.
-.nem
.index numerical variables (\$1$\, \$2$\, etc)||in \if\ expansion
At the start of an \if\ expansion the values of the numeric variable
combination of conditions using \or\, the subsequent values of the numeric
variables are those of the condition that succeeded.
-.em
.item "match@_domain @{<<string1>>@}@{<<string2>>@}"
.item "match@_address @{<<string1>>@}@{<<string2>>@}"
.item "match@_local@_part @{<<string1>>@}@{<<string2>>@}"
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. At least, I haven't come
up with anything yet.
-.nem
.item "pam {<<string1>>:<<string2>>:...@}"
.index PAM authentication
in some releases of GNU/Linux \-ldl-\ is also needed.
The argument string is first expanded, and the result must be a colon-separated
-list of strings.
+list of strings.
Leading and trailing whitespace is ignored.
The PAM module is initialized with the service name `exim' and the user name
taken from the first item in the colon-separated data string (<<string1>>). The
Radius authentication (RFC 2865) is supported in a similar way to PAM. You must
set \\RADIUS@_CONFIG@_FILE\\ in \(Local/Makefile)\ to specify the location of
the Radius client configuration file in order to build Exim with Radius
-support.
+support.
You may also have to supply a suitable setting in \\EXTRALIBS\\ so that the
Radius library can be found when Exim is linked.
The string specified by \\RADIUS@_CONFIG@_FILE\\ is expanded and passed to the
matching condition.
.tempindent 0
-\$acl@_c0$\ -- \$acl@_c9$\: Values can be placed in these variables by the
+\$acl@_c0$\ -- \$acl@_c9$\: Values can be placed in these variables by the
\set\ modifier in an ACL. The values persist throughout the lifetime of an SMTP
connection. They can be used to pass information between ACLs and different
-invocations of the same ACL.
+invocations of the same ACL.
When a message is received, the values of these variables are saved with the
-message, and can be accessed by filters, routers, and transports during
+message, and can be accessed by filters, routers, and transports during
subsequent delivery.
.tempindent 0
.tempindent 0
-\$acl@_verify@_message$\: During the expansion of the \message\ and
+\$acl@_verify@_message$\: During the expansion of the \message\ and
\log@_message\ modifiers in an ACL statement after an address verification has
failed, this variable contains the original failure message that will be
overridden by the expanded string.
option in routers. The value then remains with the address while it is
processed by subsequent routers and eventually a transport. If the transport is
handling multiple addresses, the value from the first address is used. See
-chapter ~~CHAProutergeneric for more details.
+chapter ~~CHAProutergeneric for more details.
\**Note**\: the contents of \$address@_data$\ are visible in user filter files.
If \$address@_data$\ is set when the routers are called to verify an address
from an ACL, the final value remains available in subsequent conditions in the
-ACL statement. If routing the address caused it to be redirected to a single
-address, the child address is also routed as part of the verification, and in
+ACL statement. If routing the address caused it to be redirected to a single
+address, the child address is also routed as part of the verification, and in
this case the final value of \$address@_data$\ is from the child's routing.
.tempindent 0
then when the \%address@_file%\ transport is running, \$address@_file$\
contains `/home/r2d2/savemail'.
.index Sieve filter||value of \$address@_file$\
-For Sieve filters, the value may be `inbox' or a relative folder name. It is
-then up to the transport configuration to generate an appropriate absolute path
+For Sieve filters, the value may be `inbox' or a relative folder name. It is
+then up to the transport configuration to generate an appropriate absolute path
to the relevant file.
.index \\AUTH\\||on \\MAIL\\ command
.tempindent 0
\$authenticated@_sender$\:
-.em
When acting as a server, Exim takes note of the \\AUTH=\\ parameter on an
incoming SMTP \\MAIL\\ command
-.nem
if it believes the sender is sufficiently trusted, as described in section
~~SECTauthparamail. Unless the data is the string `@<@>', it is set as the
authenticated sender of the message, and the value is available during delivery
.index authentication||failure
.tempindent 0
-\$authentication@_failed$\:
+\$authentication@_failed$\:
This variable is set to `1' in an Exim server if a client issues an \\AUTH\\
command that does not succeed. Otherwise it is set to `0'. This makes it
possible to distinguish between `did not try to authenticate'
.index body of message||binary zero count
.index binary zero||in message body
.tempindent 0
-.em
\$body@_zerocount$\:
When a message is being received or delivered, this variable contains the
number of binary zero bytes in the message's body.
-.nem
.tempindent 0
\$bounce@_recipient$\:
.index gid (group id)||caller
.tempindent 0
-\$caller@_gid$\: The
-.em
-real
-.nem
+\$caller@_gid$\: The
+real
group id under which the process that called Exim was
running. This is not the same as the group id of the originator of a message
(see \$originator@_gid$\). If Exim re-execs itself, this variable in the new
.index uid (user id)||caller
.tempindent 0
-\$caller@_uid$\: The
-.em
+\$caller@_uid$\: The
real
-.nem
user id under which the process that called Exim was
running. This is not the same as the user id of the originator of a message
(see \$originator@_uid$\). If Exim re-execs itself, this variable in the new
.tempindent 0
\$dnslist@_value$\: When a client host is found to be on a DNS (black) list,
the IP address from the resource record is placed in this variable.
-If there are multiple records, all the addresses are included, comma-space
+If there are multiple records, all the addresses are included, comma-space
separated.
.tempindent 0
.numberpars $.
When an ACL is running for a \\RCPT\\ command, \$domain$\ contains the domain
of the recipient address.
-\**Note:**\ the domain of the sender address is in \$sender@_address@_domain$\
-at \\MAIL\\ time and at \\RCPT\\ time. \$domain$\ is not set for the \\MAIL\\
+\**Note:**\ the domain of the sender address is in \$sender@_address@_domain$\
+at \\MAIL\\ time and at \\RCPT\\ time. \$domain$\ is not set for the \\MAIL\\
ACL.
.nextp
When a rewrite item is being processed (see chapter ~~CHAPrewrite), \$domain$\
of the router as \$domain@_data$\. In addition, if the driver routes the
address to a transport, the value is available in that transport. If the
transport is handling multiple addresses, the value from the first address is
-used.
+used.
-\$domain@_data$\ is also set when the \domains\ condition in an ACL matches a
-domain by means of a lookup. The data read by the lookup is available during
+\$domain@_data$\ is also set when the \domains\ condition in an ACL matches a
+domain by means of a lookup. The data read by the lookup is available during
the rest of the ACL statement. In all other situations, this variable expands
to nothing.
-.em
.tempindent 0
\$exim@_gid$\: This variable contains the numerical value of the Exim group id.
.tempindent 0
\$exim@_uid$\: This variable contains the numerical value of the Exim user id.
-.nem
.tempindent 0
\$header@_<<name>>$\: This is not strictly an expansion variable. It is
This variable contains `1' if the message came from a remote host and there was
an attempt to look up the host's name from its IP address, but the attempt
failed. Otherwise the value of the variable is `0'.
-.em
Exim checks that a forward lookup of at least one of the names it receives from
-a reverse lookup yields the original IP address. If this is not the case, Exim
-does not accept the looked up name(s), and \$host@_lookup@_failed$\ is set to
-`1'. Thus, being able to find a name from an IP address (for example, the
-existence of a PTR record in the DNS) is not sufficient on its own for the
+a reverse lookup yields the original IP address. If this is not the case, Exim
+does not accept the looked up name(s), and \$host@_lookup@_failed$\ is set to
+`1'. Thus, being able to find a name from an IP address (for example, the
+existence of a PTR record in the DNS) is not sufficient on its own for the
success of a host name lookup.
-.nem
.tempindent 0
\$inode$\:
\$interface@_address$\:
When a message is received over a TCP/IP connection, this variable contains the
address of the local IP interface. See also the \-oMi-\ command line option.
-This variable can be used in ACLs and also, for example, to make the file name
+This variable can be used in ACLs and also, for example, to make the file name
for a TLS certificate depend on which interface is being used.
.tempindent 0
\$interface@_port$\:
When a message is received over a TCP/IP connection, this variable contains the
local port number. See also the \-oMi-\ command line option.
-This variable can be used in ACLs and also, for example, to make the file name
+This variable can be used in ACLs and also, for example, to make the file name
for a TLS certificate depend on which port is being used.
.tempindent 0
\$ldap@_dn$\:
-This variable, which is available only when Exim is compiled with LDAP support,
-contains the DN from the last entry in the most recently successful LDAP
+This variable, which is available only when Exim is compiled with LDAP support,
+contains the DN from the last entry in the most recently successful LDAP
lookup.
.tempindent 0
\$load@_average$\:
-This variable contains the system load average, multiplied by 1000 to that it
-is an integer. For example, if the load average is 0.21, the value of the
+This variable contains the system load average, multiplied by 1000 to that it
+is an integer. For example, if the load average is 0.21, the value of the
variable is 210. The value is recomputed every time the variable is referenced.
.tempindent 0
.display asis
data = ${quote_local_part:$local_part}@new.domain.example
.endd
-.em
-\**Note**\: The value of \$local@_part$\ is normally lower cased. If you want
-to process local parts in a case-dependent manner in a router, you can set the
+\**Note**\: The value of \$local@_part$\ is normally lower cased. If you want
+to process local parts in a case-dependent manner in a router, you can set the
\caseful@_local@_part\ option (see chapter ~~CHAProutergeneric).
-.nem
.tempindent 0
\$local@_part@_data$\:
been read.
.tempindent 0
-\$mailstore@_basename$\: This variable is set only when doing deliveries in
-`mailstore' format in the \%appendfile%\ transport. During the expansion of the
-\mailstore@_prefix\, \mailstore@_suffix\, \message__prefix\, and
+\$mailstore@_basename$\: This variable is set only when doing deliveries in
+`mailstore' format in the \%appendfile%\ transport. During the expansion of the
+\mailstore@_prefix\, \mailstore@_suffix\, \message__prefix\, and
\message@_suffix\ options, it contains the basename of the files that are being
written, that is, the name without the `.tmp', `.env', or `.msg' suffix. At all
other times, this variable is empty.
lines are separated by newline characters.
.tempindent 0
-\$message@_id$\:
+\$message@_id$\:
When a message is being received or delivered, this variable contains the
unique message id that is used by Exim to identify the message.
-An id is not created for a message until after its header has been
+An id is not created for a message until after its header has been
successfully received.
-.em
-\**Note**\: This is \*not*\ the contents of the ::Message-ID:: header line; it
-is the local id that Exim assigns to the message, for example:
+\**Note**\: This is \*not*\ the contents of the ::Message-ID:: header line; it
+is the local id that Exim assigns to the message, for example:
\"1BXTIK-0001yO-VA"\.
-.nem
.index size||of message
.index message||size
.tempindent 0
-\$message@_size$\:
+\$message@_size$\:
When a message is being processed, this variable contains its size in bytes. In
most cases, the size includes those headers that were received with the
message, but not those (such as ::Envelope-to::) that are added to individual
.index \\RCPT\\||value of \$message@_size$\
While running an ACL at the time of an SMTP \\RCPT\\ command, \$message@_size$\
-contains the size supplied on the \\MAIL\\ command, or
+contains the size supplied on the \\MAIL\\ command, or
-1
if no size was given. The value may not, of course, be truthful.
\*uname()*\ function. If \*uname()*\ returns a single-component name, Exim
calls \*gethostbyname()*\ (or \*getipnodebyname()*\ where available) in an
attempt to acquire a fully qualified host name.
-.em
See also \$smtp@_active@_hostname$\.
-.nem
.tempindent 0
\$qualify@_domain$\: The value set for this option in the configuration file.
or if not set, the value of \$qualify@_domain$\.
.tempindent 0
-\$rcpt@_count$\: When a message is being received by SMTP, this variable
+\$rcpt@_count$\: When a message is being received by SMTP, this variable
contains the number of \\RCPT\\ commands received for the current message. If
this variable is used in a \\RCPT\\ ACL, its value includes the current
command.
.tempindent 0
-\$rcpt@_defer@_count$\: When a message is being received by SMTP, this variable
+\$rcpt@_defer@_count$\: When a message is being received by SMTP, this variable
contains the number of \\RCPT\\ commands in the current message that have
previously been rejected with a temporary (4\*xx*\) response.
\$received@_for$\: If there is only a single recipient address in an incoming
message, this variable contains that address when the ::Received:: header line
is being built.
-.em
The value is copied after recipient rewriting has happened, but before the
\*local@_scan()*\ function is run.
-.nem
.tempindent 0
\$received@_protocol$\: When a message is being processed, this variable
contains the name of the protocol by which it was received. See also the
\-oMr-\ option.
-.em
.tempindent 0
\$recipient@_data$\: This variable is set after an indexing lookup success in
an ACL \recipients\ condition. It contains the data from the lookup, and the
require recipients = cdb*@@;/some/file
deny \*some further test involving*\ @$recipient@_data
.endd
-\**Warning**\: This variable is set only when a lookup is used as an indexing
+\**Warning**\: This variable is set only when a lookup is used as an indexing
method in the address list, using the semicolon syntax as in the example above.
The variable is not set for a lookup that is used as part of the string
expansion that all such lists undergo before being interpreted.
-.nem
.tempindent 0
\$recipients$\: This variable contains a list of envelope recipients for a
.numberpars
In a system filter file.
.nextp
-In the \\DATA\\ or non-SMTP ACL, that is, in the final ACL for accepting a
+In the \\DATA\\ or non-SMTP ACL, that is, in the final ACL for accepting a
message.
.endp
.tempindent 0
\$return@_path$\: When a message is being delivered, this variable contains the
return path -- the sender field that will be sent as part of the envelope. It
-is not enclosed in @<@> characters.
-At the start of routing an address,
+is not enclosed in @<@> characters.
+At the start of routing an address,
\$return@_path$\ has the same value as \$sender@_address$\, but if, for
example, an incoming message to a mailing list has been expanded by a router
which specifies a different address for bounce messages, \$return@_path$\
subsequently contains the new bounce address, whereas \$sender@_address$\
always contains the original sender address that was received with the message.
-In other words, \$sender@_address$\ contains the incoming envelope sender, and
+In other words, \$sender@_address$\ contains the incoming envelope sender, and
\$return@_path$\ contains the outgoing envelope sender.
.tempindent 0
.tempindent 0
\$runrc$\: This variable contains the return code from a command that is run by
the \@$@{run...@}\ expansion item.
-\**Warning**\: In a router or transport, you cannot assume the order in which
-option values are expanded, except for those pre-conditions whose order of
-testing is documented. Therefore, you cannot reliably expect to set \$runrc$\
+\**Warning**\: In a router or transport, you cannot assume the order in which
+option values are expanded, except for those pre-conditions whose order of
+testing is documented. Therefore, you cannot reliably expect to set \$runrc$\
by the expansion of one option, and use it in another.
.tempindent 0
\$self@_hostname$\: When an address is routed to a supposedly remote host that
-turns out to be the local host, what happens is controlled by the
+turns out to be the local host, what happens is controlled by the
.index \self\ option||value of host name
\self\ generic router option. One of its values causes the address to be passed
to another router. When this happens, \$self@_hostname$\ is set to the name of
.tempindent 0
\$sender@_address@_local@_part$\: The local part portion of \$sender@_address$\.
-.em
.tempindent 0
-\$sender@_data$\: This variable is set after a lookup success in an ACL
+\$sender@_data$\: This variable is set after a lookup success in an ACL
\senders\ condition or in a router \senders\ option. It contains the data from
the lookup, and the value remains set until the next \senders\ test. Thus, you
can do things like this:
require senders = cdb*@@;/some/file
deny \*some further test involving*\ @$sender@_data
.endd
-\**Warning**\: This variable is set only when a lookup is used as an indexing
+\**Warning**\: This variable is set only when a lookup is used as an indexing
method in the address list, using the semicolon syntax as in the example above.
The variable is not set for a lookup that is used as part of the string
expansion that all such lists undergo before being interpreted.
-.nem
.tempindent 0
\$sender@_fullhost$\: When a message is received from a remote host, this
.tempindent 0
\$sender@_host@_name$\: When a message is received from a remote host, this
-variable contains the host's name as obtained by looking up its IP address.
+variable contains the host's name as obtained by looking up its IP address.
For messages received by other means, this variable is empty.
If the host name has not previously been looked up, a reference to
-\$sender@_host@_name$\ triggers a lookup (for messages from remote hosts).
-.em
+\$sender@_host@_name$\ triggers a lookup (for messages from remote hosts).
A looked up name is accepted only if it leads back to the original IP address
via a forward lookup. If either the reverse or the forward lookup fails, or if
the forward lookup does not yield the original IP address,
\$sender@_host@_name$\ remains empty, and \$host@_lookup@_failed$\ is set to
`1'.
-.nem
Exim does not automatically look up every calling host's name. If you want
maximum efficiency, you should arrange your configuration so that it avoids
.numberpars
A string containing \$sender@_host@_name$\ is expanded.
.nextp
-The calling host matches the list in \host@_lookup\. In the default
+The calling host matches the list in \host@_lookup\. In the default
configuration, this option is set to $*$, so it must be changed if lookups are
to be avoided. (In the code, the default for \host@_lookup\ is unset.)
.nextp
that require this are described in sections ~~SECThoslispatnam and
~~SECThoslispatnamsk.
.nextp
-The calling host matches \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\.
-In this case, the host name is required to compare with the name quoted in any
+The calling host matches \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\.
+In this case, the host name is required to compare with the name quoted in any
\\EHLO\\ or \\HELO\\ commands that the client issues.
.nextp
-The remote host issues a \\EHLO\\ or \\HELO\\ command that quotes one of the
-domains in \helo@_lookup@_domains\. The default value of this option is
+The remote host issues a \\EHLO\\ or \\HELO\\ command that quotes one of the
+domains in \helo@_lookup@_domains\. The default value of this option is
.display asis
helo_lookup_domains = @ : @[]
.endd
-which causes a lookup if a remote host (incorrectly) gives the server's name or
+which causes a lookup if a remote host (incorrectly) gives the server's name or
IP address in an \\EHLO\\ or \\HELO\\ command.
.endp
.tempindent 0
\$tls@_cipher$\: When a message is received from a remote host over an
encrypted SMTP connection, this variable is set to the cipher suite that was
-negotiated, for example DES-CBC3-SHA.
-In other circumstances, in particular, for message received over unencrypted
+negotiated, for example DES-CBC3-SHA.
+In other circumstances, in particular, for message received over unencrypted
connections, the variable is empty.
See chapter ~~CHAPTLS for details of TLS support.
.tempindent 0
\$tls@_peerdn$\: When a message is received from a remote host over an
-encrypted SMTP connection,
+encrypted SMTP connection,
and Exim is configured to request a certificate from the client,
the value of the Distinguished Name of the certificate is made available in the
\$tls@_peerdn$\ during subsequent processing.
.tempindent 0
\$tod@_full$\: A full version of the time and date, for example: Wed, 16 Oct
1995 09:51:40 +0100. The timezone is always given as a numerical offset from
-UTC, with positive values used for timezones that are ahead (east) of UTC, and
+UTC, with positive values used for timezones that are ahead (east) of UTC, and
negative values for those that are behind (west).
.tempindent 0
standard SMTP port, you should not need to take any special action. The
rest of this chapter does not apply to you.
-In a more complicated situation you may want to listen only on certain
+In a more complicated situation you may want to listen only on certain
interfaces, or on different ports, and for this reason there are a number of
options that can be used to influence Exim's behaviour. The rest of this
chapter describes how they operate.
192.168.23.65 ; \
::1 ; \
3ffe:ffff:836f::fe86:a061
-.endd
+.endd
There are two different formats for specifying a port along with an IP address
in \local@_interfaces\:
.numberpars
-The port is added onto the address with a dot separator. For example, to listen
+The port is added onto the address with a dot separator. For example, to listen
on port 1234 on two different IP addresses:
.display asis
local_interfaces = <; 192.168.23.65.1234 ; \
3ffe:ffff:836f::fe86:a061.1234
-.endd
+.endd
.nextp
The IP address is enclosed in square brackets, and the port is added
with a colon separator, for example:
.display asis
local_interfaces = <; [192.168.23.65]:1234 ; \
[3ffe:ffff:836f::fe86:a061]:1234
-.endd
+.endd
.endp
When a port is not specified, the value of \daemon@_smtp@_ports\ is used. The
default setting contains just one port:
IP addresses in \local@_interfaces\, only numbers (not names) can be used.
-.section Special IP listening addresses
+.section Special IP listening addresses
The addresses 0.0.0.0 and @:@:0 are treated specially. They are interpreted
as `all IPv4 interfaces' and `all IPv6 interfaces', respectively. In each
case, Exim tells the TCP/IP stack to `listen on all IPv\*x*\ interfaces'
address, but all available interface addresses are treated as local when
Exim is routing.
-In some environments the local host name may be in an MX list, but with an IP
-address that is not assigned to any local interface. In other cases it may be
+In some environments the local host name may be in an MX list, but with an IP
+address that is not assigned to any local interface. In other cases it may be
desirable to treat other host names as if they referred to the local host. Both
these cases can be handled by setting the \hosts@_treat@_as@_local\ option.
This contains host names rather than IP addresses. When a host is referenced
\log@_selector\ $t$rm{set/unset optional logging}
\log@_timezone\ $t$rm{add timezone to log lines}
\message@_logs\ $t$rm{create per-message logs}
-\preserve@_message@_logs\ $t$rm{in another directory after message completion}
+\preserve@_message@_logs\ $t$rm{after message completion}
\process@_log@_path\ $t$rm{for SIGUSR1 and \*exiwhat*\}
\syslog@_duplication\ $t$rm{controls duplicate log lines on syslog }
\syslog@_facility\ $t$rm{set syslog `facility' field}
\syslog@_processname\ $t$rm{set syslog `ident' field}
\syslog@_timestamp\ $t$rm{timestamp syslog lines}
.newline
-.em
\write@_rejectlog\ $t$rm{control use of message log}
.newline
-.nem
.endd
.section Frozen messages
\extra@_local@_interfaces\ $t$rm{not necessarily listened on}
\local@_interfaces\ $t$rm{on which to listen, with optional ports}
\pid@_file@_path\ $t$rm{override compiled-in value}
-\queue@_run@_max\ $t$rm{maximum number of simultaneous queue runners}
+\queue@_run@_max\ $t$rm{maximum simultaneous queue runners}
.endd
.section Resource control
\check@_spool@_space\ $t$rm{before accepting a message}
\deliver@_queue@_load@_max\ $t$rm{no queue deliveries if load high}
\queue@_only@_load\ $t$rm{queue incoming if load high}
-\queue@_run@_max\ $t$rm{maximum number of simultaneous queue runners}
+\queue@_run@_max\ $t$rm{maximum simultaneous queue runners}
\remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message}
\smtp@_accept@_max\ $t$rm{simultaneous incoming connections}
\smtp@_accept@_max@_nommail\ $t$rm{non-mail commands}
\tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts}
\tls@_certificate\ $t$rm{location of server certificate}
.newline
-.em
\tls@_crl\ $t$rm{certificate revocation list}
.newline
-.nem
\tls@_dhparam\ $t$rm{DH parameters for server}
\tls@_privatekey\ $t$rm{location of server private key}
\tls@_remember@_esmtp\ $t$rm{don't reset after starting TLS}
.newline
-.em
\tls@_require@_ciphers\ $t$rm{specify acceptable cipers}
.newline
-.nem
\tls@_try@_verify@_hosts\ $t$rm{try to verify client certificate}
\tls@_verify@_certificates\ $t$rm{expected client certificates}
\tls@_verify@_hosts\ $t$rm{insist on client certificate verify}
.endd
-.section Local user handling
+.section Local user handling
.display flow rm
.tabs 31
\finduser@_retries\ $t$rm{useful in NIS environments}
\smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection}
\smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections}
.newline
-.em
\smtp@_active@_hostname\ $t$rm{host name to use in messages}
.newline
-.nem
\smtp@_banner\ $t$rm{text for welcome banner}
\smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command}
\smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack}
\queue@_run@_in@_order\ $t$rm{order of arrival}
\queue@_run@_max\ $t$rm{of simultaneous queue runners}
\queue@_smtp@_domains\ $t$rm{no immediate SMTP delivery for these}
-\remote@_max@_parallel\ $t$rm{parallel SMTP delivery (per message, not overall)}
+\remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message}
\remote@_sort@_domains\ $t$rm{order of remote deliveries}
\retry@_data@_expire\ $t$rm{timeout for retry data}
\retry@_interval@_max\ $t$rm{safety net for retry rules}
.index ~~ACL||for non-SMTP messages
.index non-SMTP messages, ACL for
.conf acl@_not@_smtp string$**$ unset
-This option defines the ACL that is run when a non-SMTP message is on the point
+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
+.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 \\AUTH\\||on \\MAIL\\ command
.conf acl@_smtp@_mailauth string$**$ unset
-This option defines the ACL that is run when there is an \\AUTH\\ parameter on
+This option defines the ACL that is run when there is an \\AUTH\\ parameter on
a \\MAIL\\ command. See chapter ~~CHAPACL for details of ACLs, and chapter
~~CHAPSMTPAUTH for details of authentication.
format is not normally required these days, and few people know about it. It
has, however, been exploited by mail abusers.
-Unfortunately, it seems that some DNS black list maintainers are using this
-format to report black listing to postmasters. If you want to accept messages
-addressed to your hosts by IP address, you need to set
-\allow@_domain@_literals\ true, and also to add \"@@[]"\ to the list of local
-domains (defined in the named domain list \local@_domains\ in the default
-configuration). This `magic string' matches the domain literal form of all the
+Unfortunately, it seems that some DNS black list maintainers are using this
+format to report black listing to postmasters. If you want to accept messages
+addressed to your hosts by IP address, you need to set
+\allow@_domain@_literals\ true, and also to add \"@@[]"\ to the list of local
+domains (defined in the named domain list \local@_domains\ in the default
+configuration). This `magic string' matches the domain literal form of all the
local host's IP addresses.
.conf allow@_mx@_to@_ip boolean false
.conf allow@_utf8@_domains boolean false
Lots of discussion is going on about internationalized domain names. One
camp is strongly in favour of just using UTF-8 characters, and it seems
-that at least two other MTAs permit this. This option allows Exim users to
+that at least two other MTAs permit this. This option allows Exim users to
experiment if they wish.
If it is set true, Exim's domain parsing function allows valid
If any server authentication mechanisms are configured, Exim advertises them in
response to an \\EHLO\\ command only if the calling host matches this list.
Otherwise, Exim does not advertise \\AUTH\\.
-Exim does not accept \\AUTH\\ commands from clients to which it has not
-advertised the availability of \\AUTH\\. The advertising of individual
+Exim does not accept \\AUTH\\ commands from clients to which it has not
+advertised the availability of \\AUTH\\. The advertising of individual
authentication mechanisms can be controlled by the use of the
-\server@_advertise@_condition\ generic authenticator option on the individual
+\server@_advertise@_condition\ generic authenticator option on the individual
authenticators. See chapter ~~CHAPSMTPAUTH for further details.
Certain mail clients (for example, Netscape) require the user to provide a name
.display asis
auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}}
.endd
-If \$tls@_cipher$\ is empty, the session is not encrypted, and the result of
-the expansion is empty, thus matching no hosts. Otherwise, the result of the
+If \$tls@_cipher$\ is empty, the session is not encrypted, and the result of
+the expansion is empty, thus matching no hosts. Otherwise, the result of the
expansion is $*$, which matches all hosts.
.conf auto@_thaw time 0s
.index bounce message||including body
.conf bounce@_return@_body boolean true
-This option controls whether the body of an incoming message is included in a
-bounce message when \bounce@_return@_message\ is true. If it is not set, only
+This option controls whether the body of an incoming message is included in a
+bounce message when \bounce@_return@_message\ is true. If it is not set, only
the message header is included.
.index bounce message||including original
section ~~SECTcallvercache for details of the caching.
.conf callout@_random@_local@_part string$**$ "see below"
-This option defines the `random' local part that can be used as part of callout
+This option defines the `random' local part that can be used as part of callout
verification. The default value is
.display asis
$primary_host_name-$tod_epoch-testing
.index TCP/IP||setting listening ports
.conf daemon@_smtp@_ports string "$tt{smtp}"
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
+listens. See chapter ~~CHAPinterfaces for details of how it is used. For
backward compatibility, \daemon@_smtp@_port\ (singular) is a synonym.
.conf delay@_warning "time list" 24h
delay_warning = 4h:8h:24h
.endd
the first message is sent after 4 hours, the second after 8 hours, and
-the third one after 24 hours. After that, messages are sent every 16 hours,
-because that is the interval between the last two times on the list. If you set
+the third one after 24 hours. After that, messages are sent every 16 hours,
+because that is the interval between the last two times on the list. If you set
just one time, it specifies the repeat interval. For example, with:
.display asis
delay_warning = 6h
for a long time. If a domain which exhibits this problem matches anything in
\dns__again__means__nonexist\, it is treated as if it did not exist. This
option should be used with care.
-.em
You can make it apply to reverse lookups by a setting such as this:
.display asis
dns_again_means_nonexist = *.in-addr.arpa
.endd
-.nem
.index DNS||pre-check of name syntax
.conf dns@_check@_names@_pattern string "see below"
.endd
which permits only letters, digits, and hyphens in components, but they may not
start or end with a hyphen.
-If you set \allow@_utf8@_domains\, you must modify this pattern, or set the
+If you set \allow@_utf8@_domains\, you must modify this pattern, or set the
option to an empty string.
.conf dns@_ipv4@_lookup "domain list$**$" unset
See \dns@_retrans\ above.
.conf drop@_cr boolean false
-This is an obsolete option that is now a no-op. It used to affect the way Exim
-handled CR and LF characters in incoming messages. What happens now is
+This is an obsolete option that is now a no-op. It used to affect the way Exim
+handled CR and LF characters in incoming messages. What happens now is
described in section ~~SECTlineendings.
.conf envelope@_to@_remove boolean true
The address list is expanded before use. The expansion variables
\$local@_part$\ and \$domain$\ are set from the original recipient of the error
message, and if there was any wildcard matching in the pattern, the expansion
-.index numerical variables (\$1$\, \$2$\, etc)||in \errors@_copy\
+.index numerical variables (\$1$\, \$2$\, etc)||in \errors@_copy\
variables \$0$\, \$1$\, etc. are set in the normal way.
.conf errors@_reply@_to string unset
.display
From: Mail Delivery System @<Mailer-Daemon@@<<qualify-domain>>@>
.endd
-where <<qualify-domain>> is the value of the \qualify@_domain\ option.
+where <<qualify-domain>> is the value of the \qualify@_domain\ option.
Experience shows that people reply to bounce messages. If the
\errors@_reply@_to\ option is set, a ::Reply-To:: header is added to bounce and
warning messages. For example:
the directory configured at compile time by the \\BIN@_DIRECTORY\\ setting. It
is necessary to change \exim@_path\ if, exceptionally, Exim is run from some
other place.
-\**Warning**\: Do not use a macro to define the value of this option, because
-you will break those Exim utilities that scan the configuration file to find
-where the binary is. (They then use the \-bP-\ option to extract option
+\**Warning**\: Do not use a macro to define the value of this option, because
+you will break those Exim utilities that scan the configuration file to find
+where the binary is. (They then use the \-bP-\ option to extract option
settings such as the value of \spool@_directory\.)
.conf exim@_user string "compile-time configured"
used. See chapter ~~CHAPsecurity for a discussion of security issues.
.conf extra@_local@_interfaces "string list" unset
-.index
-This option defines network interfaces that are to be considered local when
-routing, but which are not used for listening by the daemon. See section
+.index
+This option defines network interfaces that are to be considered local when
+routing, but which are not used for listening by the daemon. See section
~~SECTreclocipadd for details.
.conf extract@_addresses@_remove@_arguments boolean true
Exim freezes a message. This means that no further delivery attempts take place
until an administrator (or the \auto@_thaw\ feature) thaws the message. If
\freeze@_tell\ is set, Exim generates a warning message whenever it freezes
-something, unless the message it is freezing is a
+something, unless the message it is freezing is a
locally-generated
bounce message. (Without this exception there is the possibility of looping.)
The warning message is sent to the addresses supplied as the comma-separated
value of this option. If several of the message's addresses cause freezing,
-only a single message is sent.
+only a single message is sent.
If the freezing was automatic, the reason(s) for freezing can be found in the
-message log. If you configure freezing in a filter or ACL, you must arrange for
+message log. If you configure freezing in a filter or ACL, you must arrange for
any logging that you require.
.conf gecos@_name string$**$ unset
When these options are set, \gecos@_pattern\ is treated as a regular expression
that is to be applied to the field (again with & replaced by the login name),
and if it matches, \gecos@_name\ is expanded and used as the user's name.
-.index numerical variables (\$1$\, \$2$\, etc)||in \gecos@_name\
+.index numerical variables (\$1$\, \$2$\, etc)||in \gecos@_name\
Numeric variables such as \$1$\, \$2$\, etc. can be used in the expansion to
pick up sub-fields that were matched by the pattern. In HP-UX, where the user's
name terminates at the first comma, the following can be used:
.index limit||size of message header section
This option controls the overall maximum size of a message's header
section. The default is the value of \\HEADER@_MAXSIZE\\ in
-\(Local/Makefile)\; the default for that is 1M. Messages with larger header
+\(Local/Makefile)\; the default for that is 1M. Messages with larger header
sections are rejected.
.conf header@_line@_maxsize integer 0
-.index header lines||maximum size of
+.index header lines||maximum size of
.index limit||size of one header line
This option limits the length of any individual header line in a message, after
all the continuations have been joined together. Messages with individual
some SMTP clients that send syntactic junk. They can be accommodated by setting
this option. Note that this is a syntax check only. See \helo@_verify@_hosts\
if you want to do semantic checking.
-See also \helo@_allow@_chars\ for a way of extending the permitted character
+See also \helo@_allow@_chars\ for a way of extending the permitted character
set.
.conf helo@_allow@_chars string unset
when looked up using \*gethostbyname()*\ (or \*getipnodebyname()*\ when
available) yields the calling host address.
.endp
-However, the \\EHLO\\ or \\HELO\\ command is not rejected if any of the checks
+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 you want
verification failure to cause rejection of \\EHLO\\ or \\HELO\\, use
\\HELO\\ or \\EHLO\\ in the same way as for \helo@_try@_verify@_hosts\. If the
check fails, the \\HELO\\ or \\EHLO\\ command is rejected with a 550 error, and
entries are written to the main and reject logs. If a \\MAIL\\ command is
-received before \\EHLO\\ or \\HELO\\, it is rejected with a
-503
+received before \\EHLO\\ or \\HELO\\, it is rejected with a
+503
error.
.conf hold@_domains "domain list$**$" unset
.conf host@_lookup@_order "string list" $tt{bydns:byaddr}
This option specifies the order of different lookup methods when Exim is trying
-to find a host name from an IP address. The default is to do a DNS lookup
+to find a host name from an IP address. The default is to do a DNS lookup
first, and then to try a local lookup (using \*gethostbyaddr()*\ or equivalent)
if that fails. You can change the order of these lookups, or omit one entirely,
if you want.
\**Warning**\: the `byaddr' method does not always yield aliases when there are
-multiple PTR records in the DNS and the IP address is not listed in
+multiple PTR records in the DNS and the IP address is not listed in
\(/etc/hosts)\. Different operating systems give different results in this
case. That is why the default tries a DNS lookup first.
.conf host@_reject@_connection "host list$**$" unset
.index host||rejecting connections from
If this option is set, incoming SMTP calls from the hosts listed are rejected
-as soon as the connection is made.
+as soon as the connection is made.
This option is obsolete, and retained only for backward compatibility, because
nowadays the ACL specified by \acl@_smtp@_connect\ can also reject incoming
connections immediately.
section ~~SECTdomainlist), and when checking the \hosts\ option in the \%smtp%\
transport for the local host (see the \allow@_localhost\ option in that
transport).
-See also \local@_interfaces\, \extra@_local@_interfaces\, and chapter
-~~CHAPinterfaces, which contains a discussion about local network interfaces
+See also \local@_interfaces\, \extra@_local@_interfaces\, and chapter
+~~CHAPinterfaces, which contains a discussion about local network interfaces
and recognising the local host.
.conf ignore@_bounce@_errors@_after time 10w
.index bounce message||discarding
.index discarding bounce message
-This option affects the processing of bounce messages that cannot be delivered,
-that is, those that suffer a permanent delivery failure. (Bounce messages that
+This option affects the processing of bounce messages that cannot be delivered,
+that is, those that suffer a permanent delivery failure. (Bounce messages that
suffer temporary delivery failures are of course retried in the usual way.)
After a permanent delivery failure, bounce messages are frozen,
See \local@_from@_prefix\ above.
.conf local@_interfaces "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
-~~CHAPinterfaces contains a full description of this option and the related
-options \extra@_local@_interfaces\ and \hosts@_treat@_as@_local\. The default
+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
+~~CHAPinterfaces contains a full description of this option and the related
+options \extra@_local@_interfaces\ and \hosts@_treat@_as@_local\. The default
value for \local@_interfaces\ is
.display asis
local_interfaces = 0.0.0.0
.index limit||message size
.index size||of message, limit
This option limits the maximum size of message that Exim will process. The
-value is expanded for each incoming
+value is expanded for each incoming
connection so, for example, it can be made to depend on the IP address of the
remote host for messages arriving via TCP/IP. \**Note**\: This limit cannot be
made to depend on a message's sender or any other properties of an individual
recipient, and remote deliveries are normally run under Exim's own uid and gid.
It is usually desirable to prevent any deliveries from running as root, as a
safety precaution.
-
-When Exim is built, an option called \\FIXED@_NEVER@_USERS\\ can be set to a
-list of users that must not be used for local deliveries. This list is fixed in
-the binary and cannot be overridden by the configuration file. By default, it
-contains just the single user name `root'. The \never@_users\ runtime option
+
+When Exim is built, an option called \\FIXED@_NEVER@_USERS\\ can be set to a
+list of users that must not be used for local deliveries. This list is fixed in
+the binary and cannot be overridden by the configuration file. By default, it
+contains just the single user name `root'. The \never@_users\ runtime option
can be used to add more users to the fixed list.
If a message is to be delivered as one of the users on the fixed list or the
.endd
If no path is set, the pid is written to the file \(exim-daemon.pid)\ in Exim's
spool directory.
-The value set by the option can be overridden by the \-oP-\ command line
-option. A pid file is not written if a `non-standard' daemon is run by means of
+The value set by the option can be overridden by the \-oP-\ command line
+option. A pid file is not written if a `non-standard' daemon is run by means of
the \-oX-\ option, unless a path is explicitly supplied by \-oP-\.
.conf pipelining@_advertise@_hosts "host list$**$" $*$
\\PIPELINING\\ extension to specific hosts. When \\PIPELINING\\ is not
advertised and \smtp@_enforce@_sync\ is true, an Exim server enforces strict
synchronization for each SMTP command and response.
-.em
When \\PIPELINING\\ is advertised, Exim assumes that clients will use it; `out
-of order' commands that are `expected' do not count as protocol errors (see
+of order' commands that are `expected' do not count as protocol errors (see
\smtp@_max@_synprot@_errors\).
-.nem
.conf preserve@_message@_logs boolean false
.index message logs, preserving
.index name||of local host
.index host||name of local
.index local host||name of
-.em
This specifies the name of the current host. It is used in the default \\EHLO\\
or \\HELO\\ command for outgoing SMTP messages (changeable via the \helo@_data\
option in the \%smtp%\ transport),
-.nem
and as the default for \qualify@_domain\. If it is not set, Exim calls
\*uname()*\ to find it. If this fails, Exim panics and dies. If the name
returned by \*uname()*\ contains only one component, Exim passes it to
\*gethostbyname()*\ (or \*getipnodebyname()*\ when available) in order to
obtain the fully qualified version.
-.em
The value of \$primary@_hostname$\ is also used by default in some SMTP
response messages from an Exim server. This can be changed dynamically by
setting \smtp@_active@_hostname\.
-.nem
.conf print@_topbitchars boolean false
.index printing characters
.conf process@_log@_path string unset
.index process log path
-.index log||process log
+.index log||process log
.index \*exiwhat*\
This option sets the name of the file to which an Exim process writes its
`process log' when sent a USR1 signal. This is used by the \*exiwhat*\ utility
Received: by scrooge.carol.example with local (Exim 4.00)
id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000
.endd
-.em
-Until the body of the message has been received, the timestamp is the time when
-the message started to be received. Once the body has arrived, and all policy
-checks have taken place, the timestamp is updated to the time at which the
+Until the body of the message has been received, the timestamp is the time when
+the message started to be received. Once the body has arrived, and all policy
+checks have taken place, the timestamp is updated to the time at which the
message was accepted.
-.nem
.conf received@_headers@_max integer 30
.index loop||prevention
affects message header lines. Exim does not reject unqualified recipient
addresses in headers, but it qualifies them only if the message came from a
host that matches \recipient@_unqualified@_hosts\,
-.em
or if the message was submitted locally (not using TCP/IP), and the \-bnq-\
option was not set.
-.nem
.conf recipients@_max integer 0
.index limit||number of recipients
-.index recipient||maximum number
+.index recipient||maximum number
If this option is set greater than zero, it specifies the maximum number of
original recipients for any message. Additional recipients that are generated
by aliasing or forwarding do not count. SMTP messages get a 452 response for
reject unqualified addresses in headers that contain sender addresses, but it
qualifies them only if the message came from a host that matches
\sender@_unqualified@_hosts\,
-.em
or if the message was submitted locally (not using TCP/IP), and the \-bnq-\
option was not set.
-.nem
.conf smtp@_accept@_keepalive boolean true
.index keepalive||on incoming connection
Exim counts the number of `non-mail' commands in an SMTP session, and drops the
connection if there are too many. This option defines `too many'. The check
catches some denial-of-service attacks, repeated failing \\AUTH\\s, or a mad
-client looping sending \\EHLO\\, for example. The check is applied only if the
+client looping sending \\EHLO\\, for example. The check is applied only if the
client host matches \smtp@_accept@_max@_nonmail@_hosts\.
When a new message is expected, one occurrence of \\RSET\\ is not counted. This
connections are accepted only from hosts listed in \smtp@_reserve@_hosts\.
See also \smtp@_accept@_max@_per@_host\.
-.em
.conf smtp@_active@_hostname string$**$ unset
.index host||name in SMTP responses
.index SMTP||host name in responses
.endd
If you set \smtp@_active@_hostname\, you probably also want to set
\smtp@_banner\, since its default value references \$primary@_hostname$\.
-.nem
.conf smtp@_banner string$**$ "see below"
.index SMTP||welcome banner
transmission delays (unexpected input may be on its way but not yet received
when Exim checks). However, it does detect many instances. The check can be
disabled by setting \smtp@_enforce@_sync\ false.
-.em
See also \pipelining@_advertise@_hosts\.
-.nem
.conf smtp@_etrn@_command string$**$ unset
.index \\ETRN\\||command to be run
.conf smtp@_max@_synprot@_errors integer 3
.index SMTP||limiting syntax and protocol errors
.index limit||SMTP syntax and protocol errors
-Exim rejects SMTP commands that contain syntax or protocol errors. In
+Exim rejects SMTP commands that contain syntax or protocol errors. In
particular, a syntactically invalid email address, as in this command:
.display asis
RCPT TO:<abc xyz@a.b.c>
too many syntax or protocol errors in one SMTP session, the connection is
dropped. The limit is set by this option.
-.em
.index \\PIPELINING\\||expected errors
-When the \\PIPELINING\\ extension to SMTP is in use, some protocol errors are
-`expected', for instance, a \\RCPT\\ command after a rejected \\MAIL\\ command.
-Exim assumes that \\PIPELINING\\ will be used if it advertises it (see
-\pipelining@_advertise@_hosts\), and in this situation, `expected' errors do
+When the \\PIPELINING\\ extension to SMTP is in use, some protocol errors are
+`expected', for instance, a \\RCPT\\ command after a rejected \\MAIL\\ command.
+Exim assumes that \\PIPELINING\\ will be used if it advertises it (see
+\pipelining@_advertise@_hosts\), and in this situation, `expected' errors do
not count towards the limit.
-.nem
.conf smtp@_max@_unknown@_commands integer 3
.index SMTP||limiting unknown commands
.index limit||unknown SMTP commands
-If there are too many unrecognized commands in an incoming SMTP session, an
-Exim server drops the connection. This is a defence against some kinds of abuse
-that subvert web
-.em
-clients
-.nem
+If there are too many unrecognized commands in an incoming SMTP session, an
+Exim server drops the connection. This is a defence against some kinds of abuse
+that subvert web
+clients
into making connections to SMTP ports; in these circumstances, a number of
non-SMTP command lines are sent first.
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.
-It is also possible to configure delays explicitly in ACLs. See section
+It is also possible to configure delays explicitly in ACLs. See section
~~SECTACLmodi for details.
This sets a timeout value for SMTP reception. It applies to all forms of SMTP
input, including batch SMTP. If a line of input (either an SMTP command or a
data line) is not received within this time, the SMTP connection is dropped and
-the message is abandoned.
+the message is abandoned.
A line is written to the log containing one of the following messages:
.display asis
SMTP command timeout on connection from...
SMTP data timeout on connection from...
.endd
-The former means that Exim was expecting to read an SMTP command; the latter
+The former means that Exim was expecting to read an SMTP command; the latter
means that it was in the \\DATA\\ phase, reading the contents of a message.
ignored. If this is in the envelope and the message is passed on to another
MTA, the dot is not passed on. If this option is not set, a dot at the end of a
domain causes a syntax error.
-.em
-However, addresses in header lines are checked only when an ACL requests header
+However, addresses in header lines are checked only when an ACL requests header
syntax checking.
-.nem
.conf syslog@_duplication boolean true
.index syslog||duplicate log lines, suppressing
.conf syslog@_facility string unset
.index syslog||facility, setting
-This option sets the syslog `facility' name, used when Exim is logging to
+This option sets the syslog `facility' name, used when Exim is logging to
syslog. The value must be one of the strings `mail', `user', `news', `uucp',
-`daemon', or `local\*x*\' where \*x*\ is a digit between 0 and 7. If this
+`daemon', or `local\*x*\' where \*x*\ is a digit between 0 and 7. If this
option is unset, `mail' is used. See chapter ~~CHAPlog for details of Exim's
logging.
assumed to be in this file if \tls@_privatekey\ is unset. See chapter ~~CHAPTLS
for further details.
-\**Note**\: The certificates defined by this option are used only when Exim is
+\**Note**\: The certificates defined by this option are used only when Exim is
receiving incoming messages as a server. If you want to supply certificates for
use when sending messages as a client, you must set the \tls@_certificate\
option in the relevant \%smtp%\ transport.
-.em
.conf tls@_crl string$**$ unset
.index TLS||server certificate revocation list
.index certificate||revocation list for server
This option specifies a certificate revocation list. The expanded value must
be the name of a file that contains a CRL in PEM format.
-.nem
.conf tls@_dhparam string$**$ unset
.index TLS||D-H parameters for server
The value of this option is expanded, and must then be the absolute path to
a file which contains the server's DH parameter values.
-This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is
+This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is
ignored. See section ~~SECTopenvsgnu for further details.
.conf tls@_privatekey string$**$ unset
.index TLS||server private key, location of
The value of this option is expanded, and must then be the absolute path to
a file which contains the server's private key.
-If this option is unset, the private key is assumed to be in the same file as
+If this option is unset, the private key is assumed to be in the same file as
the server's certificates. See chapter ~~CHAPTLS for further details.
.conf tls@_remember@_esmtp boolean false
support for broken clients that fail to send a new \\EHLO\\ after starting a
TLS session.
-.em
.conf tls@_require@_ciphers string$**$ unset
.index TLS||requiring specific ciphers
.index cipher||requiring specific
This option controls which ciphers can be used for incoming TLS connections.
-(The \%smtp%\ transport has an option of the same name for controlling outgoing
+(The \%smtp%\ transport has an option of the same name for controlling outgoing
connections.) This option is expanded for each connection, so can be varied for
different clients if required. The value of this option must be a list of
permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control
in somewhat different ways. Details are given in section ~~SECTreqciphsslgnu.
-.nem
.conf tls@_try@_verify@_hosts "host list$**$" unset
.index TLS||client certificate verification
.index TLS||client certificate verification
.index certificate||verification of client
This option, along with \tls@_try@_verify@_hosts\, controls the checking of
-certificates from clients.
-The expected certificates are defined by \tls@_verify@_certificates\, which
-must be set. A configuration error occurs if either \tls@_verify@_hosts\ or
+certificates from clients.
+The expected certificates are defined by \tls@_verify@_certificates\, which
+must be set. A configuration error occurs if either \tls@_verify@_hosts\ or
\tls@_try@_verify@_hosts\ is set and \tls@_verify@_certificates\ is not set.
Any client that matches \tls@_verify@_hosts\ is constrained by
.index trusted group
.index group||trusted
If this option is set, any process that is running in one of the listed groups,
-or which has one of them as a supplementary group, is trusted.
+or which has one of them as a supplementary group, is trusted.
The groups can be specified numerically or by name.
See section ~~SECTtrustedadmin for details of what trusted callers are
permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only
.index trusted user
.index user||trusted
If this option is set, any process that is running as one of the listed users
-is trusted.
+is trusted.
The users can be specified numerically or by name.
See section ~~SECTtrustedadmin for details of what trusted callers are
permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only
users are allowed to set envelope sender addresses that match any of the
patterns in the list. Like all address lists, the string is expanded. The
identity of the user is in \$sender@_ident$\, so you can, for example, restrict
-users to setting senders that start with their login ids
+users to setting senders that start with their login ids
followed by a hyphen
by a setting like this:
.display asis
\delay@_warning\. Details of the file's contents are given in chapter
~~CHAPemsgcust. See also \bounce@_message@_file\.
-.em
.conf write@_rejectlog boolean true
.index reject log||disabling
If this option is set false, Exim no longer writes anything to the reject log.
See chapter ~~CHAPlog for details of what Exim writes to its logs.
-.nem
.endconf
.index options||generic, for routers
.index generic options||router
-This chapter describes the generic options that apply to all routers,
+This chapter describes the generic options that apply to all routers,
identifying those that are preconditions. For a general description of how a
router operates, see sections ~~SECTrunindrou and ~~SECTrouprecon. The second
of these sections specifies the order in which the preconditions are tested.
-The order of expansion of the options that provide data for a transport is:
+The order of expansion of the options that provide data for a transport is:
\errors@_to\, \headers@_add\, \headers@_remove\, \transport\.
.startconf
When the expansion succeeds, the value is retained with the address, and can be
accessed using the variable \$address@_data$\ in the current router, subsequent
-routers, and the eventual transport.
+routers, and the eventual transport.
-\**Warning**\: if the current or any subsequent router is a \%redirect%\ router
+\**Warning**\: if the current or any subsequent router is a \%redirect%\ router
that runs a user's filter file, the contents of \$address@_data$\ are
accessible in the filter. This is not normally a problem, because such data is
-usually either not confidential or it `belongs' to the current user, but if you
-do put confidential data into \$address@_data$\ you need to remember this
+usually either not confidential or it `belongs' to the current user, but if you
+do put confidential data into \$address@_data$\ you need to remember this
point.
Even if the router declines or passes, the value of \$address@_data$\ remains
lookups. (Exim does cache the most recent lookup, but there may be several
addresses in a message which cause lookups to occur.)
-The \address@_data\ facility is also useful as a means of passing information
+The \address@_data\ facility is also useful as a means of passing information
from one router to another,
-and from a router to a transport. In addition, if \address@_data\ is set by a
-router when verifying an address from an ACL, its value is available for use in
+and from a router to a transport. In addition, if \address@_data\ is set by a
+router when verifying an address from an ACL, its value is available for use in
the rest of the ACL statement.
.index router||skipping when address testing
If this option is set false, the router is skipped when routing is being tested
by means of the \-bt-\ command line option. This can be a convenience when your
-first router sends messages to an external scanner, because it saves you
-having to set the `already scanned' indicator when testing real address
+first router sends messages to an external scanner, because it saves you
+having to set the `already scanned' indicator when testing real address
routing.
.display asis
cannot_route_message = Unknown local user
.endd
-on the final router that checks for local users. If string expansion fails, the
+on the final router that checks for local users. If string expansion fails, the
default message is used.
Unless the expansion failure was explicitly forced, a message about the failure
is written to the main and panic logs, in addition to the normal message about
than trying to read \(/etc/passwd)\ directly. This means that other methods of
holding password data (such as NIS) are supported. If the local part is a local
user, \$home$\ is set from the password data, and can be tested in other
-preconditions that are evaluated after this one
+preconditions that are evaluated after this one
(the order of evaluation is given in section ~~SECTrouprecon). However, the
value of \$home$\ can be overridden by \router@_home@_directory\.
If the local part is not a local user, the router is skipped.
If you want to check that the local part is either the name of a local user
-or matches something else, you cannot combine \check@_local@_user\ with a
-setting of \local@_parts\, because that specifies the logical \*and*\ of the
-two conditions. However, you can use a \%passwd%\ lookup in a \local@_parts\
+or matches something else, you cannot combine \check@_local@_user\ with a
+setting of \local@_parts\, because that specifies the logical \*and*\ of the
+two conditions. However, you can use a \%passwd%\ lookup in a \local@_parts\
setting to achieve this. For example:
.display asis
local_parts = passwd;$local_part : lsearch;/etc/other/users
of the other options below are common special cases that could in fact be
specified using \condition\.
Note that \condition\ is the last precondition to be evaluated (see
-section ~~SECTrouprecon).
+section ~~SECTrouprecon).
.conf debug@_print string$**$ unset
.index testing||variables in drivers
If this option is set and debugging is enabled (see the \-d-\ command line
-option), the string is expanded and included in the debugging output.
-If expansion of the string fails, the error message is written to the debugging
+option), the string is expanded and included in the debugging output.
+If expansion of the string fails, the error message is written to the debugging
output, and Exim carries on processing.
This option is provided to help with checking out the values of variables and
so on when debugging router configurations. For example, if a \condition\
.conf disable@_logging boolean false
If this option is set true, nothing is logged for any routing errors
-.em
or for any deliveries caused by this router. You should not set this option
unless you really, really know what you are doing. See also the generic
transport option of the same name.
-.nem
.conf domains "domain list$**$ (precondition)" unset
.index router||restricting to specific domains
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
expansions of the driver's private options.
-See section ~~SECTrouprecon for a list of the order in which preconditions
+See section ~~SECTrouprecon for a list of the order in which preconditions
are evaluated.
delivery or it may generate child addresses. In both cases, if there is a
delivery problem during later processing, the resulting bounce message is sent
to the address that results from expanding this string, provided that the
-address verifies successfully.
-\errors@_to\ is expanded before \headers@_add\, \headers@_remove\, and
+address verifies successfully.
+\errors@_to\ is expanded before \headers@_add\, \headers@_remove\, and
\transport\.
If the option is unset, or the expansion is forced to fail, or the result of
If this option is turned off, the router is skipped when testing an address
as a result of processing an SMTP \\EXPN\\ command. You might, for example,
want to turn it off on a router for users' \(.forward)\ files, while leaving it
-on for the system alias file.
-See section ~~SECTrouprecon for a list of the order in which preconditions
+on for the system alias file.
+See section ~~SECTrouprecon for a list of the order in which preconditions
are evaluated.
The use of the SMTP \\EXPN\\ command is controlled by an ACL (see chapter
.index router||setting group
When a router queues an address for a transport, and the transport does not
specify a group, the group given here is used when running the delivery
-process.
-The group may be specified numerically or by name. If expansion fails, the
+process.
+The group may be specified numerically or by name. If expansion fails, the
error is logged and delivery is deferred.
The default is unset, unless \check@_local@_user\ is set, when the default
is taken from the password information. See also \initgroups\ and \user\ and
option has no effect when an address is being verified. The \headers@_remove\
option is expanded after \errors@_to\ and \headers@_add\, but before
\transport\. If the expansion is forced to fail, the option has no effect.
-Other expansion failures are treated as configuration errors.
+Other expansion failures are treated as configuration errors.
-.em
After expansion, the string must consist of a colon-separated list of header
names. This is confusing, because header names themselves are often terminated
by colons. In this case, the colons are the list separators, not part of the
names.
-.nem
For example:
.display asis
headers_remove = return-receipt-to:acknowledge-to
.display asis
ignore_target_hosts = 127.0.0.1
.endd
-on the relevant router.
-.em
+on the relevant router.
If all the hosts found by a \%dnslookup%\ router are discarded in this way, the
router declines. In a conventional configuration, an attempt to mail to such a
domain would then normally provoke the `unrouteable domain' error, and an
Similarly, if \ignore@_target@_hosts\ is set on an \%ipliteral%\ router, the
router declines if presented with one of the listed addresses.
-.nem
This option may also be useful for ignoring link-local and site-local IPv6
addresses. Because, like all host lists, the value of \ignore@_target@_hosts\
running, the prefix is removed from the local part, and is available in the
expansion variable \$local@_part@_prefix$\. If the router accepts the address,
this remains true during subsequent delivery.
-In particular, the local part that is transmitted in the \\RCPT\\ command
-for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. This
-behaviour can be overridden by setting \rcpt@_include@_affixes\ true on the
+In particular, the local part that is transmitted in the \\RCPT\\ command
+for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. This
+behaviour can be overridden by setting \rcpt@_include@_affixes\ true on the
relevant transport.
The prefix facility is commonly used to handle local parts of the form
.index router||restricting to specific local parts
.index local part||checking in router
The router is run only if the local part of the address matches the list.
-See section ~~SECTrouprecon for a list of the order in which preconditions
+See section ~~SECTrouprecon for a list of the order in which preconditions
are evaluated, and
section ~~SECTlocparlis for a discussion of local part lists. Because the
string is expanded, it is possible to make it depend on the domain, for
This option provides a general mechanism for predicating the running of a
router on the existence or non-existence of certain files or directories.
Before running a router, as one of its precondition tests, Exim works its way
-through the \require@_files\ list, expanding each item separately.
+through the \require@_files\ list, expanding each item separately.
Because the list is split before expansion, any colons in expansion items must
be doubled, or the facility for using a different list separator must be used.
-If any expansion is forced to fail, the item is ignored. Other expansion
+If any expansion is forced to fail, the item is ignored. Other expansion
failures cause routing of the address to be deferred.
If any expanded string is empty, it is ignored. Otherwise, except as described
transport (for example \(.procmailrc)\).
During delivery, the \*stat()*\ function is run as root, but there is a
-facility for some checking of the accessibility of a file by another user.
+facility for some checking of the accessibility of a file by another user.
This is not a proper permissions check, but just a `rough' check that
operates as follows:
may yield the error \\EACCES\\ (`Permission denied'). This means that the Exim
user is not permitted to read one of the directories on the file's path.
-\**Warning 2**\: Even when Exim is running as root while delivering a message,
-\*stat()*\ can yield \\EACCES\\ for a file on an NFS directory that is mounted
+\**Warning 2**\: Even when Exim is running as root while delivering a message,
+\*stat()*\ can yield \\EACCES\\ for a file on an NFS directory that is mounted
without root access.
-In both cases,
+In both cases,
the default action is to consider this a configuration error, and routing is
deferred because the existence or non-existence of the file cannot be
determined. However, in some circumstances it may be desirable to treat this
require_files = +/some/file
.endd
If the router is not an essential part of verification (for example, it
-handles users' \(.forward)\ files), another solution is to set the \verify\
+handles users' \(.forward)\ files), another solution is to set the \verify\
option false so that the router is skipped when verifying.
for transport delays; they are controlled by a generic transport option of the
same name.
-.em
-The setting of \retry@_use@_local@_part\ applies only to the router on which it
-appears. If the router generates child addresses, they are routed
+The setting of \retry@_use@_local@_part\ applies only to the router on which it
+appears. If the router generates child addresses, they are routed
independently; this setting does not become attached to them.
-.nem
.conf router@_home@_directory string$**$ unset
Expansion of \router@_home@_directory\ happens immediately after the
\check@_local@_user\ test (if configured), before any further expansions take
-place.
+place.
(See section ~~SECTrouprecon for a list of the order in which preconditions
are evaluated.)
While the router is running, \router__home@_directory\ overrides the value of
.index local host||MX pointing to
This option applies to those routers that use a recipient address to find a
list of remote hosts. Currently, these are the \%dnslookup%\, \%ipliteral%\,
-and \%manualroute%\ routers.
+and \%manualroute%\ routers.
Certain configurations of the \%queryprogram%\ router can also specify a list
of remote hosts.
Usually such routers are configured to send the message to a remote host via an
.conf senders "address list$**$ (precondition)" unset
.index router||checking senders
If this option is set, the router is skipped unless the message's sender
-address matches something on the list.
-See section ~~SECTrouprecon for a list of the order in which preconditions
+address matches something on the list.
+See section ~~SECTrouprecon for a list of the order in which preconditions
are evaluated.
There are issues concerning verification when the running of routers is
The \translate@_ip@_address\ string is expanded for every IP address generated
by the router, with the generated address set in \$host@_address$\. If the
-expansion is forced to fail, no action is taken.
+expansion is forced to fail, no action is taken.
For any other expansion error, delivery of the message is deferred.
If the result of the expansion is an IP address, that replaces the original
address; otherwise the result is assumed to be a host name -- this is looked up
.conf transport string$**$ unset
This option specifies the transport to be used when a router accepts an address
and sets it up for delivery. A transport is never needed if a router is used
-only for verification. The value of the option is expanded at routing time,
-after the expansion of \errors@_to\,
+only for verification. The value of the option is expanded at routing time,
+after the expansion of \errors@_to\,
\headers@_add\, and \headers@_remove\,
and result must be the name of one of the configured transports. If it is
not, delivery is deferred.
\transport@_home@_directory\ is not set for the router, the home directory for
the tranport is taken from the password data if \check@_local@_user\ is set for
the router. Otherwise it is taken from \router@_home@_directory\ if that option
-is set; if not, no home directory is set for the transport.
+is set; if not, no home directory is set for the transport.
See chapter ~~CHAPenvironment for further details of the local delivery
environment.
When this option is set true, routing does not cease if the router accepts the
address. Instead, a copy of the incoming address is passed to the next router,
-overriding a false setting of \more\. There is little point in setting \more\
-false if \unseen\ is always true, but it may be useful in cases when the value
+overriding a false setting of \more\. There is little point in setting \more\
+false if \unseen\ is always true, but it may be useful in cases when the value
of \unseen\ contains expansion items (and therefore, presumably, is sometimes
true and sometimes false).
The \unseen\ option can be used to cause
.index copy of message (\unseen\ option)
copies of messages to be delivered to some other destination, while also
-carrying out a normal delivery. In effect, the current address is made into a
-`parent' that has two children -- one that is delivered as specified by this
+carrying out a normal delivery. In effect, the current address is made into a
+`parent' that has two children -- one that is delivered as specified by this
router, and a clone that goes on to be routed further.
Header lines added to the address (or specified for removal) by this router or
by previous routers affect the `unseen' copy of the message only. The clone
-that continues to be processed by further routers starts with no added headers
+that continues to be processed by further routers starts with no added headers
and none specified for removal.
However, any data that was set by the \address@_data\ option in the current or
.index filter||user for processing
When a router queues an address for a transport, and the transport does not
specify a user, the user given here is used when running the delivery process.
-The user may be specified numerically or by name. If expansion fails, the
+The user may be specified numerically or by name. If expansion fails, the
error is logged and delivery is deferred.
This user is also used by the \%redirect%\ router when running a filter file.
The default is unset, except when \check@_local@_user\ is set. In this case,
and \verify@_recipient\.
\**Warning**\: When the router is being run to verify addresses for an incoming
-SMTP message, Exim is not running as root, but under its own uid. If the router
-accesses any files, you need to make sure that they are accessible to the Exim
+SMTP message, Exim is not running as root, but under its own uid. If the router
+accesses any files, you need to make sure that they are accessible to the Exim
user or group.
.conf verify@_recipient "boolean (precondition)" true
If this option is false, the router is skipped when verifying recipient
addresses
or testing recipient verification using \-bv-\.
-See section ~~SECTrouprecon for a list of the order in which preconditions
+See section ~~SECTrouprecon for a list of the order in which preconditions
are evaluated.
.conf verify@_sender "boolean (precondition)" true
If this option is false, the router is skipped when verifying sender addresses
or testing sender verification using \-bvs-\.
-See section ~~SECTrouprecon for a list of the order in which preconditions
+See section ~~SECTrouprecon for a list of the order in which preconditions
are evaluated.
.endconf
domain in the DNS. A transport must always be set for this router, unless
\verify@_only\ is set.
-.em
-If SRV support is configured (see \check@_srv\ below), Exim first searches for
+If SRV support is configured (see \check@_srv\ below), Exim first searches for
SRV records. If none are found, or if SRV support is not configured,
MX records are looked up. If no MX records exist, address records are sought.
However, \mx@_domains\ can be set to disable the direct use of address records.
Unless they have the highest priority (lowest MX value), MX records that point
to the local host, or to any host name that matches \hosts__treat__as__local\,
are discarded, together with any other MX records of equal or lower priority.
-.nem
.index MX record||pointing to local host
.index local host||MX pointing to
differently to other domains. The way in which Exim decides whether a host is
the local host is described in section ~~SECTreclocipadd.
-.em
.conf check@_srv string$**$ unset
.index SRV record||enabling use of
The dnslookup router supports the use of SRV records (see RFC 2782) in
purpose. However, SRV records have an additional `weight' feature which
some people might find useful when trying to split an SMTP load between
hosts of different power.
-.nem
.conf mx@_domains "domain list$**$" unset
.index MX record||required to exist
.index SRV record||required to exist
-.em
A domain that matches \mx@_domains\ is required to have either an MX or an SRV
record in order to be recognised. (The name of this option could be improved.)
-.nem
For example, if all the mail hosts in \*fict.example*\ are known to have MX
records, except for those in \*discworld.fict.example*\, you could use this
setting:
without processing them independently,
provided the following conditions are met:
.numberpars $.
-No router that processed the address specified \headers@_add\ or
+No router that processed the address specified \headers@_add\ or
\headers@_remove\.
.nextp
-The router did not change the address in any way, for example, by `widening'
+The router did not change the address in any way, for example, by `widening'
the domain.
.endp
.endconf
-.em
.section Effect of qualify@_single and search@_parents
-When a domain from an envelope recipient is changed by the resolver as a result
+When a domain from an envelope recipient is changed by the resolver as a result
of the \qualify@_single\ or \search@_parents\ options, Exim rewrites the
corresponding address in the message's header lines unless \rewrite@_headers\
is set false. Exim then re-routes the address, using the full domain.
.endd
that may happen while processing a router precondition before the router is
entered. No widening ever takes place for these lookups.
-.nem
.chapter The ipliteral router
.set runningfoot "ipliteral router"
.index \%ipliteral%\ router
-.index domain literal||routing
+.index domain literal||routing
.index routers||\%ipliteral%\
This router has no private options. Unless it is being used purely for
verification (see \verify@_only\) a transport is required to be defined by the
.display asis
root@[192.168.1.1]
.endd
-by setting up delivery to the host with that IP address.
+by setting up delivery to the host with that IP address.
-.em
-If the IP address matches something in \ignore@_target@_hosts\, the router
+If the IP address matches something in \ignore@_target@_hosts\, the router
declines.
-.nem
.index \self\ option||in \%ipliteral%\ router
If an IP literal turns out to refer to the local host, the generic \self\
-option determines what happens.
+option determines what happens.
The RFCs require support for domain literals; however, their use is
controversial in today's Internet. If you want to use this router, you must
.conf hosts string unset
This option must be supplied. Its value is a colon-separated list of host
-names. The hosts are looked up using \*gethostbyname()*\
+names. The hosts are looked up using \*gethostbyname()*\
(or \*getipnodebyname()*\ when available)
and are tried in order until one responds to the query. If none respond, what
happens is controlled by \optional\.
dict.ref.example mail-1.ref.example:mail-2.ref.example ; \
thes.ref.example mail-3.ref.example:mail-4.ref.example
.endd
-The three parts of a rule are separated by white space. The pattern and the
+The three parts of a rule are separated by white space. The pattern and the
list of hosts can be enclosed in quotes if necessary, and if they are, the
usual quoting rules apply. Each rule in a \route@_list\ must start with a
single domain pattern, which is the only mandatory item in the rule. The
pattern is in the same format as one item in a domain list (see section
-~~SECTdomainlist),
+~~SECTdomainlist),
except that it may not be the name of an interpolated file.
That is, it may be wildcarded, or a regular expression, or a file or database
lookup (with semicolons doubled, because of the use of semicolon as a separator
.endp
-.em
.section How the list of hosts is used
-When an address is routed to an \%smtp%\ transport by \%manualroute%\, each of
+When an address is routed to an \%smtp%\ transport by \%manualroute%\, each of
the hosts is tried, in the order specified, when carrying out the SMTP
delivery. However, the order can be changed by setting the \hosts@_randomize\
option, either on the router (see section ~~SECTprioptman above), or on the
route_list = * x.y.z:p.q.r/MX:e.f.g
.endd
If the \hosts@_randomize\ option is set, the order of the items in the list is
-randomized before any lookups are done. Exim then scans the list; for any name
-that is not followed by \"/MX"\ it looks up an IP address. If this turns out to
+randomized before any lookups are done. Exim then scans the list; for any name
+that is not followed by \"/MX"\ it looks up an IP address. If this turns out to
be an interface on the local host and the item is not the first in the list,
Exim discards it and any subsequent items. If it is the first item, what
-happens is controlled by the
+happens is controlled by the
.index \self\ option||in \%manualroute%\ router
\self\ option of the router.
values in the MX records, according to the usual rules. Because randomizing
happens before the MX lookup, it does not affect the order that is defined by
MX preferences.
-.nem
If the local host is present in the sublist obtained from MX records, but is
not the most preferred host in that list, it and any equally or less
failures when looking up IP addresses: \pass@_on@_timeout\ and
\host@_find@_failed\ are used when relevant.
-.em
The generic \ignore@_target@_hosts\ option applies to all hosts in the list,
whether obtained from an MX lookup or not.
-.nem
.section How the options are used
per-rule basis, and how the IP addresses of the hosts are to be found when
routing to a remote transport. These options are as follows:
.numberpars $.
-\randomize\: randomize the order of the hosts in this list, overriding the
+\randomize\: randomize the order of the hosts in this list, overriding the
setting of \hosts@_randomize\ for this routing rule only.
.nextp
\no@_randomize\: do not randomize the order of the hosts in this list,
also look in \(/etc/hosts)\ or other sources of information.
.nextp
\bydns\: look up address records for the hosts directly in the DNS; fail if
-no address records are found. If there is a temporary DNS error (such as a
-timeout), delivery is deferred.
+no address records are found. If there is a temporary DNS error (such as a
+timeout), delivery is deferred.
.endp
For example:
.display asis
The list of hosts and the lookup type are needed only if the transport is an
\%smtp%\ transport that does not itself supply a list of hosts.
-The format of the list of hosts is the same as for the \%manualroute%\ router.
+The format of the list of hosts is the same as for the \%manualroute%\ router.
As well as host names and IP addresses, it may contain names followed by
\"/MX"\ to specify sublists of hosts that are obtained by looking up MX
records.
-If the lookup type is not specified, Exim behaves as follows when trying to
+If the lookup type is not specified, Exim behaves as follows when trying to
find an IP address for each host: First, a DNS lookup is done. If this yields
anything other than \\HOST@_NOT@_FOUND\\, that result is used. Otherwise, Exim
goes on to try a call to \*getipnodebyname()*\ or \*gethostbyname()*\, and the
driver = redirect
data = ${lookup{$local_part}lsearch{/etc/aliases}}
.endd
-.em
-If the lookup fails, the expanded string in this example is empty. When the
+If the lookup fails, the expanded string in this example is empty. When the
expansion of \data\ results in an empty string, the router declines. A forced
expansion failure also causes the router to decline; other expansion failures
cause delivery to be deferred.
-.nem
A configuration using \file\ is commonly used for handling users' \(.forward)\
files, like this:
\(.forward)\ files, as in the example above. There are two reasons for this:
.numberpars $.
When Exim is receiving an incoming SMTP message from a remote host, it is
-running under the Exim uid, not as root.
-No additional groups are set up, even if the Exim uid is a member of other
+running under the Exim uid, not as root.
+No additional groups are set up, even if the Exim uid is a member of other
groups (that is, the \*initgroups()*\ function is not run).
Exim is unable to change uid to read the file as the user, and it may not be
able to read it as the Exim user. So in practice the router may not be able to
Otherwise, the data must be a comma-separated list of redirection items, as
described in the next section.
.endp
-When a message is redirected to a file (a `mail folder'), the file name given
-in a non-filter redirection list must always be an absolute path. A filter may
-generate a relative path -- how this is handled depends on the transport's
-configuration. See section ~~SECTfildiropt for a discussion of this issue for
+When a message is redirected to a file (a `mail folder'), the file name given
+in a non-filter redirection list must always be an absolute path. A filter may
+generate a relative path -- how this is handled depends on the transport's
+configuration. See section ~~SECTfildiropt for a discussion of this issue for
the \%appendfile%\ transport.
(but never to enclose the entire address). In the following description, `item'
refers to what remains after any surrounding double quotes have been removed.
-\**Warning**\: If you use an Exim expansion to construct a redirection address,
-and the expansion contains a reference to \$local@_part$\, you should make use
-of the \quote\ expansion operator, in case the local part contains special
-characters. For example, to redirect all mail for the domain
-\*obsolete.example*\, retaining the existing local part, you could use this
+\**Warning**\: If you use an Exim expansion to construct a redirection address,
+and the expansion contains a reference to \$local@_part$\, you should make use
+of the \quote\ expansion operator, in case the local part contains special
+characters. For example, to redirect all mail for the domain
+\*obsolete.example*\, retaining the existing local part, you could use this
setting:
.display asis
data = ${quote:$local_part}@newdomain.example
A redirection item may safely be the same as the address currently under
consideration. This does not cause a routing loop, because a router is
automatically skipped if any ancestor of the address that is being processed
-.em
-is the same as the current address and was processed by the current router.
-.nem
+is the same as the current address and was processed by the current router.
Such an address is therefore passed to the following routers, so it is handled
as if there were no redirection. When making this loop-avoidance test, the
complete local part, including any prefix or suffix, is used.
addresses are qualified using the value in \qualify@_recipient\, but you can
force the incoming domain to be used by setting \qualify__preserve@_domain\.
-Care must be taken if there are alias names for local users.
-.em
+Care must be taken if there are alias names for local users.
Consider an MTA handling a single local domain where the system alias file
contains:
.display asis
Sam.Reman: spqr
.endd
Now suppose that Sam (whose login id is \*spqr*\) wants to save copies of
-messages in the local mailbox, and also forward copies elsewhere. He creates
+messages in the local mailbox, and also forward copies elsewhere. He creates
this forward file:
.display asis
Sam.Reman, spqr@reme.elsewhere.example
.endd
With these settings, an incoming message addressed to \*Sam.Reman*\ fails. The
\%redirect%\ router for system aliases does not process \*Sam.Reman*\ the
-second time round, because it has previously routed it,
-.nem
+second time round, because it has previously routed it,
and the following routers presumably cannot handle the alias. The forward file
should really contain
.display asis
.index address redirection||to pipe
An item is treated as a pipe command if it begins with `|' and does not parse
as a valid RFC 2822 address that includes a domain. A transport for running the
-command must be specified by the \pipe@_transport\ option.
-.em
+command must be specified by the \pipe@_transport\ option.
Normally, either the router or the transport specifies a user and a group under
which to run the delivery. The default is to use the Exim user and group.
-.nem
Single or double quotes can be used for enclosing the individual arguments of
the pipe command; no interpretation of escapes is done for single quotes. If
forward slash character, it is interpreted as a directory name rather than a
file name, and \directory@_transport\ is used instead.
-.em
Normally, either the router or the transport specifies a user and a group under
which to run the delivery. The default is to use the Exim user and group.
.index \(/dev/null)\
However, if a redirection item is the path \(/dev/null)\, delivery to it is
bypassed at a high level, and the log entry shows `$*$$*$bypassed$*$$*$'
instead of a transport name. In this case the user and group are not used.
-.nem
.nextp
.index included address list
.index address redirection||included external list
:include:<<path name>>
.endd
a list of further items is taken from the given file and included at that
-point.
-\**Note**\: such a file can not be a filter file; it is just an out-of-line
+point.
+\**Note**\: such a file can not be a filter file; it is just an out-of-line
addition to the list.
The items in the included list are separated by commas or newlines and are not
subject to expansion. If this is the first item in an alias list in an
message is generated. This has the same effect as specifing \(/dev/null)\, but
can be independently disabled.
-\**Warning**\: If \":blackhole:"\ appears anywhere in a redirection list, no
-delivery is done for the original local part, even if other redirection items
-are present. If you are generating a multi-item list (for example, by reading a
-database) and need the ability to provide a no-op item, you must use
+\**Warning**\: If \":blackhole:"\ appears anywhere in a redirection list, no
+delivery is done for the original local part, even if other redirection items
+are present. If you are generating a multi-item list (for example, by reading a
+database) and need the ability to provide a no-op item, you must use
\(/dev/null)\.
.nextp
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
+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
configuration file for handling users' \(.forward)\ files. It is recommended
for this use of the \%redirect%\ router.
-.em
When \check@_ancestor\ is set, if a generated address (including the domain) is
the same as any ancestor of the current address, it is replaced by a copy of
the current address. This helps in the case where local part A is aliased to B,
-and B has a \(.forward)\ file pointing back to A. For example, within a single
+and B has a \(.forward)\ file pointing back to A. For example, within a single
domain, the local part `Joe.Bloggs' is aliased to `jb' and \(@~jb/.forward)\
contains:
-.nem
.display
@\Joe.Bloggs, <<other item(s)>>
.endd
A \%redirect%\ router sets up a direct delivery to a file when a path name not
ending in a slash is specified as a new `address'. The transport used is
specified by this option, which, after expansion, must be the name of a
-configured transport.
+configured transport.
This should normally be an \%appendfile%\ transport.
When it is running, the file name is in \$address@_file$\.
.index address redirection||one-time expansion
Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection
files each time it tries to deliver a message causes a problem
-when one or more of the generated addresses fails be delivered at the first
-attempt. The problem is not one of duplicate delivery -- Exim is clever enough
+when one or more of the generated addresses fails be delivered at the first
+attempt. The problem is not one of duplicate delivery -- Exim is clever enough
to handle that -- but of what happens when the redirection list changes during
the time that the message is on Exim's queue. This is particularly true in the
case of mailing lists, where new subscribers might receive copies of messages
list is in addition to the local user's primary group when \check@_local@_user\
is set. See \check@_group\ above.
-.em
.conf qualify@_domain string$**$ unset
If this option is set and an unqualified address (one without a domain) is
generated, it is qualified with the domain specified by expanding this string,
instead of the global setting in \qualify@_recipient\. If the expansion fails,
the router declines. If you want to revert to the default, you can have the
expansion generate \$qualify@_recipient$\.
-.nem
.conf pipe@_transport string$**$ unset
A \%redirect%\ router sets up a direct delivery to a pipe when a string starting
with a vertical bar character is specified as a new `address'. The transport
used is specified by this option, which, after expansion, must be the name of a
-configured transport.
+configured transport.
This should normally be a \%pipe%\ transport.
When the transport is run, the pipe command is in \$address@_pipe$\.
.index preserving domain in redirection
.index address redirection||domain, preserving
If this is set and an unqualified address (one without a domain) is generated,
-it is qualified with the domain of the
-.em
+it is qualified with the domain of the
parent address (the immediately preceding ancestor) instead of the local
\qualify@_domain\ or global \qualify@_recipient\ value.
-.nem
.conf repeat@_use boolean true
If this option is set false, the router is skipped for a child address that has
A \%redirect%\ router sets up an automatic reply when a \mail\ or \vacation\
command is used in a filter file. The transport used is specified by this
option, which, after expansion, must be the name of a configured transport.
-This should normally be an \%autoreply%\ transport. Other transports are
+This should normally be an \%autoreply%\ transport. Other transports are
unlikely to do anything sensible or useful.
.conf rewrite boolean true
so it is passed to the following routers.
.index Sieve filter||syntax errors in
-Currently, any syntax errors in a Sieve filter file cause the `keep' action to
-occur. The values of \skip@_syntax@_errors\, \syntax@_errors@_to\, and
+Currently, any syntax errors in a Sieve filter file cause the `keep' action to
+occur. The values of \skip@_syntax@_errors\, \syntax@_errors@_to\, and
\syntax@_errors@_text\ are not used.
\skip@_syntax@_errors\ can be used to specify that errors in users' forward
local_users:
driver = accept
check_local_user
- transport = group_delivery
+ transport = group_delivery
# Transports ...
# This transport overrides the group
logged, and delivery is deferred.
.conf disable@_logging boolean false
-If this option is set true, nothing is logged for any
-.em
-deliveries by the transport or for any
-.nem
+If this option is set true, nothing is logged for any
+deliveries by the transport or for any
transport errors. You should not set this option unless you really, really know
what you are doing.
.index testing||variables in drivers
If this option is set and debugging is enabled (see the \-d-\ command line
option), the string is expanded and included in the debugging output when the
-transport is run.
-If expansion of the string fails, the error message is written to the debugging
+transport is run.
+If expansion of the string fails, the error message is written to the debugging
output, and Exim carries on processing.
This facility is provided to help with checking out the values of variables and
so on when debugging driver configurations. For example, if a \headers@_add\
headers_remove = return-receipt-to:acknowledge-to
.endd
Any existing headers matching those names are not included in any message that
-is transmitted by the transport.
+is transmitted by the transport.
If the result of the expansion is an empty string, or if the expansion is
forced to fail, no action is taken. Other expansion failures are treated as
errors and cause the delivery to be deferred.
This option controls the size of messages passed through the transport. It is
expanded before use; the result of the expansion must be a sequence of digits,
optionally followed by K or M.
-If the expansion fails for any reason, including forced failure, or if the
+If the expansion fails for any reason, including forced failure, or if the
result is not of the required form, delivery is deferred.
If the value is greater than zero and the size of a message exceeds this
limit, the address is failed. If there is any chance that the resulting bounce
option can be used to support VERP (Variable Envelope Return Paths) -- see
chapter ~~CHAPSMTP.
-\**Note**\: If a delivery error is detected locally,
-.em
+\**Note**\: If a delivery error is detected locally,
including the case when a remote server rejects a message at SMTP time,
the bounce message is not sent to the value of this option, but to the
previously set errors address (which defaults to the incoming sender address).
-.nem
.conf return@_path@_add boolean false
\shadow@_condition\ is unset, or its expansion does not result in the empty
string or one of the strings `0' or `no' or `false', the message is also passed
to the shadow transport, with the same delivery address or addresses.
-If expansion fails, no action is taken except that non-forced expansion
+If expansion fails, no action is taken except that non-forced expansion
failures cause a log line to be written.
The result of the shadow transport is discarded and does not affect the
.conf transport@_filter@_timeout time 5m
.index transport||filter, timeout
-When Exim is reading the output of a transport filter, it a applies a timeout
-that can be set by this option. Exceeding the timeout is treated as a
+When Exim is reading the output of a transport filter, it a applies a timeout
+that can be set by this option. Exceeding the timeout is treated as a
temporary delivery failure.
associated group is taken as the value of the gid to be used if the \group\
option is not set.
-.em
For deliveries that use local transports, a user and group are normally
specified explicitly or implicitly (for example, as a result of
\check@_local@_user\) by the router or transport.
-.nem
.index hints database||access by remote transport
For remote transports, you should leave this option unset unless you really are
In an \%lmtp%\ transport, when delivering over `local SMTP' to some process,
a single copy saves time, and is the normal way LMTP is expected to work.
.nextp
-In a \%pipe%\ transport, when passing the message
-to a scanner program or
+In a \%pipe%\ transport, when passing the message
+to a scanner program or
to some other delivery mechanism such as UUCP, multiple recipients may be
acceptable.
.endp
If \batch@_id\ is set, it is expanded for each address, and only those
addresses with the same expanded value are batched. This allows you to specify
customized batching conditions.
-Failure of the expansion for any reason, including forced failure, disables
-batching, but it does not stop the delivery from taking place.
+Failure of the expansion for any reason, including forced failure, disables
+batching, but it does not stop the delivery from taking place.
.nextp
Batched addresses must also have the same errors address (where to send
delivery errors), the same header additions and removals, the same user and
\use@_bsmtp\ option, because it always delivers using the SMTP protocol.
.index \%pipe%\ transport||with multiple addresses
-If you are not using BSMTP, but are using a \%pipe%\ transport, you can include
-\$pipe@_addresses$\ as part of the command. This is not a true variable; it is
-a bit of magic that causes each of the recipient addresses to be inserted into
-the command as a separate argument. This provides a way of accessing all the
+If you are not using BSMTP, but are using a \%pipe%\ transport, you can include
+\$pipe@_addresses$\ as part of the command. This is not a true variable; it is
+a bit of magic that causes each of the recipient addresses to be inserted into
+the command as a separate argument. This provides a way of accessing all the
addresses that are being delivered in the batch.
If you are using a batching \%appendfile%\ transport without \use@_bsmtp\, the
only way to preserve the recipient addresses is to set the \envelope@_to@_add\
-option. This causes an ::Envelope-to:: header line to be added to the message,
+option. This causes an ::Envelope-to:: header line to be added to the message,
containing all the recipients.
\%appendfile%\ is most commonly used for local deliveries to users' mailboxes.
However, it can also be used as a pseudo-remote transport for putting messages
into files for remote delivery by some means other than Exim. `Batch SMTP'
-format is often used in this case (see the \use@_bsmtp\ option).
+format is often used in this case (see the \use@_bsmtp\ option).
.section The file and directory options
.rset SECTfildiropt "~~chapter.~~section"
-The \file\ option specifies a single file, to which the message is appended;
-the \directory\ option specifies a directory, in which a new file containing
+The \file\ option specifies a single file, to which the message is appended;
+the \directory\ option specifies a directory, in which a new file containing
the message is created. Only one of these two options can be set, and for
normal deliveries to mailboxes, one of them \*must*\ be set.
operation. There are two cases:
.numberpars $.
If neither \file\ nor \directory\ is set, the redirection operation
-must specify an absolute path (one that begins with \"/"\). This is the most
-common case when users with local accounts use filtering to sort mail into
+must specify an absolute path (one that begins with \"/"\). This is the most
+common case when users with local accounts use filtering to sort mail into
different folders. See for example, the \%address@_file%\ transport in the
default configuration. If the path ends with a slash, it is assumed to be the
-name of a directory. A delivery to a directory can also be forced by setting
+name of a directory. A delivery to a directory can also be forced by setting
\maildir@_format\ or \mailstore@_format\.
.nextp
If \file\ or \directory\ is set for a delivery from a redirection, it is used
to determine the file or directory name for the delivery. Normally, the
-contents of \$address@_file$\ are used in some way in the string expansion.
+contents of \$address@_file$\ are used in some way in the string expansion.
.endp
.index Sieve filter||configuring \%appendfile%\
.endd
or Sieve filter commands of the form:
.display asis
-require "fileinto";
+require "fileinto";
fileinto "folder23";
.endd
In this situation, the expansion of \file\ or \directory\ in the transport must
-transform the relative path into an appropriate absolute file name. In the case
-of Sieve filters, the name \*inbox*\ must be handled. It is the name that is
-used as a result of a `keep' action in the filter. This example shows one way
+transform the relative path into an appropriate absolute file name. In the case
+of Sieve filters, the name \*inbox*\ must be handled. It is the name that is
+used as a result of a `keep' action in the filter. This example shows one way
of handling this requirement:
.display asis
file = ${if eq{$address_file}{inbox} \
}} \
}
.endd
-With this setting of \file\, \*inbox*\ refers to the standard mailbox location,
+With this setting of \file\, \*inbox*\ refers to the standard mailbox location,
absolute paths are used without change, and other folders are in the \(mail)\
directory within the home directory.
.conf batch@_id string$**$ unset
See the description of local delivery batching in chapter ~~CHAPbatching.
-However, batching is automatically disabled for \%appendfile%\ deliveries that
-happen as a result of forwarding or aliasing or other redirection directly to a
+However, batching is automatically disabled for \%appendfile%\ deliveries that
+happen as a result of forwarding or aliasing or other redirection directly to a
file.
.conf batch@_max integer 1
If \use@_bsmtp\ is set the values of \check@_string\ and \escape@_string\ are
forced to `.' and `..' respectively, and any settings in the configuration are
ignored. Otherwise, they default to `From ' and `>From ' when the \file\ option
-is set, and unset when
+is set, and unset when
any of the \directory\, \maildir\, or \mailstore\ options are set.
The default settings, along with \message@_prefix\ and \message@_suffix\, are
\\SUPPORT@_MAILDIR\\ is present in \(Local/Makefile)\. See section
~~SECTmaildirdelivery below for further details.
-.em
.conf maildir@_quota@_directory@_regex string "See below"
.index maildir format||quota, directories included in
.index quota||maildir, directories included in
maildir_quota_directory_regex = ^(?:cur|new|\..*)$
.endd
which includes the \(cur)\ and \(new)\ directories, and any maildir++ folders
-(directories whose names begin with a dot). If you want to exclude the
+(directories whose names begin with a dot). If you want to exclude the
\(Trash)\
folder from the count (as some sites do), you need to change this setting to
.display asis
.endd
This uses a negative lookahead in the regular expression to exclude the
directory whose name is \(.Trash)\.
-.nem
.conf maildir@_retries integer 10
This option specifies the number of times to retry when writing a file in
\**Note**\: The \message@_prefix\ and \message@_suffix\ options are not
automatically changed by the use of \mbx@_format\. They should normally be set
-empty when using MBX format, so this option almost always appears in this
+empty when using MBX format, so this option almost always appears in this
combination:
.display asis
mbx_format = true
or to the total space used in the directory tree when the \directory\ option is
set. In the latter case, computation of the space used is expensive, because
all the files in the directory (and any sub-directories) have to be
-individually inspected and their sizes summed.
-.em
+individually inspected and their sizes summed.
(See \quota@_size@_regex\ and \maildir@_use@_size@_file\ for ways to avoid this
in environments where users have no shell access to their mailboxes).
As there is no interlock against two simultaneous deliveries into a
multi-file mailbox, it is possible for the quota to be overrun in this case.
For single-file mailboxes, of course, an interlock is a necessity.
-.nem
A file's size is taken as its \*used*\ value. Because of blocking effects, this
may be a lot less than the actual amount of disk space allocated to the file.
fails because this quota is exceeded, the handling of the error is as for
system quota failures.
-.em
-\**Note**\: A value of zero is interpreted as `no quota'.
-.nem
+\**Note**\: A value of zero is interpreted as `no quota'.
By default, Exim's quota checking mimics system quotas, and restricts the
mailbox to the specified maximum size, though the value is not accurate to the
maildir_tag = ,S=$message_size
quota_size_regex = ,S=(\d+)
.endd
-The regular expression should not assume that the length is at the end of the
-file name (even though \maildir@_tag\ puts it there) because maildir MUAs
+The regular expression should not assume that the length is at the end of the
+file name (even though \maildir@_tag\ puts it there) because maildir MUAs
sometimes add other information onto the ends of message file names.
.conf quota@_warn@_message string$**$ "see below"
The contents of the \message@_prefix\ and \message@_suffix\ options are written
verbatim, so must contain their own carriage return characters if these are
needed. In cases where these options have non-empty defaults, the values end
-with a single linefeed, so they
+with a single linefeed, so they
must
be changed to end with \"@\r@\n"\ if \use@_crlf\ is set.
.index locking files
Once the file is open, unless both \use@_fcntl@_lock\ and \use@_flock@_lock\
are false, it is locked using \*fcntl()*\ or \*flock()*\ or both. If
-\use@_mbx@_lock\ is false, an exclusive lock is requested in each case.
+\use@_mbx@_lock\ is false, an exclusive lock is requested in each case.
However, if \use@_mbx@_lock\ is true,
Exim takes out a shared lock on the open file,
and an exclusive lock on the file whose name is
.index delivery||to single file
.index `From' line
When the \directory\ option is set instead of \file\, each message is delivered
-into a newly-created file or set of files. When \%appendfile%\ is activated
-directly from a \%redirect%\ router, neither \file\ nor \directory\ is normally
-set, because the path for delivery is supplied by the router. (See for example,
-the \%address@_file%\ transport in the default configuration.) In this case,
-delivery is to a new file if either the path name ends in \"/"\, or the
+into a newly-created file or set of files. When \%appendfile%\ is activated
+directly from a \%redirect%\ router, neither \file\ nor \directory\ is normally
+set, because the path for delivery is supplied by the router. (See for example,
+the \%address@_file%\ transport in the default configuration.) In this case,
+delivery is to a new file if either the path name ends in \"/"\, or the
\maildir@_format\ or \mailstore@_format\ option is set.
No locking is required while writing the message to a new file, so the various
\check@_string\, \message@_prefix\, and \message@_suffix\ are all unset when
any of \directory\, \maildir@_format\, or \mailstore@_format\ is set.
-If Exim is required to check a \quota\ setting, it adds up the sizes of all the
-files in the delivery directory by default. However, you can specify a
-different directory by setting \quota@_directory\. Also, for maildir deliveries
+If Exim is required to check a \quota\ setting, it adds up the sizes of all the
+files in the delivery directory by default. However, you can specify a
+different directory by setting \quota@_directory\. Also, for maildir deliveries
(see below) the \(maildirfolder)\ convention is honoured.
.index maildir format||description of
If the \maildir@_format\ option is true, Exim delivers each message by writing
it to a file whose name is \(tmp/<<stime>>.H<<mtime>>P<<pid>>.<<host>>)\ in the
-given directory. If the delivery is successful, the file is renamed into the
+given directory. If the delivery is successful, the file is renamed into the
\(new)\ subdirectory.
In the file name, <<stime>> is the current time of day in seconds, and
.section Using tags to record message sizes
-If \maildir@_tag\ is set, the string is expanded for each delivery.
+If \maildir@_tag\ is set, the string is expanded for each delivery.
When the maildir file is renamed into the \(new)\ sub-directory, the
tag is added to its name. However, if adding the tag takes the length of the
name to the point where the test \*stat()*\ call fails with \\ENAMETOOLONG\\,
-the tag is dropped and the maildir file is created with no tag.
+the tag is dropped and the maildir file is created with no tag.
Tags can be used to encode the size of files in their names; see
-\quota@_size@_regex\ above for an example. The expansion of \maildir@_tag\
+\quota@_size@_regex\ above for an example. The expansion of \maildir@_tag\
happens after the message has been written. The value of the \$message@_size$\
variable is set to the number of bytes actually written. If the expansion is
forced to fail, the tag is ignored, but a non-forced failure causes delivery to
colon is inserted.
-.em
.section Using a maildirsize file
.index quota||in maildir delivery
.index maildir format||\(maildirsize)\ file
file is maintained (with a zero quota setting), but no quota is imposed.
A regular expression is available for controlling which directories in the
-maildir participate in quota calculations. See the description of the
+maildir participate in quota calculations. See the description of the
\maildir@_quota@_directory@_regex\ option above for details.
-.nem
.section Mailstore delivery
The parameters of the message to be sent can be specified in the configuration
by options described below. However, these are used only when the address
passed to the transport does not contain its own reply information. When the
-transport is run as a consequence of a
+transport is run as a consequence of a
\mail\
or \vacation\ command in a filter file, the parameters of the message are
supplied by the filter, and passed with the address. The transport's options
Non-printing characters are not permitted in the header lines generated for the
message that \%autoreply%\ creates, with the exception of newlines that are
-immediately followed by whitespace. If any non-printing characters are found,
+immediately followed by whitespace. If any non-printing characters are found,
the transport defers.
Whether characters with the top bit set count as printing characters or not is
controlled by the \print@_topbitchars\ global option.
If either the log file or the `once' file has to be created, this mode is used.
.conf once string$**$ unset
-This option names a file or DBM database in which a record of each
+This option names a file or DBM database in which a record of each
::To:: recipient is kept when the message is specified by the transport.
\**Note**\: This does not apply to ::Cc:: or ::Bcc:: recipients.
If \once@_file@_size\ is not set, a DBM database is used, and it is allowed to
input and output to operate the LMTP protocol.
.conf socket string$**$ unset
-This option must be set if \command\ is not set. The result of expansion must
-be the name of a Unix domain socket. The transport connects to the socket and
+This option must be set if \command\ is not set. The result of expansion must
+be the name of a Unix domain socket. The transport connects to the socket and
delivers the message to it using the LMTP protocol.
.conf timeout time 5m
-The transport is aborted if the created process
+The transport is aborted if the created process
or Unix domain socket
does not respond to LMTP commands or message input within this timeout.
command itself. The \command\ option on the transport is ignored.
.endp
-The \%pipe%\ transport is a non-interactive delivery method. Exim can also
-deliver messages over pipes using the LMTP interactive protocol. This is
+The \%pipe%\ transport is a non-interactive delivery method. Exim can also
+deliver messages over pipes using the LMTP interactive protocol. This is
implemented by the \%lmtp%\ transport.
In the case when \%pipe%\ is run as a consequence of an entry in a local user's
script, it normally means that the script was terminated by a signal whose
value is the return code minus 128.
-If Exim is unable to run the command (that is, if \*execve()*\ fails), the
-return code is set to 127. This is the value that a shell returns if it is
-asked to run a non-existent command. The wording for the log line suggests that
+If Exim is unable to run the command (that is, if \*execve()*\ fails), the
+return code is set to 127. This is the value that a shell returns if it is
+asked to run a non-existent command. The wording for the log line suggests that
a non-existent command may be the problem.
The \return@_output\ option can affect the result of a pipe delivery. If it is
.conf ignore@_status boolean false
If this option is true, the status returned by the subprocess that is set up to
run the command is ignored, and Exim behaves as if zero had been returned.
-Otherwise, a non-zero status
+Otherwise, a non-zero status
or termination by signal
causes an error return from the transport unless the status value is one of
those listed in \temp@_errors\; these cause the delivery to be deferred and
This option specifies the string that is set up in the \\PATH\\ environment
variable of the subprocess. If the \command\ option does not yield an absolute
path name, the command is sought in the \\PATH\\ directories, in the usual way.
-\**Warning**\: This does not apply to a command specified as a transport
+\**Warning**\: This does not apply to a command specified as a transport
filter.
.conf pipe@_as@_creator boolean false
.conf temp@_errors "string list" "see below"
.index \%pipe%\ transport||temporary failure
This option contains either a colon-separated list of numbers, or a single
-asterisk. If \ignore@_status\ is false
-.em
+asterisk. If \ignore@_status\ is false
and \return@_output\ is not set,
-.nem
and the command exits with a non-zero return code, the failure is treated as
temporary and the delivery is deferred if the return code matches one of the
numbers, or if the setting is a single asterisk. Otherwise, non-zero return
.conf gethostbyname boolean false
If this option is true when the \hosts\ and/or \fallback@_hosts\ options are
-being used, names are looked up using \*gethostbyname()*\
+being used, names are looked up using \*gethostbyname()*\
(or \*getipnodebyname()*\ when available)
instead of using the DNS. Of course, that function may in fact use the DNS, but
it may also consult other sources of information such as \(/etc/hosts)\.
.index MX record||maximum tried
This option limits the number of IP addresses that are tried for any one
delivery
-.em
in cases where there are temporary delivery errors.
-.nem
Section ~~SECTvalhosmax describes in detail how the value of this option is
used.
.index TLS||requiring for certain servers
Exim will insist on using a TLS session when delivering to any host that
matches this list. See chapter ~~CHAPTLS for details of TLS.
-\**Note**\: This option affects outgoing mail only. To insist on TLS for
+\**Note**\: This option affects outgoing mail only. To insist on TLS for
incoming messages, use an appropriate ACL.
.index authentication||optional in client
call. The variables \$host$\ and \$host@_address$\ refer to the host to which a
connection is about to be made during the expansion of the string. Forced
expansion failure, or an empty string result causes the option to be ignored.
-Otherwise, after expansion,
-.em
+Otherwise, after expansion,
the string must be a list of IP addresses, colon-separated by default, but the
separator can be changed in the usual way.
-.nem
For example:
.display asis
interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
it begins with a digit it is taken as a port number; otherwise it is looked up
using \*getservbyname()*\. The default value is normally `smtp', but if
\protocol\ is set to `lmtp', the default is `lmtp'.
-If the expansion fails, or if a port number cannot be found, delivery is
+If the expansion fails, or if a port number cannot be found, delivery is
deferred.
and address of the server during the expansion. See chapter ~~CHAPTLS for
details of TLS.
-\**Note**\: This option must be set if you want Exim to use TLS when sending
-messages as a client. The global option of the same name specifies the
-certificate for Exim as a server; it is not automatically assumed that the same
+\**Note**\: This option must be set if you want Exim to use TLS when sending
+messages as a client. The global option of the same name specifies the
+certificate for Exim as a server; it is not automatically assumed that the same
certificate should be used when Exim is operating as a client.
-.em
.conf tls@_crl string$**$ unset
.index TLS||client certificate revocation list
.index certificate||revocation list for client
This option specifies a certificate revocation list. The expanded value must
be the name of a file that contains a CRL in PEM format.
-.nem
.conf tls@_privatekey string$**$ unset
.index TLS||client private key, location of
The value of this option must be the absolute path to a file which contains the
client's private key, for use when sending a message over an encrypted
connection. The values of \$host$\ and \$host@_address$\ are set to the name
-and address of the server during the expansion.
-If this option is unset, the private key is assumed to be in the same file as
+and address of the server during the expansion.
+If this option is unset, the private key is assumed to be in the same file as
the certificate.
See chapter ~~CHAPTLS for details of TLS.
.index TLS||requiring specific ciphers
.index cipher||requiring specific
The value of this option must be a list of permitted cipher suites, for use
-when setting up an
-.em
-outgoing encrypted connection. (There is a global option of the same name for
+when setting up an
+outgoing encrypted connection. (There is a global option of the same name for
controlling incoming connections.)
-.nem
The values of \$host$\ and \$host@_address$\ are set to the name and address of
the server during the expansion. See chapter ~~CHAPTLS for details of TLS; note
that this option is used in different ways by OpenSSL and GnuTLS (see section
~~SECTreqciphsslgnu).
.conf tls@_tempfail@_tryclear boolean true
-When the server host is not in \hosts@_require@_tls\, and there is a problem in
+When the server host is not in \hosts@_require@_tls\, and there is a problem in
setting up a TLS session, this option determines whether or not Exim should try
to deliver the message unencrypted. If it is set false, delivery to the
current host is deferred; if there are other hosts, they are tried. If this
.index limit||hosts, maximum number tried
The \hosts@_max@_try\ option limits the number of hosts that are tried
for a single delivery. However, despite the term `host' in its name, the option
-actually applies to each IP address independently. In other words, a multihomed
+actually applies to each IP address independently. In other words, a multihomed
host is treated as several independent hosts, just as it is for retrying.
Many of the larger ISPs have multiple MX records which often point to
Trying every single IP address on such a long list does not seem sensible; if
several at the top of the list fail, it is reasonable to assume there is some
problem that is likely to affect all of them. Roughly speaking, the value of
-\hosts@_max@_try\ is the maximum number that are tried before deferring the
+\hosts@_max@_try\ is the maximum number that are tried before deferring the
delivery. However, the logic cannot be quite that simple.
Firstly, IP addresses that are skipped because their retry times have not
counted. This behaviour helps in the case of a domain with a retry rule that
hardly ever delays any hosts, as is now explained:
-Consider the case of a long list of hosts with one MX value, and a few with a
+Consider the case of a long list of hosts with one MX value, and a few with a
higher MX value. If \hosts@_max@_try\ is small (the default is 5) only a few
hosts at the top of the list are tried at first. With the default retry rule,
which specifies increasing retry times, the higher MX hosts are eventually
Others believe that life is not possible without it. Exim provides the
facility; you do not have to use it.
-.em
The main rewriting rules that appear in the `rewrite' section of the
configuration file are applied to addresses in incoming messages, both envelope
addresses and addresses in header lines. Each rule specifies the types of
address to which it applies.
-.nem
Rewriting of addresses in header lines applies only to those headers that
were received with the message, and, in the case of transport rewriting, those
\*fp42@@hitch.fict.example*\ becomes \*Ford.Prefect@@hitch.fict.example*\.
.endp
-.em
.section When does rewriting happen?
.index rewriting||timing of
.index ~~ACL||rewriting addresses in
Configured address rewriting can take place at several different stages of a
-message's processing.
+message's processing.
-At the start of an ACL for \\MAIL\\, the sender address may have been rewritten
+At the start of an ACL for \\MAIL\\, the sender address may have been rewritten
by a special SMTP-time rewrite rule (see section ~~SECTrewriteS), but no
ordinary rewrite rules have yet been applied. If, however, the sender address
is verified in the ACL, it is rewritten before verification, and remains
from the sender address when a recipient is verified. The address is rewritten
for the verification, but the rewriting is not remembered at this stage. The
value of \$local@_part$\ and \$domain$\ after verification are always the same
-as they were before (that is, they contain the unrewritten -- except for
+as they were before (that is, they contain the unrewritten -- except for
SMTP-time rewriting -- address).
-Once a message's header lines have been received, all the envelope recipient
+Once a message's header lines have been received, all the envelope recipient
addresses are permanently rewritten, and rewriting is also applied to the
addresses in the header lines (if configured).
.index \*local@_scan()*\ function||address rewriting, timing of
When an address is being routed, either for delivery or for verification,
rewriting is applied immediately to child addresses that are generated by
redirection, unless \no@_rewrite\ is set on the router.
-.nem
.index envelope sender, rewriting
.index rewriting||at transport time
single-item address list, which means that it is expanded before being tested
against the address.
-Domains in patterns should be given in lower case. Local parts in patterns are
-case-sensitive. If you want to do case-insensitive matching of local parts, you
+Domains in patterns should be given in lower case. Local parts in patterns are
+case-sensitive. If you want to do case-insensitive matching of local parts, you
can use a regular expression that starts with \"^(?i)"\.
.index numerical variables (\$1$\, \$2$\, etc)||in rewriting rules
alice@lookingglass.fict.example * F,24h,30m;
.endd
applies only to temporary failures involving the local part \alice\.
-In practice, almost all rules start with a domain name pattern without a local
+In practice, almost all rules start with a domain name pattern without a local
part.
.index regular expressions||in retry rules
-\**Warning**\: If you use a regular expression in a routing rule, it must match
-a complete address, not just a domain, because that is how regular expressions
-work in address lists.
+\**Warning**\: If you use a regular expression in a routing rule, it must match
+a complete address, not just a domain, because that is how regular expressions
+work in address lists.
.display
^@\Nxyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Wrong\
^@\N[^@@]+@@xyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Right\
\retry@_use@_local@_part\ is set for the transport (it defaults true for all
local transports).
-.em
When Exim is looking for a retry rule after a remote delivery attempt has
failed, what happens depends on the type of failure. After a 4\*xx*\ SMTP
response for a recipient address, the whole address is used when searching the
-retry rules. The rule that is found is used to create a retry time for the
+retry rules. The rule that is found is used to create a retry time for the
failing address.
For a temporary error that is not related to an individual address,
-.nem
(for example, a connection timeout), each line in the retry configuration is
checked twice. First, the name of the remote host is used as a domain name
(preceded by `*@@' when matching a regular expression). If this does not match
\*timeout@_connect@_MX*\: connection timeout from a host obtained from an MX
record
.nextp
-\*timeout@_connect@_A*\: connection timeout from a host not obtained from an MX
+\*timeout@_connect@_A*\: connection timeout from a host not obtained from an MX
record
.nextp
\*timeout@_connect*\: any connection timeout
\*timeout@_MX*\: any timeout from a host obtained from an MX
record
.nextp
-\*timeout@_A*\: any timeout from a host not obtained from an MX
+\*timeout@_A*\: any timeout from a host not obtained from an MX
record
.nextp
\*timeout*\: any timeout
been read for <<time>>. For example, \*quota@_4d*\ applies to a quota error
when the mailbox has not been read for four days.
-.em
.index mailbox||time of last read
\**Warning**\: It is not always possible to determine a `time of last read' for
a mailbox:
If the mailbox is a single file, the time of last access is used.
.nextp
.index maildir format||time of last read
-For a maildir delivery, the time of last modification of the \(new)\
-subdirectory is used. As the mailbox is over quota, no new files will be
-created in the \(new)\ subdirectory, so any change is assumed to be the result
+For a maildir delivery, the time of last modification of the \(new)\
+subdirectory is used. As the mailbox is over quota, no new files will be
+created in the \(new)\ subdirectory, so any change is assumed to be the result
of an MUA moving a new message to the \(cur)\ directory when it is first read.
.nextp
For other kinds of multi-file delivery, the time of last read cannot be
obtained, and so a retry rule that uses this type of error field is never
matched.
.endp
-.nem
.endp
The quota errors apply both to system-enforced quotas and to Exim's own quota
mechanism in the \%appendfile%\ transport. The \*quota*\ error also applies
.endd
the cutoff time is four days. Reaching the retry cutoff is independent of how
long any specific message has been failing; it is the length of continuous
-failure for the recipient address that counts.
+failure for the recipient address that counts.
When the cutoff time is reached for a local delivery, or for all the IP
addresses associated with a remote delivery, a subsequent delivery failure
.index \\AUTH\\||description of
Very briefly, the way SMTP authentication works is as follows:
.numberpars $.
-The server advertises a number of authentication \*mechanisms*\ in response to
+The server advertises a number of authentication \*mechanisms*\ in response to
the client's \\EHLO\\ command.
.nextp
The client issues an \\AUTH\\ command, naming a specific mechanism. The command
.conf server@_advertise@_condition string$**$ unset
When a server is about to advertise an authentication mechanism, the condition
is expanded. If it yields the empty string, `0', `no', or `false', the
-mechanism is not advertised.
-If the expansion fails, the mechanism is not advertised. If the failure was not
+mechanism is not advertised.
+If the expansion fails, the mechanism is not advertised. If the failure was not
forced, and was not caused by a lookup defer, the incident is logged.
See section ~~SECTauthexiser below for further discussion.
command line option), the string is expanded and included in the debugging
output when the authenticator is run as a server. This can help with checking
out the values of variables.
-If expansion of the string fails, the error message is written to the debugging
+If expansion of the string fails, the error message is written to the debugging
output, and Exim carries on processing.
.conf server@_set@_id string$**$ unset
.conf server@_mail@_auth@_condition string$**$ unset
This option allows a server to discard authenticated sender addresses supplied
-as part of \\MAIL\\ commands in SMTP connections that are authenticated by the
+as part of \\MAIL\\ commands in SMTP connections that are authenticated by the
driver on which \server__mail__auth@_condition\ is set. The option is not used
as part of the authentication process; instead its (unexpanded) value is
remembered for later use.
.rset SECTauthparamail "~~chapter.~~section"
.index authentication||sender, authenticated
.index \\AUTH\\||on \\MAIL\\ command
-When a client supplied an \\AUTH=\\ item on a \\MAIL\\ command, Exim applies
+When a client supplied an \\AUTH=\\ item on a \\MAIL\\ command, Exim applies
the following checks before accepting it as the authenticated sender of the
message:
.numberpars $.
-If the connection is not using extended SMTP (that is, \\HELO\\ was used rather
+If the connection is not using extended SMTP (that is, \\HELO\\ was used rather
than \\EHLO\\), the use of \\AUTH=\\ is a syntax error.
.nextp
If the value of the \\AUTH=\\ parameter is `@<@>', it is ignored.
.section Authentication on an Exim server
.rset SECTauthexiser "~~chapter.~~section"
.index authentication||on an Exim server
-When Exim receives an \\EHLO\\ command, it advertises the public names of those
-authenticators that are configured as servers, subject to the following
+When Exim receives an \\EHLO\\ command, it advertises the public names of those
+authenticators that are configured as servers, subject to the following
conditions:
.numberpars $.
The client host must match \auth@_advertise@_hosts\ (default $*$).
.nextp
-It the \server@_advertise@_condition\ option is set, its expansion must not
+It the \server@_advertise@_condition\ option is set, its expansion must not
yield the empty string, `0', `no', or `false'.
.endp
-The order in which the authenticators are defined controls the order in which
+The order in which the authenticators are defined controls the order in which
the mechanisms are advertised.
Some mail clients (for example, some versions of Netscape) require the user to
.display asis
server_advertise_condition = ${if eq{$tls_cipher}{}{no}{yes}}
.endd
-If the session is encrypted, \$tls@_cipher$\ is not empty, and so the expansion
+If the session is encrypted, \$tls@_cipher$\ is not empty, and so the expansion
yields `yes', which allows the advertisement to happen.
When an Exim server receives an \\AUTH\\ command from a client, it rejects it
.nextp
No authenticators are configured with server options; or
.nextp
-Expansion of \server@_advertise@_condition\ blocked the advertising of all the
+Expansion of \server@_advertise@_condition\ blocked the advertising of all the
server authenticators.
.endp
Otherwise, Exim runs the ACL specified by \acl@_smtp@_auth\ in order
to decide whether to accept the command. If \acl@_smtp@_auth\ is not set,
-\\AUTH\\ is accepted from any client host.
+\\AUTH\\ is accepted from any client host.
If \\AUTH\\ is not rejected by the ACL, Exim searches its configuration for a
-server authentication mechanism that was advertised in response to \\EHLO\\ and
+server authentication mechanism that was advertised in response to \\EHLO\\ and
that matches the one named in the \\AUTH\\ command. If it finds one, it runs
the appropriate authentication protocol, and authentication either succeeds or
fails. If there is no matching advertised mechanism, the \\AUTH\\ command is
.endd
Note the use of single quotes to prevent the shell interpreting the
backslashes, so that they can be interpreted by Perl to specify characters
-whose code value is zero.
+whose code value is zero.
\**Warning 1**\: If either of the user or password strings starts with an octal
digit, you must use three zeros instead of one after the leading backslash. If
you do not, the octal digit that starts your string will be incorrectly
interpreted as part of the code for the first character.
-\**Warning 2**\: If there are characters in the strings that Perl interprets
-specially, you must use a Perl escape to prevent them being misinterpreted. For
+\**Warning 2**\: If there are characters in the strings that Perl interprets
+specially, you must use a Perl escape to prevent them being misinterpreted. For
example, a command such as
.display asis
encode '\0user@domain.com\0pas$$word'
.index \\AUTH\\||on \\MAIL\\ command
When Exim has authenticated itself to a remote server, it adds the \\AUTH\\
parameter to the \\MAIL\\ commands it sends, if it has an authenticated sender
-for the message.
-If the message came from a remote host, the authenticated sender is the one
-that was receiving on an incoming \\MAIL\\ command, provided that the incoming
+for the message.
+If the message came from a remote host, the authenticated sender is the one
+that was receiving on an incoming \\MAIL\\ command, provided that the incoming
connection was authenticated and the \server@_mail@_auth\ condition allowed the
authenticated sender to be retained. If a local process calls Exim to send a
message, the sender address that is built from the login name and
expanded and saved in \$authenticated@_id$\. For any other result, a temporary
error code is returned, with the expanded string as the error text.
-\**Warning**\: If you use a lookup in the expansion to find the user's
-password, be sure to make the authentication fail if the user is unknown.
+\**Warning**\: If you use a lookup in the expansion to find the user's
+password, be sure to make the authentication fail if the user is unknown.
There are good and bad examples at the end of the next section.
.index authentication||PLAIN mechanism
.index binary zero||in \%plaintext%\ authenticator
The PLAIN authentication mechanism (RFC 2595) specifies that three strings be
-sent as one item of data (that is, one combined string containing two NUL
+sent as one item of data (that is, one combined string containing two NUL
separators). The data is sent either as part of the \\AUTH\\ command, or
subsequently in response to an empty prompt from the server.
fixed_plain:
driver = plaintext
public_name = PLAIN
- server_prompts = :
+ server_prompts = :
server_condition = \
${if and {{eq{$2}{username}}{eq{$3}{mysecret}}}{yes}{no}}
server_set_id = $2
.display asis
AUTH PLAIN
.endd
-to initiate authentication, in which case the server replies with an empty
+to initiate authentication, in which case the server replies with an empty
prompt. The client must respond with the combined data string.
-.em
The data string is base64 encoded, as required by the RFC. This example,
when decoded, is \"<<NUL>>username<<NUL>>mysecret"\, where <<NUL>> represents a
zero byte. This is split up into three strings, the first of which is empty.
The \server@_condition\ option in the authenticator checks that the second two
are \"username"\ and \"mysecret"\ respectively.
-Having just one fixed user name and password, as in this example, is not very
-realistic, though for a small organization with only a handful of
+Having just one fixed user name and password, as in this example, is not very
+realistic, though for a small organization with only a handful of
authenticating clients it could make sense.
-.nem
A more sophisticated instance of this authenticator could use the user name in
\$2$\ to look up a password in a file or database, and maybe do an encrypted
which it then compares to the supplied password (\$3$\). Why is this example
incorrect? It works fine for existing users, but consider what happens if a
non-existent user name is given. The lookup fails, but as no success/failure
-strings are given for the lookup, it yields an empty string. Thus, to defeat
-the authentication, all a client has to do is to supply a non-existent user
+strings are given for the lookup, it yields an empty string. Thus, to defeat
+the authentication, all a client has to do is to supply a non-existent user
name and an empty password. The correct way of writing this test is:
.display asis
server_condition = ${lookup{$2}dbm{/etc/authpwd}\
- {${if eq{$value}{$3}{yes}{no}}}{no}}
+ {${if eq{$value}{$3}{yes}{no}}}{no}}
.endd
In this case, if the lookup succeeds, the result is checked; if the lookup
fails, authentication fails. If \crypteq\ is being used instead of \eq\, the
public_name = LOGIN
server_prompts = Username:: : Password::
server_condition = ${if ldapauth \
-.newline
+.newline
{user="cn=${quote_ldap_dn:$1},ou=people,o=example.org" \
pass=${quote:$2} \
-.newline
+.newline
ldap://ldap.example.org/}{yes}{no}}
server_set_id = uid=$1,ou=people,o=example.org
.endd
Note the use of the \quote@_ldap@_dn\ operator to correctly quote the DN for
authentication. However, the basic \quote\ operator, rather than any of the
-LDAP quoting operators, is the correct one to use for the password, because
-quoting is needed only to make the password conform to the Exim syntax. At the
+LDAP quoting operators, is the correct one to use for the password, because
+quoting is needed only to make the password conform to the Exim syntax. At the
LDAP level, the password is an uninterpreted string.
-.section Support for different kinds of authentication
+.section Support for different kinds of authentication
A number of string expansion features are provided for the purpose of
interfacing to different ways of user authentication. These include checking
traditionally encrypted passwords from \(/etc/passwd)\ (or equivalent), PAM,
For example, the following authenticator checks that the user name given by the
client is `ph10', and if so, uses `secret' as the password. For any other user
-name, authentication fails.
+name, authentication fails.
.display asis
fixed_cram:
driver = cram_md5
.conf server@_password string$**$ unset
.index numerical variables (\$1$\, \$2$\, etc)||in \%spa%\ authenticator
-This option is expanded, and the result must be the cleartext password for the
+This option is expanded, and the result must be the cleartext password for the
authenticating user, whose name is at this point in \$1$\. For example:
.display asis
spa:
public_name = NTLM
server_password = ${lookup{$1}lsearch{/etc/exim/spa_clearpass}}
.endd
-If the expansion is forced to fail, authentication fails. Any other expansion
+If the expansion is forced to fail, authentication fails. Any other expansion
failure causes a temporary error code to be returned.
.endconf
.index TLS||on SMTP connection
.index OpenSSL
.index GnuTLS
-.em
Support for TLS (Transport Layer Security), formerly known as SSL (Secure
Sockets Layer), is implemented by making use of the OpenSSL library or the
GnuTLS library (Exim requires GnuTLS release 1.0 or later).
-.nem
There is no cryptographic code in the Exim distribution itself for implementing
TLS. In order to use this feature you must install OpenSSL or GnuTLS, and then
build a version of Exim that includes TLS support (see section
There are some differences in usage when using GnuTLS instead of OpenSSL:
.numberpars $.
-.em
-The \tls@_verify@_certificates\ option must contain the name of a file, not the
+The \tls@_verify@_certificates\ option must contain the name of a file, not the
name of a directory (for OpenSSL it can be either).
-.nem
.nextp
The \tls@_dhparam\ option is ignored, because early versions of GnuTLS had no
-facility for varying its Diffie-Hellman parameters. I understand that this has
+facility for varying its Diffie-Hellman parameters. I understand that this has
changed, but Exim has not been updated to provide this facility.
.nextp
GnuTLS uses RSA and D-H parameters that take a substantial amount of
Arranging this is easy; just delete the file when you want new values to be
computed.
.nextp
-.em
-Distinguished Name (DN) strings reported by the OpenSSL library use a slash for
-separating fields; GnuTLS uses commas, in accordance with RFC 2253. This
+Distinguished Name (DN) strings reported by the OpenSSL library use a slash for
+separating fields; GnuTLS uses commas, in accordance with RFC 2253. This
affects the value of the \$tls@_peerdn$\ variable.
-.nem
.nextp
OpenSSL identifies cipher suites using hyphens as separators, for example:
DES-CBC3-SHA. GnuTLS uses underscores, for example: RSA@_ARCFOUR@_SHA. What is
more, OpenSSL complains if underscores are present in a cipher list. To make
life simpler, Exim changes underscores to hyhens for OpenSSL and hyphens to
underscores for GnuTLS when processing lists of cipher suites in the
-.em
-\tls@_require@_ciphers\ options (the global option and the \%smtp%\ transport
+\tls@_require@_ciphers\ options (the global option and the \%smtp%\ transport
option).
-.nem
.nextp
-.em
The \tls@_require@_ciphers\ options operate differently, as described in the
following section.
-.nem
.endp
-.em
.section Requiring specific ciphers in OpenSSL and GnuTLS
.rset SECTreqciphsslgnu "~~chapter.~~section"
.index TLS||requiring specific ciphers
Unrecognized algorithms are ignored. In a client, the order of the list
specifies a preference order for the algorithms.
-.nem
.section Configuring an Exim server to use TLS
source of this background information, which is not Exim-specific. (There are a
few comments below in section ~~SECTcerandall.)
-\**Note**\: These options do not apply when Exim is operating as a client --
-they apply only in the case of a server. For a client, you must set the options
+\**Note**\: These options do not apply when Exim is operating as a client --
+they apply only in the case of a server. For a client, you must set the options
of the same name in an \%smtp%\ transport.
With just these options, Exim will work as a server with clients such as
tls_dhparam = /some/file/name
.endd
is set, the SSL library is initialized for the use of Diffie-Hellman ciphers
-with the parameters contained in the file. This increases the set of cipher
+with the parameters contained in the file. This increases the set of cipher
suites that the server supports. See the command
.display asis
openssl dhparam
.endd
for a way of generating this data.
-At present, \tls@_dhparam\ is used only when Exim is linked with OpenSSL. It is
+At present, \tls@_dhparam\ is used only when Exim is linked with OpenSSL. It is
ignored if GnuTLS is being used.
The strings supplied for these three options are expanded every time a client
incoming message (by default -- you can, of course, change this), and it is
also included in the log line that records a message's arrival, keyed by `X=',
unless the \tls@_cipher\ log selector is turned off.
-The \encrypted\ condition can be used to test for specific cipher suites in
+The \encrypted\ condition can be used to test for specific cipher suites in
ACLs.
The ACLs that run for subsequent SMTP commands can check the name of the cipher
Exim requests a certificate as part of the setup of the TLS session. The
contents of the certificate are verified by comparing it with a list of
expected certificates. These must be available in a file or,
-.em
for OpenSSL only (not GnuTLS), a directory, identified by
\tls@_verify@_certificates\.
-.nem
A file can contain multiple certificates, concatenated end to end. If a
-directory is used
-.em
-(OpenSSL only),
-.nem
+directory is used
+(OpenSSL only),
each certificate must be in a separate file, with a name (or a symbolic link)
of the form <<hash>>.0, where <<hash>> is a hash value constructed from the
certificate. You can compute the relevant hash by running the command
\received@_header@_text\ to change the ::Received:: header. When no certificate
is supplied, \$tls@_peerdn$\ is empty.
-.em
.section Revoked certificates
.index TLS||revoked certificates
.index revocation list
identically named option for the \%smtp%\ transport. In each case, the value of
the option is expanded and must then be the name of a file that contains a CRL
in PEM format.
-.nem
.section Configuring an Exim client to use TLS
.index cipher||logging
provide the client with a certificate, which is passed to the server if it
requests it. If the server is Exim, it will request a certificate only if
\tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\ matches the client.
-\**Note**\: these options must be set in the \%smtp%\ transport for Exim to use
+\**Note**\: these options must be set in the \%smtp%\ transport for Exim to use
TLS when it is operating as a client. Exim does not assume that a server
certificate (set by the global options of the same name) should also be used
when operating as a client.
If \tls@_verify@_certificates\ is set, it must name a file or,
-.em
for OpenSSL only (not GnuTLS), a directory, that contains a collection of
expected server certificates. The client verifies the server's certificate
against this collection, taking into account any revoked certificates that are
in the list defined by \tls@_crl\.
-.nem
If
\tls@_require@_ciphers\ is set on the \%smtp%\ transport, it must contain a
if \\AUTH\\ is in use, before sending the next message.
The RFC is not clear as to whether or not an SMTP session continues in clear
-after TLS has been shut down, or whether TLS may be restarted again later, as
+after TLS has been shut down, or whether TLS may be restarted again later, as
just described. However, if the server is Exim, this shutdown and
reinitialization works. It is not known which (if any) other servers operate
successfully if the client closes a TLS session and continues with unencrypted
and delay other deliveries to that host.
To test for this case, Exim sends an \\EHLO\\ command to the server after
-closing down the TLS session. If this fails in any way, the connection is
+closing down the TLS session. If this fails in any way, the connection is
closed instead of being passed to a new delivery process, but no retry
information is recorded.
-There is also a manual override; you can set \hosts@_nopass@_tls\ on the
-\%smtp%\ transport to match those hosts for which Exim should not pass
+There is also a manual override; you can set \hosts@_nopass@_tls\ on the
+\%smtp%\ transport to match those hosts for which Exim should not pass
connections to new processes if TLS has been used.
Other parts of the \*modssl*\ documentation are also helpful, and have
links to further files.
Eric Rescorla's book, \*SSL and TLS*\, published by Addison-Wesley (ISBN
-0-201-61598-3), contains both introductory and more in-depth descriptions.
+0-201-61598-3), contains both introductory and more in-depth descriptions.
Some sample programs taken from the book are available from
.display rm
\?http://www.rtfm.com/openssl-examples/?\
.index policy control||access control lists
Access Control Lists (ACLs) are defined in a separate section of the run time
configuration file, headed by `begin acl'. Each ACL definition starts with a
-name, terminated by a colon. Here is a complete ACL section which contains just
+name, terminated by a colon. Here is a complete ACL section that contains just
one very small ACL:
.display asis
begin acl
The majority of ACLs are used to control Exim's behaviour when it receives
certain SMTP commands. This applies both to incoming TCP/IP connections, and
-when a local process submits a message over a pipe (using the \-bs-\ option).
-The most common use is for controlling which recipients are accepted in
-incoming messages. In addition, you can also define an ACL that is used to
-check local non-SMTP messages. The default configuration file contains an
-example of a realistic ACL for checking \\RCPT\\ commands. This is discussed in
-chapter ~~CHAPdefconfil.
+when a local process submits a message using SMTP by specifying the \-bs-\
+option. The most common use is for controlling which recipients are accepted
+in incoming messages. In addition, you can define an ACL that is used to check
+local non-SMTP messages. The default configuration file contains an example of
+a realistic ACL for checking \\RCPT\\ commands. This is discussed in chapter
+~~CHAPdefconfil.
.section Testing ACLs
The \-bh-\ command line option provides a way of testing your ACL configuration
In order to cause an ACL to be used, you have to name it in one of the relevant
options in the main part of the configuration. These options are:
.index \\AUTH\\||ACL for
-.index \\DATA\\, ACL for
+.index \\DATA\\, ACLs for
.index \\ETRN\\||ACL for
.index \\EXPN\\||ACL for
.index \\HELO\\||ACL for
.index \\EHLO\\||ACL for
.index \\MAIL\\||ACL for
+.index \\QUIT\\, ACL for
.index \\RCPT\\||ACL for
.index \\STARTTLS\\, ACL for
.index \\VRFY\\||ACL for
+.index SMTP||connection, ACL for
+.index non-smtp message, ACL for
.display
.tabs 20
.if !~~sys.fancy
\acl@_not@_smtp\ $t $rm{ACL for non-SMTP messages}
\acl@_smtp@_auth\ $t $rm{ACL for \\AUTH\\}
\acl@_smtp@_connect\ $t $rm{ACL for start of SMTP connection}
-\acl@_smtp@_data\ $t $rm{ACL after \\DATA\\}
+\acl@_smtp@_data\ $t $rm{ACL after \\DATA\\ is complete}
\acl@_smtp@_etrn\ $t $rm{ACL for \\ETRN\\}
\acl@_smtp@_expn\ $t $rm{ACL for \\EXPN\\}
\acl@_smtp@_helo\ $t $rm{ACL for \\HELO\\ or \\EHLO\\}
\acl@_smtp@_mail\ $t $rm{ACL for \\MAIL\\}
-.newline
\acl@_smtp@_mailauth\ $t $rm{ACL for the \\AUTH\\ parameter of \\MAIL\\}
.newline
+.em
+\acl@_smtp@_mime\ $t $rm{ACL for content-scanning MIME parts}
+\acl@_smtp@_predata\ $t $rm{ACL at start of \\DATA\\ command}
+\acl@_smtp@_quit\ $t $rm{ACL for \\QUIT\\}
+.nem
+.newline
\acl@_smtp@_rcpt\ $t $rm{ACL for \\RCPT\\}
\acl@_smtp@_starttls\ $t $rm{ACL for \\STARTTLS\\}
\acl@_smtp@_vrfy\ $t $rm{ACL for \\VRFY\\}
in an SMTP dialogue. The majority of policy tests on incoming messages can be
done when \\RCPT\\ commands arrive. A rejection of \\RCPT\\ should cause the
sending MTA to give up on the recipient address contained in the \\RCPT\\
-command, whereas rejection at other times may cause the client MTA to keep on
-trying to deliver the message. It is therefore recommended that you do as much
+command, whereas rejection at other times may cause the client MTA to keep on
+trying to deliver the message. It is therefore recommended that you do as much
testing as possible at \\RCPT\\ time.
-However, you cannot test the contents of the message, for example, to verify
-addresses in the headers, at \\RCPT\\ time. Such tests have to appear in the
-ACL that is run after the message has been received, before the final response
-to the \\DATA\\ command is sent. This is the ACL specified by
-\acl@_smtp@_data\. At this time, it is no longer possible to reject individual
-recipients. An error response should reject the entire message. Unfortunately,
-it is known that some MTAs do not treat hard (5$it{xx}) errors correctly at
-this point -- they keep the message on their queues and try again later, but
-that is their problem, though it does waste some of your resources.
-
-The ACL test specified by \acl@_smtp@_connect\ happens after the test specified
+.em
+.section The MIME ACLs
+The \acl@_smtp@_mime\ option is available only when Exim is compiled with the
+content-scanning extension. For details, see chapter ~~CHAPexiscan.
+
+
+.section The DATA ACLs
+.index \\DATA\\, ACLs for
+Two ACLs are associated with the \\DATA\\ command. When the command is
+received, the ACL defined by \acl@_smtp@_predata\ is obeyed. This gives you
+control after all the \\RCPT\\ commands, but before the message itself
+is received. It offers the opportunity to give a negative response to the
+\\DATA\\ command itself. Header lines added by \\MAIL\\ or \\RCPT\\ ACLs are
+not visible at this time, but any that are defined here are visible when the
+\acl@_smtp@_data\ ACL is run.
+
+You cannot test the contents of the message, for example, to verify
+addresses in the headers, at \\RCPT\\ time or when the \\DATA\\ command is
+received.
+.nem
+Such tests have to appear in the ACL that is run after the message has been
+received, before the final response to the \\DATA\\ command is sent. This is
+the ACL specified by \acl@_smtp@_data\. At this time, it is no longer possible
+to reject individual recipients. An error response rejects the entire message.
+Unfortunately, it is known that some MTAs do not treat hard (5$it{xx}) errors
+correctly at this point -- they keep the message on their queues and try again
+later, but that is their problem, though it does waste some of your resources.
+
+.section The connect ACL
+.index SMTP||connection, ACL for
+The ACL test specified by \acl@_smtp@_connect\ happens after the test specified
by \host__reject__connection\ (which is now an anomaly) and any TCP Wrappers
testing (if configured).
+.em
+.section The QUIT ACL
+.rset SECTQUITACL "~~chapter.~~section"
+.index \\QUIT\\, ACL for
+The ACL for the SMTP \\QUIT\\ command is anomalous, in that the
+outcome of the ACL does not affect the response code to \\QUIT\\,
+which is always 221. Thus, the ACL does not in fact control any access.
+For this reason, the only verbs that are permitted are \accept\ and \warn\.
+
+This ACL can be used for tasks such as custom logging at the end of an SMTP
+session. For example, you can use ACL variables in other ACLs to count
+messages, recipients, etc., and log the totals at \\QUIT\\ time using one or
+more \logwrite\ modifiers on a \warn\ verb.
+
+You do not need to have a final \accept\, but if you do, you can use a
+\message\ modifier to specify custom text that is sent as part of the 221
+response to \\QUIT\\.
+
+This ACL is run only for a `normal' \\QUIT\\. For certain kinds of disastrous
+failure (for example, failure to open a log file, or when Exim is bombing out
+because it has detected an unrecoverable error), all SMTP commands from the
+client are given temporary error responses until \\QUIT\\ is received or the
+connection is closed. In these special cases, the \\QUIT\\ ACL does not run.
+.nem
+
+.section The non-SMTP ACL
+.index non-smtp message, ACL for
The non-SMTP ACL applies to all non-interactive incoming messages, that is, it
applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not
really SMTP.) This ACL is run just before the \*local@_scan()*\ function. Any
encryption and authentication) are not relevant and are forbidden in this ACL.
+.section Finding an ACL to use
+.index ~~ACL||finding which to use
+The value of an \acl@_smtp@_$it{xxx}\ option is expanded before use, so you can
+use different ACLs in different circumstances. The resulting string does not
+have to be the name of an ACL in the configuration file; there are other
+possibilities. Having expanded the string, Exim searches for an ACL as follows:
+.numberpars $.
+If the string begins with a slash, Exim uses it as a file name, and reads its
+contents as an ACL. The lines are processed in the same way as lines in the
+Exim configuration file. In particular, continuation lines are supported, blank
+lines are ignored, as are lines whose first non-whitespace character is `@#'.
+If the file does not exist or cannot be read, an error occurs (typically
+causing a temporary failure of whatever caused the ACL to be run). For example:
+.display asis
+acl_smtp_data = /etc/acls/\
+ ${lookup{$sender_host_address}lsearch\
+ {/etc/acllist}{$value}{default}}
+.endd
+This looks up an ACL file to use on the basis of the host's IP address, falling
+back to a default if the lookup fails. If an ACL is successfully read from a
+file, it is retained in memory for the duration of the Exim process, so that it
+can be re-used without having to re-read the file.
+.nextp
+If the string does not start with a slash, and does not contain any spaces,
+Exim searches the ACL section of the configuration for an ACL whose name
+matches the string.
+.nextp
+If no named ACL is found, or if the string contains spaces, Exim parses
+the string as an inline ACL. This can save typing in cases where you just
+want to have something like
+.display asis
+acl_smtp_vrfy = accept
+.endd
+in order to allow free use of the \\VRFY\\ command. Such a string may contain
+newlines; it is processed in the same way as an ACL that is read from a file.
+.endp
+
+
.section ACL return codes
.index ~~ACL||return codes
-The result of running an ACL is either `accept' or `deny', or, if some test
+.em
+Except for the \\QUIT\\ ACL, which does not affect the SMTP return code (see
+section ~~SECTQUITACL above), the
+.nem
+result of running an ACL is either `accept' or `deny', or, if some test
cannot be completed (for example, if a database is down), `defer'. These
results cause 2$it{xx}, 5$it{xx}, and 4$it{xx} return codes, respectively, to
be used in the SMTP dialogue. A fourth return, `error', occurs when there is an
error such as invalid syntax in the ACL. This also causes a 4$it{xx} return
code.
-The ACLs that are relevant to message reception may also return `discard'. This
+.em
+For the non-SMTP ACL, `defer' and `error' are treated in the same way as
+`deny', because there is no mechanism for passing temporary errors to the
+submitters of non-SMTP messages.
+.nem
+
+ACLs that are relevant to message reception may also return `discard'. This
has the effect of `accept', but causes either the entire message or an
individual recipient address to be discarded. In other words, it is a
-blackholing facility. Use it with great care.
+blackholing facility. Use it with care.
If the ACL for \\MAIL\\ returns `discard', all recipients are discarded, and no
ACL is run for subsequent \\RCPT\\ commands. The effect of `discard' in a
-\\RCPT\\ ACL is to discard just the one address. If there are no recipients
-left when the message's data is received, the \\DATA\\ ACL is not run. A
-`discard' return from the \\DATA\\ or the non-SMTP ACL discards all the
+\\RCPT\\ ACL is to discard just the one recipient address. If there are no
+recipients left when the message's data is received, the \\DATA\\ ACL is not
+run. A `discard' return from the \\DATA\\ or the non-SMTP ACL discards all the
remaining recipients.
+.em
+The `discard' return is not permitted for the \acl@_smtp@_predata\ ACL.
+.nem
-The \*local@_scan()*\ function is always run, even if there are no remaining
+.index \*local@_scan()*\ function||when all recipients discarded
+The \*local@_scan()*\ function is always run, even if there are no remaining
recipients; it may create new recipients.
.section Unset ACL options
.index ~~ACL||unset options
-.em
The default actions when any of the \acl@_$it{xxx}\ options are unset are not
all the same. \**Note**\: These defaults apply only when the relevant ACL is
-not defined at all. For any defined ACL, the default action if control reaches
+not defined at all. For any defined ACL, the default action when control reaches
the end of the ACL statements is `deny'.
-.nem
For \acl@_not@_smtp\, \acl@_smtp@_auth\, \acl@_smtp@_connect\,
\acl@_smtp@_data\, \acl@_smtp@_helo\, \acl__smtp__mail\, \acl@_smtp@_mailauth\,
-and \acl@_smtp@_starttls\, the
.em
-action when the ACL is not defined is `accept'.
+\acl@_smtp@_predata\, \acl@_smtp@_quit\,
+.nem
+and \acl@_smtp@_starttls\, the action when the ACL is not defined is `accept'.
For the others (\acl@_smtp@_etrn\, \acl@_smtp@_expn\, \acl@_smtp@_rcpt\, and
\acl@_smtp@_vrfy\), the action when the ACL is not defined is `deny'.
-.nem
This means that \acl@_smtp@_rcpt\ must be defined in order to receive any
messages over an SMTP connection. For an example, see the ACL in the default
configuration file.
ACL statements. In the case of \\RCPT\\ (but not \\MAIL\\ or \\DATA\\),
\$domain$\ and \$local@_part$\ are set from the argument address.
-When an ACL for the \\AUTH\\ parameter of \\MAIL\\ is being run, the variables
-that contain information about the host are set, but \$sender@_address$\ is not
+When an ACL for the \\AUTH\\ parameter of \\MAIL\\ is being run, the variables
+that contain information about the host are set, but \$sender@_address$\ is not
yet set.
+.em
+Section ~~SECTauthparamail contains a discussion of this parameter and
+how it is used.
+.nem
The \$message@_size$\ variable is set to the value of the \\SIZE\\ parameter on
the \\MAIL\\ command at \\MAIL\\ and \\RCPT\\ time, or -1 if that parameter was
-not given.
-Its value is updated to the true message size by the time the ACL after
-\\DATA\\ is run.
+not given. Its value is updated to the true message size by the time the ACL
+after \\DATA\\ is run.
The \$rcpt@_count$\ variable increases by one for each \\RCPT\\ command
received. The \$recipients@_count$\ variable increases by one each time a
.section Data for non-message ACLs
.rset SECTdatfornon "~~chapter.~~section"
.index ~~ACL||data for non-message ACL
-When an ACL for \\AUTH\\, \\ETRN\\, \\EXPN\\,
-\\STARTTLS\\,
-or \\VRFY\\ is being run, the remainder of the SMTP command line is placed in
+.em
+When an ACL is being run for \\AUTH\\, \\EHLO\\, \\ETRN\\, \\EXPN\\, \\HELO\\,
+.nem
+\\STARTTLS\\, or \\VRFY\\, the remainder of the SMTP command line is placed in
\$smtp@_command@_argument$\. This can be tested using a \condition\ condition.
For example, here is an ACL for use with \\AUTH\\, which insists that either
the session is encrypted, or the CRAM-MD5 authentication method is used. In
.display asis
acl_check_auth:
accept encrypted = *
+.newline
+.em
accept condition = ${if eq{${uc:$smtp_command_argument}}\
- {CRAM-MD5}{yes}{no}}
+ {CRAM-MD5}}
+.nem
+.newline
deny message = TLS encryption or CRAM-MD5 required
.endd
-(Another way of applying this restriction is to arrange for the authenticators
-that use cleartext passwords not to be advertised when the connection is not
-encrypted. You can use the generic \server@_advertise@_condition\ authenticator
+(Another way of applying this restriction is to arrange for the authenticators
+that use cleartext passwords not to be advertised when the connection is not
+encrypted. You can use the generic \server@_advertise@_condition\ authenticator
option to&nb
projects / exim.git / commitdiff