The -bh command line option provides a way of testing your ACL configuration locally by running a fake SMTP session with which you interact. The host relay-test.mail-abuse.org provides a service for checking your relaying configuration (see section 40.49 for more details).

In order to cause an ACL to be used, you have to name it in one of the relevant options in the main part of the configuration. These options are:

For example, if you set

acl_smtp_rcpt = small_acl

the little ACL defined above is used whenever Exim receives a RCPT command in an SMTP dialogue. The majority of policy tests on incoming messages can be done when RCPT commands arrive. A rejection of RCPT should cause the sending MTA to give up on the recipient address contained in the RCPT command, whereas rejection at other times may cause the client MTA to keep on trying to deliver the message. It is therefore recommended that you do as much testing as possible at RCPT time.

The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not really SMTP.) Many of the ACL conditions (for example, host tests, and tests on the state of the SMTP connection such as encryption and authentication) are not relevant and are forbidden in these ACLs. However, the sender and recipients are known, so the senders and sender_domains conditions and the $sender_address and $recipients variables can be used. Variables such as $authenticated_sender are also available. You can specify added header lines in any of these ACLs.

The acl_not_smtp_start ACL is run right at the start of receiving a non-SMTP message, before any of the message has been read. (This is the analogue of the acl_smtp_predata ACL for SMTP input.) In the case of batched SMTP input, it runs after the DATA command has been reached. The result of this ACL is ignored; it cannot be used to reject a message. If you really need to, you could set a value in an ACL variable here and reject based on that in the acl_not_smtp ACL. However, this ACL can be used to set controls, and in particular, it can be used to set

control = suppress_local_fixups

This cannot be used in the other non-SMTP ACLs because by the time they are run, it is too late.

The acl_not_smtp_mime ACL is available only when Exim is compiled with the content-scanning extension. For details, see chapter 41.

The acl_not_smtp ACL is run just before the local_scan() function. Any kind of rejection is treated as permanent, because there is no way of sending a temporary error for these kinds of message.

The ACL test specified by acl_smtp_connect happens at the start of an SMTP session, after the test specified by host_reject_connection (which is now an anomaly) and any TCP Wrappers testing (if configured). If the connection is accepted by an accept verb that has a message modifier, the contents of the message override the banner message that is otherwise specified by the smtp_banner option.

The ACL test specified by acl_smtp_helo happens when the client issues an EHLO or HELO command, after the tests specified by helo_accept_junk_hosts, helo_allow_chars, helo_verify_hosts, and helo_try_verify_hosts. Note that a client may issue more than one EHLO or HELO command in an SMTP session, and indeed is required to issue a new EHLO or HELO after successfully setting up encryption following a STARTTLS command.

If the command is accepted by an accept verb that has a message modifier, the message may not contain more than one line (it will be truncated at the first newline and a panic logged if it does). Such a message cannot affect the EHLO options that are listed on the second and subsequent lines of an EHLO response.

Two ACLs are associated with the DATA command, because it is two-stage command, with two responses being sent to the client. When the DATA command is received, the ACL defined by acl_smtp_predata is obeyed. This gives you control after all the RCPT commands, but before the message itself is received. It offers the opportunity to give a negative response to the DATA command before the data is transmitted. Header lines added by MAIL or RCPT ACLs are not visible at this time, but any that are defined here are visible when the acl_smtp_data ACL is run.

You cannot test the contents of the message, for example, to verify addresses in the headers, at RCPT time or when the DATA command is received. Such tests have to appear in the ACL that is run after the message itself has been received, before the final response to the DATA command is sent. This is the ACL specified by acl_smtp_data, which is the second ACL that is associated with the DATA command.

For both of these ACLs, it is not possible to reject individual recipients. An error response rejects the entire message. Unfortunately, it is known that some MTAs do not treat hard (5xx) responses to the DATA command (either before or after the data) correctly – they keep the message on their queues and try again later, but that is their problem, though it does waste some of your resources.

The acl_smtp_mime option is available only when Exim is compiled with the content-scanning extension. For details, see chapter 41.

