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. The run time configuration file must be owned by root or by the user that is specified at compile time by the EXIM_USER option, and it must not be world-writeable or group-writeable, unless its group is the one specified at compile time by the EXIM_GROUP option.
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. Chapter 7 is a ``walk-through'' discussion of this configuration.
If a syntax error is detected while reading the configuration file, Exim writes a message on the standard error, and exits with a non-zero return code. The message is also written to the panic log.
A one-off alternate configuration file can be specified by the -C command line option, but if this option is 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.
One-off changes to a configuration file can be specified by the -D command line option, which defines and overrides values for macros used inside the file. However, like -C, the use of this option by a non-privileged user causes Exim to discard its root privilege.
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.
Exim's configuration file is divided into a number of different parts. General option settings must always appear at the start of the file. The other parts are all optional, and may appear in any order. Each part other than the first is introduced by the word ``begin'' followed by the name of the part. The optional parts are:
ACL: Access control lists for controlling incoming SMTP mail.
authenticators: Configuration settings for the authenticator drivers. These are concerned with the SMTP AUTH command (see chapter 32).
routers: Configuration settings for the router drivers. Routers process addresses and determine how the message is to be delivered.
transports: Configuration settings for the transport drivers. Transports define mechanisms for copying messages to destinations.
retry: Retry rules, for use when a message cannot be immediately delivered.
rewrite: Global address rewriting rules, for use when a message arrives and when new addresses are generated during delivery.
Blank lines in the file, and lines starting with a # character (ignoring leading white space) are treated as comments and are ignored. Note: 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 ACLs, retry rules, and rewriting rules have their own syntax which is described in chapters 37, 31, and 30, respectively. The other parts of the configuration file have some syntactic items in common, and these are described below, from section 6.5 onwards. Before that, the simple include and macro facilities are introduced.
You can include other files inside Exim's run time configuration file by using this syntax:
.include <file name>
on a line by itself. Double quotes round the file name are optional. Includes may be nested to any depth, but remember that Exim reads its configuration file often, so it is a good idea to keep them to a minimum.
The processing of inclusions happens early, at a physical line level, so, like comment lines, an inclusion can be used in the middle of an option setting, for example:
hosts_lookup = a.b.c \ .include /some/file
Include processing happens before macro processing. Its effect is to process the lines of the file as if they occurred inline where the inclusion appears.
If a line in the main part of the configuration (that is, before the first ``begin'' 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. The 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 (and any included files) 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 else>>
but putting the definitions in the opposite order would provoke a configuration error.
If a line consists solely of a macro name, and the expansion of the macro is empty, the line is ignored. Also, a macro at the start of a line may turn the line into a comment line. Because continuations are processed before macros, this applies to the logical line, including any continuations. This is different to effect of a literal # character, which applies only to the physical line it is in.
As an example of macro usage, consider a configuration where aliases are looked up in a MySQL database. It helps to keep the file less cluttered if long strings such as SQL statements are defined separately as macros, for example:
ALIAS_QUERY = select mailbox from user where \
login=${quote_mysql:$local_part};
This can then be used in a redirect router setting like this:
data = ${lookup mysql{ALIAS_QUERY}}
In earlier versions of Exim macros were sometimes used for domain, host, or address lists. In Exim 4 these are handled better by named lists - see section 10.5.
Macros in the configuration file can be overridden by the -D command line option, but Exim immediately gives up its root privilege when -D is used, unless called by root or the Exim user.
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 queue_only = true no_queue_only queue_only = false
The types of data that are used by non-boolean options are described in the following sections.
If an integer 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.
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.
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, it is taken as consisting of the remainder of the line plus any continuation lines, starting at the first character after any leading white space, with trailing white space characters removed, and with no interpretation of the characters in the string. 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 mail
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. These cases are rare, so quoting is almost never needed in current versions of Exim. 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.
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 11). 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.
User and group names are specified as strings, using the syntax described above, but the strings are interpreted specially. 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.
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 6.10 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 = 127.0.0.1 : ::::1
contains two IP addresses, the IPv4 address 127.0.0.1 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 an 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 = <; 127.0.0.1 ; ::1
This facility applies to all lists, with the exception of the list in log_file_path. It is recommended that the use of non-colon separators be confined to circumstances where they really are needed.
Three parts of Exim's run time configuration file contain option settings for different kinds of driver: routers, transports, and authenticators. Each driver is defined in the configuration file by a sequence of lines like this:
<instance name>:
<option>
...
<option>
The order in which routers are defined is important, because addresses are passed to individual routers one by one, in order. The order in which transports are defined does not matter at all. The order in which authenticators are defined is used only when Exim, as a client, is searching them to find one which matches an authentication mechanism offered by the server.
Within a driver definition, there are two kinds of option: generic and private. The generic options are those that apply to all drivers of the same type (that is, all routers, all transports or all authenticators). There is always at least one generic option setting, called driver, which specifies which particular driver is being used. The private options are special for each driver, and none need appear because they all have default values.
The options may appear in any order, except that the driver option must precede any private options, since these depend on the particular driver. For this reason, it is recommended that driver always be the first option.
Each instance of a driver is given an identifying instance name name for reference in logging and elsewhere. The name can be any sequence of letters, digits, and underscores (starting with a letter) and must be unique among drivers of the same type. A router and a transport (for example) can each have the same name, but no two router instances can have the same name. The name of a driver instance should not be confused with the name of the underlying driver. For example, the configuration lines
remote_smtp: driver = smtp
create an instance of the smtp transport driver whose name is remote_smtp. The same driver code can be used more than once, with different instance names and different option settings each time. A second instance of the smtp transport, with different options, might be defined thus:
special_smtp: driver = smtp port = 1234 command_timeout = 10s
The names remote_smtp and special_smtp are used to reference these transport instances from routers, and these names appear in log lines.
Comment lines may be present in the middle of driver specifications. The full list of option settings for any particular driver instance, including all the defaults, can be extracted by making use of the -bP command line option.