Exim uses a single runtime configuration file which it reads when it is starting up. 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', then 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 runtime 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.
A one-off alternative configuration file can be specified by the `-C' command line option, but if this is done, Exim immediately gives up its root privilege, unless called by root or the Exim user, so this option 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.
Exim's configuration file is in six parts, which must appear in the correct order in the file, separated by a line containing just the word `end'. These parts contain:
Blank lines in the file are ignored, and lines starting with a # character are treated as comments and are also ignored. Note that a &&s character other than at the beginning of a line is not treated specially, and does not introduce a comment. 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 configuration settings for the various drivers are described in chapters "Driver specifications" -- "The queryprogram router". The retry and rewriting rules have their own syntax which is described in chapters "Retry configuration" and "Address rewriting". The remaining parts have some syntactic items in common, and these are described in sections "Common option syntax" onwards. Before that, the simple macro facility is described.
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, 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 is the replacement text, and has leading and trailing white space removed. If the line ends with a backslash character after trailing space is removed, then the next line is concatenated with it, with the backslash character and any leading space on the following line omitted. This continues for as long as lines end in backslash. Thus a replacement text can never end with a backslash character, but this doesn't seem to me 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 example, suppose you have lots of local domains, but they fall into three different categories. You could set up
LOCAL1 = domain1:\
domain2
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.
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:
exim_user = exim
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, the switch is turned on; if it is preceded by `no_' or `not_' then the switch is turned off. However, boolean options may alternatively be followed by an equals sign and one of the words `true', `false', `yes', or `no'. For example:
sender_verify no_smtp_verify queue_only = true
The types of data that may be required by non-boolean options are described in the following sections.
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. No negative values are involved. 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 option settings are output, some are always shown in octal, and for others, 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.
A fixed point number consists of a decimal integer, optionally followed by a decimal point and up to three further digits.
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.
If a string data item does not start with a double-quote character, then it is taken as consisting of the remainder of the line, starting at the first character after any white space, with trailing white space characters removed, and with no interpretation of the characters therein.
If a string does start with a double-quote, then it continues to a closing double-quote, with the backslash character being interpreted as an escape character. If a backslash occurs at the end of an input line, the string is continued on the following line, with any leading white space being removed. 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 two settings are equivalent:
trusted_users = "uucp:\
mail"
trusted_users = uucp:mail
If a backslash occurs in the middle of a line in a quoted string, the following escapes are recognized:
\\ 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, then that character replaces the pair.
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. The input syntax for such strings is as just described; the expansion process is described in chapter "String expansions".
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.
Some configuration settings accept a colon-separated list of strings. 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 "String" above is an example. There is a limit of 1023 on the number of characters in an item in a string list. If a colon is actually needed in an item in a string list, it can be entered as two colons. This is unfortunately necessary for all colons appearing in IPv6 addresses.
Leading and trailing white space on each item in a string 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:
local_interfaces = "127.0.0.1 : ::::1"
See `README.IPV6' for general information about IPv6 support in Exim.
Domain lists are colon-separated string lists containing a number of patterns that are to be matched against a mail domain. For example, the `local_domains' option contains a domain list which must match all the domains that Exim is to treat as local. Several different kinds of matching are provided:
partial-dbm;/partial/domainsThis causes partial matching logic to be invoked; a description of how this works is given in the next section.
Here is an example which uses several different kinds of pattern:
local_domains = "@@:\
lib.unseen.edu:\
*.foundation.fict.book:\
^[1-2]\\d{3}\\.fict\\.book$:\
dbm;/opt/data/penguin/book:\
nis;domains.byname:\
nisplus;[name=$key,status=local],domains.org_dir"
Note the necessary doubling of the backslashes in the regular expression.
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. The patterns are tested in order, so it makes sense to put the most commonly matched patterns earlier in the string.When one of the single-key lookup types is preceded by `partial-' then matching proceeds as follows: First the subject text is looked up verbatim; if that fails, `*.' is added to the front of the subject and another lookup is tried. If that fails, domains are chopped off and replaced by `*.' until there are fewer than two left. For example, if the file contains
*.neverwhere.tvs
then domains such as `market.neverwhere.tvs' and `downst.neverwhere.tvs' match it, as does `neverwhere.tvs' itself, provided there isn't a separate entry for it in the file. A different minimum number of components can be imposed by supplying a number after `partial', for example, `partial3-dbm'.
An address list is a string list in which each item is a pattern to be matched against a mail address. There are several alternative formats:
sender_reject_recipients = partial-dbm;/black/listcan reference a single file whose keys are a mixture of complete domains, partial domains, and individual mail addresses.
aol.com: spammer1 : spammer2 : ^[0-9]+$ :
spammer3 : spammer4
As in all colon-separated lists in Exim, a colon can be included in an item by
doubling.
If the last item in the list starts with a right angle-bracket, then the
remainder of the item is taken as a new key to look up in order to obtain a
continuation list of local parts. The new key can be any sequence of
characters. Thus one might have entries like
aol.com: spammer1 : spammer 2 : >*
xyz.com: spammer3 : >*
*: ^\d{8}$
in a file that was searched with `dbm*', to produce a match for 8-digit
local parts for all domains. Of course, using this feature costs another lookup
each time a chain is followed, but the effort needed to maintain the data is
reduced.
It is possible to construct loops using this facility, and in order to
catch them, the chains may be no more than fifty items long.
sender_reject = "*@*.spamming.site:\
bozo@partial-lsearch;/list/of/dodgy/sites"
The domain may be given as a single @ character, as in a domain list,
standing for the local host name, leading to items of the form `user@@'.
Host lists are used to control what remote hosts are allowed to do (for example, use the local host as a relay) and are in the same form as domain lists, with some extensions. IP literal addresses are permitted, and any item can optionally be preceded by
<ident>@ or !<ident>@
where <ident> is an RFC 1413 identification string. For example,
sender_host_accept = exim@my.mail.gate sender_host_reject = 111.111.111.111:!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. Such entries may be freely mixed with other types, and address literals can be IPv4 or IPv6 addresses (when IPv6 support is compiled into Exim). The presence of a colon in a string is taken as an indication that it is an IPv6 address; such colons have to be doubled, because colon is the item separator.
When a host list contains a pattern whose form is anything other than a literal host name or IP address, Exim has to use the remote host's IP address to look up its name (using `gethostbyaddr()') in order to match it against the host list pattern. If the lookup fails, Exim takes a hard line by default: if the host list is of the `accept' type, it behaves as if the remote host does not match the entry, whereas if it is of the `reject' type, it behaves as if it does.
In some situations this may be too harsh, so if an entry in a host list is the string `+allow_unknown', and a `gethostbyaddr()' lookup for any subsequent item in the list fails, the opposite action to the default happens. That is, for an `accept' list the host is deemed to be in the list, and for a `reject' list it is deemed not to be in the list.
Net lists are colon-separated string lists in which each item identifies an IP network (that is, a set of IP addresses) or is the name of a file containing a list of such items. Each item consists of an IP network number and a net mask, separated by a slash.
IPv4 addresses are given in the normal `dotted-quad' notation, and the mask for an IPv4 address can also be given in this form, a syntax which is retained for compatibility, but which is no longer recommended. The preferred mask specification is a single number, specifying the number of 1 bits, starting at the most significant end.
IPv6 addresses are given in colon-separated format, but the colons have to be doubled so as not to be taken as item separators. For these addresses the mask is always a single number. This example shows both kinds of address:
receiver_unqualified_nets = "123.123.0.0/16: \
5f03::1200::836f::::/48"
When a netlist is used for checking a host, its IP address is compared with the network number using the given mask. If an IPv4 host calls an IPv6 host, the incoming address actually appears in the IPv6 host as `::ffff:<v4address>'. When such an address is tested against a netlist, it is converted into a traditional IPv4 address first.
When a netlist item is a file name, each line in the file must be a netlist item, complete with mask. Blank lines and lines starting with # are ignored. In fact, a &&s character anywhere in a line causes the rest of the line to be ignored in a netlist file. Note that this is not true of Exim configuration files in general. For example, if the file `/opt/exim/unqualnets' contained
123.123.0.0/16 5f03:1200:836f::/48
then specifying
receiver_unqualified_nets = /opt/exim/unqualnets
has exactly the same effect as the previous example above. Note that there are no colon separators or backslash continuations, and that colons in IPv6 addresses are not doubled.
Go to the first, previous, next, last section, table of contents.