The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL does not affect the response code to QUIT, which is always 221. Thus, the ACL does not in fact control any access. For this reason, the only verbs that are permitted are accept and warn.

This ACL can be used for tasks such as custom logging at the end of an SMTP session. For example, you can use ACL variables in other ACLs to count messages, recipients, etc., and log the totals at QUIT time using one or more logwrite modifiers on a warn verb.

Warning: Only the $acl_cx variables can be used for this, because the $acl_mx variables are reset at the end of each incoming message.

You do not need to have a final accept, but if you do, you can use a message modifier to specify custom text that is sent as part of the 221 response to QUIT.

This ACL is run only for a “normal” QUIT. For certain kinds of disastrous failure (for example, failure to open a log file, or when Exim is bombing out because it has detected an unrecoverable error), all SMTP commands from the client are given temporary error responses until QUIT is received or the connection is closed. In these special cases, the QUIT ACL does not run.

The not-QUIT ACL, specified by smtp_notquit_acl, is run in most cases when an SMTP session ends without sending QUIT. However, when Exim itself is is bad trouble, such as being unable to write to its log files, this ACL is not run, because it might try to do things (such as write to log files) that make the situation even worse.

Like the QUIT ACL, this ACL is provided to make it possible to do customized logging or to gather statistics, and its outcome is ignored. The delay modifier is forbidden in this ACL, and the only permitted verbs are accept and warn.

When the not-QUIT ACL is running, the variable $smtp_notquit_reason is set to a string that indicates the reason for the termination of the SMTP connection. The possible values are:

In most cases when an SMTP connection is closed without having received QUIT, Exim sends an SMTP response message before actually closing the connection. With the exception of the acl-drop case, the default message can be overridden by the message modifier in the not-QUIT ACL. In the case of a drop verb in another ACL, it is the message from the other ACL that is used.

The value of an acl_smtp_xxx option is expanded before use, so you can use different ACLs in different circumstances. For example,

acl_smtp_rcpt = ${if ={25}{$interface_port} \
                     {acl_check_rcpt} {acl_check_rcpt_submit} }

In the default configuration file there are some example settings for providing an RFC 4409 message submission service on port 587 and a non-standard “smtps” service on port 465. You can use a string expansion like this to choose an ACL for MUAs on these ports which is more appropriate for this purpose than the default ACL on port 25.

The expanded string does not have to be the name of an ACL in the configuration file; there are other possibilities. Having expanded the string, Exim searches for an ACL as follows:

Except for the QUIT ACL, which does not affect the SMTP return code (see section 40.8 above), the result of running an ACL is either “accept” or “deny”, or, if some test cannot be completed (for example, if a database is down), “defer”. These results cause 2xx, 5xx, and 4xx return codes, respectively, to be used in the SMTP dialogue. A fourth return, “error”, occurs when there is an error such as invalid syntax in the ACL. This also causes a 4xx return code.

For the non-SMTP ACL, “defer” and “error” are treated in the same way as “deny”, because there is no mechanism for passing temporary errors to the submitters of non-SMTP messages.

ACLs that are relevant to message reception may also return “discard”. This has the effect of “accept”, but causes either the entire message or an individual recipient address to be discarded. In other words, it is a blackholing facility. Use it with care.

If the ACL for MAIL returns “discard”, all recipients are discarded, and no ACL is run for subsequent RCPT commands. The effect of “discard” in a RCPT ACL is to discard just the one recipient address. If there are no recipients left when the message’s data is received, the DATA ACL is not run. A “discard” return from the DATA or the non-SMTP ACL discards all the remaining recipients. The “discard” return is not permitted for the acl_smtp_predata ACL.

The local_scan() function is always run, even if there are no remaining recipients; it may create new recipients.

The default actions when any of the acl_xxx options are unset are not all the same. Note: These defaults apply only when the relevant ACL is not defined at all. For any defined ACL, the default action when control reaches the end of the ACL statements is “deny”.

For acl_smtp_quit and acl_not_smtp_start there is no default because these two are ACLs that are used only for their side effects. They cannot be used to accept or reject anything.

