Exim Internet Mailer

<-previousnext->

XWARNING: This documentation is for an old version of Exim (latest)

Chapter 1 - Introduction

Exim is a mail transfer agent (MTA) for hosts that are running Unix or Unix-like operating systems. It was designed on the assumption that it would be run on hosts that are permanently connected to the Internet. However, it can be used on intermittently connected hosts with suitable configuration adjustments.

Configuration files currently exist for the following operating systems: AIX, BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and UnixWare. Some of these operating systems are no longer current and cannot easily be tested, so the configuration files may no longer work in practice.

There are also configuration files for compiling Exim in the Cygwin environment that can be installed on systems running Windows. However, this document does not contain any information about running Exim in the Cygwin environment.

The terms and conditions for the use and distribution of Exim are contained in the file NOTICE. Exim is distributed under the terms of the GNU General Public Licence, a copy of which may be found in the file LICENCE.

The use, supply, or promotion of Exim for the purpose of sending bulk, unsolicited electronic mail is incompatible with the basic aims of Exim, which revolve around the free provision of a service that enhances the quality of personal communications. The author of Exim regards indiscriminate mass-mailing as an antisocial, irresponsible abuse of the Internet.

Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the experience of running and working on the Smail 3 code, I could never have contemplated starting to write a new MTA. Many of the ideas and user interfaces were originally taken from Smail 3, though the actual code of Exim is entirely new, and has developed far beyond the initial concept.

Many people, both in Cambridge and around the world, have contributed to the development and the testing of Exim, and to porting it to various operating systems. I am grateful to them all. The distribution now contains a file called ACKNOWLEDGMENTS, in which I have started recording the names of contributors.

1. Exim documentation

This edition of the Exim specification applies to version 4.92.1 of Exim. Substantive changes from the 4.91 edition are marked in some renditions of this document; this paragraph is so marked if the rendition is capable of showing a change indicator.

This document is very much a reference manual; it is not a tutorial. The reader is expected to have some familiarity with the SMTP mail transfer protocol and with general Unix system administration. Although there are some discussions and examples in places, the information is mostly organized in a way that makes it easy to look up, rather than in a natural order for sequential reading. Furthermore, this manual aims to cover every aspect of Exim in detail, including a number of rarely-used, special-purpose features that are unlikely to be of very wide interest.

