Go to the first, previous, next, last section, table of contents.

7. The Exim configuration file

Exim uses a single run time configuration file which is read whenever an Exim binary is executed. The name of the file is compiled into the binary for security reasons, and is specified by the CONFIGURE_FILE compilation option.

Some sites may wish to use the same Exim binary on different machines that share a file system, but to use different configuration files on each machine. If CONFIGURE_FILE_USE_NODE is defined in `Local/Makefile', Exim first looks for a file whose name is the configuration file name followed by a dot and the machine's node name, as obtained from the uname() function. If this file does not exist, the standard name is tried.

In some esoteric situations different versions of Exim may be run under different effective uids and the CONFIGURE_FILE_USE_EUID is defined to help with this. See the comments in `src/EDITME' for details.

The run time configuration file must be owned by root or by the user that is specified at compile time by the EXIM_UID option, and it must not be world-writeable or group-writeable, unless its group is the one specified at compile time by the EXIM_GID option.

Macros in the configuration file can be overridden by the -D command line option, and a one-off alternative configuration file can be specified by the -C command line option, but if either of these options are used, Exim immediately gives up its root privilege, unless called by root or the Exim user. -C is useful mainly for checking the syntax of configuration files before installing them. No owner or group checks are done on a configuration file specified by -C.

A default configuration file, which will work correctly in simple situations, is provided in the file src/configure.default. The installation process copies this into CONFIGURE_FILE if there is no previously-existing configuration file.

If a syntax error is detected while reading the configuration file, Exim writes a message on the standard error, and exists with a non-zero return code. The message is also written to the panic log.

7.1 Configuration file format

Exim's configuration file is in seven parts, which must appear in the correct order in the file, separated by lines containing just the word `end'. However, any parts at the end of the file that are not required may be omitted. The file contains:

Blank lines in the file are ignored, and lines starting with a # character (ignoring leading white space) are treated as comments and are also ignored. Note that a # character other than at the beginning of a line is not treated specially, and does not introduce a comment.

Any non-comment line can be continued by ending it with a backslash. Trailing white space after the backslash is ignored, and leading white space at the start of continuation lines is also ignored. Comment lines may appear in the middle of a sequence of continuation lines.

A convenient way to create a configuration file is to start from the default, which is supplied in src/configure.default, and add, delete, or change settings as required.

The retry and rewriting rules have their own syntax which is described in chapters 33 and 34, respectively. The other parts of the configuration file (whose settings are described in chapters 11--32 and 35--37) have some syntactic items in common, and these are described below, from section 7.3 onwards. Before that, the simple macro facility is introduced.

7.2 Macros in the configuration file