For acl_not_smtp, acl_smtp_auth, acl_smtp_connect, acl_smtp_data, acl_smtp_helo, acl_smtp_mail, acl_smtp_mailauth, acl_smtp_mime, acl_smtp_predata, and acl_smtp_starttls, the action when the ACL is not defined is “accept”.

For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy), the action when the ACL is not defined is “deny”. This means that acl_smtp_rcpt must be defined in order to receive any messages over an SMTP connection. For an example, see the ACL in the default configuration file.

When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables that contain information about the host and the message’s sender (for example, $sender_host_address and $sender_address) are set, and can be used in ACL statements. In the case of RCPT (but not MAIL or DATA), $domain and $local_part are set from the argument address. The entire SMTP command is available in $smtp_command.

When an ACL for the AUTH parameter of MAIL is running, the variables that contain information about the host are set, but $sender_address is not yet set. Section 33.2 contains a discussion of this parameter and how it is used.

The $message_size variable is set to the value of the SIZE parameter on the MAIL command at MAIL, RCPT and pre-data time, or to -1 if that parameter is not given. The value is updated to the true message size by the time the final DATA ACL is run (after the message data has been received).

The $rcpt_count variable increases by one for each RCPT command received. The $recipients_count variable increases by one each time a RCPT command is accepted, so while an ACL for RCPT is being processed, it contains the number of previously accepted recipients. At DATA time (for both the DATA ACLs), $rcpt_count contains the total number of RCPT commands, and $recipients_count contains the total number of accepted recipients.

When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY, the remainder of the SMTP command line is placed in $smtp_command_argument, and the entire SMTP command is available in $smtp_command. These variables can be tested using a condition condition. For example, here is an ACL for use with AUTH, which insists that either the session is encrypted, or the CRAM-MD5 authentication method is used. In other words, it does not permit authentication methods that use cleartext passwords on unencrypted connections.

acl_check_auth:
  accept encrypted = *
  accept condition = ${if eq{${uc:$smtp_command_argument}}\
                     {CRAM-MD5}}
  deny   message   = TLS encryption or CRAM-MD5 required

(Another way of applying this restriction is to arrange for the authenticators that use cleartext passwords not to be advertised when the connection is not encrypted. You can use the generic server_advertise_condition authenticator option to do this.)

An individual ACL consists of a number of statements. Each statement starts with a verb, optionally followed by a number of conditions and “modifiers”. Modifiers can change the way the verb operates, define error and log messages, set variables, insert delays, and vary the processing of accepted messages.

If all the conditions are met, the verb is obeyed. The same condition may be used (with different arguments) more than once in the same statement. This provides a means of specifying an “and” conjunction between conditions. For example:

deny  dnslists = list1.example
dnslists = list2.example

If there are no conditions, the verb is always obeyed. Exim stops evaluating the conditions and modifiers when it reaches a condition that fails. What happens then depends on the verb (and in one case, on a special modifier). Not all the conditions make sense at every testing point. For example, you cannot test a sender address in the ACL that is run for a VRFY command.

The ACL verbs are as follows:

At the end of each ACL there is an implicit unconditional deny.

As you can see from the examples above, the conditions and modifiers are written one to a line, with the first one on the same line as the verb, and subsequent ones on following lines. If you have a very long condition, you can continue it onto several physical lines by the usual backslash continuation mechanism. It is conventional to align the conditions vertically.

There are some special variables that can be set during ACL processing. They can be used to pass information between different ACLs, different invocations of the same ACL in the same SMTP connection, and between ACLs and the routers, transports, and filters that are used to deliver a message. The names of these variables must begin with $acl_c or $acl_m, followed either by a digit or an underscore, but the remainder of the name can be any sequence of alphanumeric characters and underscores that you choose. There is no limit on the number of ACL variables. The two sets act as follows:

When a message is accepted, the current values of all the ACL variables are preserved with the message and are subsequently made available at delivery time. The ACL variables are set by a modifier called set. For example:

accept hosts = whatever
       set acl_m4 = some value
accept authenticated = *
       set acl_c_auth = yes

