<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
span.changed { background-color: #99ff99; }
span.off { }
pre.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] pre.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] div.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
</style><title>7. The default configuration file</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch06.html" title="6. The Exim run time configuration file" /><link rel="next" href="ch08.html" title="8. Regular expressions" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch06.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch08.html">Next</a></td></tr></table></div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a href="index.html#toc0079" id="CHAPdefconfil">7. The default configuration file</a></h2></div>
</div>
</div>
<p>
<a id="IIDconfiwal" class="indexterm"></a>
<a id="id492386" class="indexterm"></a>
The default configuration file supplied with Exim as <em class="filename">src/configure.default</em>
is sufficient for a host with simple mail requirements. As an introduction to
the way Exim is configured, this chapter “<span class="quote">walks through</span>” the default
configuration, giving brief explanations of the settings. Detailed descriptions
of the options are given in subsequent chapters. The default configuration file
itself contains extensive comments about ways you might want to modify the
initial settings. However, note that there are many options that are not
mentioned at all in the default configuration.
</p>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0080" id="SECTdefconfmain">7.1 Main configuration settings</a></h3></div>
</div>
</div>
<p>
The main (global) configuration option settings must always come first in the
file. The first thing you’ll see in the file, after some initial comments, is
the line
</p>
<pre class="literallayout"># primary_hostname =
</pre><p>
This is a commented-out setting of the <span><strong class="option">primary_hostname</strong></span> option. Exim needs
to know the official, fully qualified name of your host, and this is where you
can specify it. However, in most cases you do not need to set this option. When
it is unset, Exim uses the <em class="function">uname()</em> system function to obtain the host name.
</p>
<p>
The first three non-comment configuration lines are as follows:
</p>
<pre class="literallayout">domainlist local_domains = @
domainlist relay_to_domains =
hostlist relay_from_hosts = 127.0.0.1
</pre><p>
These are not, in fact, option settings. They are definitions of two named
domain lists and one named host list. Exim allows you to give names to lists of
domains, hosts, and email addresses, in order to make it easier to manage the
configuration file (see section <a href="ch10.html#SECTnamedlists" title="10.5 Named lists">10.5</a>).
</p>
<p>
The first line defines a domain list called <span class="emphasis"><em>local_domains</em></span>; this is used
later in the configuration to identify domains that are to be delivered
on the local host.
</p>
<p>
<a id="id492503" class="indexterm"></a>
There is just one item in this list, the string “<span class="quote">@</span>”. This is a special form
of entry which means “<span class="quote">the name of the local host</span>”. Thus, if the local host is
called <span class="emphasis"><em>a.host.example</em></span>, mail to <span class="emphasis"><em>any.user@a.host.example</em></span> is expected to
be delivered locally. Because the local host’s name is referenced indirectly,
the same configuration file can be used on different hosts.
</p>
<p>
The second line defines a domain list called <span class="emphasis"><em>relay_to_domains</em></span>, but the
list itself is empty. Later in the configuration we will come to the part that
controls mail relaying through the local host; it allows relaying to any
domains in this list. By default, therefore, no relaying on the basis of a mail
domain is permitted.
</p>
<p>
The third line defines a host list called <span class="emphasis"><em>relay_from_hosts</em></span>. This list is
used later in the configuration to permit relaying from any host or IP address
that matches the list. The default contains just the IP address of the IPv4
loopback interface, which means that processes on the local host are able to
submit mail for relaying by sending it over TCP/IP to that interface. No other
hosts are permitted to submit messages for relaying.
</p>
<p>
Just to be sure there’s no misunderstanding: at this point in the configuration
we aren’t actually setting up any controls. We are just defining some domains
and hosts that will be used in the controls that are specified later.
</p>
<p>
The next two configuration lines are genuine option settings:
</p>
<pre class="literallayout">acl_smtp_rcpt = acl_check_rcpt
acl_smtp_data = acl_check_data
</pre><p>
These options specify <span class="emphasis"><em>Access Control Lists</em></span> (ACLs) that are to be used
during an incoming SMTP session for every recipient of a message (every RCPT
command), and after the contents of the message have been received,
respectively. The names of the lists are <span class="emphasis"><em>acl_check_rcpt</em></span> and
<span class="emphasis"><em>acl_check_data</em></span>, and we will come to their definitions below, in the ACL
section of the configuration. The RCPT ACL controls which recipients are
accepted for an incoming message – if a configuration does not provide an ACL
to check recipients, no SMTP mail can be accepted. The DATA ACL allows the
contents of a message to be checked.
</p>
<p>
Two commented-out option settings are next:
</p>
<pre class="literallayout"># av_scanner = clamd:/tmp/clamd
# spamd_address = 127.0.0.1 783
</pre><p>
These are example settings that can be used when Exim is compiled with the
content-scanning extension. The first specifies the interface to the virus
scanner, and the second specifies the interface to SpamAssassin. Further
details are given in chapter <a href="ch41.html" title="41. Content scanning at ACL time">41</a>.
</p>
<p>
Three more commented-out option settings follow:
</p>
<pre class="literallayout"># tls_advertise_hosts = *
# tls_certificate = /etc/ssl/exim.crt
# tls_privatekey = /etc/ssl/exim.pem
</pre><p>
These are example settings that can be used when Exim is compiled with
support for TLS (aka SSL) as described in section <a href="ch04.html#SECTinctlsssl" title="4.6 Including TLS/SSL encryption support">4.6</a>. The
first one specifies the list of clients that are allowed to use TLS when
connecting to this server; in this case the wildcard means all clients. The
other options specify where Exim should find its TLS certificate and private
key, which together prove the server’s identity to any clients that connect.
More details are given in chapter <a href="ch39.html" title="39. Encrypted SMTP connections using TLS/SSL">39</a>.
</p>
<p>
Another two commented-out option settings follow:
</p>
<pre class="literallayout"># daemon_smtp_ports = 25 : 465 : 587
# tls_on_connect_ports = 465
</pre><p>
<a id="id492681" class="indexterm"></a>
<a id="id492696" class="indexterm"></a>
<a id="id492710" class="indexterm"></a>
<a id="id492725" class="indexterm"></a>
<a id="id492736" class="indexterm"></a>
<a id="id492747" class="indexterm"></a>
<a id="id492761" class="indexterm"></a>
These options provide better support for roaming users who wish to use this
server for message submission. They are not much use unless you have turned on
TLS (as described in the previous paragraph) and authentication (about which
more in section <a href="ch07.html#SECTdefconfauth" title="7.7 Authenticators configuration">7.7</a>). The usual SMTP port 25 is often blocked
on end-user networks, so RFC 4409 specifies that message submission should use
port 587 instead. However some software (notably Microsoft Outlook) cannot be
configured to use port 587 correctly, so these settings also enable the
non-standard “<span class="quote">smtps</span>” (aka “<span class="quote">ssmtp</span>”) port 465 (see section
<a href="ch13.html#SECTsupobssmt" title="13.4 Support for the obsolete SSMTP (or SMTPS) protocol">13.4</a>).
</p>
<p>
Two more commented-out options settings follow:
</p>
<pre class="literallayout"># qualify_domain =
# qualify_recipient =
</pre><p>
The first of these specifies a domain that Exim uses when it constructs a
complete email address from a local login name. This is often needed when Exim
receives a message from a local process. If you do not set <span><strong class="option">qualify_domain</strong></span>,
the value of <span><strong class="option">primary_hostname</strong></span> is used. If you set both of these options,
you can have different qualification domains for sender and recipient
addresses. If you set only the first one, its value is used in both cases.
</p>
<p>
<a id="id492837" class="indexterm"></a>
The following line must be uncommented if you want Exim to recognize
addresses of the form <span class="emphasis"><em>user@[10.11.12.13]</em></span> that is, with a “<span class="quote">domain literal</span>”
(an IP address within square brackets) instead of a named domain.
</p>
<pre class="literallayout"># allow_domain_literals
</pre><p>
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
<span class="emphasis"><em>postmaster</em></span>) where domain literals are still useful.
</p>
<p>
The next configuration line is a kind of trigger guard:
</p>
<pre class="literallayout">never_users = root
</pre><p>
It specifies that no delivery must ever be run as the root user. The normal
convention is to set up <span class="emphasis"><em>root</em></span> as an alias for the system administrator. This
setting is a guard against slips in the configuration.
The list of users specified by <span><strong class="option">never_users</strong></span> is not, however, the complete
list; the build-time configuration in <em class="filename">Local/Makefile</em> has an option called
FIXED_NEVER_USERS specifying a list that cannot be overridden. The
contents of <span><strong class="option">never_users</strong></span> are added to this list. By default
FIXED_NEVER_USERS also specifies root.
</p>
<p>
When a remote host connects to Exim in order to send mail, the only information
Exim has about the host’s identity is its IP address. The next configuration
line,
</p>
<pre class="literallayout">host_lookup = *
</pre><p>
specifies that Exim should do a reverse DNS lookup on all incoming connections,
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 “<span class="quote">nearby</span>” networks.
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.
</p>
<p>
The next two lines are concerned with <span class="emphasis"><em>ident</em></span> callbacks, as defined by RFC
1413 (hence their names):
</p>
<pre class="literallayout">rfc1413_hosts = *
rfc1413_query_timeout = 5s
</pre><p>
These settings cause Exim to make ident callbacks for all incoming SMTP calls.
You can limit the hosts to which these calls are made, or change the timeout
that is used. If you set the timeout to zero, all ident calls are disabled.
Although they are cheap and can provide useful information for tracing problem
messages, some hosts and firewalls have problems with ident calls. This can
result in a timeout instead of an immediate refused connection, leading to
delays on starting up an incoming SMTP session.
</p>
<p>
When Exim receives messages over SMTP connections, it expects all addresses to
be fully qualified with a domain, as required by the SMTP definition. However,
if you are running a server to which simple clients submit messages, you may
find that they send unqualified addresses. The two commented-out options:
</p>
<pre class="literallayout"># sender_unqualified_hosts =
# recipient_unqualified_hosts =
</pre><p>
show how you can specify hosts that are permitted to send unqualified sender
and recipient addresses, respectively.
</p>
<p>
The <span><strong class="option">percent_hack_domains</strong></span> option is also commented out:
</p>
<pre class="literallayout"># percent_hack_domains =
</pre><p>
It provides a list of domains for which the “<span class="quote">percent hack</span>” is to operate.
This is an almost obsolete form of explicit email routing. If you do not know
anything about it, you can safely ignore this topic.
</p>
<p>
The last two settings in the main part of the default configuration are
concerned with messages that have been “<span class="quote">frozen</span>” on Exim’s queue. When a
message is frozen, Exim no longer continues to try to deliver it. Freezing
occurs when a bounce message encounters a permanent failure because the sender
address of the original message that caused the bounce is invalid, so the
bounce cannot be delivered. This is probably the most common case, but there
are also other conditions that cause freezing, and frozen messages are not
always bounce messages.
</p>
<pre class="literallayout">ignore_bounce_errors_after = 2d
timeout_frozen_after = 7d
</pre><p>
The first of these options specifies that failing bounce messages are to be
discarded after 2 days on the queue. The second specifies that any frozen
message (whether a bounce message or not) is to be timed out (and discarded)
after a week. In this configuration, the first setting ensures that no failing
bounce message ever lasts a week.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0081" id="SECID54">7.2 ACL configuration</a></h3></div>
</div>
</div>
<p>
<a id="id493062" class="indexterm"></a>
<a id="id493076" class="indexterm"></a>
In the default configuration, the ACL section follows the main configuration.
It starts with the line
</p>
<pre class="literallayout">begin acl
</pre><p>
and it contains the definitions of two ACLs, called <span class="emphasis"><em>acl_check_rcpt</em></span> and
<span class="emphasis"><em>acl_check_data</em></span>, that were referenced in the settings of <span><strong class="option">acl_smtp_rcpt</strong></span>
and <span><strong class="option">acl_smtp_data</strong></span> above.
</p>
<p>
<a id="id493124" class="indexterm"></a>
The first ACL is used for every RCPT command in an incoming SMTP message. Each
RCPT command specifies one of the message’s recipients. The ACL statements
are considered in order, until the recipient address is either accepted or
rejected. The RCPT command is then accepted or rejected, according to the
result of the ACL processing.
</p>
<pre class="literallayout">acl_check_rcpt:
</pre><p>
This line, consisting of a name terminated by a colon, marks the start of the
ACL, and names it.
</p>
<pre class="literallayout">accept hosts = :
</pre><p>
This ACL statement accepts the recipient if the sending host matches the list.
But what does that strange list mean? It doesn’t actually contain any host
names or IP addresses. The presence of the colon puts an empty item in the
list; Exim matches this only if the incoming message did not come from a remote
host, because in that case, the remote hostname is empty. The colon is
important. Without it, the list itself is empty, and can never match anything.
</p>
<p>
What this statement is doing is to accept unconditionally all recipients in
messages that are submitted by SMTP from local processes using the standard
input and output (that is, not using TCP/IP). A number of MUAs operate in this
manner.
</p>
<pre class="literallayout">deny message = Restricted characters in address
domains = +local_domains
local_parts = ^[.] : ^.*[@%!/|]
deny message = Restricted characters in address
domains = !+local_domains
local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
</pre><p>
These statements are concerned with local parts that contain any of the
characters “<span class="quote">@</span>”, “<span class="quote">%</span>”, “<span class="quote">!</span>”, “<span class="quote">/</span>”, “<span class="quote">|</span>”, or dots in unusual places.
Although these characters are entirely legal in local parts (in the case of
“<span class="quote">@</span>” and leading dots, only if correctly quoted), they do not commonly occur
in Internet mail addresses.
</p>
<p>
The first three have in the past been associated with explicitly routed
addresses (percent is still sometimes used – see the <span><strong class="option">percent_hack_domains</strong></span>
option). Addresses containing these characters are regularly tried by spammers
in an attempt to bypass relaying restrictions, and also by open relay testing
programs. Unless you really need them it is safest to reject these characters
at this early stage. This configuration is heavy-handed in rejecting these
characters for all messages it accepts from remote hosts. This is a deliberate
policy of being as safe as possible.
</p>
<p>
The first rule above is stricter, and is applied to messages that are addressed
to one of the local domains handled by this host. This is implemented by the
first condition, which restricts it to domains that are listed in the
<span class="emphasis"><em>local_domains</em></span> domain list. The “<span class="quote">+</span>” character is used to indicate a
reference to a named list. In this configuration, there is just one domain in
<span class="emphasis"><em>local_domains</em></span>, but in general there may be many.
</p>
<p>
The second condition on the first statement uses two regular expressions to
block local parts that begin with a dot or contain “<span class="quote">@</span>”, “<span class="quote">%</span>”, “<span class="quote">!</span>”, “<span class="quote">/</span>”,
or “<span class="quote">|</span>”. If you have local accounts that include these characters, you will
have to modify this rule.
</p>
<p>
Empty components (two dots in a row) are not valid in RFC 2822, but Exim
allows them because they have been encountered in practice. (Consider the
common convention of local parts constructed as
“<span class="quote"><span class="emphasis"><em>first-initial.second-initial.family-name</em></span></span>” when applied to someone like
the author of Exim, who has no second initial.) However, a local part starting
with a dot or containing “<span class="quote">/../</span>” can cause trouble if it is used as part of a
file name (for example, for a mailing list). This is also true for local parts
that contain slashes. A pipe symbol can also be troublesome if the local part
is incorporated unthinkingly into a shell command line.
</p>
<p>
The second rule above applies to all other domains, and is less strict. This
allows your own users to send outgoing messages to sites that use slashes
and vertical bars in their local parts. It blocks local parts that begin
with a dot, slash, or vertical bar, but allows these characters within the
local part. However, the sequence “<span class="quote">/../</span>” is barred. The use of “<span class="quote">@</span>”, “<span class="quote">%</span>”,
and “<span class="quote">!</span>” is blocked, as before. The motivation here is to prevent your users
(or your users’ viruses) from mounting certain kinds of attack on remote sites.
</p>
<pre class="literallayout">accept local_parts = postmaster
domains = +local_domains
</pre><p>
This statement, which has two conditions, accepts an incoming address if the
local part is <span class="emphasis"><em>postmaster</em></span> and the domain is one of those listed in the
<span class="emphasis"><em>local_domains</em></span> domain list. The “<span class="quote">+</span>” character is used to indicate a
reference to a named list. In this configuration, there is just one domain in
<span class="emphasis"><em>local_domains</em></span>, but in general there may be many.
</p>
<p>
The presence of this statement means that mail to postmaster is never blocked
by any of the subsequent tests. This can be helpful while sorting out problems
in cases where the subsequent tests are incorrectly denying access.
</p>
<pre class="literallayout">require verify = sender
</pre><p>
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 message could be delivered to it. In the case of remote
addresses, basic verification checks only the domain, but <span class="emphasis"><em>callouts</em></span> can be
used for more verification if required. Section <a href="ch40.html#SECTaddressverification" title="40.40 Address verification">40.40</a>
discusses the details of address verification.
</p>
<pre class="literallayout">accept hosts = +relay_from_hosts
control = submission
</pre><p>
This statement accepts the address if the message is coming from one of the
hosts that are defined as being allowed to relay through this host. Recipient
verification is omitted here, because in many cases the clients are dumb MUAs
that do not cope well with SMTP error responses. For the same reason, the
second line specifies “<span class="quote">submission mode</span>” for messages that are accepted. This
is described in detail in section <a href="ch44.html#SECTsubmodnon" title="44.1 Submission mode for non-local messages">44.1</a>; it causes Exim to fix
messages that are deficient in some way, for example, because they lack a
<span class="emphasis"><em>Date:</em></span> header line. If you are actually relaying out from MTAs, you should
probably add recipient verification here, and disable submission mode.
</p>
<pre class="literallayout">accept authenticated = *
control = submission
</pre><p>
This statement accepts the address if the client host has authenticated itself.
Submission mode is again specified, on the grounds that such messages are most
likely to come from MUAs. The default configuration does not define any
authenticators, though it does include some nearly complete commented-out
examples described in <a href="ch07.html#SECTdefconfauth" title="7.7 Authenticators configuration">7.7</a>. This means that no client can in
fact authenticate until you complete the authenticator definitions.
</p>
<pre class="literallayout">require message = relay not permitted
domains = +local_domains : +relay_domains
</pre><p>
This statement rejects the address if its domain is neither a local domain nor
one of the domains for which this host is a relay.
</p>
<pre class="literallayout">require verify = recipient
</pre><p>
This statement requires the recipient address to be verified; if verification
fails, the address is rejected.
</p>
<pre class="literallayout"># deny message = rejected because $sender_host_address \
# is in a black list at $dnslist_domain\n\
# $dnslist_text
# dnslists = black.list.example
#
# warn dnslists = black.list.example
# add_header = X-Warning: $sender_host_address is in \
# a black list at $dnslist_domain
# log_message = found in $dnslist_domain
</pre><p>
These commented-out lines are examples of how you could configure Exim to check
sending hosts against a DNS black list. The first statement rejects messages
from blacklisted hosts, whereas the second just inserts a warning header
line.
</p>
<pre class="literallayout"># require verify = csa
</pre><p>
This commented-out line is an example of how you could turn on client SMTP
authorization (CSA) checking. Such checks do DNS lookups for special SRV
records.
</p>
<pre class="literallayout">accept
</pre><p>
The final statement in the first ACL unconditionally accepts any recipient
address that has successfully passed all the previous tests.
</p>
<pre class="literallayout">acl_check_data:
</pre><p>
This line marks the start of the second ACL, and names it. Most of the contents
of this ACL are commented out:
</p>
<pre class="literallayout"># deny malware = *
# message = This message contains a virus \
# ($malware_name).
</pre><p>
These lines are examples of how to arrange for messages to be scanned for
viruses when Exim has been compiled with the content-scanning extension, and a
suitable virus scanner is installed. If the message is found to contain a
virus, it is rejected with the given custom error message.
</p>
<pre class="literallayout"># warn spam = nobody
# message = X-Spam_score: $spam_score\n\
# X-Spam_score_int: $spam_score_int\n\
# X-Spam_bar: $spam_bar\n\
# X-Spam_report: $spam_report
</pre><p>
These lines are an example of how to arrange for messages to be scanned by
SpamAssassin when Exim has been compiled with the content-scanning extension,
and SpamAssassin has been installed. The SpamAssassin check is run with
<code class="literal">nobody</code> as its user parameter, and the results are added to the message as a
series of extra header line. In this case, the message is not rejected,
whatever the spam score.
</p>
<pre class="literallayout">accept
</pre><p>
This final line in the DATA ACL accepts the message unconditionally.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0082" id="SECID55">7.3 Router configuration</a></h3></div>
</div>
</div>
<p>
<a id="id493608" class="indexterm"></a>
<a id="id493622" class="indexterm"></a>
The router configuration comes next in the default configuration, introduced
by the line
</p>
<pre class="literallayout">begin routers
</pre><p>
Routers are the modules in Exim that make decisions about where to send
messages. An address is passed to each router in turn, until it is either
accepted, or failed. This means that the order in which you define the routers
matters. Each router is fully described in its own chapter later in this
manual. Here we give only brief overviews.
</p>
<pre class="literallayout"># domain_literal:
# driver = ipliteral
# domains = !+local_domains
# transport = remote_smtp
</pre><p>
<a id="id493667" class="indexterm"></a>
This router is commented out because the majority of sites do not want to
support domain literal addresses (those of the form <span class="emphasis"><em>user@[10.9.8.7]</em></span>). If
you uncomment this router, you also need to uncomment the setting of
<span><strong class="option">allow_domain_literals</strong></span> in the main part of the configuration.
</p>
<pre class="literallayout">dnslookup:
driver = dnslookup
domains = ! +local_domains
transport = remote_smtp
ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
no_more
</pre><p>
The first uncommented router handles addresses that do not involve any local
domains. This is specified by the line
</p>
<pre class="literallayout">domains = ! +local_domains
</pre><p>
The <span><strong class="option">domains</strong></span> option lists the domains to which this router applies, but the
exclamation mark is a negation sign, so the router is used only for domains
that are not in the domain list called <span class="emphasis"><em>local_domains</em></span> (which was defined at
the start of the configuration). The plus sign before <span class="emphasis"><em>local_domains</em></span>
indicates that it is referring to a named list. Addresses in other domains are
passed on to the following routers.
</p>
<p>
The name of the router driver is <span><strong class="command">dnslookup</strong></span>,
and is specified by the <span><strong class="option">driver</strong></span> 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 <span><strong class="option">driver</strong></span> option must be
one of the driver modules that is in the Exim binary.
</p>
<p>
The <span><strong class="command">dnslookup</strong></span> router routes addresses by looking up their domains in the
DNS in order to obtain a list of hosts to which the address is routed. If the
router succeeds, the address is queued for the <span><strong class="command">remote_smtp</strong></span> transport, as
specified by the <span><strong class="option">transport</strong></span> option. If the router does not find the domain
in the DNS, no further routers are tried because of the <span><strong class="option">no_more</strong></span> setting, so
the address fails and is bounced.
</p>
<p>
The <span><strong class="option">ignore_target_hosts</strong></span> 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
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
continue to try to deliver the message periodically until the address timed
out.
</p>
<pre class="literallayout">system_aliases:
driver = redirect
allow_fail
allow_defer
data = ${lookup{$local_part}lsearch{/etc/aliases}}
# user = exim
file_transport = address_file
pipe_transport = address_pipe
</pre><p>
Control reaches this and subsequent routers only for addresses in the local
domains. This router checks to see whether the local part is defined as an
alias in the <em class="filename">/etc/aliases</em> file, and if so, redirects it according to the
data that it looks up from that file. If no data is found for the local part,
the value of the <span><strong class="option">data</strong></span> option is empty, causing the address to be passed to
the next router.
</p>
<p>
<em class="filename">/etc/aliases</em> 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
<em class="filename">Local/Makefile</em> before building Exim.
</p>
<pre class="literallayout">userforward:
driver = redirect
check_local_user
# local_part_suffix = +* : -*
# local_part_suffix_optional
file = $home/.forward
# allow_filter
no_verify
no_expn
check_ancestor
file_transport = address_file
pipe_transport = address_pipe
reply_transport = address_reply
</pre><p>
This is the most complicated router in the default configuration. It is another
redirection router, but this time it is looking for forwarding data set up by
individual users. The <span><strong class="option">check_local_user</strong></span> setting specifies a check that the
local part of the address is the login name of a local user. If it is not, the
router is skipped. The two commented options that follow <span><strong class="option">check_local_user</strong></span>,
namely:
</p>
<pre class="literallayout"># local_part_suffix = +* : -*
# local_part_suffix_optional
</pre><p>
<a id="id493883" class="indexterm"></a>
show how you can specify the recognition of local part suffixes. If the first
is uncommented, a suffix beginning with either a plus or a minus sign, followed
by any sequence of characters, is removed from the local part and placed in the
variable <em class="varname">$local_part_suffix</em>. The second suffix option specifies that the
presence of a suffix in the local part is optional. When a suffix is present,
the check for a local login uses the local part with the suffix removed.
</p>
<p>
When a local user account is found, the file called <em class="filename">.forward</em> in the user’s
home directory is consulted. If it does not exist, or is empty, the router
declines. Otherwise, the contents of <em class="filename">.forward</em> are interpreted as
redirection data (see chapter <a href="ch22.html" title="22. The redirect router">22</a> for more details).
</p>
<p>
<a id="id493938" class="indexterm"></a>
Traditional <em class="filename">.forward</em> files contain just a list of addresses, pipes, or
files. Exim supports this by default. However, if <span><strong class="option">allow_filter</strong></span> is set (it
is commented out by default), the contents of the file are interpreted as a set
of Exim or Sieve filtering instructions, provided the file begins with “<span class="quote">#Exim
filter</span>” or “<span class="quote">#Sieve filter</span>”, respectively. User filtering is discussed in the
separate document entitled <span class="emphasis"><em>Exim’s interfaces to mail filtering</em></span>.
</p>
<p>
The <span><strong class="option">no_verify</strong></span> and <span><strong class="option">no_expn</strong></span> options mean that this router is skipped when
verifying addresses, or when running as a consequence of an SMTP EXPN command.
There are two reasons for doing this:
</p>
<div class="orderedlist">
<ol type="1"><li><p>
Whether or not a local user has a <em class="filename">.forward</em> file is not really relevant when
checking an address for validity; it makes sense not to waste resources doing
unnecessary work.
</p>
</li><li><p>
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’ <em class="filename">.forward</em> files at
this time.
</p>
</li></ol></div>
<p>
The setting of <span><strong class="option">check_ancestor</strong></span> prevents the router from generating a new
address that is the same as any previous address that was redirected. (This
works round a problem concerning a bad interaction between aliasing and
forwarding – see section <a href="ch22.html#SECTredlocmai" title="22.5 Redirecting to a local mailbox">22.5</a>).
</p>
<p>
The final three option settings specify the transports that are to be used when
forwarding generates a direct delivery to a file, or to a pipe, or sets up an
auto-reply, respectively. For example, if a <em class="filename">.forward</em> file contains
</p>
<pre class="literallayout">a.nother@elsewhere.example, /home/spqr/archive
</pre><p>
the delivery to <em class="filename">/home/spqr/archive</em> is done by running the <span><strong class="option">address_file</strong></span>
transport.
</p>
<pre class="literallayout">localuser:
driver = accept
check_local_user
# local_part_suffix = +* : -*
# local_part_suffix_optional
transport = local_delivery
</pre><p>
The final router sets up delivery into local mailboxes, provided that the local
part is the name of a local login, by accepting the address and assigning it to
the <span><strong class="command">local_delivery</strong></span> transport. Otherwise, we have reached the end of the
routers, so the address is bounced. The commented suffix settings fulfil the
same purpose as they do for the <span><strong class="command">userforward</strong></span> router.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0083" id="SECID56">7.4 Transport configuration</a></h3></div>
</div>
</div>
<p>
<a id="id494126" class="indexterm"></a>
<a id="id494140" class="indexterm"></a>
Transports define mechanisms for actually delivering messages. They operate
only when referenced from routers, so the order in which they are defined does
not matter. The transports section of the configuration starts with
</p>
<pre class="literallayout">begin transports
</pre><p>
One remote transport and four local transports are defined.
</p>
<pre class="literallayout">remote_smtp:
driver = smtp
</pre><p>
This transport is used for delivering messages over SMTP connections. All its
options are defaulted. The list of remote hosts comes from the router.
</p>
<pre class="literallayout">local_delivery:
driver = appendfile
file = /var/mail/$local_part
delivery_date_add
envelope_to_add
return_path_add
# group = mail
# mode = 0660
</pre><p>
This <span><strong class="command">appendfile</strong></span> transport is used for local delivery to user mailboxes in
traditional BSD mailbox format. By default it runs under the uid and gid of the
local user, which requires the sticky bit to be set on the <em class="filename">/var/mail</em>
directory. Some systems use the alternative approach of running mail deliveries
under a particular group instead of using the sticky bit. The commented options
show how this can be done.
</p>
<p>
Exim adds three headers to the message as it delivers it: <span class="emphasis"><em>Delivery-date:</em></span>,
<span class="emphasis"><em>Envelope-to:</em></span> and <span class="emphasis"><em>Return-path:</em></span>. This action is requested by the three
similarly-named options above.
</p>
<pre class="literallayout">address_pipe:
driver = pipe
return_output
</pre><p>
This transport is used for handling deliveries to pipes that are generated by
redirection (aliasing or users’ <em class="filename">.forward</em> files). The <span><strong class="option">return_output</strong></span>
option specifies that any output generated by the pipe is to be returned to the
sender.
</p>
<pre class="literallayout">address_file:
driver = appendfile
delivery_date_add
envelope_to_add
return_path_add
</pre><p>
This transport is used for handling deliveries to files that are generated by
redirection. The name of the file is not specified in this instance of
<span><strong class="command">appendfile</strong></span>, because it comes from the <span><strong class="command">redirect</strong></span> router.
</p>
<pre class="literallayout">address_reply:
driver = autoreply
</pre><p>
This transport is used for handling automatic replies generated by users’
filter files.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0084" id="SECID57">7.5 Default retry rule</a></h3></div>
</div>
</div>
<p>
<a id="id494314" class="indexterm"></a>
<a id="id494328" class="indexterm"></a>
The retry section of the configuration file contains rules which affect the way
Exim retries deliveries that cannot be completed at the first attempt. It is
introduced by the line
</p>
<pre class="literallayout">begin retry
</pre><p>
In the default configuration, there is just one rule, which applies to all
errors:
</p>
<pre class="literallayout">* * F,2h,15m; G,16h,1h,1.5; F,4d,6h
</pre><p>
This causes any temporarily failing address to be retried every 15 minutes for
2 hours, then at intervals starting at one hour and increasing by a factor of
1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address
is not delivered after 4 days of temporary failure, it is bounced.
</p>
<p>
If the retry section is removed from the configuration, or is empty (that is,
if no retry rules are defined), Exim will not retry deliveries. This turns
temporary errors into permanent errors.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0085" id="SECID58">7.6 Rewriting configuration</a></h3></div>
</div>
</div>
<p>
The rewriting section of the configuration, introduced by
</p>
<pre class="literallayout">begin rewrite
</pre><p>
contains rules for rewriting addresses in messages as they arrive. There are no
rewriting rules in the default configuration file.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0086" id="SECTdefconfauth">7.7 Authenticators configuration</a></h3></div>
</div>
</div>
<p>
<a id="id494423" class="indexterm"></a>
The authenticators section of the configuration, introduced by
</p>
<pre class="literallayout">begin authenticators
</pre><p>
defines mechanisms for the use of the SMTP AUTH command. The default
configuration file contains two commented-out example authenticators
which support plaintext username/password authentication using the
standard PLAIN mechanism and the traditional but non-standard LOGIN
mechanism, with Exim acting as the server. PLAIN and LOGIN are enough
to support most MUA software.
</p>
<p>
The example PLAIN authenticator looks like this:
</p>
<pre class="literallayout">#PLAIN:
# driver = plaintext
# server_set_id = $auth2
# server_prompts = :
# server_condition = Authentication is not yet configured
# server_advertise_condition = ${if def:tls_cipher }
</pre><p>
And the example LOGIN authenticator looks like this:
</p>
<pre class="literallayout">#LOGIN:
# driver = plaintext
# server_set_id = $auth1
# server_prompts = <| Username: | Password:
# server_condition = Authentication is not yet configured
# server_advertise_condition = ${if def:tls_cipher }
</pre><p>
The <span><strong class="option">server_set_id</strong></span> option makes Exim remember the authenticated username
in <em class="varname">$authenticated_id</em>, which can be used later in ACLs or routers. The
<span><strong class="option">server_prompts</strong></span> option configures the <span><strong class="command">plaintext</strong></span> authenticator so
that it implements the details of the specific authentication mechanism,
i.e. PLAIN or LOGIN. The <span><strong class="option">server_advertise_condition</strong></span> setting controls
when Exim offers authentication to clients; in the examples, this is only
when TLS or SSL has been started, so to enable the authenticators you also
need to add support for TLS as described in <a href="ch07.html#SECTdefconfmain" title="7.1 Main configuration settings">7.1</a>.
</p>
<p>
The <span><strong class="option">server_condition</strong></span> setting defines how to verify that the username and
password are correct. In the examples it just produces an error message.
To make the authenticators work, you can use a string expansion
expression like one of the examples in <a href="ch34.html" title="34. The plaintext authenticator">34</a>.
</p>
<p>
<a id="id494542" class="indexterm"></a>
</p>
</div>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch06.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</body></html>
