The default configuration file supplied with Exim as src/configure.default is sufficient for a host with simple mail requirements. As an introduction to the way Exim is configured, this chapter ``walks through'' 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.
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
# primary_hostname =
This is a commented-out setting of the primary_hostname 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 uname() system function to obtain the host name.
The first three non-comment configuration lines are as follows:
domainlist local_domains = @ domainlist relay_to_domains = hostlist relay_from_hosts = 127.0.0.1
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 10.5).
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. There is in fact 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 called a.host.example, mail to any.user@a.host.example 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.
The second line defines a domain list called relay_to_domains, 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.
The third line defines a host list called relay_from_hosts. 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.
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.
The next configuration line is a genuine option setting:
acl_smtp_rcpt = acl_check_rcpt
This option specifies an Access Control List (ACL) which is to be used during an incoming SMTP session for every recipient of a message. 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 configuration does not provide an ACL to check recipients, no SMTP mail can be accepted.
Two commented-out options settings are next:
# qualify_domain = # qualify_recipient =
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 qualify_domain, the value of primary_hostname 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, it is used in both cases.
The following line must be uncommented if you want Exim to recognize addresses of the form user@[10.11.12.13] that is, with a ``domain literal'' (an IP address) instead of a named domain.
# allow_domain_literals
The RFCs still require this form, but it makes little sense to permit mail to be sent to specific hosts by their IP address in the modern Internet. This ancient format has been used by those seeking to abuse hosts by using them for unwanted relaying.
The next configuration line is a kind of trigger guard:
never_users = root
It specifies that no local delivery must ever be run as the root user. The normal convention is to set up root as an alias for the system administrator. This setting is a guard against slips in the configuration.
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,
host_lookup = *
specifies that Exim should do a reverse DNS lookup on all incoming connections, in order to get the true 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.
The next two lines are concerned with ident callbacks, as defined by RFC 1413 (hence their names):
rfc1413_hosts = * rfc1413_query_timeout = 30s
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 them. This can result in a timeout instead of an immediate refused connection, leading to delays on starting up an incoming SMTP session.
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:
# sender_unqualified_hosts = # recipient_unqualified_hosts =
show how you can specify hosts that are permitted to send unqualified sender and recipient addresses, respectively.
The percent_hack_domains option is also commented out:
# percent_hack_domains =
It provides a list of domains for which the ``percent hack'' 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.
The last two settings in the main part of the default configuration are concerned with messages that have been ``frozen'' 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.
ignore_bounce_errors_after = 2d timeout_frozen_after = 7d
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.
In the default configuration, the ACL section follows the main configuration. It starts with the line
begin acl
and it contains the definition of one ACL called acl_check_rcpt that was referenced in the setting of acl_smtp_rcpt above. This 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.
acl_check_rcpt:
This line, consisting of a name terminated by a colon, marks the start of the ACL, and names it.
accept hosts = :
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 didn't come from a remote host. The colon is important. Without it, the list itself is empty, and can never match anything.
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.
deny local_parts = ^.*[@%!/|]
This statement uses a regular expression to reject addresses with local parts that contain any of the characters ``@'', ``%'', ``!'', ``/'' or ``|''. Although these characters are entirely legal in local parts (in the case of ``@'' only if correctly quoted), they do not normally occur in Internet mail addresses.
The first three have in the past been associated with explicitly routed addresses (percent is still sometimes used - see the percent_hack_domains 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. Slash is included in the list to avoid problems in local parts that are used to construct file names. Vertical bar is included because of its use as a pipe symbol in shell commands.
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. By moving the test elsewhere in the ACL, you can relax the restriction so that, for example, it applies only to addresses in your local domains.
accept local_parts = postmaster domains = +local_domains
This statement, which has two conditions, accepts an incoming address if the local part is postmaster and the domain is one of those listed in the local_domains domain list. The ``+'' character is used to indicate a reference to a named list. In this configuration, there is just one domain in local_domains, but in general there may be many.
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.
require verify = sender
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 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 37.10 discusses the details of address verification.
# deny message = rejected because $sender_host_address is \ # in a black list at $dnslist_domain\n\ # $dnslist_text # dnslists = black.list.example # # warn message = X-Warning: $sender_host_address is \ # in a black list at $dnslist_domain # log_message = found in $dnslist_domain # dnslists = black.list.example
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 merely inserts a warning header line.
accept domains = +local_domains endpass message = unknown user verify = recipient
This statement accepts the incoming recipient address if its domain is one of the local domains, but only if the address can be verified. Verification of local addresses normally checks both the local part and the domain. The endpass line needs some explanation: if the condition above endpass fails, that is, if the address is not in a local domain, control is passed to the next ACL statement. However, if the condition below endpass fails, that is, if a recipient in a local domain cannot be verified, access is denied and the recipient is rejected. The message modifier provides a customized error message for the failure.
accept domains = +relay_to_domains endpass message = unrouteable address verify = recipient
This statement accepts the incoming recipient address if its domain is one of the domains for which this host is a relay, but again, only if the address can be verified.
accept hosts = +relay_from_hosts
Control reaches this statement only if the recipient's domain is neither a local domain, nor a relay domain. The 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. If you are actually relaying out from MTAs, you should probably add recipient verification here.
accept authenticated = *
Control reaches here for attempts to relay to arbitrary domains from arbitrary hosts. The statement accepts the address only if the client host has authenticated itself. The default configuration does not define any authenticators, which means that no client can in fact authenticate. You will need to add authenticator definitions if you want to make use of this ACL statement.
deny message = relay not permitted
The final statement denies access, giving a specific error message. Reaching the end of the ACL also causes access to be denied, but with the generic message ``administrative prohibition''.
The router configuration comes next in the default configuration, introduced by the line
begin routers
Routers are the configuration 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.
# domain_literal: # driver = ipliteral # transport = remote_smtp
This router is commented out because the vast majority of sites do not want to support domain literal addresses (those of the form user@[10.9.8.7]). If you uncomment this router, you will also need to uncomment the setting of allow_domain_literals in the main part of the configuration.
dnslookup: driver = dnslookup domains = ! +local_domains transport = remote_smtp ignore_target_hosts = 127.0.0.0/8 no_more
The first router handles addresses that do not involve any local domains. This is specified by the line
domains = ! +local_domains
The domains 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 local_domains (which was defined at the start of the configuration). The plus sign before local_domains indicates that it is referring to a named list. Addresses in other domains are passed on to the following routers.
The name of the router driver is dnslookup. This is a router which 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 remote_smtp transport, as specified by the transport option. If the router does not find the domain in the DNS, no further routers are tried because of the no_more setting, so the address fails and is bounced.
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 which have IP addresses in the 127 subnet (typically 127.0.0.1). Completely ignoring these addresses causes Exim to fail to route the 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.
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
Control reaches this (and subsequent routes) only for addresses in the local domains. This router checks to see whether the local part is defined as an alias in the /etc/aliases 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 data option is empty, causing the address to be passed to the next router.
userforward: driver = redirect check_local_user file = $home/.forward no_verify no_expn check_ancestor # allow_filter file_transport = address_file pipe_transport = address_pipe reply_transport = address_reply
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 check_local_user setting means that the first thing it does is to check that the local part of the address is the login name of a 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.
Traditional .forward files contain just a list of addresses, pipes, or files. Exim supports this by default. However, if allow_filter is set (it is commented out by default), the contents of the file are interpreted as a set of Exim filtering instructions, provided the file begins with ``#Exim filter''. User filtering is discussed in the separate document entitled Exim's interface to mail filtering.
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. The setting of check_ancestor 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 21.5).
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 .forward file contains
a.nother@elsewhere.example, /home/spqr/archive
the delivery to /home/spqr/archive is done by running the address_file transport.
localuser: driver = accept check_local_user transport = local_delivery
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 queuing it for the local_delivery transport. Otherwise, we have reached the end of the routers, so the address is bounced.
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
begin transports
One remote transport, and four local transports are defined.
remote_smtp: driver = smtp
This transport is used for delivering messages over SMTP connections. All its options are defaulted. The list of remote hosts comes from the router.
local_delivery: driver = appendfile file = /var/mail/$local_part delivery_date_add envelope_to_add return_path_add # group = mail # mode = 0660
This appendfile 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 /var/mail 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.
Exim adds three headers to the message as it delivers it: Delivery-date:, Envelope-to: and Return-path:. This action is requested by the three similarly-named options above.
address_pipe: driver = pipe return_output
This transport is used for handling deliveries to pipes that are generated by redirection (aliasing or users' .forward files). The return_output option specifies that any output generated by the pipe is to be returned to the sender.
address_file: driver = appendfile delivery_date_add envelope_to_add return_path_add
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 appendfile, because it comes from the redirect router.
address_reply: driver = autoreply
This transport is used for handling automatic replies generated by users' filter files.
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
begin retry
In the default configuration, there is just one rule, which applies to all errors:
* * F,2h,15m; G,16h,1h,1.5; F,4d,6h
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 failure, it is bounced.
The rewriting section of the configuration, introduced by
begin rewrite
contains rules for rewriting addresses in messages as they arrive. There are no rewriting rules in the default configuration file.
The authenticators section of the configuration, introduced by
begin authenticators
defines mechanisms for the use of the SMTP AUTH command. No authenticators are specified in the default configuration file.