Exim Internet Mailer

1. Testing ACLs

The -bh command line option provides a way of testing your ACL configuration locally by running a fake SMTP session with which you interact.

2. Specifying when ACLs are used

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.

control = suppress_local_fixups

 check_wellknown:
  accept control = wellknown/\
		    ${lookup {${xtextd:$smtp_command_argument}} \
			dsearch,key=path,filter=file,ret=full \
			{$spooldir/wellknown.d}}

  mailtest -h host.example.com -w security.txt

3. Finding an ACL to use

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 an RFC 8314 “submissions” 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:

• If the string begins with a slash, Exim uses it as a filename, and reads its contents as an ACL. The lines are processed in the same way as lines in the Exim configuration file. In particular, continuation lines are supported, blank lines are ignored, as are lines whose first non-whitespace character is “#”. If the file does not exist or cannot be read, an error occurs (typically causing a temporary failure of whatever caused the ACL to be run). For example:

  acl_smtp_data = /etc/acls/\
    ${lookup{$sender_host_address}lsearch\
    {/etc/acllist}{$value}{default}}
  

  This looks up an ACL file to use on the basis of the host’s IP address, falling back to a default if the lookup fails. If an ACL is successfully read from a file, it is retained in memory for the duration of the Exim process, so that it can be re-used without having to re-read the file.

• If the string does not start with a slash, and does not contain any spaces, Exim searches the ACL section of the configuration for an ACL whose name matches the string.

• If no named ACL is found, or if the string contains spaces, Exim parses the string as an inline ACL. This can save typing in cases where you just want to have something like

  acl_smtp_vrfy = accept
  

  in order to allow free use of the VRFY command. Such a string may contain newlines; it is processed in the same way as an ACL that is read from a file.

4. ACL return codes

Except for the QUIT ACL, which does not affect the SMTP return code (see section 44.9 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.

If the ACL for VRFY returns “accept”, a recipient verify (without callout) is done on the address and the result determines the SMTP response.

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

5. Unset ACL options

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, acl_smtp_vrfy

and acl_smtp_wellknown),

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.

6. Data for message ACLs

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.

7. Data for non-message ACLs

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.)

8. Format of an ACL

An individual ACL definition 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 definition of an ACL ends where another starts, or a different configuration section starts.

9. ACL verbs

The ACL verbs are as follows:

• accept: If all the conditions are met, the ACL returns “accept”. If any of the conditions are not met, what happens depends on whether endpass appears among the conditions (for syntax see below). If the failing condition is before endpass, control is passed to the next ACL statement; if it is after endpass, the ACL returns “deny”. Consider this statement, used to check a RCPT command:

  accept domains = +local_domains
         endpass
         verify = recipient
  

  If the recipient domain does not match the domains condition, control passes to the next statement. If it does match, the recipient is verified, and the command is accepted if verification succeeds. However, if verification fails, the ACL yields “deny”, because the failing condition is after endpass.

  The endpass feature has turned out to be confusing to many people, so its use is not recommended nowadays. It is always possible to rewrite an ACL so that endpass is not needed, and it is no longer used in the default configuration.

  If a message modifier appears on an accept statement, its action depends on whether or not endpass is present. In the absence of endpass (when an accept verb either accepts or passes control to the next statement), message can be used to vary the message that is sent when an SMTP command is accepted. For example, in a RCPT ACL you could have:

  accept  <some conditions>
          message = OK, I will allow you through today
  

  You can specify an SMTP response code, optionally followed by an “extended response code” at the start of the message, but the first digit must be the same as would be sent by default, which is 2 for an accept verb.

  If endpass is present in an accept statement, message specifies an error message that is used when access is denied. This behaviour is retained for backward compatibility, but current “best practice” is to avoid the use of endpass.

• defer: If all the conditions are true, the ACL returns “defer” which, in an SMTP session, causes a 4xx response to be given. For a non-SMTP ACL, defer is the same as deny, because there is no way of sending a temporary error. For a RCPT command, defer is much the same as using a redirect router and :defer: while verifying, but the defer verb can be used in any ACL, and even for a recipient it might be a simpler approach.

• deny: If all the conditions are met, the ACL returns “deny”. If any of the conditions are not met, control is passed to the next ACL statement. For example,

  deny dnslists = blackholes.mail-abuse.org
  

  rejects commands from hosts that are on a DNS black list.

• discard: This verb behaves like accept, except that it returns “discard” from the ACL instead of “accept”. It is permitted only on ACLs that are concerned with receiving messages. When all the conditions are true, the sending entity receives a “success” response. However, discard causes recipients to be discarded. If it is used in an ACL for RCPT, just the one recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all the message’s recipients are discarded. Recipients that are discarded before DATA do not appear in the log line when the received_recipients log selector is set.

  If the log_message modifier is set when discard operates, its contents are added to the line that is automatically written to the log. The message modifier operates exactly as it does for accept.

• drop: This verb behaves like deny, except that an SMTP connection is forcibly closed after the 5xx error message has been sent. For example:

  drop   condition = ${if > {$rcpt_count}{20}}
         message   = I don't take more than 20 RCPTs
  

  There is no difference between deny and drop for the connect-time ACL. The connection is always dropped after sending a 550 response.

• require: If all the conditions are met, control is passed to the next ACL statement. If any of the conditions are not met, the ACL returns “deny”. For example, when checking a RCPT command,

  require message = Sender did not verify
          verify  = sender
  

  passes control to subsequent statements only if the message’s sender can be verified. Otherwise, it rejects the command. Note the positioning of the message modifier, before the verify condition. The reason for this is discussed in section 44.11.

• warn: If all the conditions are true, a line specified by the log_message modifier is written to Exim’s main log. Control always passes to the next ACL statement. If any condition is false, the log line is not written. If an identical log line is requested several times in the same message, only one copy is actually written to the log. If you want to force duplicates to be written, use the logwrite modifier instead.

  If log_message is not present, a warn verb just checks its conditions and obeys any “immediate” modifiers (such as control, set, logwrite, add_header, and remove_header) that appear before the first failing condition. There is more about adding header lines in section 44.15.

  If any condition on a warn statement cannot be completed (that is, there is some sort of defer), the log line specified by log_message is not written. This does not include the case of a forced failure from a lookup, which is considered to be a successful completion. After a defer, no further conditions or modifiers in the warn statement are processed. The incident is logged, and the ACL continues to be processed, from the next statement onwards.

  When one of the warn conditions is an address verification that fails, the text of the verification failure message is in $acl_verify_message. If you want this logged, you must set it up explicitly. For example:

  warn   !verify = sender
         log_message = sender verify failed: $acl_verify_message
  

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.

10. ACL variables

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:

• The values of those variables whose names begin with $acl_c persist throughout an SMTP connection. They are never reset. Thus, a value that is set while receiving one message is still available when receiving the next message on the same SMTP connection.

• The values of those variables whose names begin with $acl_m persist only while a message is being received. They are reset afterwards. They are also reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session.

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.

11. Condition and modifier processing

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 is 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.

12. ACL modifiers

The ACL modifiers are as follows:

add_header = <text>

This modifier specifies one or more header lines that are to be added to an incoming message, assuming, of course, that the message is ultimately accepted. For details, see section 44.15.

continue = <text>

This modifier does nothing of itself, and processing of the ACL always continues with the next condition or modifier. The value of continue is in the side effects of expanding its argument. Typically this could be used to update a database. It is really just a syntactic tidiness, to avoid having to write rather ugly lines like this:

condition = ${if eq{0}{<some expansion>}{true}{true}}

Instead, all you need is

continue = <some expansion>

control = <text>

This modifier affects the subsequent processing of the SMTP connection or of an incoming message that is accepted. The effect of the first type of control lasts for the duration of the connection, whereas the effect of the second type lasts only until the current message has been received. The message-specific controls always apply to the whole message, not to individual recipients, even if the control modifier appears in a RCPT ACL.

As there are now quite a few controls that can be applied, they are described separately in section 44.13. The control modifier can be used in several different ways. For example:

• It can be at the end of an accept statement:

      accept  ...some conditions
              control = queue
  

  In this case, the control is applied when this statement yields “accept”, in other words, when the conditions are all true.

• It can be in the middle of an accept statement:

      accept  ...some conditions...
              control = queue
              ...some more conditions...
  

  If the first set of conditions are true, the control is applied, even if the statement does not accept because one of the second set of conditions is false. In this case, some subsequent statement must yield “accept” for the control to be relevant.

