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 that 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 using SMTP by specifying the -bs option. The most common use is for controlling which recipients are accepted in incoming messages. In addition, you can 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.
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 39.37 for more details).
In order to cause an ACL to be used, you have to name it in one of the relevant options in the main part of the configuration. These options are:
| 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 is complete |
| 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_mime | ACL for content-scanning MIME parts |
| acl_smtp_predata | ACL at start of DATA command |
| acl_smtp_quit | ACL for QUIT |
| 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.
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.
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).
Two ACLs are associated with the DATA command, because it is two-stage command, with two responses being sent to the client. When the DATA command is received, the ACL defined by acl_smtp_predata is obeyed. This gives you control after all the RCPT commands, but before the message itself is received. It offers the opportunity to give a negative response to the DATA command before the data is transmitted. Header lines added by MAIL or RCPT ACLs are not visible at this time, but any that are defined here are visible when the acl_smtp_data ACL is run.
You cannot test the contents of the message, for example, to verify addresses in the headers, at RCPT time or when the DATA command is received. Such tests have to appear in the ACL that is run after the message itself has been received, before the final response to the DATA command is sent. This is the ACL specified by acl_smtp_data, which is the second ACL that is associated with the DATA command.
For both of these ACLs, it is not possible to reject individual recipients. An error response rejects the entire message. Unfortunately, it is known that some MTAs do not treat hard (5xx) responses to the DATA command (either before or after the data) correctly – they keep the message on their queues and try again later, but that is their problem, though it does waste some of your resources.
The acl_smtp_mime option is available only when Exim is compiled with the content-scanning extension. For details, see chapter 40.
The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL does not affect the response code to QUIT, which is always 221. Thus, the ACL does not in fact control any access. For this reason, the only verbs that are permitted are accept and warn.
This ACL can be used for tasks such as custom logging at the end of an SMTP session. For example, you can use ACL variables in other ACLs to count messages, recipients, etc., and log the totals at QUIT time using one or more logwrite modifiers on a warn verb.
You do not need to have a final accept, but if you do, you can use a message modifier to specify custom text that is sent as part of the 221 response to QUIT.
This ACL is run only for a “normal” QUIT. For certain kinds of disastrous failure (for example, failure to open a log file, or when Exim is bombing out because it has detected an unrecoverable error), all SMTP commands from the client are given temporary error responses until QUIT is received or the connection is closed. In these special cases, the QUIT ACL does not run.
The value of an acl_smtp_xxx option is expanded before use, so you can use different ACLs in different circumstances. The resulting 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 file name, 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.
Except for the QUIT ACL, which does not affect the SMTP return code (see section 39.7 above), the result of running an ACL is either “accept” or “deny”, or, if some test cannot be completed (for example, if a database is down), “defer”. These results cause 2xx, 5xx, and 4xx return codes, respectively, to be used in the SMTP dialogue. A fourth return, “error”, occurs when there is an error such as invalid syntax in the ACL. This also causes a 4xx return code.
For the non-SMTP ACL, “defer” and “error” are treated in the same way as “deny”, because there is no mechanism for passing temporary errors to the submitters of non-SMTP messages.
ACLs that are relevant to message reception may also return “discard”. This has the effect of “accept”, but causes either the entire message or an individual recipient address to be discarded. In other words, it is a blackholing facility. Use it with care.
If the ACL for MAIL returns “discard”, all recipients are discarded, and no ACL is run for subsequent RCPT commands. The effect of “discard” in a RCPT ACL is to discard just the one recipient address. If there are no recipients left when the message's data is received, the DATA ACL is not run. A “discard” return from the DATA or the non-SMTP ACL discards all the remaining recipients. The “discard” return is not permitted for the acl_smtp_predata ACL.
The local_scan() function is always run, even if there are no remaining recipients; it may create new recipients.
The default actions when any of the acl_xxx options are unset are not all the same. Note: These defaults apply only when the relevant ACL is not defined at all. For any defined ACL, the default action when control reaches the end of the ACL statements is “deny”.
For acl_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, acl_smtp_quit, and acl_smtp_starttls, the action when the ACL is not defined is “accept”.
For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy), the action when the ACL is not defined is “deny”. This means that acl_smtp_rcpt must be defined in order to receive any messages over an SMTP connection. For an example, see the ACL in the default configuration file.
When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables that contain information about the host and the message's sender (for example, $sender_host_address and $sender_address) are set, and can be used in ACL statements. In the case of RCPT (but not MAIL or DATA), $domain and $local_part are set from the argument address.
When an ACL for the AUTH parameter of MAIL is running, the variables that contain information about the host are set, but $sender_address is not yet set. Section 33.2 contains a discussion of this parameter and how it is used.
The $message_size variable is set to the value of the SIZE parameter on the MAIL command at MAIL, RCPT and pre-data time, or to -1 if that parameter is not given. The value is updated to the true message size by the time the final DATA ACL is run (after the message data has been received).
The $rcpt_count variable increases by one for each RCPT command received. The $recipients_count variable increases by one each time a RCPT command is accepted, so while an ACL for RCPT is being processed, it contains the number of previously accepted recipients. At DATA time (for both the DATA ACLs), $rcpt_count contains the total number of RCPT commands, and $recipients_count contains the total number of accepted recipients.
When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY, the remainder of the SMTP command line is placed in $smtp_command_argument. 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}}
deny message = TLS encryption or CRAM-MD5 required
(Another way of applying this restriction is to arrange for the authenticators that use cleartext passwords not to be advertised when the connection is not encrypted. You can use the generic server_advertise_condition authenticator option to do this.)
An individual ACL consists of a number of statements. Each statement starts with a verb, optionally followed by a number of conditions and “modifiers”. Modifiers can change the way the verb operates, define error and log messages, set variables, insert delays, and vary the processing of accepted messages.
If all the conditions are met, the verb is obeyed. The same condition may be used (with different arguments) more than once in the same statement. This provides a means of specifying an “and” conjunction between conditions. For example:
deny dnslists = list1.example dnslists = list2.example
If there are no conditions, the verb is always obeyed. Exim stops evaluating the conditions and modifiers when it reaches a condition that fails. What happens then depends on the verb (and in one case, on a special modifier). Not all the conditions make sense at every testing point. For example, you cannot test a sender address in the ACL that is run for a VRFY command.
The ACL verbs are as follows:
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.
defer: If all the conditions are met, 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, and it causes recipients to be discarded. If the log_message modifier is set when discard operates, its contents are added to the line that is automatically written to the log.
If discard 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 log_recipients log selector is set.
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 message = I don't take more than 20 RCPTs
condition = ${if > {$rcpt_count}{20}}
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 verify = sender
passes control to subsequent statements only if the message's sender can be verified. Otherwise, it rejects the command.
warn: If all the conditions are met, a header line is added to an incoming message and/or a line is written to Exim's main log. In all cases, control passes to the next ACL statement. The text of the added header line and the log line are specified by modifiers; if they are not present, a warn verb just checks its conditions and obeys any “immediate” modifiers such as set and logwrite. There is more about adding header lines in section 39.19.
If any condition on a warn statement cannot be completed (that is, there is some sort of defer), no header lines are added and the configured log line is not written. No further conditions or modifiers in the warn statement are processed. The incident is logged, but the ACL continues to be processed, from the next statement onwards.
If a message modifier is present on a warn verb in an ACL that is not testing an incoming message, it is ignored, and the incident is logged.
A warn statement may use the log_message modifier to cause a line to be written to the main log when the statement's conditions are true. 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.
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.
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. There are two sets of these variables:
The values of $acl_c0 to $acl_c9 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 $acl_m0 to $acl_m9 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 modifier called set. For example:
accept hosts = whatever set acl_m4 = some value
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.
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.
The arguments of conditions and modifiers are expanded. A forced failure of an expansion causes a condition to be ignored, that is, it behaves as if the condition is true. Consider these two statements:
accept senders = ${lookup{$host_name}lsearch\
{/some/file}{$value}fail}
accept senders = ${lookup{$host_name}lsearch\
{/some/file}{$value}{}}
Each attempts to look up a list of acceptable senders. If the lookup succeeds, the returned list is searched, but if the lookup fails the behaviour is different in the two cases. The fail in the first statement causes the condition to be ignored, leaving no further conditions. The accept verb therefore succeeds. The second statement, however, generates an empty list when the lookup fails. No sender can match an empty list, so the condition fails, and therefore the accept also fails.
ACL modifiers appear mixed in with conditions in ACL statements. Some of them specify actions that are taken as the conditions for a statement are checked; others specify text for messages that are used when access is denied or a warning is generated. The control modifier affects the way an incoming message is handled.
The positioning of the modifiers in an ACL statement important, because the processing of a verb ceases as soon as its outcome is known. Only those modifiers that have already been encountered will take effect. For example, consider this use of the message modifier:
require message = Can't verify sender verify = sender message = Can't verify recipient verify = recipient message = This message cannot be used
If sender verification fails, Exim knows that the result of the statement is “deny”, so it goes no further. The first message modifier has been seen, so its text is used as the error message. If sender verification succeeds, but recipient verification fails, the second message is used. If recipient verification succeeds, the third message becomes “current”, but is never used because there are no more conditions to cause failure.
For the deny verb, on the other hand, it is always the last message modifier that is used, because all the conditions must be true for rejection to happen. Specifying more than one message modifier does not make sense, and the message can even be specified after all the conditions. For example:
deny hosts = ... !senders = *@my.domain.example message = Invalid sender from client host
The “deny” result does not happen until the end of the statement is reached, by which time Exim has set up the message.
The ACL modifiers are as follows:
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 39.18. 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_only
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_only ...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_response
This modifier causes Exim to wait for the time interval before proceeding. The time is given in the usual Exim notation. This modifier may appear in any ACL. The delay happens as soon as the modifier is processed. However, when testing Exim using the -bh option, the delay is not actually imposed (an appropriate message is output instead).
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 ...
This modifier, which has no argument, is recognized only in accept 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”. See the description of accept above.
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_cipher encrypted = DES-CBC3-SHA
log_message adds to any underlying error message that may exist because of the condition failure. For example, while verifying a recipient address, a :fail: redirection might have already set up a message. Although the message is usually defined before the conditions to which it applies, the 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 succesful 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.
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, 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
This modifier sets up a text string that is expanded and used as an error message if the current statement causes the ACL to deny access. The expansion happens at the time Exim decides that access is to be denied, not at the time it processes message. If the expansion fails, or generates an empty string, the modifier is ignored. For ACLs that are triggered by SMTP commands, the message is returned as part of the SMTP error response.
The message modifier is also used with the warn verb to specify one or more header lines to be added to an incoming message when all the conditions are true. See section 39.19 for more details. If message is used with warn in an ACL that is not concerned with receiving a message, it has no effect.
The text 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. Like log_message, the contents of message are not expanded until after a condition has failed.
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.
This modifier puts a value into one of the ACL variables (see section 39.15).
The control modifier supports the following settings:
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.
This control affects only the current recipient. Moreover, it applies 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 = 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 = 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 facilty should be used with extreme caution.
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.
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_response
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.
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. No immediate delivery process is started. In other words, it has the effect as the queue_only global option. However, the control applies only 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 add 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 43 describes the processing that Exim applies to messages. Section 43.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.
The message modifier can be used on a warn statement to add an extra header line to an incoming message, as in this example:
warn message = X-blacklisted-at: $dnslist_domain dnslists = sbl.spamhaus.org : \ dialup.mail-abuse.org
If an identical header line is requested several times (provoked, for example, by multiple RCPT commands), only one copy is actually added to the message. If the text of the message modifier contains one or more newlines that are not followed by a space or a tab, it is assumed to contain multiple header lines. Each one is checked for valid syntax; X-ACL-Warn: is added to the front of any line that is not a valid header line.
By default, new lines are added 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 message = :after_received:X-My-Header: something or other...
If more than one header is supplied in a single warn statement, 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 will 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.
Header lines that are added by an ACL at MAIL or RCPT time are not visible in string expansions in ACLs for subsequent RCPT commands or in the acl_smtp_predata ACL. However, they are visible in string expansions in the ACL that is run after DATA is complete (the acl_smtp_data ACL). This is also true for header lines that are added in the acl_smtp_predata ACL. If a message is rejected after DATA, all added header lines are included in the entry that is written to the reject log.
If you want to preserve data between MAIL, RCPT, and the acl_smtp_predata ACLs, you can use ACL variables, as described in section 39.15.
Some of conditions listed in this section are available only when Exim is compiled with the content-scanning extension. They are included here briefly for completeness. More detailed descriptions can be found in the discussion on content scanning in chapter 40.
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 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.
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 = *
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
values, some error is assumed to have occured, and the ACL returns “defer”.
This condition is available only when Exim is compiled with the content-scanning extension, and it is allowed only the the ACL defined by acl_smtp_mime. It causes the current MIME part to be decoded into a file. For details, see chapter 40.
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 39.21--39.29 for details.
This condition is relevant only after a RCPT command. 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.
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 = *
This condition tests that the calling host matches the host list.
Exim's command line takes the standard Unix form of a sequence of options, each starting with a hyphen character, followed by a number of arguments. The options are compatible with the main options of Sendmail, and there are also some additional options, some of which are compatible with Smail 3. Certain combinations of options do not make sense, and provoke an error if used. The form of the arguments depends on which options are set.
If Exim is called under the name mailq, it behaves as if the option -bp were present before any other options. The -bp option requests a listing of the contents of the mail queue on the standard output. This feature is for compatibility with some systems that contain a command of that name in one of the standard libraries, symbolically linked to /usr/sbin/sendmail or /usr/lib/sendmail.
If Exim is called under the name rsmtp it behaves as if the option -bS were present before any other options, for compatibility with Smail. The -bS option is used for reading in a number of messages in batched SMTP format.
If Exim is called under the name rmail it behaves as if the -i and -oee options were present before any other options, for compatibility with Smail. The name rmail is used as an interface by some UUCP systems.
If Exim is called under the name runq it behaves as if the option -q were present before any other options, for compatibility with Smail. The -q option causes a single queue runner process to be started.
If Exim is called under the name newaliases it behaves as if the option -bi were present before any other options, for compatibility with Sendmail. This option is used for rebuilding Sendmail's alias file. Exim does not have the concept of a single alias file, but can be configured to run a given command if called with the -bi option.
Some Exim options are available only to trusted users and others are available only to admin users. In the description below, the phrases “Exim user” and “Exim group” mean the user and group defined by EXIM_USER and EXIM_GROUP in Local/Makefile or set by the exim_user and exim_group options. These do not necessarily have to use the name “exim”.
The trusted users are root, the Exim user, any user listed in the trusted_users configuration option, and any user whose current group or any supplementary group is one of those listed in the trusted_groups configuration option. Note that the Exim group is not automatically trusted.
Trusted users are always permitted to use the -f option or a leading “From ” line to specify the envelope sender of a message that is passed to Exim through the local interface (see the -bm and -f options below). See the untrusted_set_sender option for a way of permitting non-trusted users to set envelope senders. For a trusted user, there is never any check on the contents of the From: header line, and a Sender: line is never added. Furthermore, any existing Sender: line in incoming local (non-TCP/IP) messages is not removed.
Trusted users may also specify a host name, host address, interface address, protocol name, ident value, and authentication data when submitting a message locally. Thus, they are able to insert messages into Exim's queue locally that have the characteristics of messages received from a remote host. Untrusted users may in some circumstances use -f, but can never set the other values that are available to trusted users.
The admin users are root, the Exim user, and any user that is a member of the Exim group or of any group listed in the admin_groups configuration option. The current group does not have to be one of these groups.
Admin users are permitted to list the queue, and to carry out certain operations on messages, for example, to force delivery failures. It is also necessary to be an admin user in order to see the full information provided by the Exim monitor, and full debugging output.
By default, the use of the -M, -q, -R, and -S options to cause Exim to attempt delivery of messages on its queue is restricted to admin users. However, this restriction can be relaxed by setting the prod_requires_admin option false (that is, specifying no_prod_requires_admin).
Similarly, the use of the -bp option to list all the messages in the queue is restricted to admin users unless queue_list_requires_admin is set false.
Warning: If you configure your system so that admin users are able to edit Exim's configuration file, you are giving those users an easy way of getting root. There is further discussion of this issue at the start of chapter 6.
The command options are described in alphabetical order below.
This is a pseudo-option whose only purpose is to terminate the options and therefore to cause subsequent command line items to be treated as arguments rather than options, even if they begin with hyphens.
This option causes Exim to output a few sentences stating what it is. The same output is generated if the Exim binary is called with no options and no arguments.
This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit clean; it ignores this option.
This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually the -bd option is combined with the -q<time> option, to specify that the daemon should also initiate periodic queue runs.
The -bd option can be used only by an admin user. If either of the -d (debugging) or -v (verifying) options are set, the daemon does not disconnect from the controlling terminal. When running this way, it can be stopped by pressing ctrl-C.
By default, Exim listens for incoming connections to the standard SMTP port on all the host's running interfaces. However, it is possible to listen on other ports, on multiple ports, and only on specific interfaces. Chapter 13 contains a description of the options that control this.
When a listening daemon is started without the use of -oX (that is, without overriding the normal configuration), it writes its process id to a file called exim-daemon.pid in Exim's spool directory. This location can be overridden by setting PID_FILE_PATH in Local/Makefile. The file is written while Exim is still running as root.
When -oX is used on the command line to start a listening daemon, the process id is not written to the normal pid file path. However, -oP can be used to specify a path on the command line if a pid file is required.
The SIGHUP signal can be used to cause the daemon to re-exec itself. This should be done whenever Exim's configuration file, or any file that is incorporated into it by means of the .include facility, is changed, and also whenever a new version of Exim is installed. It is not necessary to do this when other files that are referenced from the configuration (for example, alias files) are changed, because these are reread each time they are used.
This option has the same effect as -bd except that it never disconnects from the controlling terminal, even when no debugging is specified.
Run Exim in expansion testing mode. Exim discards its root privilege, to prevent ordinary users from using this mode to read otherwise inaccessible files. If no arguments are given, Exim runs interactively, prompting for lines of data. If Exim was built with USE_READLINE=yes in Local/Makefile, it tries to load the libreadline library dynamically whenever the -be option is used without command line arguments. If successful, it uses the readline() function, which provides extensive line-editing facilities, for reading the test data. A line history is supported.
Long expansion expressions can be split over several lines by using backslash continuations. As in Exim's run time configuration, whitespace at the start of continuation lines is ignored. Each argument or data line is passed through the string expansion mechanism, and the result is output. Variable values from the configuration file (for example, $qualify_domain) are available, but no message-specific values (such as $domain) are set, because no message is being processed.
This option is the same as -bf except that it assumes that the filter being tested is a system filter. The additional commands that are available only in system filters are recognized.
This option runs Exim in user filter testing mode; the file is the filter file
to be tested, and a test message must be supplied on the standard input. If
there are no message-dependent tests in the filter, an empty file can be
supplied.
If you want to test a system filter file, use -bF instead of -bf. You can
use both -bF and -bf on the same command, in order to
test a system filter and a user filter in the same run. For example:
exim -bF /system/filter -bf /user/filter </test/message
This is helpful when the system filter adds header lines or sets filter variables that are used by the user filter.
If the test filter file does not begin with one of the special lines
# Exim filter # Sieve filter
it is taken to be a normal .forward file, and is tested for validity under that interpretation. See sections 22.4 to 22.6 for a description of the possible contents of non-filter redirection lists.
The result of an Exim command that uses -bf, provided no errors are detected, is a list of the actions that Exim would try to take if presented with the message for real. More details of filter testing are given in the separate document entitled Exim's interfaces to mail filtering.
When testing a filter file, the envelope sender can be set by the -f option,
or by a “From ” line at the start of the test message. Various parameters that
would normally be taken from the envelope recipient address of the message can
be set by means of additional command line options (see the next four options).
This sets the domain of the recipient address when a filter file is being tested by means of the -bf option. The default is the value of $qualify_domain.
This sets the local part of the recipient address when a filter file is being tested by means of the -bf option. The default is the username of the process that calls Exim. A local part should be specified with any prefix or suffix stripped, because that is how it appears to the filter when a message is actually being delivered.
This sets the prefix of the local part of the recipient address when a filter file is being tested by means of the -bf option. The default is an empty prefix.
This sets the suffix of the local part of the recipient address when a filter file is being tested by means of the -bf option. The default is an empty suffix.
This option runs a fake SMTP session as if from the given IP address, using the standard input and output. The IP address may include a port number at the end, after a full stop. For example:
exim -bh 10.9.8.7.1234 exim -bh fe80::a00:20ff:fe86:a061.5678
When an IPv6 address is given, it is converted into canonical form. In the case of the second example above, the value of $sender_host_address after conversion to the canonical form is fe80:0000:0000:0a00:20ff:fe86:a061.5678.
Comments as to what is going on are written to the standard error file. These include lines beginning with “LOG” for anything that would have been logged. This facility is provided for testing configuration options for incoming messages, to make sure they implement the required policy. For example, you can test your relay controls using -bh.
Warning 1: You cannot test features of the configuration that rely on ident (RFC 1413) callouts. These cannot be done when testing using -bh because there is no incoming SMTP connection.
Warning 2: Address verification callouts (see section 39.31) are also skipped when testing using -bh. If you want these callouts to occur, use -bhc instead.
Messages supplied during the testing session are discarded, and nothing is written to any of the real log files. There may be pauses when DNS (and other) lookups are taking place, and of course these may time out. The -oMi option can be used to specify a specific IP interface and port if this is important.
The exim_checkaccess utility is a “packaged” version of -bh whose output just states whether a given recipient address from a given host is acceptable or not. See section 49.8.
This option operates in the same way as -bh, except that address verification callouts are performed if required. This includes consulting and updating the callout cache database.
Sendmail interprets the -bi option as a request to rebuild its alias file. Exim does not have the concept of a single alias file, and so it cannot mimic this behaviour. However, calls to /usr/lib/sendmail with the -bi option tend to appear in various scripts such as NIS make files, so the option must be recognized.
If -bi is encountered, the command specified by the bi_command configuration option is run, under the uid and gid of the caller of Exim. If the -oA option is used, its value is passed to the command as an argument. The command set by bi_command may not contain arguments. The command can use the exim_dbmbuild utility, or some other means, to rebuild alias files if this is required. If the bi_command option is not set, calling Exim with -bi is a no-op.
This option runs an Exim receiving process that accepts an incoming, locally-generated message on the current input. The recipients are given as the command arguments (except when -t is also present – see below). Each argument can be a comma-separated list of RFC 2822 addresses. This is the default option for selecting the overall action of an Exim call; it is assumed if no other conflicting option is present.
If any addresses in the message are unqualified (have no domain), they are qualified by the values of the qualify_domain or qualify_recipient options, as appropriate. The -bnq option (see below) provides a way of suppressing this for special cases.
Policy checks on the contents of local messages can be enforced by means of the non-SMTP ACL. See chapter 39 for details. The return code is zero if the message is successfully accepted. Otherwise, the action is controlled by the -oex option setting – see below.
The format of the message must be as defined in RFC 2822, except that, for compatibility with Sendmail and Smail, a line in one of the forms
From sender Fri Jan 5 12:55 GMT 1997
From sender Fri, 5 Jan 97 12:55:01
(with the weekday optional, and possibly with additional text after the date) is permitted to appear at the start of the message. There appears to be no authoritative specification of the format of this line. Exim recognizes it by matching against the regular expression defined by the uucp_from_pattern option, which can be changed if necessary. The specified sender is treated as if it were given as the argument to the -f option, but if a -f option is also present, its argument is used in preference to the address taken from the message. The caller of Exim must be a trusted user for the sender of a message to be set in this way.
By default, Exim automatically qualifies unqualified addresses (those without domains) that appear in messages that are submitted locally (that is, not over TCP/IP). This qualification applies both to addresses in envelopes, and addresses in header lines. Sender addresses are qualified using qualify_domain, and recipient addresses using qualify_recipient (which defaults to the value of qualify_domain).
Sometimes, qualification is not wanted. For example, if -bS (batch SMTP) is being used to re-submit messages that originally came from remote hosts after content scanning, you probably do not want to qualify unqualified addresses in header lines. (Such lines will be present only if you have not enabled a header syntax check in the appropriate ACL.)
The -bnq option suppresses all qualification of unqualified addresses in messages that originate on the local host. When this is used, unqualified addresses in the envelope provoke errors (causing message rejection) and unqualified addresses in header lines are left alone.
If this option is given with no arguments, it causes the values of all Exim's main configuration options to be written to the standard output. The values of one or more specific options can be requested by giving their names as arguments, for example:
exim -bP qualify_domain hold_domains
However, any option setting that is preceded by the word “hide” in the configuration file is not shown in full, except to an admin user. For other users, the output is as in this example:
mysql_servers = <value not displayable>
If configure_file is given as an argument, the name of the run time configuration file is output. If a list of configuration files was supplied, the value that is output here is the name of the file that was actually used.
If log_file_path or pid_file_path are given, the names of the directories where log files and daemon pid files are written are output, respectively. If these values are unset, log files are written in a sub-directory of the spool directory called log, and the pid file is written directly into the spool directory.
If -bP is followed by a name preceded by +, for example,
exim -bP +local_domains
it searches for a matching named list of any type (domain, host, address, or local part) and outputs what it finds.
If one of the words router, transport, or authenticator is given, followed by the name of an appropriate driver instance, the option settings for that driver are output. For example:
exim -bP transport local_delivery
The generic driver options are output first, followed by the driver's private options. A list of the names of drivers of a particular type can be obtained by using one of the words router_list, transport_list, or authenticator_list, and a complete list of all drivers with their option settings can be obtained by using routers, transports, or authenticators.
This option requests a listing of the contents of the mail queue on the standard output. If the -bp option is followed by a list of message ids, just those messages are listed. By default, this option can be used only by an admin user. However, the queue_list_requires_admin option can be set false to allow any user to see the queue.
Each message on the queue is displayed as in the following example:
25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example>
red.king@looking-glass.fict.example
<other addresses>
The first line contains the length of time the message has been on the queue (in this case 25 minutes), the size of the message (2.9K), the unique local identifier for the message, and the message sender, as contained in the envelope. For bounce messages, the sender address is empty, and appears as “<>”. If the message was submitted locally by an untrusted user who overrode the default sender address, the user's login name is shown in parentheses before the sender address. If the message is frozen (attempts to deliver it are suspended) then the text “*** frozen ***” is displayed at the end of this line.
The recipients of the message (taken from the envelope, not the headers) are displayed on subsequent lines. Those addresses to which the message has already been delivered are marked with the letter D. If an original address gets expanded into several addresses via an alias or forward file, the original is displayed with a D only when deliveries for all of its child addresses are complete.
This option operates like -bp, but in addition it shows delivered addresses that were generated from the original top level address(es) in each message by alias or forwarding operations. These addresses are flagged with “+D” instead of just “D”.
This option counts the number of messages on the queue, and writes the total to the standard output. It is restricted to admin users, unless queue_list_requires_admin is set false.
This option operates like -bp, but the output is not sorted into chronological order of message arrival. This can speed it up when there are lots of messages on the queue, and is particularly useful if the output is going to be post-processed in a way that doesn't need the sorting.
This option is a combination of -bpr and -bpa.
This option is a combination of -bpr and -bpu.
This option operates like -bp but shows only undelivered top-level addresses for each message displayed. Addresses generated by aliasing or forwarding are not shown, unless the message was deferred after processing by a router with the one_time option set.
This option is for testing retry rules, and it must be followed by up to three arguments. It causes Exim to look for a retry rule that matches the values and to write it to the standard output. For example:
exim -brt bach.comp.mus.example Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m;
See chapter 32 for a description of Exim's retry rules. The first argument, which is required, can be a complete address in the form local_part@domain, or it can be just a domain name. The second argument is an optional second domain name; if no retry rule is found for the first argument, the second is tried. This ties in with Exim's behaviour when looking for retry rules for remote hosts – if no rule is found that matches the host, one that matches the mail domain is sought. The final argument is the name of a specific delivery error, as used in setting up retry rules, for example “quota_3d”.
This option is for testing address rewriting rules, and it must be followed by a single argument, consisting of either a local part without a domain, or a complete address with a fully qualified domain. Exim outputs how this address would be rewritten for each possible place it might appear. See chapter 31 for further details.
This option is used for batched SMTP input, which is an alternative interface for non-interactive local message submission. A number of messages can be submitted in a single run. However, despite its name, this is not really SMTP input. Exim reads each message's envelope from SMTP commands on the standard input, but generates no responses. If the caller is trusted, or untrusted_set_sender is set, the senders in the SMTP MAIL commands are believed; otherwise the sender is always the caller of Exim.
The message itself is read from the standard input, in SMTP format (leading dots doubled), terminated by a line containing just a single dot. An error is provoked if the terminating dot is missing. A further message may then follow.
As for other local message submissions, the contents of incoming batch SMTP messages can be checked using the non-SMTP ACL (see chapter 39). Unqualified addresses are automatically qualified using qualify_domain and qualify_recipient, as appropriate, unless the -bnq option is used.
Some other SMTP commands are recognized in the input. HELO and EHLO act as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; QUIT quits, ignoring the rest of the standard input.
If any error is encountered, reports are written to the standard output and error streams, and Exim gives up immediately. The return code is 0 if no error was detected; it is 1 if one or more messages were accepted before the error was detected; otherwise it is 2.
More details of input using batched SMTP are given in section 44.12.
This option causes Exim to accept one or more messages by reading SMTP commands on the standard input, and producing SMTP replies on the standard output. SMTP policy controls, as defined in ACLs (see chapter 39) are applied.
Some user agents use this interface as a way of passing locally-generated messages to the MTA. In this usage, if the caller of Exim is trusted, or untrusted_set_sender is set, the senders of messages are taken from the SMTP MAIL commands. Otherwise the content of these commands is ignored and the sender is set up as the calling user. Unqualified addresses are automatically qualified using qualify_domain and qualify_recipient, as appropriate, unless the -bnq option is used.
The -bs option is also used to run Exim from inetd, as an alternative to using a listening daemon. Exim can distinguish the two cases by checking whether the standard input is a TCP/IP socket. When Exim is called from inetd, the source of the mail is assumed to be remote, and the comments above concerning senders and qualification do not apply. In this situation, Exim behaves in exactly the same way as it does when receiving a message via the listening daemon.
This option runs Exim in address testing mode, in which each argument is taken as an address to be tested for deliverability. The results are written to the standard output. If a test fails, and the caller is not an admin user, no details of the failure are output, because these might contain sensitive information such as usernames and passwords for database lookups.
If no arguments are given, Exim runs in an interactive manner, prompting with a right angle bracket for addresses to be tested. Unlike the -be test option, you cannot arrange for Exim to use the readline() function, because it is running as root and there are security issues.
Each address is handled as if it were the recipient address of a message (compare the -bv option). It is passed to the routers and the result is written to the standard output. However, any router that has no_address_test set is bypassed. This can make -bt easier to use for genuine routing tests if your first router passes everything to a scanner program.
The return code is 2 if any address failed outright; it is 1 if no address failed outright but at least one could not be resolved for some reason. Return code 0 is given only when all addresses succeed.
Warning: -bt can only do relatively simple testing. If any of the routers in the configuration makes any tests on the sender address of a message, you can use the -f option to set an appropriate sender when running -bt tests. Without it, the sender is assumed to be the calling user at the default qualifying domain. However, if you have set up (for example) routers whose behaviour depends on the contents of an incoming message, you cannot test those conditions using -bt. The -N option provides a possible way of doing such tests.
This option causes Exim to write the current version number, compilation number, and compilation date of the exim binary to the standard output. It also lists the DBM library this is being used, the optional modules (such as specific lookup types), the drivers that are included in the binary, and the name of the run time configuration file that is in use.
As part of its operation, -bV causes Exim to read and syntax check its configuration file. However, this is a static check only. It cannot check values that are to be expanded. For example, although a misspelt ACL verb is detected, an error in the verb's arguments is not. You cannot rely on -bV alone to discover (for example) all the typos in the configuration; some realistic testing is needed. The -bh and -N options provide more dynamic testing facilities.
This option runs Exim in address verificat
The Exim monitor is an application which displays in an X window information about the state of Exim's queue and what Exim is doing. An admin user can perform certain operations on messages from this GUI interface; however all such facilities are also available from the command line, and indeed, the monitor itself makes use of the command line to perform any actions requested.
The monitor is started by running the script called eximon. This is a shell script that sets up a number of environment variables, and then runs the binary called eximon.bin. The default appearance of the monitor window can be changed by editing the Local/eximon.conf file created by editing exim_monitor/EDITME. Comments in that file describe what the various parameters are for.
The parameters that get built into the eximon script can be overridden for a particular invocation by setting up environment variables of the same names, preceded by “EXIMON_”. For example, a shell command such as
EXIMON_LOG_DEPTH=400 eximon
(in a Bourne-compatible shell) runs eximon with an overriding setting of the LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it overrides the Exim log file configuration. This makes it possible to have eximon tailing log data that is written to syslog, provided that MAIL.INFO syslog messages are routed to a file on the local host.
X resources can be used to change the appearance of the window in the normal way. For example, a resource setting of the form
Eximon*background: gray94
changes the colour of the background to light grey rather than white. The stripcharts are drawn with both the data lines and the reference lines in black. This means that the reference lines are not visible when on top of the data. However, their colour can be changed by setting a resource called “highlight” (an odd name, but that's what the Athena stripchart widget uses). For example, if your X server is running Unix, you could set up lighter reference lines in the stripcharts by obeying
xrdb -merge <<End Eximon*highlight: gray End
In order to see the contents of messages on the queue, and to operate on them, eximon must either be run as root or by an admin user.
The monitor's window is divided into three parts. The first contains one or more stripcharts and two action buttons, the second contains a “tail” of the main log file, and the third is a display of the queue of messages awaiting delivery, with two more action buttons. The following sections describe these different parts of the display.
The first stripchart is always a count of messages on the queue. Its name can be configured by setting QUEUE_STRIPCHART_NAME in the Local/eximon.conf file. The remaining stripcharts are defined in the configuration script by regular expression matches on log file entries, making it possible to display, for example, counts of messages delivered to certain hosts or using certain transports. The supplied defaults display counts of received and delivered messages, and of local and SMTP deliveries. The default period between stripchart updates is one minute; this can be adjusted by a parameter in the Local/eximon.conf file.
The stripchart displays rescale themselves automatically as the value they are displaying changes. There are always 10 horizontal lines in each chart; the title string indicates the value of each division when it is greater than one. For example, “x2” means that each division represents a value of 2.
It is also possible to have a stripchart which shows the percentage fullness of a particular disk partition, which is useful when local deliveries are confined to a single partition. This relies on the availability of the statvfs() function or equivalent in the operating system. Most, but not all versions of Unix that support Exim have this. For this particular stripchart, the top of the chart always represents 100%, and the scale is given as “x10%”. This chart is configured by setting SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the Local/eximon.conf file.
Below the stripcharts there is an action button for quitting the monitor. Next to this is another button marked “Siz