Previous Next Contents (Exim 4.30 Specification)

38. Access control lists

Access Control Lists (ACLs) are defined in a separate section of the run time configuration file, headed by “begin acl”. Each ACL definition starts with a name, terminated by a colon. Here is a complete ACL section which contains just one very small ACL:

  begin acl
  
  small_acl:
    accept   hosts = one.host.only

You can have as many lists as you like in the ACL section, and the order in which they appear does not matter. The lists are self-terminating.

The majority of ACLs are used to control Exim's behaviour when it receives certain SMTP commands. This applies both to incoming TCP/IP connections, and when a local process submits a message over a pipe (using the -bs option). The most common use is for controlling which recipients are accepted in incoming messages. In addition, you can also define an ACL that is used to check local non-SMTP messages. The default configuration file contains an example of a realistic ACL for checking RCPT commands. This is discussed in chapter 7.

38.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. The host relay-test.mail-abuse.org provides a service for checking your relaying configuration (see section 38.27 for more details).

38.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:

  acl_not_smtp   ACL for non-SMTP messages

  acl_smtp_auth   ACL for AUTH

  acl_smtp_connect   ACL for start of SMTP connection

  acl_smtp_data   ACL after DATA

  acl_smtp_etrn   ACL for ETRN

  acl_smtp_expn   ACL for EXPN

  acl_smtp_helo   ACL for HELO or EHLO

  acl_smtp_mail   ACL for MAIL

  acl_smtp_mailauth   ACL for the AUTH parameter of MAIL

  acl_smtp_rcpt   ACL for RCPT

  acl_smtp_starttls   ACL for STARTTLS

  acl_smtp_vrfy   ACL for VRFY

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.

However, you cannot test the contents of the message, for example, to verify addresses in the headers, at RCPT time. Such tests have to appear in the ACL that is run after the message has been received, before the final response to the DATA command is sent. This is the ACL specified by acl_smtp_data. At this time, it is no longer possible to reject individual recipients. An error response should reject the entire message. Unfortunately, it is known that some MTAs do not treat hard (5xx) errors correctly at this point – they keep the message on their queues and try again later, but that is their problem, though it does waste some of your resources.

The ACL test specified by acl_smtp_connect happens after the test specified by host_reject_connection (which is now an anomaly) and any TCP Wrappers testing (if configured).

The non-SMTP ACL applies to all non-interactive incoming messages, that is, it applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not really SMTP.) This ACL is run just before the local_scan() function. Any kind of rejection is treated as permanent, because there is no way of sending a temporary error for these kinds of message. Many of the ACL conditions (for example, host tests, and tests on the state of the SMTP connection such as encryption and authentication) are not relevant and are forbidden in this ACL.

38.3. ACL return codes

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.

The 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 great 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 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 local_scan() function is always run, even if there are no remaining recipients; it may create new recipients.

38.4. Unset ACL options

The default actions when any of the acl_smtp_xxx options are unset are not all the same.

For acl_not_smtp, acl_smtp_auth, acl_smtp_connect, acl_smtp_data, acl_smtp_helo, acl_smtp_mail, acl_smtp_mailauth, and acl_smtp_starttls, the default action is “accept”.

For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy), the default action 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.

38.5. Data for message ACLs

When an ACL for MAIL, RCPT, or DATA is being run, 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.

When an ACL for the AUTH parameter of MAIL is being run, the variables that contain information about the host are set, but $sender_address is not yet set.

The $message_size variable is set to the value of the SIZE parameter on the MAIL command at MAIL and RCPT time, or -1 if that parameter was not given. Its value is updated to the true message size by the time the ACL after DATA is run.

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, $rcpt_count contains the total number of RCPT commands, and $recipients_count contains the total number of accepted recipients.

38.6. Data for non-message ACLs

When an ACL for AUTH, ETRN, EXPN, STARTTLS, or VRFY is being run, the remainder of the SMTP command line is placed in $smtp_command_argument. This 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}{yes}{no}}
    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.)

38.7. Use of the ACL selection options

The value of an acl_smtp_xxx option is expanded before use, so you can use different ACLs in different circumstances, and in fact the resulting string does not have to be the name of a configured list. Having expanded the string, Exim searches for an ACL as follo Exim 4.30 Specification Concepts

Concepts

A B C D E F G H I J K L M N O P Q R S T U V W X “

`acl_not_smtp`	ACL for non-SMTP messages
`acl_smtp_auth`	ACL for AUTH
`acl_smtp_connect`	ACL for start of SMTP connection
`acl_smtp_data`	ACL after DATA
`acl_smtp_etrn`	ACL for ETRN
`acl_smtp_expn`	ACL for EXPN
`acl_smtp_helo`	ACL for HELO or EHLO
`acl_smtp_mail`	ACL for MAIL
`acl_smtp_mailauth`	ACL for the AUTH parameter of MAIL
`acl_smtp_rcpt`	ACL for RCPT
`acl_smtp_starttls`	ACL for STARTTLS
`acl_smtp_vrfy`	ACL for VRFY