Exim Internet Mailer

Chapter 61 - Events

The events mechanism in Exim can be used to intercept processing at a number of points. It was originally invented to give a way to do customised logging actions (for example, to a database) but can also be used to modify some processing actions.

Most installations will never need to use Events. The support can be left out of a build by defining DISABLE_EVENT=yes in Local/Makefile.

There are two major classes of events: main and transport. The main configuration option event_action controls reception events; a transport option event_action controls delivery events.

Both options are a string which is expanded when the event fires. An example might look like:

event_action = ${if eq {msg:delivery}{$event_name} \
{${lookup pgsql {SELECT * FROM record_Delivery( \
    '${quote_pgsql:$sender_address_domain}',\
    '${quote_pgsql:${lc:$sender_address_local_part}}', \
    '${quote_pgsql:$domain}', \
    '${quote_pgsql:${lc:$local_part}}', \
    '${quote_pgsql:$host_address}', \
    '${quote_pgsql:${lc:$host}}', \
    '${quote_pgsql:$message_exim_id}')}} \
} {}}

Events have names which correspond to the point in process at which they fire. The name is placed in the variable $event_name and the event action expansion must check this, as it will be called for every possible event type.

The current list of events is:

New event types may be added in future.

The event name is a colon-separated list, defining the type of event in a tree of possibilities. It may be used as a list or just matched on as a whole. There will be no spaces in the name.

The second column in the table above describes whether the event fires before or after the action is associates with. Those which fire before can be used to affect that action (more on this below).

The third column in the table above says what section of the configuration should define the event action.

An additional variable, $event_data, is filled with information varying with the event type:

The :defer events populate one extra variable: $event_defer_errno.

For complex operations an ACL expansion can be used in event_action, however due to the multiple contexts that Exim operates in during the course of its processing:

• variables set in transport events will not be visible outside that transport call

• acl_m variables in a server context are lost on a new connection, and after smtp helo/ehlo/mail/starttls/rset commands

Using an ACL expansion with the logwrite modifier can be a useful way of writing to the main log.

The expansion of the event_action option should normally return an empty string. Should it return anything else the following will be forced:

All other message types ignore the result string, and no other use is made of it.

For a tcp:connect event, if the connection is being made to a proxy then the $host_address and $host_port variables will be that of the proxy and not the target system.

For tls:cert events, if GnuTLS is in use this will trigger only per chain element received on the connection. For OpenSSL it will trigger for every chain element including those loaded locally.

For dns:fail events from dnsdb lookups, a “defer_never” option does not affect the reporting of DNS_AGAIN.