Go to the first, previous, next, last section, table of contents.

Other policy controls on incoming mail

Exim provides a number of facilities for controlling incoming mail from remote hosts, in addition to the verification options described in the previous chapter. These controls can be used to stop unwanted messages getting into your machine. After a message has been accepted, the filtering mechanism described in chapter "System-wide message filtering" can be used to check it before going ahead with delivery.

An MTA is said to relay a message if it receives it from some host and delivers it directly to another host as a result of a remote address contained within it. Expanding a local address via an alias or forward file and then passing the message on to a remote host does not count as relaying. There are special options for controlling which remote hosts may use the local host as a relay.

The options described in this chapter control three stages of checking that are applied to an incoming SMTP message:

  1. At the start of an SMTP connection, a check on the remote host is made, leading to one of the following conclusions:
    1. No mail whatsoever is acceptable from the remote host.
    2. The remote host is permitted to send messages to local recipients only, but is not permitted to use the local host as a relay.
    3. The remote host is permitted to send messages to local recipients, and can also use the local host as a relay to certain specified domains only.
    4. The remote host is permitted to send mail to any recipient.
    If the host is completely unacceptable, the SMTP connection may be rejected immediately, or (depending on the configuration) the message may be refused later on by a rejection at the end of the message (so the headers can be logged) or by rejecting every recipient.
  2. The message's sender, which is obtained from the MAIL FROM command, is checked. Again there is a choice of immediate rejection, or delayed rejection of all recipients.
  3. Unless there are no controls on relaying, the recipient address in each RCPT TO command is checked.

These checks are all in addition to any verification that may be enabled. The following sections give details of the various checking options. The `-bh' command line option can be used to run fake SMTP sessions for the purpose of testing them.

Host checking using RBL

The Realtime Blocking List (RBL) is a blacklist of hosts that is maintained in the DNS. See `http://maps.vix.com/rbl/' for the background to this. If the `rbl_domains' option is set, Exim looks up inverted incoming IP addresses in each of the given domains. For example, if the setting is

rbl_domains = rbl.maps.vix.com:local.rbl.xxx.yyy

and an SMTP call is received from the host whose IP address is, then DNS lookups for address records for

are done. If an RBL lookup succeeds, the message is rejected by refusing all recipients, that is, by giving permanent error returns to all RCPT TO commands, except for any recipients that are listed in `recipients_reject_except'. It is fairly common to set

recipients_reject_except = postmaster@your.domain

to allow your host to accept mail to the postmaster from blacklisted hosts. When a message is to be rejected, a TXT record is looked up in the DNS, and if it exists, its contents are returned as part of the 550 rejection message. If a lookup times out or otherwise fails to give a decisive answer, the mail is not blocked.

Networks and individual hosts can be excepted from RBL checking by setting `rbl_except_nets' to match them.

If `rbl_reject_recipients' is turned off, then any hosts that are found by searching `rbl_domains' are just logged rather than causing the message's recipients to be rejected.

If `rbl_warn_header' is true (the default) and `rbl_reject_recipients' is false, an `X-RBL-Warning:' header is added to the message, containing the RBL warning text. This can be detected later by the system-wide filter file, or in individual users' private filter files.

Other host checking

If `sender_host_accept' is set, Exim accepts mail only from a host (plus ident) that matches one of its entries; however, it rejects any call that matches `sender_host_reject', unless it also matches `sender_host_reject_except'. Thus `sender_host_reject' can be used to specify exclusions from a wildcarded item in `sender_host_accept', while `sender_host_reject_except' can similarly be used for exclusions from an item in `sender_host_reject'. For example:

sender_host_accept = *.zz
sender_host_reject = *.yy.zz
sender_host_reject_except = xx.yy.zz

rejects mail from any host outside the `zz' domain, and all hosts in the `yy.zz' domain, except for `xx.yy.zz'.

Calls are rejected as a result of these options by sending a 5xx error code as soon as the connection is received. Since this does not relate to any particular message, the remote host is likely to keep on trying to send mail (possibly to an alternative MX host) until it times out. This may be what is wanted in some circumstances (for example, you want temporarily to hold back all incoming mail from some host), but when dealing with incoming spam, for example, one normally wants messages to be rejected once and for all, and `sender_host_reject_recipients' should be used instead of `sender_host_reject'.

