<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
span.changed { background-color: #99ff99; }
span.off { }
pre.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] pre.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] div.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
</style><title>6. The Exim run time configuration file</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch05.html" title="5. The Exim command line" /><link rel="next" href="ch07.html" title="7. The default configuration file" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch05.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch07.html">Next</a></td></tr></table></div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a href="index.html#toc0056" id="CHAPconf">6. The Exim run time configuration file</a></h2></div>
</div>
</div>
<p>
<a id="id489452" class="indexterm"></a>
<a id="id489463" class="indexterm"></a>
<a id="id489478" class="indexterm"></a>
<a id="id489489" class="indexterm"></a>
<a id="id489504" class="indexterm"></a>
<a id="id489518" class="indexterm"></a>
Exim uses a single run time configuration file that is read whenever an Exim
binary is executed. Note that in normal operation, this happens frequently,
because Exim is designed to operate in a distributed manner, without central
control.
</p>
<p>
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. <span class="bold"><strong>Note</strong></span>: Only simple syntax
errors can be detected at this time. The values of any expanded options are
not checked until the expansion happens, even when the expansion does not
actually alter the string.
</p>
<p>
The name of the configuration file is compiled into the binary for security
reasons, and is specified by the CONFIGURE_FILE compilation option. In
most configurations, this specifies a single file. However, it is permitted to
give a colon-separated list of file names, in which case Exim uses the first
existing file in the list.
</p>
<p>
<a id="id489565" class="indexterm"></a>
<a id="id489576" class="indexterm"></a>
<a id="id489587" class="indexterm"></a>
<a id="id489598" class="indexterm"></a>
<a id="id489609" class="indexterm"></a>
<a id="id489624" class="indexterm"></a>
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, or by the user that is
specified at compile time by the CONFIGURE_OWNER option (if set). The
configuration file must not be world-writeable or group-writeable, unless its
group is the one specified at compile time by the EXIM_GROUP option or by the
CONFIGURE_GROUP option.
</p>
<p>
<span class="bold"><strong>Warning</strong></span>: In a conventional configuration, where the Exim binary is setuid
to root, anybody who is able to edit the run time configuration file has an
easy way to run commands as root. If you make your mail administrators members
of the Exim group, but do not trust them with root, make sure that the run time
configuration is not group writeable.
</p>
<p>
A default configuration file, which will work correctly in simple situations,
is provided in the file <em class="filename">src/configure.default</em>. If CONFIGURE_FILE
defines just one file name, the installation process copies the default
configuration to a new file of that name if it did not previously exist. If
CONFIGURE_FILE is a list, no default is automatically installed. Chapter
<a href="ch07.html" title="7. The default configuration file">7</a> is a “<span class="quote">walk-through</span>” discussion of the default
configuration.
</p>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0057" id="SECID40">6.1 Using a different configuration file</a></h3></div>
</div>
</div>
<p>
<a id="id489698" class="indexterm"></a>
A one-off alternate configuration can be specified by the <span><strong class="option">-C</strong></span> command line
option, which may specify a single file or a list of files. However, when
<span><strong class="option">-C</strong></span> is used, Exim gives up its root privilege, unless called by root or the
Exim user (or unless the argument for <span><strong class="option">-C</strong></span> is identical to the built-in value
from CONFIGURE_FILE). <span><strong class="option">-C</strong></span> 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 <span><strong class="option">-C</strong></span>.
</p>
<p>
The privileged use of <span><strong class="option">-C</strong></span> by the Exim user can be locked out by setting
ALT_CONFIG_ROOT_ONLY in <em class="filename">Local/Makefile</em> when building Exim. However,
if you do this, you also lock out the possibility of testing a
configuration using <span><strong class="option">-C</strong></span> 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 <span><strong class="option">-C</strong></span> 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
<span><strong class="option">-odq</strong></span>, and another to do the delivery, using <span><strong class="option">-M</strong></span>).
</p>
<p>
If ALT_CONFIG_PREFIX is defined <em class="filename">in Local/Makefile</em>, it specifies a
prefix string with which any file named in a <span><strong class="option">-C</strong></span> command line option must
start. In addition, the file name must not contain the sequence “<span class="quote"><code class="literal">/../</code></span>”.
There is no default setting for ALT_CONFIG_PREFIX; when it is unset, any file
name can be used with <span><strong class="option">-C</strong></span>.
</p>
<p>
One-off changes to a configuration can be specified by the <span><strong class="option">-D</strong></span> command line
option, which defines and overrides values for macros used inside the
configuration file. However, like <span><strong class="option">-C</strong></span>, the use of this option by a
non-privileged user causes Exim to discard its root privilege.
If DISABLE_D_OPTION is defined in <em class="filename">Local/Makefile</em>, the use of <span><strong class="option">-D</strong></span> is
completely disabled, and its use causes an immediate error exit.
</p>
<p>
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 <em class="filename">Local/Makefile</em>, 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 <em class="function">uname()</em> 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 <span><strong class="option">-C</strong></span>.
</p>
<p>
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 <em class="filename">src/EDITME</em> for details.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0058" id="SECTconffilfor">6.2 Configuration file format</a></h3></div>
</div>
</div>
<p>
<a id="id489880" class="indexterm"></a>
<a id="id489894" class="indexterm"></a>
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 “<span class="quote">begin</span>” followed by the name of the part. The
optional parts are:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
<span class="emphasis"><em>ACL</em></span>: Access control lists for controlling incoming SMTP mail (see chapter
<a href="ch40.html" title="40. Access control lists">40</a>).
</p>
</li><li><p>
<a id="id489937" class="indexterm"></a>
<span class="emphasis"><em>authenticators</em></span>: Configuration settings for the authenticator drivers. These
are concerned with the SMTP AUTH command (see chapter <a href="ch33.html" title="33. SMTP authentication">33</a>).
</p>
</li><li><p>
<span class="emphasis"><em>routers</em></span>: Configuration settings for the router drivers. Routers process
addresses and determine how the message is to be delivered (see chapters
<a href="ch15.html" title="15. Generic options for routers">15</a>–<a href="ch22.html" title="22. The redirect router">22</a>).
</p>
</li><li><p>
<span class="emphasis"><em>transports</em></span>: Configuration settings for the transport drivers. Transports
define mechanisms for copying messages to destinations (see chapters
<a href="ch24.html" title="24. Generic options for transports">24</a>–<a href="ch30.html" title="30. The smtp transport">30</a>).
</p>
</li><li><p>
<span class="emphasis"><em>retry</em></span>: Retry rules, for use when a message cannot be delivered immediately.
If there is no retry section, or if it is empty (that is, no retry rules are
defined), Exim will not retry deliveries. In this situation, temporary errors
are treated the same as permanent errors. Retry rules are discussed in chapter
<a href="ch32.html" title="32. Retry configuration">32</a>.
</p>
</li><li><p>
<span class="emphasis"><em>rewrite</em></span>: Global address rewriting rules, for use when a message arrives and
when new addresses are generated during delivery. Rewriting is discussed in
chapter <a href="ch31.html" title="31. Address rewriting">31</a>.
</p>
</li><li><p>
<span class="emphasis"><em>local_scan</em></span>: Private options for the <em class="function">local_scan()</em> function. If you
want to use this feature, you must set
</p>
<pre class="literallayout">LOCAL_SCAN_HAS_OPTIONS=yes
</pre><p>
in <em class="filename">Local/Makefile</em> before building Exim. Details of the <em class="function">local_scan()</em>
facility are given in chapter <a href="ch42.html" title="42. Adding a local scan function to Exim">42</a>.
</p>
</li></ul></div>
<p>
<a id="id490101" class="indexterm"></a>
<a id="id490116" class="indexterm"></a>
<a id="id490130" class="indexterm"></a>
Leading and trailing white space in configuration lines is always ignored.
</p>
<p>
Blank lines in the file, and lines starting with a # character (ignoring
leading white space) are treated as comments and are ignored. <span class="bold"><strong>Note</strong></span>: A
# character other than at the beginning of a line is not treated specially,
and does not introduce a comment.
</p>
<p>
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.
</p>
<p>
A convenient way to create a configuration file is to start from the
default, which is supplied in <em class="filename">src/configure.default</em>, and add, delete, or
change settings as required.
</p>
<p>
The ACLs, retry rules, and rewriting rules have their own syntax which is
described in chapters <a href="ch40.html" title="40. Access control lists">40</a>, <a href="ch32.html" title="32. Retry configuration">32</a>, and <a href="ch31.html" title="31. Address rewriting">31</a>,
respectively. The other parts of the configuration file have some syntactic
items in common, and these are described below, from section <a href="ch06.html#SECTcos" title="6.10 Common option syntax">6.10</a>
onwards. Before that, the inclusion, macro, and conditional facilities are
described.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0059" id="SECID41">6.3 File inclusions in the configuration file</a></h3></div>
</div>
</div>
<p>
<a id="id490227" class="indexterm"></a>
<a id="id490238" class="indexterm"></a>
<a id="id490253" class="indexterm"></a>
<a id="id490269" class="indexterm"></a>
You can include other files inside Exim’s run time configuration file by
using this syntax:
</p>
<div class="literallayout">
<code class="literal">.include</code> <<span class="emphasis"><em>file name</em></span>><br />
<code class="literal">.include_if_exists</code> <<span class="emphasis"><em>file name</em></span>><br />
</div>
<p>
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.
</p>
<p>
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.
</p>
<p>
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:
</p>
<pre class="literallayout">hosts_lookup = a.b.c \
.include /some/file
</pre><p>
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.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0060" id="SECTmacrodefs">6.4 Macros in the configuration file</a></h3></div>
</div>
</div>
<p>
<a id="id490367" class="indexterm"></a>
<a id="id490381" class="indexterm"></a>
If a line in the main part of the configuration (that is, before the first
“<span class="quote">begin</span>” line) begins with an upper case letter, it is taken as a macro
definition, and must be of the form
</p>
<div class="literallayout">
<<span class="emphasis"><em>name</em></span>> = <<span class="emphasis"><em>rest of line</em></span>><br />
</div>
<p>
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.
</p>
<p>
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 <span><strong class="option">local_scan</strong></span>, retry, or rewrite sections of the configuration.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0061" id="SECID42">6.5 Macro substitution</a></h3></div>
</div>
</div>
<p>
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
</p>
<div class="literallayout">
<code class="literal">ABCD_XYZ = </code><<span class="emphasis"><em>something</em></span>><br />
<code class="literal">ABCD = </code><<span class="emphasis"><em>something else</em></span>><br />
</div>
<p>
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 <code class="literal">.include</code> line.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0062" id="SECID43">6.6 Redefining macros</a></h3></div>
</div>
</div>
<p>
Once defined, the value of a macro can be redefined later in the configuration
(or in an included file). Redefinition is specified by using <span class="emphasis"><em>==</em></span> instead of
<span class="emphasis"><em>=</em></span>. For example:
</p>
<pre class="literallayout">MAC = initial value
...
MAC == updated value
</pre><p>
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:
</p>
<pre class="literallayout">MAC = initial value
...
MAC == MAC and something added
</pre><p>
This can be helpful in situations where the configuration file is built
from a number of other files.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0063" id="SECID44">6.7 Overriding macro values</a></h3></div>
</div>
</div>
<p>
The values set for macros in the configuration file can be overridden by the
<span><strong class="option">-D</strong></span> command line option, but Exim gives up its root privilege when <span><strong class="option">-D</strong></span> is
used, unless called by root or the Exim user. A definition on the command line
using the <span><strong class="option">-D</strong></span> option causes all definitions and redefinitions within the
file to be ignored.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0064" id="SECID45">6.8 Example of macro usage</a></h3></div>
</div>
</div>
<p>
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:
</p>
<pre class="literallayout">ALIAS_QUERY = select mailbox from user where \
login=${quote_mysql:$local_part};
</pre><p>
This can then be used in a <span><strong class="command">redirect</strong></span> router setting like this:
</p>
<pre class="literallayout">data = ${lookup mysql{ALIAS_QUERY}}
</pre><p>
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 <a href="ch10.html#SECTnamedlists" title="10.5 Named lists">10.5</a>.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0065" id="SECID46">6.9 Conditional skips in the configuration file</a></h3></div>
</div>
</div>
<p>
<a id="id490641" class="indexterm"></a>
<a id="id490656" class="indexterm"></a>
You can use the directives <code class="literal">.ifdef</code>, <code class="literal">.ifndef</code>, <code class="literal">.elifdef</code>,
<code class="literal">.elifndef</code>, <code class="literal">.else</code>, and <code class="literal">.endif</code> 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).
</p>
<p>
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:
</p>
<pre class="literallayout">.ifdef AAA
message_size_limit = 50M
.else
message_size_limit = 100M
.endif
</pre><p>
sets a message size limit of 50M if the macro <code class="literal">AAA</code> 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 “<span class="quote">or</span>” condition. To
obtain an “<span class="quote">and</span>” condition, you need to use nested <code class="literal">.ifdef</code>s.
</p>
<p>
Although you can use a macro expansion to generate one of these directives,
it is not very useful, because the condition “<span class="quote">there was a macro substitution
in this line</span>” will always be true.
</p>
<p>
Text following <code class="literal">.else</code> and <code class="literal">.endif</code> is ignored, and can be used as comment
to clarify complicated nestings.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0066" id="SECTcos">6.10 Common option syntax</a></h3></div>
</div>
</div>
<p>
<a id="id490788" class="indexterm"></a>
<a id="id490799" class="indexterm"></a>
<a id="id490810" class="indexterm"></a>
For the main set of options, driver options, and <em class="function">local_scan()</em> 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:
</p>
<pre class="literallayout">qualify_domain = mydomain.example.com
</pre><p>
<a id="id490848" class="indexterm"></a>
<a id="id490860" class="indexterm"></a>
<a id="id490874" class="indexterm"></a>
Some option settings may contain sensitive data, for example, passwords for
accessing databases. To stop non-admin users from using the <span><strong class="option">-bP</strong></span> command
line option to read these values, you can precede the option settings with the
word “<span class="quote">hide</span>”. For example:
</p>
<pre class="literallayout">hide mysql_servers = localhost/users/admin/secret-password
</pre><p>
For non-admin users, such options are displayed like this:
</p>
<pre class="literallayout">mysql_servers = <value not displayable>
</pre><p>
If “<span class="quote">hide</span>” is used on a driver option, it hides the value of that option on
all instances of the same driver.
</p>
<p>
The following sections describe the syntax used for the different data types
that are found in option settings.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0067" id="SECID47">6.11 Boolean options</a></h3></div>
</div>
</div>
<p>
<a id="id490949" class="indexterm"></a>
<a id="id490964" class="indexterm"></a>
<a id="id490975" class="indexterm"></a>
<a id="id490989" class="indexterm"></a>
Options whose type is given as boolean are on/off switches. There are two
different ways of specifying such options: with and without a data value. If
the option name is specified on its own without data, the switch is turned on;
if it is preceded by “<span class="quote">no_</span>” or “<span class="quote">not_</span>” the switch is turned off. However,
boolean options may be followed by an equals sign and one of the words
“<span class="quote">true</span>”, “<span class="quote">false</span>”, “<span class="quote">yes</span>”, or “<span class="quote">no</span>”, as an alternative syntax. For example,
the following two settings have exactly the same effect:
</p>
<pre class="literallayout">queue_only
queue_only = true
</pre><p>
The following two lines also have the same (opposite) effect:
</p>
<pre class="literallayout">no_queue_only
queue_only = false
</pre><p>
You can use whichever syntax you prefer.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0068" id="SECID48">6.12 Integer values</a></h3></div>
</div>
</div>
<p>
<a id="id491070" class="indexterm"></a>
<a id="id491081" class="indexterm"></a>
If an option’s type is given as “<span class="quote">integer</span>”, the value can be given in decimal,
hexadecimal, or octal. If it starts with a digit greater than zero, a decimal
number is assumed. Otherwise, it is treated as an octal number unless it starts
with the characters “<span class="quote">0x</span>”, in which case the remainder is interpreted as a
hexadecimal number.
</p>
<p>
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 sometimes, but not always, printed using the letters K
and M. The printing style is independent of the actual input format that was
used.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0069" id="SECID49">6.13 Octal integer values</a></h3></div>
</div>
</div>
<p>
<a id="id491132" class="indexterm"></a>
<a id="id491143" class="indexterm"></a>
If an option’s type is given as “<span class="quote">octal integer</span>”, its value is always
interpreted as an octal number, whether or not it starts with the digit zero.
Such options are always output in octal.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0070" id="SECID50">6.14 Fixed point numbers</a></h3></div>
</div>
</div>
<p>
<a id="id491179" class="indexterm"></a>
<a id="id491190" class="indexterm"></a>
If an option’s type is given as “<span class="quote">fixed-point</span>”, its value must be a decimal
integer, optionally followed by a decimal point and up to three further digits.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0071" id="SECTtimeformat">6.15 Time intervals</a></h3></div>
</div>
</div>
<p>
<a id="id491224" class="indexterm"></a>
<a id="id491239" class="indexterm"></a>
A time interval is specified as a sequence of numbers, each followed by one of
the following letters, with no intervening white space:
</p>
<div class="informaltable">
<table border="0"><colgroup><col align="left" /><col align="left" /></colgroup><tbody><tr><td align="left"> <span><strong class="option">s</strong></span></td><td align="left">seconds</td></tr><tr><td align="left"> <span><strong class="option">m</strong></span></td><td align="left">minutes</td></tr><tr><td align="left"> <span><strong class="option">h</strong></span></td><td align="left">hours</td></tr><tr><td align="left"> <span><strong class="option">d</strong></span></td><td align="left">days</td></tr><tr><td align="left"> <span><strong class="option">w</strong></span></td><td align="left">weeks</td></tr></tbody></table></div>
<p>
For example, “<span class="quote">3h50m</span>” specifies 3 hours and 50 minutes. The values of time
intervals are output in the same format. Exim does not restrict the values; it
is perfectly acceptable, for example, to specify “<span class="quote">90m</span>” instead of “<span class="quote">1h30m</span>”.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0072" id="SECTstrings">6.16 String values</a></h3></div>
</div>
</div>
<p>
<a id="id491378" class="indexterm"></a>
<a id="id491393" class="indexterm"></a>
If an option’s type is specified as “<span class="quote">string</span>”, the value can be specified with
or without double-quotes. If it does not start with a double-quote, the value
consists of the remainder of the line plus any continuation lines, starting at
the first character after any leading white space, with trailing white space
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 two settings are
therefore equivalent:
</p>
<pre class="literallayout">trusted_users = uucp:mail
trusted_users = uucp:\
# This comment line is ignored
mail
</pre><p>
<a id="id491426" class="indexterm"></a>
<a id="id491440" class="indexterm"></a>
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:
</p>
<div class="informaltable">
<table border="0"><colgroup><col align="left" /><col align="left" /></colgroup><tbody><tr><td align="left"> <code class="literal">\\</code></td><td align="left">single backslash</td></tr><tr><td align="left"> <code class="literal">\n</code></td><td align="left">newline</td></tr><tr><td align="left"> <code class="literal">\r</code></td><td align="left">carriage return</td></tr><tr><td align="left"> <code class="literal">\t</code></td><td align="left">tab</td></tr><tr><td align="left"> <code class="literal">\</code><<span class="emphasis"><em>octal digits</em></span>></td><td align="left">up to 3 octal digits specify one character</td></tr><tr><td align="left"> <code class="literal">\x</code><<span class="emphasis"><em>hex digits</em></span>></td><td align="left">up to 2 hexadecimal digits specify one character</td></tr></tbody></table></div>
<p>
If a backslash is followed by some other character, including a double-quote
character, that character replaces the pair.
</p>
<p>
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.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0073" id="SECID51">6.17 Expanded strings</a></h3></div>
</div>
</div>
<p>
<a id="id491614" class="indexterm"></a>
Some strings in the configuration file are subjected to <span class="emphasis"><em>string expansion</em></span>,
by which means various parts of the string may be changed according to the
circumstances (see chapter <a href="ch11.html" title="11. String expansions">11</a>). 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.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0074" id="SECID52">6.18 User and group names</a></h3></div>
</div>
</div>
<p>
<a id="id491660" class="indexterm"></a>
<a id="id491674" class="indexterm"></a>
<a id="id491689" class="indexterm"></a>
<a id="id491703" class="indexterm"></a>
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
<em class="function">getpwnam()</em> or <em class="function">getgrnam()</em> function, as appropriate.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0075" id="SECTlistconstruct">6.19 List construction</a></h3></div>
</div>
</div>
<p>
<a id="id491747" class="indexterm"></a>
<a id="id491762" class="indexterm"></a>
<a id="id491777" class="indexterm"></a>
The data for some configuration options is a list of items, with colon as the
default separator. Many of these options are shown with type “<span class="quote">string list</span>” in
the descriptions later in this document. Others are listed as “<span class="quote">domain list</span>”,
“<span class="quote">host list</span>”, “<span class="quote">address list</span>”, or “<span class="quote">local part list</span>”. Syntactically, they
are all the same; however, those other than “<span class="quote">string list</span>” are subject to
particular kinds of interpretation, as described in chapter
<a href="ch10.html" title="10. Domain, host, address, and local part lists">10</a>.
</p>
<p>
In all these cases, the entire list is treated as a single string as far as the
input syntax is concerned. The <span><strong class="option">trusted_users</strong></span> setting in section
<a href="ch06.html#SECTstrings" title="6.16 String values">6.16</a> 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
</p>
<pre class="literallayout">local_interfaces = 127.0.0.1 : ::::1
</pre><p>
contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1.
</p>
<p>
<span class="bold"><strong>Note</strong></span>: Although leading and trailing white space is ignored in individual
list items, it is not ignored when parsing the list. The space after the first
colon in the example above is necessary. If it were not there, the list would
be interpreted as the two items 127.0.0.1:: and 1.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0076" id="SECID53">6.20 Changing list separators</a></h3></div>
</div>
</div>
<p>
<a id="id491887" class="indexterm"></a>
<a id="id491901" class="indexterm"></a>
Doubling colons in IPv6 addresses 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:
</p>
<pre class="literallayout">local_interfaces = <; 127.0.0.1 ; ::1
</pre><p>
This facility applies to all lists, with the exception of the list in
<span><strong class="option">log_file_path</strong></span>. It is recommended that the use of non-colon separators be
confined to circumstances where they really are needed.
</p>
<p>
<a id="id491944" class="indexterm"></a>
<a id="id491958" class="indexterm"></a>
It is also possible to use newline and other control characters (those with
code values less than 32, plus DEL) as separators in lists. Such separators
must be provided literally at the time the list is processed. For options that
are string-expanded, you can write the separator using a normal escape
sequence. This will be processed by the expander before the string is
interpreted as a list. For example, if a newline-separated list of domains is
generated by a lookup, you can process it directly by a line such as this:
</p>
<pre class="literallayout">domains = <\n ${lookup mysql{.....}}
</pre><p>
This avoids having to change the list separator in such data. You are unlikely
to want to use a control character as a separator in an option that is not
expanded, because the value is literal text. However, it can be done by giving
the value in quotes. For example:
</p>
<pre class="literallayout">local_interfaces = "<\n 127.0.0.1 \n ::1"
</pre><p>
Unlike printing character separators, which can be included in list items by
doubling, it is not possible to include a control character as data when it is
set as the separator. Two such characters in succession are interpreted as
enclosing an empty list item.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0077" id="SECTempitelis">6.21 Empty items in lists</a></h3></div>
</div>
</div>
<p>
<a id="id492019" class="indexterm"></a>
An empty item at the end of a list is always ignored. In other words, trailing
separator characters are ignored. Thus, the list in
</p>
<pre class="literallayout">senders = user@domain :
</pre><p>
contains only a single item. If you want to include an empty string as one item
in a list, it must not be the last item. For example, this list contains three
items, the second of which is empty:
</p>
<pre class="literallayout">senders = user1@domain : : user2@domain
</pre><p>
<span class="bold"><strong>Note</strong></span>: There must be white space between the two colons, as otherwise they
are interpreted as representing a single colon data character (and the list
would then contain just one item). If you want to specify a list that contains
just one, empty item, you can do it as in this example:
</p>
<pre class="literallayout">senders = :
</pre><p>
In this case, the first item is empty, and the second is discarded because it
is at the end of the list.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0078" id="SECTfordricon">6.22 Format of driver configurations</a></h3></div>
</div>
</div>
<p>
<a id="id492099" class="indexterm"></a>
There are separate parts in the configuration for defining routers, transports,
and authenticators. In each part, you are defining a number of driver
instances, each with its own set of options. Each driver instance is defined by
a sequence of lines like this:
</p>
<div class="literallayout">
<<span class="emphasis"><em>instance name</em></span>>:<br />
<<span class="emphasis"><em>option</em></span>><br />
...<br />
<<span class="emphasis"><em>option</em></span>><br />
</div>
<p>
In the following example, the instance name is <span><strong class="command">localuser</strong></span>, and it is
followed by three options settings:
</p>
<pre class="literallayout">localuser:
driver = accept
check_local_user
transport = local_delivery
</pre><p>
For each driver instance, you specify which Exim code module it uses – by the
setting of the <span><strong class="option">driver</strong></span> option – and (optionally) some configuration
settings. For example, in the case of transports, if you want a transport to
deliver with SMTP you would use the <span><strong class="command">smtp</strong></span> driver; if you want to deliver to
a local file you would use the <span><strong class="command">appendfile</strong></span> driver. Each of the drivers is
described in detail in its own separate chapter later in this manual.
</p>
<p>
You can have several routers, transports, or authenticators that are based on
the same underlying driver (each must have a different instance name).
</p>
<p>
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 that matches an authentication mechanism offered by the
server.
</p>
<p>
<a id="id492201" class="indexterm"></a>
<a id="id492212" class="indexterm"></a>
Within a driver instance definition, there are two kinds of option: <span class="emphasis"><em>generic</em></span>
and <span class="emphasis"><em>private</em></span>. The generic options are those that apply to all drivers of the
same type (that is, all routers, all transports or all authenticators). The
<span><strong class="option">driver</strong></span> option is a generic option that must appear in every definition.
<a id="id492242" class="indexterm"></a>
The private options are special for each driver, and none need appear, because
they all have default values.
</p>
<p>
The options may appear in any order, except that the <span><strong class="option">driver</strong></span> option must
precede any private options, since these depend on the particular driver. For
this reason, it is recommended that <span><strong class="option">driver</strong></span> always be the first option.
</p>
<p>
Driver instance names, which are used for reference in log entries and
elsewhere, 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 module. For example, the
configuration lines:
</p>
<pre class="literallayout">remote_smtp:
driver = smtp
</pre><p>
create an instance of the <span><strong class="command">smtp</strong></span> transport driver whose name is
<span><strong class="command">remote_smtp</strong></span>. 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 <span><strong class="command">smtp</strong></span> transport, with different options, might be defined
thus:
</p>
<pre class="literallayout">special_smtp:
driver = smtp
port = 1234
command_timeout = 10s
</pre><p>
The names <span><strong class="command">remote_smtp</strong></span> and <span><strong class="command">special_smtp</strong></span> would be used to reference
these transport instances from routers, and these names would appear in log
lines.
</p>
<p>
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
defaulted values, can be extracted by making use of the <span><strong class="option">-bP</strong></span> command line
option.
</p>
</div>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch05.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</body></html>