If a line in the main part of the configuration (that is, before the first `end' line) begins with an upper-case letter, it is taken as a macro definition, and must be of the form

<name> = <rest of line>

The name must consist of letters, digits, and underscores, and need not all be in upper-case, though that is recommended. The rest of the line, including any continuations, is the replacement text, and has leading and trailing white space removed. Quotes are not removed. A replacement text can never end with a backslash character, but this doesn't seem to be a serious limitation.

Once a macro is defined, all subsequent lines in the file are scanned for the macro name; if there are several macros, the line is scanned for each in turn, in the order in which they are defined. The replacement text is not re-scanned for the current macro, though it will be for subsequently defined macros. For this reason, a macro name may not contain the name of a previously defined macro as a substring. You could, for example, define

ABCD_XYZ = <<something>>
ABCD = <<something>>

but putting the definitions in the opposite order would provoke a configuration error.

As an example of macro usage, suppose you have lots of local domains, but they fall into three different categories. You could set up

LOCAL1 = domain1:\
LOCAL2 = domain3:domain4
LOCAL3 = dbm;/list/of/other/domains

local_domains = LOCAL1:LOCAL2:LOCAL3

and then use the domains option on appropriate directors to handle each set of domains differently. This avoids having to list each domain in more than one place. Warning: This technique is convenient only for positive lists. Because it is just a textual replacement, preceding a macro name in a list with ! has the effect of negating just the first item within the macro, not all of them.

7.3 Common option syntax

For the main set of options and for driver options, each setting is on a line by itself, and starts with a name consisting of lower-case letters and underscores. Many options require a data value, and in these cases the name must be followed by an equals sign (with optional white space) and then the value. For example:

qualify_domain = mydomain.example.com

Some option settings may contain sensitive data, for example, passwords for accessing databases. To stop non-admin users from using the -bP command line option to read their values, you can precede them with the word `hide'. For example:

hide mysql_servers = localhost/users/admin/secret-password

For non-admin users, such options are displayed like this:

mysql_servers = <value not displayable>

If `hide' is used on a driver option, it hides the value of that option on all instances of the same driver.

Options whose type is given as boolean are on/off switches that are not always followed by a data value. If the option name is specified on its own without data, the switch is turned on; if it is preceded by `no_' or `not_' the switch is turned off. However, boolean options may be followed by an equals sign and one of the words `true', `false', `yes', or `no'. For example:

queue_only = true

The types of data that are used by non-boolean options are described in the following sections.

7.4 Integer

If a numerical data item starts with the characters `0x', the remainder of it is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it starts with the digit 0, and decimal if not. If an integer value is followed by the letter K, it is multiplied by 1024; if it is followed by the letter M, it is multiplied by 1024x1024.

When the values of integer option settings are output, values which are an exact multiple of 1024 or 1024x1024 are printed using the letters K and M. The printing style is independent of the actual input format that was used.

7.5 Octal integer

The value of an option specified as an octal integer is always interpreted in octal, whether or not it starts with the digit zero. Such options are always output in octal.

7.6 Fixed point number

A fixed point number consists of a decimal integer, optionally followed by a decimal point and up to three further digits.

7.7 Time interval

A time interval is specified as a sequence of numbers, each followed by one of the following letters, with no intervening white space:

s    seconds
m    minutes
h    hours
d    days
w    weeks

For example, `3h50m' specifies 3 hours and 50 minutes. The values of time intervals are output in the same format.

7.8 String

If a string data item does not start with a double-quote character, it is taken as consisting of the remainder of the line plus any continuation lines, starting at the first character after any white space, with trailing white space characters removed, and with no interpretation of the characters therein. Because Exim removes comment lines (those beginning with #) at an early stage, they can appear in the middle of a multi-line string. The following settings are therefore equivalent:

trusted_users = uucp:mail

trusted_users = uucp:\
                # This comment line is ignored

If a string does start with a double-quote, it must end with a closing double-quote, and any backslash characters other than those used for line continuation are interpreted as escape characters, as follows:

\\               single backslash
\n               newline
\r               carriage return
\t               tab
\<octal digits>  up to 3 octal digits specify one character
\x<hex digits>   up to 2 hexadecimal digits specify one character

If a backslash is followed by some other character, including a double-quote character, that character replaces the pair.

Quoting is necessary only if you want to make use of the backslash escapes to insert special characters, or if you need to specify a value with leading or trailing spaces. However, in versions of Exim before 3.14, quoting was required in order to continue lines, so you may come across older configuration files and examples that apparently quote unnecessarily.

7.9 Expanded strings

Some strings in the configuration file are subjected to string expansion, by which means various parts of the string may be changed according to the circumstances (see chapter 9). The input syntax for such strings is as just described; in particular, the handling of backslashes in quoted strings is done as part of the input process, before expansion takes place. However, backslash is also an escape character for the expander, so any backslashes that are required for that reason must be doubled if they are within a quoted configuration string.

7.10 User and group names

User and group names are specified as strings, using the syntax described above, but the strings are interpreted specially. In the main section of the configuration file, a user or group name must either consist entirely of digits, or be a name that can be looked up using the getpwnam() or getgrnam() function, as appropriate.

When a user or group is specified as an option for a driver, it may alternatively be a string that gets expanded each time the user or group value is required. The presence of a $ character in the string causes this action to happen. Each time the string is expanded, the result must either be a digit string, or a name that can be looked up using getpwnam() or getgrnam(), as appropriate.

7.11 List construction

Some configuration settings accept a colon-separated list of items. In these cases, the entire list is treated as a single string as far as the input syntax is concerned. The trusted_users setting in section 7.8 above is an example. If a colon is actually needed in an item in a list, it must be entered as two colons. Leading and trailing white space on each item in a list is ignored. This makes it possible to include items that start with a colon, and in particular, certain forms of IPv6 address. For example, the list

local_interfaces = : ::::1

contains two IP addresses, the IPv4 address and the IPv6 address ::1. IPv6 addresses are going to become more and more common as the new protocol gets more widely deployed. Doubling their colons is a unwelcome chore, so a mechanism was introduced to allow the separator character to be changed. If a list begins with a left angle bracket, followed by any punctuation character, that character is used instead of colon as the list separator. For example, the list above can be rewritten to use a semicolon separator like this:

local_interfaces = <; ; ::1

This facility applies to all lists, with the exception of the lists in log_file_path and tls_verify_ciphers. It is recommended that the use of non-colon separators be confined to circumstances where it really is needed, and that colon be used in most cases.

7.12 Domain lists

Domain lists are constructed as described in section 7.11. They contain patterns that are to be matched against a mail domain. For example, the local_domains option is a domain list, one of whose patterns must match every domain that Exim is to treat as local.

Items in a domain list may be positive or negative. Negative items are indicated by a leading exclamation mark, which may be followed by optional white space. The list is scanned from left to right. If the domain matches a positive item, it is in the set of domains which the list defines; if it matches a negative item, it is not in the set. If the end of the list is reached without the domain having matched any of the patterns, it is accepted if the last item was a negative one, but not if it was a positive one. For example,

relay_domains = !a.b.c : *.b.c

matches any domain ending in `.b.c' except for `a.b.c'. Domains that match neither `a.b.c' nor `*.b.c' are not accepted, because the last item in the list is positive. However, if the setting were

relay_domains = !a.b.c

then all domains other than `a.b.c' would be accepted because the last item in the list is negative. In effect, a list that ends with a negative item behaves as if it had `: *' appended to it.

The following types of item may appear in domain lists:

Here is an example which uses several different kinds of pattern:

local_domains = @:\

There are obvious processing trade-offs among the various matching modes. Using an asterisk is faster than a regular expression, and listing a few names explicitly probably is too. The use of a file or database lookup is expensive, but may be the only option if hundreds of names are required. Because the patterns are tested in order, it makes sense to put the most commonly matched patterns earlier.

7.13 Host lists

Host lists are constructed as described in section 7.11. They contain patterns which are matched against host names or IP addresses. Host lists are used to control what remote hosts are allowed to do (for example, use the local host as a relay). Their patterns define a set of hosts that the list matches.

Items in the list may be positive or negative. Negation is indicated by preceding an item with an exclamation mark. A plain absolute file name (beginning with a slash) can be used to include items from a file. Negation and included files operate exactly as for domain lists -- see section 7.12 for examples.

The following types of pattern may appear in a host list:

The remaining items are wildcarded patterns for matching against the host name. If the host name is not already known, Exim calls gethostbyaddr() to obtain it from the IP address. This typically causes a reverse DNS lookup to occur. If the lookup fails, Exim takes a hard line by default and access is not permitted. If the list is an `accept' list, Exim behaves as if the current host is not in the set defined by the list, whereas if it is a `reject' list, it behaves as if it is.

To change this behaviour, the special item `+allow_unknown' may appear in the list (at top level -- it is not recognized in an indirected file). If any subsequent items require a host name, and the reverse DNS lookup fails, Exim permits the access, that is, its behaviour is the opposite to the default. For example,

host_reject = +allow_unknown:*.enemy.ex

rejects connections from any host whose name matches `*.enemy.ex', but only if it can find a host name from the incoming IP address. If `+warn_unknown' is used instead of `+allow_unknown', the effect is the same, except that Exim writes an entry to its log when it accepts a host whose name it cannot look up.

As a result of aliasing, hosts may have more than one name. When processing any of the following items, all the host's names are checked.

7.14 Mixing host names and addresses in host lists

If you have both names and IP addresses in the same host list, you should normally put the IP addresses first. For example:

host_accept_relay = : *.friends.domain

The reason for this lies in the left-to-right way that Exim processes lists. It can test IP addresses without doing any DNS lookups, but when it reaches an item that requires a DNS lookup, it normally fails if the DNS lookup fails, because it cannot find a host name to compare with the pattern. (There is the `+allow_unknown' facility -- described above -- for changing this, but it is not recommended.) If the above list were in the other order, Exim would reject relaying from any host whose name could not be found, even if it were

7.15 Use of RFC 1413 identification in host lists

Any item in a host list (other than a plain file name or `+allow_unknown') can optionally be preceded by


where <ident> is an RFC 1413 identification string. For example,

host_reject = !exim@my.mail.gate:!root@public.host

If an <ident> string is present, it must match the RFC 1413 identification sent by the remote host, unless it is preceded by an exclamation mark, in which case it must not match. The remainder of the item, following the @, may be either positive or negative.

7.16 Address lists

Address lists are constructed as described in section 7.11. They contain patterns which are matched against mail addresses. As in the case of domain lists, the list is searched from left to right, any item may be preceded by an exclamation mark to negate it, and a plain file name may appear as an entire item, causing each line of the file to be read and treated as a separate pattern. Because local parts may legitimately contain # characters, a comment in the file is recognized only if # is followed by white space or the end of the line.

The following kinds of pattern may appear inline or as lines in an included file:

7.17 Case of letters in address lists

Domains in email addresses are always handled caselessly, but for local parts case may be significant on some systems (see locally_caseless for how Exim deals with this when processing local addresses). However, RFC 2505 (Anti-Spam Recommendations for SMTP MTAs) suggests that matching of addresses to blocking lists should be done in a case-independent manner. Since most address lists in Exim are used for this kind of control, Exim attempts to do this by default.

The domain portion of an address is always lowercased before matching it to an address list. The local part is lowercased by default, and any string comparisons that take place are done caselessly. This means that the data in the address list itself, in files included as plain file names, and in any file that is looked up using the `@@' mechanism, can be in any case. However, the keys in files that are looked up by a search type other than lsearch (which works caselessly) must be in lower case, because these lookups are not case-independent.

To allow for the possibility of caseful address list matching, if an item in the list is the string `+caseful' then the original case of the local part is restored for any comparisons that follow, and string comparisons are no longer case-independent. This does not affect the domain.

Go to the first, previous, next, last section, table of contents.