Note: A leading dollar sign is not used when naming a variable that is to be set. If you want to set a variable without taking any action, you can use a warn verb without any other modifiers or conditions.

What happens if a syntactically valid but undefined ACL variable is referenced depends on the setting of the strict_acl_vars option. If it is false (the default), an empty string is substituted; if it is true, an error is generated.

Versions of Exim before 4.64 have a limited set of numbered variables, but their names are compatible, so there is no problem with upgrading.

An exclamation mark preceding a condition negates its result. For example:

deny   domains = *.dom.example
      !verify  = recipient

causes the ACL to return “deny” if the recipient domain ends in dom.example and the recipient address cannot be verified. Sometimes negation can be used on the right-hand side of a condition. For example, these two statements are equivalent:

deny  hosts = !192.168.3.4
deny !hosts =  192.168.3.4

However, for many conditions (verify being a good example), only left-hand side negation of the whole condition is possible.

The arguments of conditions and modifiers are expanded. A forced failure of an expansion causes a condition to be ignored, that is, it behaves as if the condition is true. Consider these two statements:

accept  senders = ${lookup{$host_name}lsearch\
                  {/some/file}{$value}fail}
accept  senders = ${lookup{$host_name}lsearch\
                  {/some/file}{$value}{}}

Each attempts to look up a list of acceptable senders. If the lookup succeeds, the returned list is searched, but if the lookup fails the behaviour is different in the two cases. The fail in the first statement causes the condition to be ignored, leaving no further conditions. The accept verb therefore succeeds. The second statement, however, generates an empty list when the lookup fails. No sender can match an empty list, so the condition fails, and therefore the accept also fails.

ACL modifiers appear mixed in with conditions in ACL statements. Some of them specify actions that are taken as the conditions for a statement are checked; others specify text for messages that are used when access is denied or a warning is generated. The control modifier affects the way an incoming message is handled.

The positioning of the modifiers in an ACL statement important, because the processing of a verb ceases as soon as its outcome is known. Only those modifiers that have already been encountered will take effect. For example, consider this use of the message modifier:

require message = Can't verify sender
        verify  = sender
        message = Can't verify recipient
        verify  = recipient
        message = This message cannot be used

If sender verification fails, Exim knows that the result of the statement is “deny”, so it goes no further. The first message modifier has been seen, so its text is used as the error message. If sender verification succeeds, but recipient verification fails, the second message is used. If recipient verification succeeds, the third message becomes “current”, but is never used because there are no more conditions to cause failure.

For the deny verb, on the other hand, it is always the last message modifier that is used, because all the conditions must be true for rejection to happen. Specifying more than one message modifier does not make sense, and the message can even be specified after all the conditions. For example:

deny   hosts = ...
      !senders = *@my.domain.example
       message = Invalid sender from client host

The “deny” result does not happen until the end of the statement is reached, by which time Exim has set up the message.

The ACL modifiers are as follows:

The control modifier supports the following settings:

All four possibilities for message fixups can be specified:

The add_header modifier can be used to add one or more extra header lines to an incoming message, as in this example:

warn dnslists = sbl.spamhaus.org : \
                dialup.mail-abuse.org
     add_header = X-blacklisted-at: $dnslist_domain

The add_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME, and non-SMTP ACLs (in other words, those that are concerned with receiving a message). The message must ultimately be accepted for add_header to have any significant effect. You can use add_header with any ACL verb, including deny (though this is potentially useful only in a RCPT ACL).

If the data for the add_header modifier contains one or more newlines that are not followed by a space or a tab, it is assumed to contain multiple header lines. Each one is checked for valid syntax; X-ACL-Warn: is added to the front of any line that is not a valid header line.

Added header lines are accumulated during the MAIL, RCPT, and predata ACLs. They are added to the message before processing the DATA and MIME ACLs. However, if an identical header line is requested more than once, only one copy is actually added to the message. Further header lines may be accumulated during the DATA and MIME ACLs, after which they are added to the message, again with duplicates suppressed. Thus, it is possible to add two identical header lines to an SMTP message, but only if one is added before DATA and one after. In the case of non-SMTP messages, new headers are accumulated during the non-SMTP ACLs, and are added to the message after all the ACLs have run. If a message is rejected after DATA or by the non-SMTP ACL, all added header lines are included in the entry that is written to the reject log.

Header lines are not visible in string expansions until they are added to the message. It follows that header lines defined in the MAIL, RCPT, and predata ACLs are not visible until the DATA ACL and MIME ACLs are run. Similarly, header lines that are added by the DATA or MIME ACLs are not visible in those ACLs. Because of this restriction, you cannot use header lines as a way of passing data between (for example) the MAIL and RCPT ACLs. If you want to do this, you can use ACL variables, as described in section 40.17.

The add_header modifier acts immediately it is encountered during the processing of an ACL. Notice the difference between these two cases:

In the first case, the header line is always added, whether or not the condition is true. In the second case, the header line is added only if the condition is true. Multiple occurrences of add_header may occur in the same ACL statement. All those that are encountered before a condition fails are honoured.

For compatibility with previous versions of Exim, a message modifier for a warn verb acts in the same way as add_header, except that it takes effect only if all the conditions are true, even if it appears before some of them. Furthermore, only the last occurrence of message is honoured. This usage of message is now deprecated. If both add_header and message are present on a warn verb, both are processed according to their specifications.

By default, new header lines are added to a message at the end of the existing header lines. However, you can specify that any particular header line should be added right at the start (before all the Received: lines), immediately after the first block of Received: lines, or immediately before any line that is not a Received: or Resent-something: header.

This is done by specifying “:at_start:”, “:after_received:”, or “:at_start_rfc:” (or, for completeness, “:at_end:”) before the text of the header line, respectively. (Header text cannot start with a colon, as there has to be a header name first.) For example:

warn add_header = \
       :after_received:X-My-Header: something or other...

If more than one header line is supplied in a single add_header modifier, each one is treated independently and can therefore be placed differently. If you add more than one line at the start, or after the Received: block, they end up in reverse order.

Warning: This facility currently applies only to header lines that are added in an ACL. It does NOT work for header lines that are added in a system filter or in a router or transport.

Some of conditions listed in this section are available only when Exim is compiled with the content-scanning extension. They are included here briefly for completeness. More detailed descriptions can be found in the discussion on content scanning in chapter 41.

Not all conditions are relevant in all circumstances. For example, testing senders and recipients does not make sense in an ACL that is being run as the result of the arrival of an ETRN command, and checks on message headers can be done only in the ACLs specified by acl_smtp_data and acl_not_smtp. You can use the same condition (with different parameters) more than once in the same ACL statement. This provides a way of specifying an “and” conjunction. The conditions are as follows:

In its simplest form, the dnslists condition tests whether the calling host is on at least one of a number of DNS lists by looking up the inverted IP address in one or more DNS domains. For example, if the calling host’s IP address is 192.168.62.43, and the ACL statement is

deny dnslists = blackholes.mail-abuse.org : \
                dialups.mail-abuse.org

the following records are looked up:

43.62.168.192.blackholes.mail-abuse.org
43.62.168.192.dialups.mail-abuse.org

As soon as Exim finds an existing DNS record, processing of the list stops. Thus, multiple entries on the list provide an “or” conjunction. If you want to test that a host is on more than one list (an “and” conjunction), you can use two separate conditions:

deny dnslists = blackholes.mail-abuse.org
     dnslists = dialups.mail-abuse.org

If a DNS lookup times out or otherwise fails to give a decisive answer, Exim behaves as if the host does not match the list item, that is, as if the DNS record does not exist. If there are further items in the DNS list, they are processed.

This is usually the required action when dnslists is used with deny (which is the most common usage), because it prevents a DNS failure from blocking mail. However, you can change this behaviour by putting one of the following special items in the list:

Each of these applies to any subsequent items on the list. For example:

deny dnslists = +defer_unknown : foo.bar.example

Testing the list of domains stops as soon as a match is found. If you want to warn for one list and block for another, you can use two different statements:

deny  dnslists = blackholes.mail-abuse.org
warn  message  = X-Warn: sending host is on dialups list
      dnslists = dialups.mail-abuse.org

DNS list lookups are cached by Exim for the duration of the SMTP session, so a lookup based on the IP address is done at most once for any incoming connection. Exim does not share information between multiple incoming connections (but your local name server cache should be active).

By default, the IP address that is used in a DNS list lookup is the IP address of the calling host. However, you can specify another IP address by listing it after the domain name, introduced by a slash. For example:

deny dnslists = black.list.tld/192.168.1.2

This feature is not very helpful with explicit IP addresses; it is intended for use with IP addresses that are looked up, for example, the IP addresses of the MX hosts or nameservers of an email sender address. For an example, see section 40.27 below.

There are some lists that are keyed on domain names rather than inverted IP addresses (see for example the domain based zones link at http://www.rfc-ignorant.org/). No reversing of components is used with these lists. You can change the name that is looked up in a DNS list by listing it after the domain name, introduced by a slash. For example,

deny  message  = Sender's domain is listed at $dnslist_domain
      dnslists = dsn.rfc-ignorant.org/$sender_address_domain

This particular example is useful only in ACLs that are obeyed after the RCPT or DATA commands, when a sender address is available. If (for example) the message’s sender is user@tld.example the name that is looked up by this example is

tld.example.dsn.rfc-ignorant.org

A single dnslists condition can contain entries for both names and IP addresses. For example:

deny dnslists = sbl.spamhaus.org : \
                dsn.rfc-ignorant.org/$sender_address_domain

The first item checks the sending host’s IP address; the second checks a domain name. The whole condition is true if either of the DNS lookups succeeds.

The syntax described above for looking up explicitly-defined values (either names or IP addresses) in a DNS blacklist is a simplification. After the domain name for the DNS list, what follows the slash can in fact be a list of items. As with all lists in Exim, the default separator is a colon. However, because this is a sublist within the list of DNS blacklist domains, it is necessary either to double the separators like this:

dnslists = black.list.tld/name.1::name.2

or to change the separator character, like this:

dnslists = black.list.tld/<;name.1;name.2

If an item in the list is an IP address, it is inverted before the DNS blacklist domain is appended. If it is not an IP address, no inversion occurs. Consider this condition:

dnslists = black.list.tld/<;192.168.1.2;a.domain

The DNS lookups that occur are:

2.1.168.192.black.list.tld
a.domain.black.list.tld

Once a DNS record has been found (that matches a specific IP return address, if specified – see section 40.30), no further lookups are done. If there is a temporary DNS error, the rest of the sublist of domains or IP addresses is tried. A temporary error for the whole dnslists item occurs only if no other DNS lookup in this sublist succeeds. In other words, a successful lookup for any of the items in the sublist overrides a temporary error for a previous item.

The ability to supply a list of items after the slash is in some sense just a syntactic convenience. These two examples have the same effect:

dnslists = black.list.tld/a.domain : black.list.tld/b.domain
dnslists = black.list.tld/a.domain::b.domain

However, when the data for the list is obtained from a lookup, the second form is usually much more convenient. Consider this example:

deny message  = The mail servers for the domain \
                $sender_address_domain \
                are listed at $dnslist_domain ($dnslist_value); \
                see $dnslist_text.
     dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\
                                   ${lookup dnsdb {>|mxh=\
                                   $sender_address_domain} }} }

Note the use of >| in the dnsdb lookup to specify the separator for multiple DNS records. The inner dnsdb lookup produces a list of MX hosts and the outer dnsdb lookup finds the IP addresses for these hosts. The result of expanding the condition might be something like this:

dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|...

Thus, this example checks whether or not the IP addresses of the sender domain’s mail servers are on the Spamhaus black list.

The key that was used for a successful DNS list lookup is put into the variable $dnslist_matched (see section 40.29).

DNS lists are constructed using address records in the DNS. The original RBL just used the address 127.0.0.1 on the right hand side of each record, but the RBL+ list and some other lists use a number of values with different meanings. The values used on the RBL+ list are:

Section 40.30 below describes how you can distinguish between different values. Some DNS lists may return more than one address record; see section 40.32 for details of how they are checked.