An “easier” discussion of Exim which provides more in-depth explanatory, introductory, and tutorial material can be found in a book entitled The Exim SMTP Mail Server (second edition, 2007), published by UIT Cambridge (https://www.uit.co.uk/exim-book/).

The book also contains a chapter that gives a general introduction to SMTP and Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date with the latest release of Exim. (Note that the earlier book about Exim, published by O’Reilly, covers Exim 3, and many things have changed in Exim 4.)

If you are using a Debian distribution of Exim, you will find information about Debian-specific features in the file /usr/share/doc/exim4-base/README.Debian. The command man update-exim.conf is another source of Debian-specific information.

As Exim develops, there may be features in newer versions that have not yet made it into this document, which is updated only when the most significant digit of the fractional part of the version number changes. Specifications of new features that are not yet in this manual are placed in the file doc/NewStuff in the Exim distribution.

Some features may be classified as “experimental”. These may change incompatibly while they are developing, or even be withdrawn. For this reason, they are not documented in this manual. Information about experimental features can be found in the file doc/experimental.txt.

All changes to Exim (whether new features, bug fixes, or other kinds of change) are noted briefly in the file called doc/ChangeLog.

This specification itself is available as an ASCII file in doc/spec.txt so that it can easily be searched with a text editor. Other files in the doc directory are:

OptionLists.txt list of all options in alphabetical order
dbm.discuss.txt discussion about DBM libraries
exim.8 a man page of Exim’s command line options
experimental.txt documentation of experimental features
filter.txt specification of the filter language
Exim3.upgrade upgrade notes from release 2 to release 3
Exim4.upgrade upgrade notes from release 3 to release 4
openssl.txt installing a current OpenSSL release

The main specification and the specification of the filtering language are also available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.5 below tells you how to get hold of these.

2. FTP site and websites

The primary site for Exim source distributions is the exim.org FTP site, available over HTTPS, HTTP and FTP. These services, and the exim.org website, are hosted at the University of Cambridge.

As well as Exim distribution tar files, the Exim website contains a number of differently formatted versions of the documentation. A recent addition to the online information is the Exim wiki (https://wiki.exim.org), which contains what used to be a separate FAQ, as well as various other examples, tips, and know-how that have been contributed by Exim users. The wiki site should always redirect to the correct place, which is currently provided by GitHub, and is open to editing by anyone with a GitHub account.

An Exim Bugzilla exists at https://bugs.exim.org. You can use this to report bugs, and also to add items to the wish list. Please search first to check that you are not duplicating a previous entry. Please do not ask for configuration help in the bug-tracker.

3. Mailing lists

The following Exim mailing lists exist:

exim-announce@exim.org Moderated, low volume announcements list
exim-users@exim.org General discussion list
exim-dev@exim.org Discussion of bugs, enhancements, etc.
exim-cvs@exim.org Automated commit messages from the VCS

You can subscribe to these lists, change your existing subscriptions, and view or search the archives via the mailing lists link on the Exim home page. If you are using a Debian distribution of Exim, you may wish to subscribe to the Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this web page:

Please ask Debian-specific questions on that list and not on the general Exim lists.

4. Bug reports

Reports of obvious bugs can be emailed to bugs@exim.org or reported via the Bugzilla (https://bugs.exim.org). However, if you are unsure whether some behaviour is a bug or not, the best thing to do is to post a message to the exim-dev mailing list and have it discussed.

5. Where to find the Exim distribution

The master distribution site for the Exim distribution is

The service is available over HTTPS, HTTP and FTP. We encourage people to migrate to HTTPS.

The content served at https://downloads.exim.org/ is identical to the content served at https://ftp.exim.org/pub/exim and ftp://ftp.exim.org/pub/exim.

If accessing via a hostname containing ftp, then the file references that follow are relative to the exim directories at these sites. If accessing via the hostname downloads then the subdirectories described here are top-level directories.

There are now quite a number of independent mirror sites around the world. Those that I know about are listed in the file called Mirrors.

Within the top exim directory there are subdirectories called exim3 (for previous Exim 3 distributions), exim4 (for the latest Exim 4 distributions), and Testing for testing versions. In the exim4 subdirectory, the current release can always be found in files called

exim-n.nn.tar.xz
exim-n.nn.tar.gz
exim-n.nn.tar.bz2

where n.nn is the highest such version number in the directory. The three files contain identical data; the only difference is the type of compression. The .xz file is usually the smallest, while the .gz file is the most portable to old systems.

The distributions will be PGP signed by an individual key of the Release Coordinator. This key will have a uid containing an email address in the exim.org domain and will have signatures from other people, including other Exim maintainers. We expect that the key will be in the "strong set" of PGP keys. There should be a trust path to that key from the Exim Maintainer’s PGP keys, a version of which can be found in the release directory in the file Exim-Maintainers-Keyring.asc. All keys used will be available in public keyserver pools, such as pool.sks-keyservers.net.

At the time of the last update, releases were being made by Jeremy Harris and signed with key 0xBCE58C8CE41F32DF. Other recent keys used for signing are those of Heiko Schlittermann, 0x26101B62F69376CE, and of Phil Pennock, 0x4D1E900E14C1CC04.

The signatures for the tar bundles are in:

exim-n.nn.tar.xz.asc
exim-n.nn.tar.gz.asc
exim-n.nn.tar.bz2.asc

For each released version, the log of changes is made available in a separate file in the directory ChangeLogs so that it is possible to find out what has changed without having to download the entire distribution.

The main distribution contains ASCII versions of this specification and other documentation; other formats of the documents are available in separate files inside the exim4 directory of the FTP site:

exim-html-n.nn.tar.gz
exim-pdf-n.nn.tar.gz
exim-postscript-n.nn.tar.gz
exim-texinfo-n.nn.tar.gz

These tar files contain only the doc directory, not the complete distribution, and are also available in .bz2 and .xz forms.

6. Limitations

  • Exim is designed for use as an Internet MTA, and therefore handles addresses in RFC 2822 domain format only. It cannot handle UUCP “bang paths”, though simple two-component bang paths can be converted by a straightforward rewriting configuration. This restriction does not prevent Exim from being interfaced to UUCP as a transport mechanism, provided that domain addresses are used.

  • Exim insists that every address it handles has a domain attached. For incoming local messages, domainless addresses are automatically qualified with a configured domain value. Configuration options specify from which remote systems unqualified addresses are acceptable. These are then qualified on arrival.

  • The only external transport mechanisms that are currently implemented are SMTP and LMTP over a TCP/IP network (including support for IPv6). However, a pipe transport is available, and there are facilities for writing messages to files and pipes, optionally in batched SMTP format; these facilities can be used to send messages to other transport mechanisms such as UUCP, provided they can handle domain-style addresses. Batched SMTP input is also catered for.

  • Exim is not designed for storing mail for dial-in hosts. When the volumes of such mail are large, it is better to get the messages “delivered” into files (that is, off Exim’s queue) and subsequently passed on to the dial-in hosts by other means.

  • Although Exim does have basic facilities for scanning incoming messages, these are not comprehensive enough to do full virus or spam scanning. Such operations are best carried out using additional specialized software packages. If you compile Exim with the content-scanning extension, straightforward interfaces to a number of common scanners are provided.

7. Runtime configuration

Exim’s runtime configuration is held in a single text file that is divided into a number of sections. The entries in this file consist of keywords and values, in the style of Smail 3 configuration files. A default configuration file which is suitable for simple online installations is provided in the distribution, and is described in chapter 7 below.

8. Calling interface

Like many MTAs, Exim has adopted the Sendmail command line interface so that it can be a straight replacement for /usr/lib/sendmail or /usr/sbin/sendmail when sending mail, but you do not need to know anything about Sendmail in order to run Exim. For actions other than sending messages, Sendmail-compatible options also exist, but those that produce output (for example, -bp, which lists the messages in the queue) do so in Exim’s own format. There are also some additional options that are compatible with Smail 3, and some further options that are new to Exim. Chapter 5 documents all Exim’s command line options. This information is automatically made into the man page that forms part of the Exim distribution.

Control of messages in the queue can be done via certain privileged command line options. There is also an optional monitor program called eximon, which displays current information in an X window, and which contains a menu interface to Exim’s command line administration options.

9. Terminology

The body of a message is the actual data that the sender wants to transmit. It is the last part of a message and is separated from the header (see below) by a blank line.

When a message cannot be delivered, it is normally returned to the sender in a delivery failure message or a “non-delivery report” (NDR). The term bounce is commonly used for this action, and the error reports are often called bounce messages. This is a convenient shorthand for “delivery failure error report”. Such messages have an empty sender address in the message’s envelope (see below) to ensure that they cannot themselves give rise to further bounce messages.

The term default appears frequently in this manual. It is used to qualify a value which is used in the absence of any setting in the configuration. It may also qualify an action which is taken unless a configuration setting specifies otherwise.

The term defer is used when the delivery of a message to a specific destination cannot immediately take place for some reason (a remote host may be down, or a user’s local mailbox may be full). Such deliveries are deferred until a later time.

The word domain is sometimes used to mean all but the first component of a host’s name. It is not used in that sense here, where it normally refers to the part of an email address following the @ sign.

A message in transit has an associated envelope, as well as a header and a body. The envelope contains a sender address (to which bounce messages should be delivered), and any number of recipient addresses. References to the sender or the recipients of a message usually mean the addresses in the envelope. An MTA uses these addresses for delivery, and for returning bounce messages, not the addresses that appear in the header lines.

The header of a message is the first part of a message’s text, consisting of a number of lines, each of which has a name such as From:, To:, Subject:, etc. Long header lines can be split over several text lines by indenting the continuations. The header is separated from the body by a blank line.

The term local part, which is taken from RFC 2822, is used to refer to the part of an email address that precedes the @ sign. The part that follows the @ sign is called the domain or mail domain.

The terms local delivery and remote delivery are used to distinguish delivery to a file or a pipe on the local host from delivery by SMTP over TCP/IP to another host. As far as Exim is concerned, all hosts other than the host it is running on are remote.

Return path is another name that is used for the sender address in a message’s envelope.

The term queue is used to refer to the set of messages awaiting delivery because this term is in widespread use in the context of MTAs. However, in Exim’s case, the reality is more like a pool than a queue, because there is normally no ordering of waiting messages.

The term queue runner is used to describe a process that scans the queue and attempts to deliver those messages whose retry times have come. This term is used by other MTAs and also relates to the command runq, but in Exim the waiting messages are normally processed in an unpredictable order.

The term spool directory is used for a directory in which Exim keeps the messages in its queue – that is, those that it is in the process of delivering. This should not be confused with the directory in which local mailboxes are stored, which is called a “spool directory” by some people. In the Exim documentation, “spool” is always used in the first sense.

<-previousTable of Contentsnext->