A one-off alternate configuration can be specified by the -C command line option, which may specify a single file or a list of files. However, when -C is used, Exim gives up its root privilege, unless called by root or the Exim user (or unless the argument for -C is identical to the built-in value from CONFIGURE_FILE). -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.

The privileged use of -C by the Exim user can be locked out by setting ALT_CONFIG_ROOT_ONLY in Local/Makefile when building Exim. However, if you do this, you also lock out the possibility of testing a configuration using -C right through message reception and delivery, even if the caller is root. The reception works, but by that time, Exim is running as the Exim user, so when it re-execs to regain privilege for the delivery, the use of -C causes privilege to be lost. However, root can test reception and delivery using two separate commands (one to put a message on the queue, using -odq, and another to do the delivery, using -M).

If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix string with which any file named in a -C command line option must start. In addition, the file name must not contain the sequence “/../”. There is no default setting for ALT_CONFIG_PREFIX; when it is unset, any file name can be used with -C.

One-off changes to a configuration can be specified by the -D command line option, which defines and overrides values for macros used inside the configuration file. However, like -C, the use of this option by a non-privileged user causes Exim to discard its root privilege. If DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is completely disabled, and its use causes an immediate error exit.

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. This processing occurs for each file name in the list given by CONFIGURE_FILE or -C.

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:

Leading and trailing white space in configuration lines is always ignored.

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. Note that the general rule for white space means that trailing white space after the backslash and leading white space at the start of continuation lines is ignored. Comment lines beginning with # (but not empty 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 39, 32, and 31, respectively. The other parts of the configuration file have some syntactic items in common, and these are described below, from section 6.10 onwards. Before that, the inclusion, macro, and conditional facilities are described.

You can include other files inside Exim’s run time configuration file by using this syntax:

on a line by itself. Double quotes round the file name are optional. If you use the first form, a configuration error occurs if the file does not exist; the second form does nothing for non-existent files. In all cases, an absolute file name is required.

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. If you change the contents of an included file, you must HUP the daemon, because an included file is read only when the configuration itself is read.

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 after macro processing (see below). Its effect is to process the lines of the included 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

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.

Macros may also be defined between router, transport, authenticator, or ACL definitions. They may not, however, be defined within an individual driver or ACL, or in the local_scan, retry, or rewrite sections of the configuration.

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 the macros are defined. The replacement text is not re-scanned for the current macro, though it is scanned 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

but putting the definitions in the opposite order would provoke a configuration error. Macro expansion is applied to individual physical lines from the file, before checking for line continuation or file inclusion (see above). If a line consists solely of a macro name, and the expansion of the macro is empty, the line is ignored. A macro at the start of a line may turn the line into a comment line or a .include line.

Once defined, the value of a macro can be redefined later in the configuration (or in an included file). Redefinition is specified by using == instead of =. For example:

MAC =  initial value
...
MAC == updated value

Redefinition does not alter the order in which the macros are applied to the subsequent lines of the configuration file. It is still the same order in which the macros were originally defined. All that changes is the macro’s value. Redefinition makes it possible to accumulate values. For example:

MAC =  initial value
...
MAC == MAC and something added

This can be helpful in situations where the configuration file is built from a number of other files.

The values set for macros in the configuration file can be overridden by the -D command line option, but Exim gives up its root privilege when -D is used, unless called by root or the Exim user. A definition on the command line using the -D option causes all definitions and redefinitions within the file to be ignored.

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.

You can use the directives .ifdef, .ifndef, .elifdef, .elifndef, .else, and .endif to dynamically include or exclude portions of the configuration file. The processing happens whenever the file is read (that is, when an Exim binary starts to run).

The implementation is very simple. Instances of the first four directives must be followed by text that includes the names of one or macros. The condition that is tested is whether or not any macro substitution has taken place in the line. Thus:

.ifdef AAA
message_size_limit = 50M
.else
message_size_limit = 100M
.endif

sets a message size limit of 50M if the macro AAA is defined, and 100M otherwise. If there is more than one macro named on the line, the condition is true if any of them are defined. That is, it is an “or” condition. To obtain an “and” condition, you need to use nested .ifdefs.

Although you can use a macro expansion to generate one of these directives, it is not very useful, because the condition “there was a macro substitution in this line” will always be true.