• It can be used with warn to apply the control, leaving the decision about accepting or denying to a subsequent verb. For example:

      warn    ...some conditions...
              control = freeze
      accept  ...
  

  This example of warn does not contain message, log_message, or logwrite, so it does not add anything to the message and does not write a log entry.

• If you want to apply a control unconditionally, you can use it with a require verb. For example:

      require  control = no_multiline_responses
  

delay = <time>

This modifier may appear in any ACL except notquit. It causes Exim to wait for the time interval before proceeding. However, when testing Exim using the -bh option, the delay is not actually imposed (an appropriate message is output instead). The time is given in the usual Exim notation, and the delay happens as soon as the modifier is processed. In an SMTP session, pending output is flushed before the delay is imposed.

Like control, delay can be used with accept or deny, for example:

deny    ...some conditions...
        delay = 30s

The delay happens if all the conditions are true, before the statement returns “deny”. Compare this with:

deny    delay = 30s
        ...some conditions...

which waits for 30s before processing the conditions. The delay modifier can also be used with warn and together with control:

warn    ...some conditions...
        delay = 2m
        control = freeze
accept  ...

If delay is encountered when the SMTP PIPELINING extension is in use, responses to several commands are no longer buffered and sent in one packet (as they would normally be) because all output is flushed before imposing the delay. This optimization is disabled so that a number of small delays do not appear to the client as one large aggregated delay that might provoke an unwanted timeout. You can, however, disable output flushing for delay by using a control modifier to set no_delay_flush.

endpass

This modifier, which has no argument, is recognized only in accept and discard statements. It marks the boundary between the conditions whose failure causes control to pass to the next statement, and the conditions whose failure causes the ACL to return “deny”. This concept has proved to be confusing to some people, so the use of endpass is no longer recommended as “best practice”. See the description of accept above for more details.

log_message = <text>

This modifier sets up a message that is used as part of the log message if the ACL denies access or a warn statement’s conditions are true. For example:

require log_message = wrong cipher suite $tls_in_cipher
        encrypted   = DES-CBC3-SHA

log_message is also used when recipients are discarded by discard. For example:

discard <some conditions>
        log_message = Discarded $local_part@$domain because...

When access is denied, log_message adds to any underlying error message that may exist because of a condition failure. For example, while verifying a recipient address, a :fail: redirection might have already set up a message.

The message may be defined before the conditions to which it applies, because the string expansion does not happen until Exim decides that access is to be denied. This means that any variables that are set by the condition are available for inclusion in the message. For example, the $dnslist_<xxx> variables are set after a DNS black list lookup succeeds. If the expansion of log_message fails, or if the result is an empty string, the modifier is ignored.

If you want to use a warn statement to log the result of an address verification, you can use $acl_verify_message to include the verification error message.

If log_message is used with a warn statement, “Warning:” is added to the start of the logged message. If the same warning log message is requested more than once while receiving a single email message, only one copy is actually logged. If you want to log multiple copies, use logwrite instead of log_message. In the absence of log_message and logwrite, nothing is logged for a successful warn statement.

If log_message is not present and there is no underlying error message (for example, from the failure of address verification), but message is present, the message text is used for logging rejections. However, if any text for logging contains newlines, only the first line is logged. In the absence of both log_message and message, a default built-in message is used for logging rejections.

log_reject_target = <log name list>

This modifier makes it possible to specify which logs are used for messages about ACL rejections. Its argument is a colon-separated list of words that can be “main”, “reject”, or “panic”. The default is main:reject. The list may be empty, in which case a rejection is not logged at all. For example, this ACL fragment writes no logging information when access is denied:

deny <some conditions>
     log_reject_target =

This modifier can be used in SMTP and non-SMTP ACLs. It applies to both permanent and temporary rejections. Its effect lasts for the rest of the current ACL.

logwrite = <text>

This modifier writes a message to a log file as soon as it is encountered when processing an ACL. (Compare log_message, which, except in the case of warn and discard, is used only if the ACL statement denies access.) The logwrite modifier can be used to log special incidents in ACLs. For example:

accept <some special conditions>
       control  = freeze
       logwrite = froze message because ...

By default, the message is written to the main log. However, it may begin with a colon, followed by a comma-separated list of log names, and then another colon, to specify exactly which logs are to be written. For example:

logwrite = :main,reject: text for main and reject logs
logwrite = :panic: text for panic log only

message = <text>

This modifier sets up a text string that is expanded and used as a response message when an ACL statement terminates the ACL with an “accept”, “deny”, or “defer” response. (In the case of the accept and discard verbs, there is some complication if endpass is involved; see the description of accept for details.)

The expansion of the message happens at the time Exim decides that the ACL is to end, not at the time it processes message. If the expansion fails, or generates an empty string, the modifier is ignored. Here is an example where message must be specified first, because the ACL ends with a rejection if the hosts condition fails:

require  message = Host not recognized
         hosts = 10.0.0.0/8

(Once a condition has failed, no further conditions or modifiers are processed.)

For ACLs that are triggered by SMTP commands, the message is returned as part of the SMTP response. The use of message with accept (or discard) is meaningful only for SMTP, as no message is returned when a non-SMTP message is accepted. In the case of the connect ACL, accepting with a message modifier overrides the value of smtp_banner. For the EHLO/HELO ACL, a customized accept message may not contain more than one line (otherwise it will be truncated at the first newline and a panic logged), and it cannot affect the EHLO options.

When SMTP is involved, the message may begin with an overriding response code, consisting of three digits optionally followed by an “extended response code” of the form n.n.n, each code being followed by a space. For example:

deny  message = 599 1.2.3 Host not welcome
      hosts = 192.168.34.0/24

The first digit of the supplied response code must be the same as would be sent by default. A panic occurs if it is not. Exim uses a 550 code when it denies access, but for the predata ACL, note that the default success code is 354, not 2xx.

Notwithstanding the previous paragraph, for the QUIT ACL, unlike the others, the message modifier cannot override the 221 response code.

The text in a message modifier is literal; any quotes are taken as literals, but because the string is expanded, backslash escapes are processed anyway. If the message contains newlines, this gives rise to a multi-line SMTP response. A long message line will also be split into multi-line SMTP responses, on word boundaries if possible.

While the text is being expanded, the $acl_verify_message variable contains any message previously set. Afterwards, $acl_verify_message is cleared.

If message is used on a statement that verifies an address, the message specified overrides any message that is generated by the verification process. However, the original message is available in the variable $acl_verify_message, so you can incorporate it into your message if you wish. In particular, if you want the text from :fail: items in redirect routers to be passed back as part of the SMTP response, you should either not use a message modifier, or make use of $acl_verify_message.

For compatibility with previous releases of Exim, a message modifier that is used with a warn verb behaves in a similar way to the add_header modifier, but this usage is now deprecated. However, message acts only when all the conditions are true, wherever it appears in an ACL command, whereas add_header acts as soon as it is encountered. If message is used with warn in an ACL that is not concerned with receiving a message, it has no effect.

queue = <text>

This modifier specifies the use of a named queue for spool files for the message. It can only be used before the message is received (i.e. not in the DATA ACL). This could be used, for example, for known high-volume burst sources of traffic, or for quarantine of messages. Separate queue-runner processes will be needed for named queues. If the text after expansion is empty, the default queue is used.

remove_header = <text>

This modifier specifies one or more header names in a colon-separated list that are to be removed from an incoming message, assuming, of course, that the message is ultimately accepted. For details, see section 44.16.

set <acl_name> = <value>

This modifier puts a value into one of the ACL variables (see section 44.10).

udpsend = <parameters>

This modifier sends a UDP packet, for purposes such as statistics collection or behaviour monitoring. The parameters are expanded, and the result of the expansion must be a colon-separated list consisting of a destination server, port number, and the packet contents. The server can be specified as a host name or IPv4 or IPv6 address. The separator can be changed with the usual angle bracket syntax. For example, you might want to collect information on which hosts connect when:

udpsend = <; 2001:dB8::dead:beef ; 1234 ;\
             $tod_zulu $sender_host_address

13. Use of the control modifier

The control modifier supports the following settings:

control = allow_auth_unadvertised

This modifier allows a client host to use the SMTP AUTH command even when it has not been advertised in response to EHLO. Furthermore, because there are apparently some really broken clients that do this, Exim will accept AUTH after HELO (rather than EHLO) when this control is set. It should be used only if you really need it, and you should limit its use to those broken clients that do not work without it. For example:

warn hosts   = 192.168.34.25
     control = allow_auth_unadvertised

Normally, when an Exim server receives an AUTH command, it checks the name of the authentication mechanism that is given in the command to ensure that it matches an advertised mechanism. When this control is set, the check that a mechanism has been advertised is bypassed. Any configured mechanism can be used by the client. This control is permitted only in the connection and HELO ACLs.

control = caseful_local_part

control = caselower_local_part

These two controls are permitted only in the ACL specified by acl_smtp_rcpt (that is, during RCPT processing). By default, the contents of $local_part are lower cased before ACL processing. If “caseful_local_part” is specified, any uppercase letters in the original local part are restored in $local_part for the rest of the ACL, or until a control that sets “caselower_local_part” is encountered.

These controls affect only the current recipient. Moreover, they apply only to local part handling that takes place directly in the ACL (for example, as a key in lookups). If a test to verify the recipient is obeyed, the case-related handling of the local part during the verification is controlled by the router configuration (see the caseful_local_part generic router option).

This facility could be used, for example, to add a spam score to local parts containing upper case letters. For example, using $acl_m4 to accumulate the spam score:

warn  control = caseful_local_part
      set acl_m4 = ${eval:\
                     $acl_m4 + \
                     ${if match{$local_part}{[A-Z]}{1}{0}}\
                    }
      control = caselower_local_part

Notice that we put back the lower cased version afterwards, assuming that is what is wanted for subsequent tests.

control = cutthrough_delivery/<options>

This option requests delivery be attempted while the item is being received.

The option is usable in the RCPT ACL. If enabled for a message received via smtp and routed to an smtp transport, and only one transport, interface, destination host and port combination is used for all recipients of the message, then the delivery connection is made while the receiving connection is open and data is copied from one to the other.

An attempt to set this option for any recipient but the first for a mail will be quietly ignored. If a recipient-verify callout (with use_sender) connection is subsequently requested in the same ACL it is held open and used for any subsequent recipients and the data, otherwise one is made after the initial RCPT ACL completes.

Note that routers are used in verify mode, and cannot depend on content of received headers. Note also that headers cannot be modified by any of the post-data ACLs (DATA, MIME and DKIM). Headers may be modified by routers (subject to the above) and transports. The Received-By: header is generated as soon as the body reception starts, rather than the traditional time after the full message is received; this will affect the timestamp.

All the usual ACLs are called; if one results in the message being rejected, all effort spent in delivery (including the costs on the ultimate destination) will be wasted. Note that in the case of data-time ACLs this includes the entire message body.

Cutthrough delivery is not supported via transport-filters or when DKIM signing of outgoing messages is done, because it sends data to the ultimate destination before the entire message has been received from the source. It is not supported for messages received with the SMTP PRDR or CHUNKING options in use.

Should the ultimate destination system positively accept or reject the mail, a corresponding indication is given to the source system and nothing is queued. If the item is successfully delivered in cutthrough mode the delivery log lines are tagged with ">>" rather than "=>" and appear before the acceptance "<=" line.

If there is a temporary error the item is queued for later delivery in the usual fashion. This behaviour can be adjusted by appending the option defer=<value> to the control; the default value is “spool” and the alternate value “pass” copies an SMTP defer response from the target back to the initiator and does not queue the message. Note that this is independent of any recipient verify conditions in the ACL.

Delivery in this mode avoids the generation of a bounce mail to a (possibly faked) sender when the destination system is doing content-scan based rejection.

control = debug/<options>

This control turns on debug logging, almost as though Exim had been invoked with -d, with the output going to a new logfile in the usual logs directory, by default called debuglog.

Logging set up by the control will be maintained across spool residency.

Options are a slash-separated list. If an option takes an argument, the option name and argument are separated by an equals character. Several options are supported:

tag=<suffix>         The filename can be adjusted with thise option.
		     The argument, which may access any variables already defined,
                     is appended to the default name.

opts=<debug options> The argument specififes what is to be logged,
                     using the same values as the -d command-line option.

stop                 Logging started with this control may be
                     stopped by using this option.

kill                 Logging started with this control may be
                     stopped by using this option.
                     Additionally the debug file will be removed,
                     providing one means for speculative debug tracing.

pretrigger=<size>    This option specifies a memory buffuer to be used
                     for pre-trigger debug capture.
                     Debug lines are recorded in the buffer until
                     and if) a trigger occurs; at which time they are
                     dumped to the debug file.  Newer lines displace the
                     oldest if the buffer is full.  After a trigger,
                     immediate writes to file are done as normal.

trigger=<reason>     This option selects cause for the pretrigger buffer
                     see above) to be copied to file.  A reason of now
                     take effect immediately; one of paniclog triggers
                     on a write to the panic log.

Some examples (which depend on variables that don’t exist in all contexts):

      control = debug
      control = debug/tag=.$sender_host_address
      control = debug/opts=+expand+acl
      control = debug/tag=.$message_exim_id/opts=+expand
      control = debug/kill
      control = debug/opts=+all/pretrigger=1024/trigger=paniclog
      control = debug/trigger=now

control = dkim_disable_verify

This control turns off DKIM verification processing entirely. For details on the operation and configuration of DKIM, see section 58.1.

control = dmarc_disable_verify

This control turns off DMARC verification processing entirely. For details on the operation and configuration of DMARC, see section 58.3.

control = dscp/<value>

This option causes the DSCP value associated with the socket for the inbound connection to be adjusted to a given value, given as one of a number of fixed strings or to numeric value. The -bI:dscp option may be used to ask Exim which names it knows of. Common values include throughput, mincost, and on newer systems ef, af41, etc. Numeric values may be in the range 0 to 0x3F.

The outbound packets from Exim will be marked with this value in the header (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee that these values will have any effect, not be stripped by networking equipment, or do much of anything without cooperation with your Network Engineer and those of all network operators between the source and destination.

control = enforce_sync

control = no_enforce_sync

These controls make it possible to be selective about when SMTP synchronization is enforced. The global option smtp_enforce_sync specifies the initial state of the switch (it is true by default). See the description of this option in chapter 14 for details of SMTP synchronization checking.

The effect of these two controls lasts for the remainder of the SMTP connection. They can appear in any ACL except the one for the non-SMTP messages. The most straightforward place to put them is in the ACL defined by acl_smtp_connect, which is run at the start of an incoming SMTP connection, before the first synchronization check. The expected use is to turn off the synchronization checks for badly-behaved hosts that you nevertheless need to work with.

control = fakedefer/<message>

This control works in exactly the same way as fakereject (described below) except that it causes an SMTP 450 response after the message data instead of a 550 response. You must take care when using fakedefer because it causes the messages to be duplicated when the sender retries. Therefore, you should not use fakedefer if the message is to be delivered normally.

control = fakereject/<message>

This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other words, only when an SMTP message is being received. If Exim accepts the message, instead the final 250 response, a 550 rejection message is sent. However, Exim proceeds to deliver the message as normal. The control applies only to the current message, not to any subsequent ones that may be received in the same SMTP connection.

The text for the 550 response is taken from the control modifier. If no message is supplied, the following is used:

550-Your message has been rejected but is being
550-kept for evaluation.
550-If it was a legitimate message, it may still be
550 delivered to the target recipient(s).

This facility should be used with extreme caution.

control = freeze

This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in other words, only when a message is being received. If the message is accepted, it is placed on Exim’s queue and frozen. The control applies only to the current message, not to any subsequent ones that may be received in the same SMTP connection.

This modifier can optionally be followed by /no_tell. If the global option freeze_tell is set, it is ignored for the current message (that is, nobody is told about the freezing), provided all the control=freeze modifiers that are obeyed for the current message have the /no_tell option.

control = no_delay_flush

Exim normally flushes SMTP output before implementing a delay in an ACL, to avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in use. This control, as long as it is encountered before the delay modifier, disables such output flushing.

control = no_callout_flush

Exim normally flushes SMTP output before performing a callout in an ACL, to avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in use. This control, as long as it is encountered before the verify condition that causes the callout, disables such output flushing.

control = no_mbox_unspool

This control is available when Exim is compiled with the content scanning extension. Content scanning may require a copy of the current message, or parts of it, to be written in “mbox format” to a spool file, for passing to a virus or spam scanner. Normally, such copies are deleted when they are no longer needed. If this control is set, the copies are not deleted. The control applies only to the current message, not to any subsequent ones that may be received in the same SMTP connection. It is provided for debugging purposes and is unlikely to be useful in production.

control = no_multiline_responses

This control is permitted for any ACL except the one for non-SMTP messages. It seems that there are broken clients in use that cannot handle multiline SMTP responses, despite the fact that RFC 821 defined them over 20 years ago.

If this control is set, multiline SMTP responses from ACL rejections are suppressed. One way of doing this would have been to put out these responses as one long line. However, RFC 2821 specifies a maximum of 512 bytes per response (“use multiline responses for more” it says – ha!), and some of the responses might get close to that. So this facility, which is after all only a sop to broken clients, is implemented by doing two very easy things:

• Extra information that is normally output as part of a rejection caused by sender verification failure is omitted. Only the final line (typically “sender verification failed”) is sent.

• If a message modifier supplies a multiline response, only the first line is output.

The setting of the switch can, of course, be made conditional on the calling host. Its effect lasts until the end of the SMTP connection.

control = no_pipelining

This control turns off the advertising of the PIPELINING extension to SMTP in the current session. To be useful, it must be obeyed before Exim sends its response to an EHLO command. Therefore, it should normally appear in an ACL controlled by acl_smtp_connect or acl_smtp_helo. See also pipelining_advertise_hosts.

control = queue/<options>*

control = queue_only

This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in other words, only when a message is being received. If the message is accepted, it is placed on Exim’s queue and left there for delivery by a subsequent queue runner. If used with no options set, no immediate delivery process is started. In other words, it has the effect as the queue_only global option or -odq command-line option.

If the first_pass_route option is given then the behaviour is like the command-line -oqds option; a delivery process is started which stops short of making any SMTP delivery. The benefit is that the hints database will be updated for the message being waiting for a specific host, and a later queue run will be able to send all such messages on a single connection.

The control only applies to the current message, not to any subsequent ones that may be received in the same SMTP connection.

control = submission/<options>

This control is permitted only for the MAIL, RCPT, and start of data ACLs (the latter is the one defined by acl_smtp_predata). Setting it tells Exim that the current message is a submission from a local MUA. In this case, Exim operates in “submission mode”, and applies certain fixups to the message if necessary. For example, it adds a Date: header line if one is not present. This control is not permitted in the acl_smtp_data ACL, because that is too late (the message has already been created).

Chapter 48 describes the processing that Exim applies to messages. Section 48.1 covers the processing that happens in submission mode; the available options for this control are described there. The control applies only to the current message, not to any subsequent ones that may be received in the same SMTP connection.

control = suppress_local_fixups

This control applies to locally submitted (non TCP/IP) messages, and is the complement of control = submission. It disables the fixups that are normally applied to locally-submitted messages. Specifically:

• Any Sender: header line is left alone (in this respect, it is a dynamic version of local_sender_retain).

• No Message-ID:, From:, or Date: header lines are added.

• There is no check that From: corresponds to the actual sender.

This control may be useful when a remotely-originated message is accepted, passed to some scanning program, and then re-submitted for delivery. It can be used only in the acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, and acl_not_smtp_start ACLs, because it has to be set before the message’s data is read.

Note: This control applies only to the current message, not to any others that are being submitted at the same time using -bs or -bS.

control = utf8_downconvert

This control enables conversion of UTF-8 in message envelope addresses to a-label form. For details see section 60.1.

control = wellknown

This control sets up a response data file for a WELLKNOWN SMTP command. It may only be used in an ACL servicing that command. For details see section 44.8.

14. Summary of message fixup control

All four possibilities for message fixups can be specified:

• Locally submitted, fixups applied: the default.

• Locally submitted, no fixups applied: use control = suppress_local_fixups.

• Remotely submitted, no fixups applied: the default.

• Remotely submitted, fixups applied: use control = submission.

15. Adding header lines in ACLs

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, DKIM, 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).

Headers will not be added to the message if the modifier is used in DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.

Leading and trailing newlines are removed from the data for the add_header modifier; if it then 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 of message headers 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 44.10.

The list of headers yet to be added is given by the $headers_added variable.

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

accept add_header = ADDED: some text
       <some condition>

accept <some condition>
       add_header = ADDED: some text

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.

16. Removing header lines in ACLs

The remove_header modifier can be used to remove one or more header lines from an incoming message, as in this example:

warn   message        = Remove internal headers
       remove_header  = x-route-mail1 : x-route-mail2

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

Headers will not be removed from the message if the modifier is used in DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.

More than one header can be removed at the same time by using a colon separated list of header specifiers. If a specifier does not start with a circumflex (^) then it is treated as a header name. The header name matching is case insensitive. If it does, then it is treated as a (front-anchored) regular expression applied to the whole header.

Note: The colon terminating a header name will need to be doubled if used in an RE, and there can legitimately be whitepace before it.

Example:

remove_header = \N^(?i)Authentication-Results\s*::\s*example.org;\N

List expansion is not performed, so you cannot use hostlists to create a list of headers, however both connection and message variable expansion are performed ($acl_c_* and $acl_m_*), illustrated in this example:

warn   hosts           = +internal_hosts
       set acl_c_ihdrs = x-route-mail1 : x-route-mail2
warn   message         = Remove internal headers
       remove_header   = $acl_c_ihdrs

Header specifiers for removal are accumulated during the MAIL, RCPT, and predata ACLs. Matching header lines are removed from the message before processing the DATA and MIME ACLs. If multiple header lines match, all are removed. There is no harm in attempting to remove the same header twice nor in removing a non-existent header. Further header specifiers for removal may be accumulated during the DATA and MIME ACLs, after which matching headers are removed if present. In the case of non-SMTP messages, remove specifiers are accumulated during the non-SMTP ACLs, and are acted on after all the ACLs have run. If a message is rejected after DATA or by the non-SMTP ACL, there really is no effect because there is no logging of what headers would have been removed.

Header lines are not visible in string expansions until the DATA phase when it is received. Any header lines removed in the MAIL, RCPT, and predata ACLs are not visible in the DATA ACL and MIME ACLs. Similarly, header lines that are removed by the DATA or MIME ACLs are still visible in those ACLs. Because of this restriction, you cannot use header lines as a way of controlling data passed between (for example) the MAIL and RCPT ACLs. If you want to do this, you should instead use ACL variables, as described in section 44.10.

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

accept remove_header = X-Internal
       <some condition>

accept <some condition>
       remove_header = X-Internal

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

Warning: This facility currently applies only to header lines that are present during ACL processing. It does NOT remove header lines that are added in a system filter or in a router or transport.

17. ACL conditions

Some of the 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 45.

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:

acl = <name of acl or ACL string or file name >

The possible values of the argument are the same as for the acl_smtp_xxx options. The named or inline ACL is run. If it returns “accept” the condition is true; if it returns “deny” the condition is false. If it returns “defer”, the current ACL returns “defer” unless the condition is on a warn verb. In that case, a “defer” return makes the condition false. This means that further processing of the warn verb ceases, but processing of the ACL continues.

If the argument is a named ACL, up to nine space-separated optional values can be appended; they appear within the called ACL in $acl_arg1 to $acl_arg9, and $acl_narg is set to the count of values. Previous values of these variables are restored after the call returns. The name and values are expanded separately. Note that spaces in complex expansions which are used as arguments will act as argument separators.

If the nested acl returns “drop” and the outer condition denies access, the connection is dropped. If it returns “discard”, the verb must be accept or discard, and the action is taken immediately – no further conditions are tested.

ACLs may be nested up to 20 deep; the limit exists purely to catch runaway loops. This condition allows you to use different ACLs in different circumstances. For example, different ACLs can be used to handle RCPT commands for different local users or different local domains.

authenticated = <string list>

If the SMTP connection is not authenticated, the condition is false. Otherwise, the name of the authenticator is tested against the list. To test for authentication by any authenticator, you can set

authenticated = *

condition = <string>

This feature allows you to make up custom conditions. If the result of expanding the string is an empty string, the number zero, or one of the strings “no” or “false”, the condition is false. If the result is any non-zero number, or one of the strings “yes” or “true”, the condition is true. For any other value, some error is assumed to have occurred, and the ACL returns “defer”. However, if the expansion is forced to fail, the condition is ignored. The effect is to treat it as true, whether it is positive or negative.

decode = <location>

This condition is available only when Exim is compiled with the content-scanning extension, and it is allowed only in the ACL defined by acl_smtp_mime. It causes the current MIME part to be decoded into a file. If all goes well, the condition is true. It is false only if there are problems such as a syntax error or a memory shortage. For more details, see chapter 45.

dnslists = <list of domain names and other data>

This condition checks for entries in DNS black lists. These are also known as “RBL lists”, after the original Realtime Blackhole List, but note that the use of the lists at mail-abuse.org now carries a charge. There are too many different variants of this condition to describe briefly here. See sections 44.18–44.10 for details.

domains = <domain list>

This condition is relevant only in a RCPT ACL. It checks that the domain of the recipient address is in the domain list. If percent-hack processing is enabled, it is done before this test is done. If the check succeeds with a lookup, the result of the lookup is placed in $domain_data until the next domains test.

Note carefully (because many people seem to fall foul of this): you cannot use domains in a DATA ACL.

encrypted = <string list>

If the SMTP connection is not encrypted, the condition is false. Otherwise, the name of the cipher suite in use is tested against the list. To test for encryption without testing for any specific cipher suite(s), set

encrypted = *

hosts = <host list>

This condition tests that the calling host matches the host list. If you have name lookups or wildcarded host names and IP addresses in the same host list, you should normally put the IP addresses first. For example, you could have:

accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts

The lookup in this example uses the host name for its key. This is implied by the lookup type “dbm”. (For a host address lookup you would use “net-dbm” and it wouldn’t matter which way round you had these two items.)

The reason for the problem with host names lies in the left-to-right way that Exim processes lists. It can test IP addresses without doing any DNS lookups, but when it reaches an item that requires a host name, it fails if it cannot find a host name to compare with the pattern. If the above list is given in the opposite order, the accept statement fails for a host whose name cannot be found, even if its IP address is 10.9.8.7.

If you really do want to do the name check first, and still recognize the IP address even if the name lookup fails, you can rewrite the ACL like this:

accept hosts = dbm;/etc/friendly/hosts
accept hosts = 10.9.8.7

The default action on failing to find the host name is to assume that the host is not in the list, so the first accept statement fails. The second statement can then check the IP address.

If a hosts condition is satisfied by means of a lookup, the result of the lookup is made available in the $host_data variable. This allows you, for example, to set up a statement like this:

deny  hosts = net-lsearch;/some/file
      message = $host_data

which gives a custom error message for each denied host.

local_parts = <local part list>

This condition is relevant only in a RCPT ACL. It checks that the local part of the recipient address is in the list. If percent-hack processing is enabled, it is done before this test. If the check succeeds with a lookup, the result of the lookup is placed in $local_part_data, which remains set until the next local_parts test.

malware = <option>

This condition is available only when Exim is compiled with the content-scanning extension and only after a DATA command. It causes the incoming message to be scanned for viruses. For details, see chapter 45.

mime_regex = <list of regular expressions>

This condition is available only when Exim is compiled with the content-scanning extension, and it is allowed only in the ACL defined by acl_smtp_mime. It causes the current MIME part to be scanned for a match with any of the regular expressions. For details, see chapter 45.

ratelimit = <parameters>

This condition can be used to limit the rate at which a user or host submits messages. Details are given in section 44.20.

recipients = <address list>

This condition is relevant only in a RCPT ACL. It checks the entire recipient address against a list of recipients.

regex = <list of regular expressions>

This condition is available only when Exim is compiled with the content-scanning extension, and is available only in the DATA, MIME, and non-SMTP ACLs. It causes the incoming message to be scanned for a match with any of the regular expressions. For details, see chapter 45.

seen = <parameters>

This condition can be used to test if a situation has been previously met, for example for greylisting. Details are given in section 44.19.

sender_domains = <domain list>

This condition tests the domain of the sender of the message against the given domain list. Note: The domain of the sender address is in $sender_address_domain. It is not put in $domain during the testing of this condition. This is an exception to the general rule for testing domain lists. It is done this way so that, if this condition is used in an ACL for a RCPT command, the recipient’s domain (which is in $domain) can be used to influence the sender checking.

Warning: It is a bad idea to use this condition on its own as a control on relaying, because sender addresses are easily, and commonly, forged.

senders = <address list>

This condition tests the sender of the message against the given list. To test for a bounce message, which has an empty sender, set

senders = :

Warning: It is a bad idea to use this condition on its own as a control on relaying, because sender addresses are easily, and commonly, forged.

spam = <username>

This condition is available only when Exim is compiled with the content-scanning extension. It causes the incoming message to be scanned by SpamAssassin. For details, see chapter 45.

verify = certificate

This condition is true in an SMTP session if the session is encrypted, and a certificate was received from the client, and the certificate was verified. The server requests a certificate only if the client matches tls_verify_hosts or tls_try_verify_hosts (see chapter 43).

verify = csa

This condition checks whether the sending host (the client) is authorized to send email. Details of how this works are given in section 44.26.

verify = header_names_ascii

This condition is relevant only in an ACL that is run after a message has been received. This usually means an ACL specified by acl_smtp_data or acl_not_smtp. It checks all header names (not the content) to make sure there are no non-ASCII characters, also excluding control characters. The allowable characters are decimal ASCII values 33 through 126.

Exim itself will handle headers with non-ASCII characters, but it can cause problems for downstream applications, so this option will allow their detection and rejection in the DATA ACL’s.

verify = header_sender/<options>

This condition is relevant only in an ACL that is run after a message has been received, that is, in an ACL specified by acl_smtp_data or acl_not_smtp. It checks that there is a verifiable address in at least one of the Sender:, Reply-To:, or From: header lines. Such an address is loosely thought of as a “sender” address (hence the name of the test). However, an address that appears in one of these headers need not be an address that accepts bounce messages; only sender addresses in envelopes are required to accept bounces. Therefore, if you use the callout option on this check, you might want to arrange for a non-empty address in the MAIL command.

Details of address verification and the options are given later, starting at section 44.21 (callouts are described in section 44.22). You can combine this condition with the senders condition to restrict it to bounce messages only:

deny    senders = :
       !verify  = header_sender
        message = A valid sender header is required for bounces

verify = header_syntax

This condition is relevant only in an ACL that is run after a message has been received, that is, in an ACL specified by acl_smtp_data or acl_not_smtp. It checks the syntax of all header lines that can contain lists of addresses (Sender:, From:, Reply-To:, To:, Cc:, and Bcc:), returning true if there are no problems. Unqualified addresses (local parts without domains) are permitted only in locally generated messages and from hosts that match sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate.

Note that this condition is a syntax check only. However, a common spamming ploy used to be to send syntactically invalid headers such as

To: @

and this condition can be used to reject such messages, though they are not as common as they used to be.

verify = helo

This condition is true if a HELO or EHLO command has been received from the client host, and its contents have been verified. If there has been no previous attempt to verify the HELO/EHLO contents, it is carried out when this condition is encountered. See the description of the helo_verify_hosts and helo_try_verify_hosts options for details of how to request verification independently of this condition, and for detail of the verification.

For SMTP input that does not come over TCP/IP (the -bs command line option), this condition is always true.

verify = not_blind/<options>

This condition checks that there are no blind (bcc) recipients in the message. Every envelope recipient must appear either in a To: header line or in a Cc: header line for this condition to be true. Local parts are checked case-sensitively; domains are checked case-insensitively. If Resent-To: or Resent-Cc: header lines exist, they are also checked. This condition can be used only in a DATA or non-SMTP ACL.

There is one possible option, case_insensitive. If this is present then local parts are checked case-insensitively.

There are, of course, many legitimate messages that make use of blind (bcc) recipients. This check should not be used on its own for blocking messages.

verify = recipient/<options>

This condition is relevant only after a RCPT command. It verifies the current recipient. Details of address verification are given later, starting at section 44.21. After a recipient has been verified, the value of $address_data is the last value that was set while routing the address. This applies even if the verification fails. When an address that is being verified is redirected to a single address, verification continues with the new address, and in that case, the subsequent value of $address_data is the value for the child address.

verify = reverse_host_lookup/<options>

This condition ensures that a verified host name has been looked up from the IP address of the client host. (This may have happened already if the host name was needed for checking a host list, or if the host matched host_lookup.) Verification ensures that the host name obtained from a reverse DNS lookup, or one of its aliases, does, when it is itself looked up in the DNS, yield the original IP address.

There is one possible option, defer_ok. If this is present and a DNS operation returns a temporary error, the verify condition succeeds.

If this condition is used for a locally generated message (that is, when there is no client host involved), it always succeeds.

verify = sender/<options>

This condition is relevant only after a MAIL or RCPT command, or after a message has been received (the acl_smtp_data or acl_not_smtp ACLs). If the message’s sender is empty (that is, this is a bounce message), the condition is true. Otherwise, the sender address is verified.

If there is data in the $address_data variable at the end of routing, its value is placed in $sender_address_data at the end of verification. This value can be used in subsequent conditions and modifiers in the same ACL statement. It does not persist after the end of the current statement. If you want to preserve the value for longer, you can save it in an ACL variable.

Details of verification are given later, starting at section 44.21. Exim caches the result of sender verification, to avoid doing it more than once per message.

verify = sender=<address>/<options>

This is a variation of the previous option, in which a modified address is verified as a sender.

Note that ’/’ is legal in local-parts; if the address may have such (eg. is generated from the received message) they must be protected from the options parsing by doubling:

verify = sender=${listquote{/}{${address:$h_sender:}}}

18. Using DNS lists

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. (Note that DNS list domains are not mail domains, so the + syntax for named lists doesn’t work - it is used for special options instead.) 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  dnslists = dialups.mail-abuse.org
      message  = X-Warn: sending host is on dialups list

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

There are a number of DNS lists to choose from, some commercial, some free, or free for small deployments. An overview can be found at https://en.wikipedia.org/wiki/Comparison_of_DNS_blacklists.

deny dnslists = black.list.tld/192.168.1.2

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

tld.example.dsn.rfc-ignorant.org

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

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

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

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

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

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

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

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

deny dnslists = spamhaus.example

deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|...

deny    hosts = !+local_networks
        message = $sender_host_address is listed \
                  at $dnslist_domain
        dnslists = rbl-plus.mail-abuse.example

deny dnslists = rblplus.mail-abuse.org=127.0.0.2

deny  dnslists = a.b.c=127.0.0.2,127.0.0.3

deny dnslists = dsn.rfc-ignorant.org\
                =127.0.0.2/$sender_address_domain

dnslists = a.b.c&0.0.0.3

dnslists = a.b.c&0.0.0.1,0.0.0.2

deny  dnslists = a.b.c=127.0.0.2,127.0.0.3

deny  dnslists = a.b.c!=127.0.0.2,127.0.0.3

deny  dnslists = a.b.c
     !dnslists = a.b.c=127.0.0.2,127.0.0.3

deny  dnslists = sbl.spamhaus.org : \
                 list.dsbl.org : \
                 dnsbl.njabl.org!=127.0.0.3 : \
                 relays.ordb.org

deny  dnslists = sbl.spamhaus.org : \
                 list.dsbl.org
deny  dnslists = dnsbl.njabl.org
     !dnslists = dnsbl.njabl.org=127.0.0.3
deny  dnslists = relays.ordb.org

deny dnslists = zen.spamhaus.org!&0.255.255.0

dnslists = a.b.c=127.0.0.1

deny   dnslists = \
         sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \
         dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
       message  = \
         rejected because $sender_host_address is blacklisted \
         at $dnslist_domain\n$dnslist_text

deny dnslists = \
         http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
         socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
         misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
         dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10

1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8.
  f.f.f.f.e.f.f.3.blackholes.mail-abuse.org

*.3.some.list.example.    A    127.0.0.1

deny   condition = ${if isip4{$sender_host_address}}
       dnslists  = some.list.example

       dnslists = <; dnsbl.example.com/<|$acl_m_addrslist

19. Previously seen user and hosts

The seen ACL condition can be used to test whether a situation has been previously met. It uses a hints database to record a timestamp against a key. The syntax of the condition is:

seen = <optional flag><time interval> / <options>

For example,

defer	seen = -5m / key=${sender_host_address}_$local_part@$domain

in a RCPT ACL will implement simple greylisting.

The parameters for the condition are a possible minus sign, then an interval, then, slash-separated, a list of options. The interval is taken as an offset before the current time, and used for the test. If the interval is preceded by a minus sign then the condition returns whether a record is found which is before the test time. Otherwise, the condition returns whether one is found which is since the test time.

Options are read in order with later ones overriding earlier ones.

The default key is $sender_host_address. An explicit key can be set using a key=value option.

If a readonly option is given then no record create or update is done. If a write option is given then a record create or update is always done. An update is done if the test is for “since”. If none of those hold and there was no existing record, a record is created.

Creates and updates are marked with the current time.

Finally, a “before” test which succeeds, and for which the record is old enough, will be refreshed with a timestamp of the test time. This can prevent tidying of the database from removing the entry. The interval for this is, by default, 10 days. An explicit interval can be set using a refresh=value option.

Note that “seen” should be added to the list of hints databases for maintenance if this ACL condition is used.

20. Rate limiting incoming messages

The ratelimit ACL condition can be used to measure and control the rate at which clients can send email. This is more powerful than the smtp_ratelimit_* options, because those options control the rate of commands in a single SMTP session only, whereas the ratelimit condition works across all connections (concurrent and sequential) from the same client host. The syntax of the ratelimit condition is:

ratelimit = <m> / <p> / <options> / <key>

If the average client sending rate is less than m messages per time period p then the condition is false; otherwise it is true.

As a side-effect, the ratelimit condition sets the expansion variable $sender_rate to the client’s computed rate, $sender_rate_limit to the configured value of m, and $sender_rate_period to the configured value of p.

The parameter p is the smoothing time constant, in the form of an Exim time interval, for example, 8h for eight hours. A larger time constant means that it takes Exim longer to forget a client’s past behaviour. The parameter m is the maximum number of messages that a client is permitted to send in each time interval. It also specifies the number of messages permitted in a fast burst. By increasing both m and p but keeping m/p constant, you can allow a client to send more messages in a burst without changing its long-term sending rate limit. Conversely, if m and p are both small, messages must be sent at an even rate.

There is a script in util/ratelimit.pl which extracts sending rates from log files, to assist with choosing appropriate settings for m and p when deploying the ratelimit ACL condition. The script prints usage instructions when it is run with no arguments.

The key is used to look up the data for calculating the client’s average sending rate. This data is stored in Exim’s spool directory, alongside the retry and other hints databases. The default key is $sender_host_address, which means Exim computes the sending rate of each client host IP address. By changing the key you can change how Exim identifies clients for the purpose of ratelimiting. For example, to limit the sending rate of each authenticated user, independent of the computer they are sending from, set the key to $authenticated_id. You must ensure that the lookup key is meaningful; for example, $authenticated_id is only meaningful if the client has authenticated (which you can check with the authenticated ACL condition).

The lookup key does not have to identify clients: If you want to limit the rate at which a recipient receives messages, you can use the key $local_part@$domain with the per_rcpt option (see below) in a RCPT ACL.

Each ratelimit condition can have up to four options. A per_* option specifies what Exim measures the rate of, for example, messages or recipients or bytes. You can adjust the measurement using the unique= and/or count= options. You can also control when Exim updates the recorded rate using a strict, leaky, or readonly option. The options are separated by a slash, like the other parameters. They may appear in any order.

Internally, Exim appends the smoothing constant p onto the lookup key with any options that alter the meaning of the stored data. The limit m is not stored, so you can alter the configured maximum rate and Exim will still remember clients’ past behaviour. If you change the per_* mode or add or remove the unique= option, the lookup key changes so Exim will forget past behaviour. The lookup key is not affected by changes to the update mode and the count= option.

acl_check_connect:
 deny ratelimit = 100 / 5m / readonly
      log_message = RATE CHECK: $sender_rate/$sender_rate_period \
                  (max $sender_rate_limit)
# ...
acl_check_mail:
 warn ratelimit = 100 / 5m / strict
      log_message = RATE UPDATE: $sender_rate/$sender_rate_period \
                  (max $sender_rate_limit)

        ln(peakrate/maxrate)

# Log all senders' rates
warn ratelimit = 0 / 1h / strict
     log_message = Sender rate $sender_rate / $sender_rate_period

# Slow down fast senders; note the need to truncate $sender_rate
# at the decimal point.
warn ratelimit = 100 / 1h / per_rcpt / strict
     delay     = ${eval: ${sg{$sender_rate}{[.].*}{}} - \
                   $sender_rate_limit }s

# Keep authenticated users under control
deny authenticated = *
     ratelimit = 100 / 1d / strict / $authenticated_id

# System-wide rate limit
defer ratelimit = 10 / 1s / $primary_hostname
      message = Sorry, too busy. Try again later.

# Restrict incoming rate from each host, with a default
# set using a macro and special cases looked up in a table.
defer ratelimit = ${lookup {$sender_host_address} \
                   cdb {DB/ratelimits.cdb} \
                   {$value} {RATELIMIT} }
      message = Sender rate exceeds $sender_rate_limit \
               messages per $sender_rate_period

21. Address verification

Several of the verify conditions described in section 44.17 cause addresses to be verified. Section 44.24 discusses the reporting of sender verification failures. The verification conditions can be followed by options that modify the verification process. The options are separated from the keyword and from each other by slashes, and some of them contain parameters. For example:

verify = sender/callout
verify = recipient/defer_ok/callout=10s,defer_ok

The first stage of address verification, which always happens, is to run the address through the routers, in “verify mode”. Routers can detect the difference between verification and routing for delivery, and their actions can be varied by a number of generic options such as verify and verify_only (see chapter 15). If routing fails, verification fails. The available options are as follows:

• If the callout option is specified, successful routing to one or more remote hosts is followed by a “callout” to those hosts as an additional check. Callouts and their sub-options are discussed in the next section.

• If there is a defer error while doing verification routing, the ACL normally returns “defer”. However, if you include defer_ok in the options, the condition is forced to be true instead. Note that this is a main verification option as well as a suboption for callouts.

• The no_details option is covered in section 44.24, which discusses the reporting of sender address verification failures.

• The success_on_redirect option causes verification always to succeed immediately after a successful redirection. By default, if a redirection generates just one address, that address is also verified. See further discussion in section 44.25.

• If the quota option is specified for recipient verify, successful routing to an appendfile transport is followed by a call into the transport to evaluate the quota status for the recipient. No actual delivery is done, but verification will succeed if the quota is sufficient for the message (if the sender gave a message size) or not already exceeded (otherwise).

After an address verification failure, $acl_verify_message contains the error message that is associated with the failure. It can be preserved by coding like this:

warn  !verify = sender
       set acl_m0 = $acl_verify_message

If you are writing your own custom rejection message or log message when denying access, you can use this variable to include information about the verification failure. This variable is cleared at the end of processing the ACL verb.

In addition, $sender_verify_failure or $recipient_verify_failure (as appropriate) contains one of the following words:

• qualify: The address was unqualified (no domain), and the message was neither local nor came from an exempted host.

• route: Routing failed.

• mail: Routing succeeded, and a callout was attempted; rejection occurred at or before the MAIL command (that is, on initial connection, HELO, or MAIL).

• recipient: The RCPT command in a callout was rejected.

• postmaster: The postmaster check in a callout was rejected.

• quota: The quota check for a local recipient did non pass.

The main use of these variables is expected to be to distinguish between rejections of MAIL and rejections of RCPT in callouts.

The above variables may also be set after a successful address verification to:

• random: A random local-part callout succeeded

22. Callout verification

For non-local addresses, routing verifies the domain, but is unable to do any checking of the local part. There are situations where some means of verifying the local part is desirable. One way this can be done is to make an SMTP callback to a delivery host for the sender address or a callforward to a subsequent host for a recipient address, to see if the host accepts the address. We use the term callout to cover both cases. Note that for a sender address, the callback is not to the client host that is trying to deliver the message, but to one of the hosts that accepts incoming mail for the sender’s domain.

Exim does not do callouts by default. If you want them to happen, you must request them by setting appropriate options on the verify condition, as described below. This facility should be used with care, because it can add a lot of resource usage to the cost of verifying an address. However, Exim does cache the results of callouts, which helps to reduce the cost. Details of caching are in section 44.2.

Recipient callouts are usually used only between hosts that are controlled by the same administration. For example, a corporate gateway host could use callouts to check for valid recipients on an internal mailserver. A successful callout does not guarantee that a real delivery to the address would succeed; on the other hand, a failing callout does guarantee that a delivery would fail.

If the callout option is present on a condition that verifies an address, a second stage of verification occurs if the address is successfully routed to one or more remote hosts. The usual case is routing by a dnslookup or a manualroute router, where the router specifies the hosts. However, if a router that does not set up hosts routes to an smtp transport with a hosts setting, the transport’s hosts are used. If an smtp transport has hosts_override set, its hosts are always used, whether or not the router supplies a host list. Callouts are only supported on smtp transports.

The port that is used is taken from the transport, if it is specified and is a remote transport. (For routers that do verification only, no transport need be specified.) Otherwise, the default SMTP port is used. If a remote transport specifies an outgoing interface, this is used; otherwise the interface is not specified. Likewise, the text that is used for the HELO command is taken from the transport’s helo_data option; if there is no transport, the value of $smtp_active_hostname is used.

For a sender callout check, Exim makes SMTP connections to the remote hosts, to test whether a bounce message could be delivered to the sender address. The following SMTP commands are sent:

HELO <local host name>
MAIL FROM:<>
RCPT TO:<the address to be tested>
QUIT

LHLO is used instead of HELO if the transport’s protocol option is set to “lmtp”.

The callout may use EHLO, AUTH and/or STARTTLS given appropriate option settings.

A recipient callout check is similar. By default, it also uses an empty address for the sender. This default is chosen because most hosts do not make use of the sender address when verifying a recipient. Using the same address means that a single cache entry can be used for each recipient. Some sites, however, do make use of the sender address when verifying. These are catered for by the use_sender and use_postmaster options, described in the next section.

If the response to the RCPT command is a 2xx code, the verification succeeds. If it is 5xx, the verification fails. For any other condition, Exim tries the next host, if any. If there is a problem with all the remote hosts, the ACL yields “defer”, unless the defer_ok parameter of the callout option is given, in which case the condition is forced to succeed.

A callout may take a little time. For this reason, Exim normally flushes SMTP output before performing a callout in an ACL, to avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in use. The flushing can be disabled by using a control modifier to set no_callout_flush.

A recipient callout which gets a 2xx code will assign untainted values to the $domain_data and $local_part_data variables, corresponding to the domain and local parts of the recipient address.

verify = recipient/callout=10s,defer_ok

MAIL FROM:<>

23. Quota caching

Exim caches the results of quota verification in order to reduce the amount of resources used. The “callout” hints database is used.

The default cache periods are five minutes for a positive (good) result and one hour for a negative result. To change the periods the quota option can be followed by an equals sign and a number of optional paramemters, separated by commas. For example:

verify = recipient/quota=cachepos=1h,cacheneg=1d

Possible parameters are:

cachepos = <time interval>

Set the lifetime for a positive cache entry. A value of zero seconds is legitimate.

cacheneg = <time interval>

As above, for a negative entry.

no_cache

Set both positive and negative lifetimes to zero.

24. Sender address verification reporting

See section 44.21 for a general discussion of verification. When sender verification fails in an ACL, the details of the failure are given as additional output lines before the 550 response to the relevant SMTP command (RCPT or DATA). For example, if sender callout is in use, you might see:

MAIL FROM:<xyz@abc.example>
250 OK
RCPT TO:<pqr@def.example>
550-Verification failed for <xyz@abc.example>
550-Called:   192.168.34.43
550-Sent:     RCPT TO:<xyz@abc.example>
550-Response: 550 Unknown local part xyz in <xyz@abc.example>
550 Sender verification failed

If more than one RCPT command fails in the same way, the details are given only for the first of them. However, some administrators do not want to send out this much information. You can suppress the details by adding /no_details to the ACL statement that requests sender verification. For example:

verify = sender/no_details

25. Redirection while verifying

A dilemma arises when a local address is redirected by aliasing or forwarding during verification: should the generated addresses themselves be verified, or should the successful expansion of the original address be enough to verify it? By default, Exim takes the following pragmatic approach:

• When an incoming address is redirected to just one child address, verification continues with the child address, and if that fails to verify, the original verification also fails.

• When an incoming address is redirected to more than one child address, verification does not continue. A success result is returned.

This seems the most reasonable behaviour for the common use of aliasing as a way of redirecting different local parts to the same mailbox. It means, for example, that a pair of alias entries of the form

A.Wol:   aw123
aw123:   :fail: Gone away, no forwarding address

work as expected, with both local parts causing verification failure. When a redirection generates more than one address, the behaviour is more like a mailing list, where the existence of the alias itself is sufficient for verification to succeed.

It is possible, however, to change the default behaviour so that all successful redirections count as successful verifications, however many new addresses are generated. This is specified by the success_on_redirect verification option. For example:

require verify = recipient/success_on_redirect/callout=10s

In this example, verification succeeds if a router generates a new address, and the callout does not occur, because no address was routed to a remote host.

When verification is being tested via the -bv option, the treatment of redirections is as just described, unless the -v or any debugging option is also specified. In that case, full verification is done for every generated address and a report is output for each of them.

26. Client SMTP authorization (CSA)

Client SMTP Authorization is a system that allows a site to advertise which machines are and are not permitted to send email. This is done by placing special SRV records in the DNS; these are looked up using the client’s HELO domain. At the time of writing, CSA is still an Internet Draft. Client SMTP Authorization checks in Exim are performed by the ACL condition:

verify = csa

This fails if the client is not authorized. If there is a DNS problem, or if no valid CSA SRV record is found, or if the client is authorized, the condition succeeds. These three cases can be distinguished using the expansion variable $csa_status, which can take one of the values “fail”, “defer”, “unknown”, or “ok”. The condition does not itself defer because that would be likely to cause problems for legitimate email.

The error messages produced by the CSA code include slightly more detail. If $csa_status is “defer”, this may be because of problems looking up the CSA SRV record, or problems looking up the CSA target address record. There are four reasons for $csa_status being “fail”:

• The client’s host name is explicitly not authorized.

• The client’s IP address does not match any of the CSA target IP addresses.

• The client’s host name is authorized but it has no valid target IP addresses (for example, the target’s addresses are IPv6 and the client is using IPv4).

• The client’s host name has no CSA SRV record but a parent domain has asserted that all subdomains must be explicitly authorized.

The csa verification condition can take an argument which is the domain to use for the DNS query. The default is:

verify = csa/$sender_helo_name

This implementation includes an extension to CSA. If the query domain is an address literal such as [192.0.2.95], or if it is a bare IP address, Exim searches for CSA SRV records in the reverse DNS as if the HELO domain was (for example) 95.2.0.192.in-addr.arpa. Therefore it is meaningful to say:

verify = csa/$sender_host_address

In fact, this is the check that Exim performs if the client does not say HELO. This extension can be turned off by setting the main configuration option dns_csa_use_reverse to be false.

If a CSA SRV record is not found for the domain itself, a search is performed through its parent domains for a record which might be making assertions about subdomains. The maximum depth of this search is limited using the main configuration option dns_csa_search_limit, which is 5 by default. Exim does not look for CSA SRV records in a top level domain, so the default settings handle HELO domains as long as seven (hostname.five.four.three.two.one.com). This encompasses the vast majority of legitimate HELO domains.

The dnsdb lookup also has support for CSA. Although dnsdb also supports direct SRV lookups, this is not sufficient because of the extra parent domain search behaviour of CSA, and (as with PTR lookups) dnsdb also turns IP addresses into lookups in the reverse DNS space. The result of a successful lookup such as:

${lookup dnsdb {csa=$sender_helo_name}}

has two space-separated fields: an authorization code and a target host name. The authorization code can be “Y” for yes, “N” for no, “X” for explicit authorization required but absent, or “?” for unknown.

27. Bounce address tag validation

Bounce address tag validation (BATV) is a scheme whereby the envelope senders of outgoing messages have a cryptographic, timestamped “tag” added to them. Genuine incoming bounce messages should therefore always be addressed to recipients that have a valid tag. This scheme is a way of detecting unwanted bounce messages caused by sender address forgeries (often called “collateral spam”), because the recipients of such messages do not include valid tags.

There are two expansion items to help with the implementation of the BATV “prvs” (private signature) scheme in an Exim configuration. This scheme signs the original envelope sender address by using a simple key to add a hash of the address and some time-based randomizing information. The prvs expansion item creates a signed address, and the prvscheck expansion item checks one. The syntax of these expansion items is described in section 11.5. The validity period on signed addresses is seven days.

As an example, suppose the secret per-address keys are stored in an MySQL database. A query to look up the key for an address could be defined as a macro like this:

PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \
                WHERE sender='${quote_mysql:$prvscheck_address}'\
                }{$value}}

Suppose also that the senders who make use of BATV are defined by an address list called batv_senders. Then, in the ACL for RCPT commands, you could use this:

# Bounces: drop unsigned addresses for BATV senders
deny senders = :
     recipients = +batv_senders
     message = This address does not send an unsigned reverse path

# Bounces: In case of prvs-signed address, check signature.
deny senders = :
     condition  = ${prvscheck {$local_part@$domain}\
                  {PRVSCHECK_SQL}{1}}
     !condition = $prvscheck_result
     message = Invalid reverse path signature.

The first statement rejects recipients for bounce messages that are addressed to plain BATV sender addresses, because it is known that BATV senders do not send out messages with plain sender addresses. The second statement rejects recipients that are prvs-signed, but with invalid signatures (either because the key is wrong, or the signature has timed out).

A non-prvs-signed address is not rejected by the second statement, because the prvscheck expansion yields an empty string if its first argument is not a prvs-signed address, thus causing the condition condition to be false. If the first argument is a syntactically valid prvs-signed address, the yield is the third string (in this case “1”), whether or not the cryptographic and timeout checks succeed. The $prvscheck_result variable contains the result of the checks (empty for failure, “1” for success).

There is one more issue you must consider when implementing prvs-signing: you have to ensure that the routers accept prvs-signed addresses and deliver them correctly. The easiest way to handle this is to use a redirect router to remove the signature with a configuration along these lines:

batv_redirect:
  driver = redirect
  data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}}

This works because, if the third argument of prvscheck is empty, the result of the expansion of a prvs-signed address is the decoded value of the original address. This router should probably be the first of your routers that handles local addresses.

To create BATV-signed addresses in the first place, a transport of this form can be used:

external_smtp_batv:
  driver = smtp
  return_path = ${prvs {$return_path} \
                       {${lookup mysql{SELECT \
                       secret FROM batv_prvs WHERE \
                       sender='${quote_mysql:$sender_address}'} \
                       {$value}fail}}}

If no key can be found for the existing return path, no signing takes place.

28. Using an ACL to control relaying

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. Redirecting a local address via an alias or forward file and then passing the message on to another host is not relaying, but a redirection as a result of the “percent hack” is.

Two kinds of relaying exist, which are 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. On the other hand, 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, but in principle these two kinds of relaying are entirely independent. What is not wanted is the transmission of mail from arbitrary remote hosts through your system to arbitrary domains.

You can implement relay control by means of suitable statements in the ACL that runs for each RCPT command. For convenience, it is often easiest to use Exim’s named list facility to define the domains and hosts involved. For example, suppose you want to do the following:

• Deliver a number of domains to mailboxes on the local host (or process them locally in some other way). Let’s say these are my.dom1.example and my.dom2.example.

• Relay mail for a number of other domains for which you are the secondary MX. These might be friend1.example and friend2.example.

• Relay mail from the hosts on your local LAN, to whatever domains are involved. Suppose your LAN is 192.168.45.0/24.

In the main part of the configuration, you put the following definitions:

domainlist local_domains    = my.dom1.example : my.dom2.example
domainlist relay_to_domains = friend1.example : friend2.example
hostlist   relay_from_hosts = 192.168.45.0/24

Now you can use these definitions in the ACL that is run for every RCPT command:

acl_check_rcpt:
  accept domains = +local_domains : +relay_to_domains
  accept hosts   = +relay_from_hosts

The first statement accepts any RCPT command that contains an address in the local or relay domains. For any other domain, control passes to the second statement, which accepts the command only if it comes from one of the relay hosts. In practice, you will probably want to make your ACL more sophisticated than this, for example, by including sender and recipient verification. The default configuration includes a more comprehensive example, which is described in chapter 7.

29. Checking a relay configuration

You can check the relay characteristics of your configuration in the same way that you can test any ACL behaviour for an incoming SMTP connection, by using the -bh option to run a fake SMTP session with which you interact.