A call from a host which matches `sender_host_reject_recipients' is not rejected at the start; instead, every RCPT TO command is subsequently rejected, which should cause the remote MTA to cease trying to deliver the message. This style of blocking also has the advantage of catering for exceptions for certain recipients, via the `recipients_reject_except' option. This is commonly set to the local postmaster address.

The format of the the accept and reject options is a colon-separated list of host items, as described in section "Host lists" in chapter "The Exim configuration file", including RFC 1413 ident values associated with any of them. When an ident value is preceded by an exclamation mark, it matches any RFC 1413 identification other than the given one. For example,

sender_host_accept = root@hub.biog.book

accepts calls only from root on the host `hub.biog.book', while

sender_host_reject = !root@hub.biog.book

accepts calls from any host except those from `hub.biog.book' made by a non-root user. The host names in these entries can be wildcarded, or can be regular expressions. However, this flexibility is gained at the cost of performance, particularly when a daemon listener is used.

If a complete host name is given, it is looked up using `gethostbyname()' when the daemon starts up, and subsequently the checks can be performed using only the IP address. On the other hand, if a wildcarded name or regular expression is given, the check has to be performed by doing a reverse lookup on the IP address for each call, in order to get the host name to match against the wildcarded string. Therefore, it is best to avoid wildcards and regular expressions wherever possible, apart from the case of a single * character, which matches anything, and which is recognized specially.

If an attempt to look up the name of a host from its IP address fails because there is no PTR record in the DNS, Exim takes a hard line by default. If the option concerned is an `accept' option, it behaves as if the host is not in the list, and if the option is a `reject' option it behaves as if it is. This behaviour can be changed by including the item `+allow_unknown' in the list. If a lookup fails while checking any subsequent items in the list, access is permitted. Setting this does mean that attempts to block hosts using wildcard names can be subverted by removing PTR records from the DNS.

Network checking

For each of the options described in the previous section there is a corresponding option which defines a set of hosts by an IP network number and a mask. They are `sender_net_accept', `sender_net_reject', `sender_net_reject_except', and `sender_net_reject_recipients'.

Each entry in one of these lists consists of an IP network number and a mask, separated by a slash. For example:

sender_net_accept =
sender_net_reject =

accepts calls only from the network, unless the call is from the subnet. The host and net tests interact -- for example, a call from a network listed in `sender_net_accept' is rejected if the host appears in `sender_host_reject'.

Net lists cannot be converted into DBM or other key-oriented lookups as host lists can. However, a net list item can be the name of a file from which other items are read (see section "Net lists" in chapter "The Exim configuration file").

Sender checking

Incoming messages can be rejected on the basis of the sender address, as given in the MAIL FROM command. A list of senders to reject is set by the `sender_reject' configuration option; see its description in chapter "Main configuration" for details. There is also a `sender_accept' option for use in special cases, and a `sender_reject_except' option to list exceptions.

Some MTAs continue to try to deliver a message even after receiving a 5xx error code for MAIL FROM. The alternative configuration option `sender_reject_recipients' is provided for use in such cases. It accepts the MAIL FROM command but rejects all subsequent RCPT TO commands. There is also a corresponding `sender_accept_recipients' option.

Control of relaying

There are two aspects of control over relaying via the local host, which might be termed `incoming' and `outgoing'. A host which is acting as a gateway or an MX backup is concerned with incoming relaying from arbitrary hosts to a specific set of domains. A host which is acting as a smart host for a number of clients is concerned with outgoing relaying from those clients to the Internet at large. Often the same host is fulfilling both functions, as illustrated in the diagram below. What is not wanted is the transmission of mail from arbitrary remote hosts through your system to arbitrary domains.

   --------------    -----------
   | Arbitrary  |    |Arbitrary|
   |remote hosts|    | domains |
   --------------    -----------
         v                ^
         v                ^
      |  v      Your      ^  |
      |  v      host      ^  |
         v                ^
         v                ^
      Specific         Specific
      domains           hosts