Text following .else and .endif is ignored, and can be used as comment to clarify complicated nestings.

For the main set of options, driver options, and local_scan() 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 these values, you can precede the option settings with the word “hide”. For example:

hide mysql_servers = localhost/usersstrong class="option">-C.


One-off changes to a configuration can be specified by the -D command line
option, which defines and overrides values for macros used inside the
configuration file. However, like -C, the use of this option by a
non-privileged user causes Exim to discard its root privilege.
If DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is
completely disabled, and its use causes an immediate error exit.


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. This processing occurs for
each file name in the list given by CONFIGURE_FILE or -C.


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:

Leading and trailing white space in configuration lines is always ignored.

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. Note that the general rule for white space means that trailing white space after the backslash and leading white space at the start of continuation lines is ignored. Comment lines beginning with # (but not empty 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 39, 32, and 31, respectively. The other parts of the configuration file have some syntactic items in common, and these are described below, from section 6.10 onwards. Before that, the inclusion, macro, and conditional facilities are described.

You can include other files inside Exim’s run time configuration file by using this syntax:

on a line by itself. Double quotes round the file name are optional. If you use the first form, a configuration error occurs if the file does not exist; the second form does nothing for non-existent files. In all cases, an absolute file name is required.

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. If you change the contents of an included file, you must HUP the daemon, because an included file is read only when the configuration itself is read.

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 after macro processing (see below). Its effect is to process the lines of the included 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

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.

Macros may also be defined between router, transport, authenticator, or ACL definitions. They may not, however, be defined within an individual driver or ACL, or in the local_scan, retry, or rewrite sections of the configuration.

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 the macros are defined. The replacement text is not re-scanned for the current macro, though it is scanned 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

but putting the definitions in the opposite order would provoke a configuration error. Macro expansion is applied to individual physical lines from the file, before checking for line continuation or file inclusion (see above). If a line consists solely of a macro name, and the expansion of the macro is empty, the line is ignored. A macro at the start of a line may turn the line into a comment line or a .include line.

Once defined, the value of a macro can be redefined later in the configuration (or in an included file). Redefinition is specified by using == instead of =. For example:

MAC =  initial value
...
MAC == updated value

Redefinition does not alter the order in which the macros are applied to the subsequent lines of the configuration file. It is still the same order in which the macros were originally defined. All that changes is the macro’s value. Redefinition makes it possible to accumulate values. For example:

MAC =  initial value
...
MAC == MAC and something added

This can be helpful in situations where the configuration file is built from a number of other files.

The values set for macros in the configuration file can be overridden by the -D command line option, but Exim gives up its root privilege when -D is used, unless called by root or the Exim user. A definition on the command line using the -D option causes all definitions and redefinitions within the file to be ignored.

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.

You can use the directives .ifdef, .ifndef, .elifdef, .elifndef, .else, and .endif to dynamically include or exclude portions of the configuration file. The processing happens whenever the file is read (that is, when an Exim binary starts to run).

The implementation is very simple. Instances of the first four directives must be followed by text that includes the names of one or macros. The condition that is tested is whether or not any macro substitution has taken place in the line. Thus:

.ifdef AAA
message_size_limit = 50M
.else
message_size_limit = 100M
.endif

sets a message size limit of 50M if the macro AAA is defined, and 100M otherwise. If there is more than one macro named on the line, the condition is true if any of them are defined. That is, it is an “or” condition. To obtain an “and” condition, you need to use nested .ifdefs.

Although you can use a macro expansion to generate one of these directives, it is not very useful, because the condition “there was a macro substitution in this line” will always be true.

Text following .else and .endif is ignored, and can be used as comment to clarify complicated nestings.

For the main set of options, driver options, and local_scan() 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 these values, you can precede the option settings with the word “hide”. For example:

hide mysql_servers = localhost/usersstrong class="option">-C.


One-off changes to a configuration can be specified by the -D command line
option, which defines and overrides values for macros used inside the
configuration file. However, like -C, the use of this option by a
non-privileged user causes Exim to discard its root privilege.
If DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is
completely disabled, and its use causes an immediate error exit.


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. This processing occurs for
each file name in the list given by CONFIGURE_FILE or -C.


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: