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 “

The Exim FAQ

This is the FAQ for the Exim Mail Transfer Agent. Many thanks to the many people who provided the original information. This file would be amazingly cluttered if I tried to list them all. Suggestions for corrections, improvements, and additions are always welcome.

This version of the FAQ applies to Exim 4.00 and later releases. It has been extensively revised, and material that was relevant only to earlier releases has been removed. As this caused some whole sections to disappear, I've taken the opportunity to re-arrange the sections and renumber everything except the configuration samples.

References of the form Cnnn, Fnnn, Lnnn, and Snnn are to the sample configuration, filter, local_scan(), and “useful script” files. These are hyperlinked from the HTML version of this FAQ. They can also be found in the separately distributed directory called config.samples. The primary location is

ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/config.samples.tar.gz ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/config.samples.tar.bz2

There are brief descriptions of these files at the end of this document.

Philip Hazel
Last update: 31-March-2004

Index

A Keyword-in-context index to the questions is available. This is usually the quickest way to find information in the FAQ.

The FAQ is divided into the following sections:

	0. General debugging	15. UUCP
	1. Building and installing	16. Modifying message bodies
	2. Routing in general	17. Encryption (TLS/SSL)
	3. Routing to remote hosts	20. Millennium
	4. Routing for local delivery	50. Miscellaneous
	5. Filtering	91. Mac OS X
	6. Delivery	92. Freebsd
	7. Policy controls	93. HP-UX
	8. Rewriting addresses	94. BSDI
	9. Headers	95. IRIX
	10. Performance	96. Linux
	11. Majordomo	97. Sun systems
	12. Fetchmail	98. Configuration cookbook
	13. Perl	99. List of sample configurations
	14. Dial-up and ISDN

List of questions

0. GENERAL DEBUGGING

Q0001: Exim is crashing. What is wrong?
Q0002: Exim is not working. What is wrong? How can I check what it is doing?
Q0003: What does the error Child process of address_pipe transport returned 69 from command xxx mean?
Q0004: My virtual domain setup isn't working. How can I debug it?
Q0005: Why is Exim not rejecting incoming messages addressed to non-existent users at SMTP time?
Q0006: I've put an entry for *.my.domain in a DBM lookup file, but it isn't getting recognized.
Q0007: I've put the entry *@domain.com in a lookup database, but it isn't working. The expansion I'm using is:
Q0008: If I run ./exim -d -bt user@domain all seems well, but when I send a message from my User Agent, it does not arrive at its destination.
Q0009: What does no immediate delivery: too many messages received in one SMTP connection mean?
Q0010: Exim puts for <address> in the Received: headers of some, but not all, messages. Is this a bug?
Q0011: Instead of exim_dbmbuild, I'm using a homegrown program to build DBM (or cdb) files, but Exim doesn't seem to be able to use them.
Q0012: Exim is unable to route to any remote domains. It doesn't seen to be able to access the DNS.
Q0013: What does the error message transport system_aliases: cannot find transport driver "redirect" in line 92 mean?
Q0014: Exim is timing out after receiving and responding to the DATA command from one particular host, and yet the client host also claims to be timing out. This seems to affect only certain messages.
Q0015: What does the message Socket bind() to port 25 for address (any) failed: address already in use mean?
Q0016: I've set verify = header_syntax in my ACL, but this causes Exim to complain about header lines like To: Work: Jim <jims@email>, Home: Bob <bobs@email> which look all right to me. Is this a bug?
Q0017: Whenever Exim tries to deliver a specific message to a particular server, it fails, giving the error Remote end closed connection after data or Broken pipe or a timeout. What's going on?
Q0018: Why do messages not get delivered down the same connection when I do something like: exim -v -R @aol.com? For other domains, I do this and I see the appropriate waiting for passed connections to get used messages.
Q0019: There seems to be a problem in the string expansion code: it doesn't recognize references to headers such as ${h_to}.
Q0020: Why do connections to my machine's SMTP port take a long time to respond with the banner, when connections to other ports respond instantly? The delay is sometimes as long as 30 seconds.
Q0021: What does failed to create child process to send failure message mean? This is a busy mail server with smtp_accept_max set to 500, but this problem started to occur at about 300 incoming connections.
Q0022: What does No transport set by system filter in a log line mean?
Q0023: Why is Exim refusing to relay, saying failed to find host name from IP address when I have the sender's IP address in an ACL condition? My configuration contains this ACL statement:
Q0024: When I run exim -bd -q10m I get PANIC LOG: exec of exim -q failed.
Q0025: I can't seem to get a pipe command to run when I include a ${if expansion in it. This fails:
Q0026: I'm trying to get Exim to connect an alias to a pipe, but it always gives error code 69, with the comment (could mean service or program unavailable).
Q0027: What does the error Spool file is locked mean?
Q0028: Exim is reporting IP addresses as 0.0.0.0 or 255.255.255.255 instead of their correct values. What's going on?
Q0029: I can't seem to figure out why PAM support doesn't work correctly.
Q0030: I'm trying to use a query-style lookup for hosts that are allowed to relay, but it is giving really weird errors.
Q0031: Exim is rejecting connections from hosts that have more than one IP address, for no apparent reason.
Q0032: Exim is failing to find the MySQL library, even though is it present within LD_LIBRARY_PATH. I'm getting this error:
Q0033: What does the error lookup of host "xx.xx.xx" failed in yyy router mean?
Q0034: Exim works fine on one host, but when I copied the binary to another identical host, it stopped working (it could not resolve DNS names).
Q0035: I set a hosts condition in an ACL to do a lookup in a file of IP addresses, but it doesn't work.
Q0036: Why do I get the error Permission denied: creating lock file hitching post when Exim tries to do a local delivery?
Q0037: I am experiencing mailbox locking problems with Sun's mailtool used over a network.
Q0038: What does the error message error in forward file (filtering not enabled): missing or malformed local part mean?
Q0039: I have installed Exim, but now I can't mail to root any more. Why is this?
Q0040: How can I stop undeliverable bounce messages (e.g. to rout

`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