Incoming relaying is controlled by restricting the domains to which an arbitrary host may send; outgoing relaying is controlled by restricting the hosts which may send to an arbitrary domain. If an arbitrary host can send via the local host to an arbitrary domain, it is open to abuse.

The relaying check happens whenever a message's recipient is received, that is, immediately after a RCPT TO command. The first check is whether the address would cause relaying at all: if its domain matches something in `local_domains' then it is destined to be handled on the local host as a local address, and relaying is not involved, unless the `percent hack' is in use. In this case, the local part is converted into a new address and that is then checked.

When the relevant domain is not in `local_domains', there is first a check for legitimate incoming relaying, by seeing if it matches `relay_domains', or, when `relay_domains_include_local_mx' is set, if it is a domain with an MX record pointing to the local host. If it does match, this is an acceptable incoming relay, and it is permitted to proceed.

For example, if the FooBar company has a firewall machine through which all mail from external hosts must pass, and this machine's configuration contains

local_domains = foobar.com
relay_domains = *.foobar.com

then mail from external hosts is rejected, unless it is for a domain ending in `foobar.com'.

If a recipient address is neither for a local domain nor an incoming relay, it must be an outgoing relay, and it is accepted only if the sending host is permitted to relay to arbitrary domains, and if the sender address is acceptable. The following options specify the set of hosts:



If the first four are unset then

When at least one of the host or net options (other than those ending in `_except') is set, the address is accepted only if `sender_host_accept_relay' and `sender_net_accept_relay' are both null or if the host matches one of their patterns, and if the host does not match any pattern in `sender_host_reject_relay' or `sender_net_reject_relay', unless it also matches `sender_host_reject_relay_except' or `sender_net_reject_relay_except'. Thus the `reject' options provide exception lists to the `accept' options, and the `except' options provide exception lists to the `reject' options.

For example, if the FooBar company's IP network is, and all hosts on that network send their outgoing mail via the firewall machine, then its configuration should contain

sender_net_accept_relay =

in order to allow only the internal hosts to use it as a relay to arbitrary domains.

In addition to the tests on the host, if `sender_address_relay' is set, the sender's address from the MAIL FROM command must match one of its patterns to allow outgoing relaying to an arbitrary domain. Also, if there are any rewriting rules with the `X' flag set, such an address is rewritten using those rules, and the result (if different) must verify successfully. See section "The additional relay checking flag" in chapter "Address rewriting" for an example of how this can be used.

By default, therefore, both the host and the sender must be acceptable before a relay is allowed to proceed. However, if `relay_match_host_or_sender' is set, an address is accepted for outgoing relaying if either the host or the sender is acceptable. Of course, sender addresses can easily be forged, but the sender check does mean you can prevent some kinds of unwanted mail from going through your host.

If you don't want to do any relaying at all, then `relay_domains' should be left unset, and `sender_host_reject_relay' set to *, in which case the only acceptable recipient addresses are those that contain a local domain. This is the setting in the default configuration file. It does not prevent a local user from setting up forwarding to some external system, but it does prevent the `percent hack' from working even when `percent_hack_domains' is set.

If you have a list of domains that any host can relay to, but there are no hosts or networks that are permitted to relay to arbitrary domains (for example, if your host is an MX backup for some domains), then set `relay_domains'. This implies

sender_host_reject_relay = *

if no host or net accept or reject options are set.

If the recipient address is an RFC 821 source routed address, that is, an address of the form `<@hop1,@hop2:user@domain>', it is the final domain which is tested. By default, however, Exim will send the message to the `hop1' domain, unless it is a local domain. The `collapse_source_routes' option can be used to prevent this.

As all the relay checking is done at RCPT TO time on incoming messages, the directors and routers are not involved. Depending on the configuration of these drivers, an address that appears to be remote to the relay checking code (that is, its domain does not match `local_domains') may nevertheless end up being delivered locally, and similarly an apparently local address may end up being delivered to some other host.

None of the relay checking applies when mail is passed to Exim locally using the `-bm', `-bs' or `-bS' options, but it does apply when `-bs' is used from `inetd'.

Exim does not attempt to fully qualify domains at RCPT TO time. If an incoming message contains a domain which is not fully qualified, it is treated as a non-local, non-relay domain (unless partial domains are included in `local_domains' or `relay_domains', but this is not recommended). The use of domains that are not fully qualified is non-standard, but it is a commonly encountered usage when an MTA is being used as a smart host by some remote UA. In this situation, it would be usual to permit the UA host to relay to any domain, so in practice there is not normally a problem.

Policy checking flowchart

The diagram below shows how the various policy checks are applied to an incoming message from a remote host. The normal flow of control is vertically down the left-hand set of boxes.

       -----------------  no
       | host accept?  |-----> reject
   yes -----------------
  -----|  host reject  |
  |    |    except?    |
  |    -----------------
  |            |
  |    -----------------   yes
  |    | host reject?  |----------> reject
  |    -----------------
  |            |
  |    -----------------   yes     -----------------
  |    |  host reject  |---------->| set HRR flag  |
  |    |  recipients?  |           |               |
  |    -----------------           -----------------
  |            |                           |
       -----------------   found   ----------------- yes  ----------------
       |  check RBL    |---------->|  RBL reject?  |----->| set HRR flag |
       -----------------           -----------------      ----------------
               |                           |                     |
               |                   -----------------             |
               |<------------------|  add header   |             |
               |                   -----------------             |
  HELO----     |                                                 |
         |     |<-------------------------------------------------
         V     |
       ----------------- fail
       |  verify HELO  |-----> reject
  MAIL         |
  FROM----     |
         |     |
         V     |
   yes -----------------
  -----| HRR flag set? |
  |    -----------------
  |            |
  |    -----------------  no
  |    |sender accept? |-----> reject
  |    -----------------
  |            |
  |    -----------------  yes      -----------------  no
  |    |sender reject? |---------->| sender reject |-----> reject
  |    |               |           |    except?    |
  |    -----------------           -----------------
  |            |                           |
  |            |<---------------------------
  |            |
  |    -----------------  no       -----------------
  |    | sender accept |---------->|  set SRR flag |
  |    |  recipients?  |           |               |
  |    -----------------           -----------------
  |            |                           |
  |            |<---------------------------
  |            |
  |    -----------------  yes      -----------------      ----------------
  |    | sender reject |---------->| sender reject | no   |              |
  |    |  recipients?  |           |  recipients   |----->| set SRR flag |
  |    |               |           |    except?    |      |              |
  |    -----------------           -----------------      ----------------
  |            |                           |                     |
       | verify sender |
  RCPT         |
    TO----     |
         |     |
         V     |
       -----------------  yes      -----------------  no
       |HRR or SRR set?|---------->|  recipients   |-----> reject
       |               |           |reject except? |
       -----------------           -----------------
               |                           |
   yes -----------------
  -----|   local or    |
  |    | relay domain? |
  |    -----------------
  |            |
  |    -----------------  no
  |    |  host accept  |------------------------------------------
  |    |    relay?     |                                         |
  |    -----------------                                         |
  |            |                                                 |
  |    -----------------  yes      ----------------- no   ----------------
  |    |  host reject  |---------->|  host reject  |----->| set HFR flag |
  |    |    relay?     |           | relay except? |      |              |
  |    -----------------           -----------------      ----------------
  |            |                           |                     |
  |            |<-------------------------------------------------
  |            |
  |    -----------------  no       -----------------
  |    |sender address |---------->|  set SFR flag |
  |    |    relay?     |           |               |
  |    -----------------           -----------------
  |            |                           |
  |            |<---------------------------
  |            |
  |    -----------------  yes      -----------------  no
  |    |relay need host|---------->|  HFR and SFR  |----------------
  |    |  or sender?   |           |   both set?   |               |
  |    -----------------           -----------------               |
  |            |                           |                       |
  |    -----------------  yes              |                       |
  |    |   SFR set?    |------> reject     |                       |
  |    -----------------                   |                       |
  |            |                           |                       |
  |    -----------------  yes      -----------------  no           |
  |    |   HFR set?    |---------->| relay domains |-----> reject  |
  |    |               |           |include lcl MX?|               |
  |    -----------------           -----------------               |
  |            |                           |                       |
  |            |                   -----------------  no           |
  |            |                   | exists MX to  |-----> reject  |
  ------------>|                   |  local host?  |               |
               |                   -----------------               |
               |                           |                       |
       |    verify     |
       |  recipient    |

The various tests are abbreviated to the names of their options, but if the option is not set, the test is skipped. Wherever `host' is used, the implication is that both host and network checking takes place. For example `host accept?' means `check that the current host matches either `sender_host_accept' or `sender_net_accept''.

If verification of a sender fails, rejection may be immediate, or it may follow later after the RCPT TO command or after the data has been received (see section "Sender verification" in chapter "Verification of incoming mail"). If recipient verification fails, rejection is immediate.

Prohibition messages

It is possible to add a site-specific message to the error response that is sent when an incoming SMTP command fails for policy reasons, for example if the sending host is in a host reject list. This is done by setting the option `prohibition_message', which causes one or more additional response lines with the same error code and a multiline marker to be output before the standard response line. For example, setting

prohibition_message = "contact postmaster@my.site for details"

causes the response to a RCPT TO command for a blocked recipient to be

550-contact postmaster@my.site for details
550 rejected: administrative prohibition

The string is expanded, and so it can do file lookups if necessary. If it ends up as an empty string, no additional response is transmitted. To make it possible to distinguish between the several different types of administrative rejection, the variable `$prohibition_reason' is set to a characteristic text string in each case. The possibilities are as follows:

host_reject                the host is in a reject list
host_accept                the host is not in an accept list
host_reject_recipients     the host is in a `reject_recipients' list
host_accept_recipients     the host is not in an `accept_recipients' list
host_reject_relay          the host is in a `reject_relay' list

host_accept_relay          the host is not in an `accept_relay' list

sender_reject              the sender is in a reject list

sender_reject_recipients   the sender is in a `reject_recipients' list

sender_accept              the sender is not in an accept list
sender_verify              sender verification failed
sender_relay               the sender is not in a sender relay list

In addition, if `relay_match_host_or_sender' is set, there are

sender+host_reject_relay  the sender is not in a sender relay list
                            and the host is in a reject relay list
sender+host_accept_relay  the sender is not in a sender relay list
                            and the host is not in an accept relay list

For example, if the configuration contains

prohibition_message = "${lookup{$prohibition_reason}lsearch\

and the file `/etc/exim/reject.messages' contains (inter alia)

host_accept_relay:  host not in relay list

then a response to a relay attempt might be

550-host not in relay list
550 relaying to <santa@northpole.com> prohibited by administrator

Because some administrators may want to put in quite long messages, and it isn't possible to get newlines into the text returned from an lsearch lookup, Exim treats the vertical bar character as a line separator in this text. If you want the looked up text to be re-expanded, you can use the `expand' operator. For example, the setting

prohibition_message = "${lookup{$prohibition_reason}lsearch\

when used with a file entry of the form

host_accept_relay:  Host $sender_fullhost is not permitted to
                    relay |through $primary_hostname.

might produce

550-Host that.host.name [] is not permitted to relay
550-through this.host.name.
550 relaying to <penguins@southpole.com> prohibited by administrator

This facility does not apply when the prohibition is due to an entry in a Realtime Blocking List and a message is available from a DNS TXT record. In that circumstance, the TXT message is used instead.

Go to the first, previous, next, last section, table of contents.