File: spec_7.html

package info (click to toggle)
exim-html 3.20-1
links: PTS
area: main
in suites: etch, etch-m68k, sarge, woody
size: 2,868 kB
ctags: 4,188
sloc: makefile: 40; sh: 19
file content (1211 lines) | stat: -rw-r--r-- 40,530 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from spec on 25 November 2000 -->

<TITLE>Exim Specification - 7. The Exim configuration file</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_6.html">previous</A>, <A HREF="spec_8.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC156" HREF="spec_toc.html#TOC156">7. The Exim configuration file</A></H1>

<P>
<A NAME="IDX451"></A>
<A NAME="IDX452"></A>
<A NAME="IDX453"></A>
<font color=green>
Exim uses a single run time configuration file which is read whenever an Exim
binary is executed.
</font>
The name of the file is compiled into the binary for security reasons, and is
specified by the CONFIGURE_FILE compilation option.

</P>
<P>
<A NAME="IDX454"></A>
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 <TT>`Local/Makefile'</TT>,
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>uname()</EM> function.
If this file does not exist, the standard name is tried.

</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 <TT>`src/EDITME'</TT> for details.

</P>
<P>
<A NAME="IDX455"></A>
<A NAME="IDX456"></A>
<A NAME="IDX457"></A>
<A NAME="IDX458"></A>
The run time configuration file must be owned by root or by the user that
is specified at compile time by the EXIM_UID option, and it must not be
world-writeable or group-writeable, unless its group is the one specified at
compile time by the EXIM_GID option.

</P>
<P>
<A NAME="IDX459"></A>
<A NAME="IDX460"></A>
<font color=green>
Macros in the configuration file can be overridden by the -<EM>D</EM> command line
option, and a one-off alternative configuration file can be specified by the
-<EM>C</EM> command line option, but if either of these options are used,
Exim immediately gives up its root privilege, unless called by root or the Exim
user. -<EM>C</EM> 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 -<EM>C</EM>.
</font>

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

</P>
<P>
<A NAME="IDX461"></A>
<A NAME="IDX462"></A>
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.

</P>

<P>



<H2><A NAME="SEC157" HREF="spec_toc.html#TOC157">7.1 Configuration file format</A></H2>

<P>
<A NAME="IDX463"></A>
<A NAME="IDX464"></A>
Exim's configuration file is in seven parts, which must appear in the correct
order in the file, separated by lines containing just the word `end'. However,
any parts at the end of the file that are not required may be omitted. The file
contains:

</P>

<UL>

<LI>

Main configuration settings:
<font color=green>
options for controlling input, and other overall parameters that are not
specific to any of the drivers.
</font>

<LI>

Configuration settings for the transport drivers. Transports define mechanisms
for copying messages to destinations.

<LI>

Configuration settings for the director drivers. Directors process local
addresses, that is, those with domains that match <EM>local_domains</EM>. These
are typically (but not necessarily) delivered on the local host.

<LI>

Configuration settings for the router drivers. Routers process remote
addresses, that is, those with domains that do not match <EM>local_domains</EM>.

<LI>

Retry rules, for use when a message cannot be immediately delivered.

<LI>

<font color=green>
Address rewriting rules, for use when a message arrives and when new addresses
are generated during delivery.
</font>

<LI>

Configuration settings for the authenticator drivers. These are concerned with
the SMTP AUTH command (see chapter 35), and this part of the
configuration can be omitted when AUTH is not in use.
</UL>

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

</P>
<P>
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.
</font>

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

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

</P>



<H2><A NAME="SEC158" HREF="spec_toc.html#TOC158">7.2 Macros in the configuration file</A></H2>

<P>
<A NAME="IDX465"></A>
<A NAME="IDX466"></A>
If a line in the main part of the configuration (that is, before the first
`end' line) begins with an upper-case letter, it is taken as a macro
definition, and must be of the form

<PRE>
&#60;<EM>name</EM>&#62; = &#60;<EM>rest of line</EM>&#62;
</PRE>

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

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

<PRE>
ABCD_XYZ = &#60;&#60;something&#62;&#62;
ABCD = &#60;&#60;something&#62;&#62;
</PRE>

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

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

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

local_domains = LOCAL1:LOCAL2:LOCAL3
</PRE>

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

</P>



<H2><A NAME="SEC159" HREF="spec_toc.html#TOC159">7.3 Common option syntax</A></H2>

<P>
<A NAME="IDX467"></A>
<A NAME="IDX468"></A>
<A NAME="IDX469"></A>
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.
<font color=green>
For example:

<PRE>
qualify_domain = mydomain.example.com
</PRE>

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

<PRE>
hide mysql_servers = localhost/users/admin/secret-password
</PRE>

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

<PRE>
mysql_servers = &#60;value not displayable&#62;
</PRE>

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

</P>
<P>
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:

<PRE>
sender_verify
no_smtp_verify
queue_only = true
</PRE>

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

</P>



<H2><A NAME="SEC160" HREF="spec_toc.html#TOC160">7.4 Integer</A></H2>

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

</P>
<P>
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.

</P>


<H2><A NAME="SEC161" HREF="spec_toc.html#TOC161">7.5 Octal integer</A></H2>

<P>
<A NAME="IDX472"></A>
<A NAME="IDX473"></A>
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.

</P>



<H2><A NAME="SEC162" HREF="spec_toc.html#TOC162">7.6 Fixed point number</A></H2>

<P>
<A NAME="IDX474"></A>
<A NAME="IDX475"></A>
A fixed point number consists of a decimal integer, optionally followed by a
decimal point and up to three further digits.

</P>



<H2><A NAME="SEC163" HREF="spec_toc.html#TOC163">7.7 Time interval</A></H2>

<P>
<A NAME="IDX476"></A>
<A NAME="IDX477"></A>
A time interval is specified as a sequence of numbers, each followed by one of
the following letters, with no intervening white space:

<PRE>
<EM>s</EM>    seconds
<EM>m</EM>    minutes
<EM>h</EM>    hours
<EM>d</EM>    days
<EM>w</EM>    weeks
</PRE>

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

</P>



<H2><A NAME="SEC164" HREF="spec_toc.html#TOC164">7.8 String</A></H2>

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

<PRE>
trusted_users = uucp:mail

trusted_users = uucp:\
                # This comment line is ignored
                mail
</PRE>

<P>
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:
</font>

<PRE>
\\               single backslash
\n               newline
\r               carriage return
\t               tab
\&#60;<EM>octal digits</EM>&#62;  up to 3 octal digits specify one character
\x&#60;<EM>hex digits</EM>&#62;   up to 2 hexadecimal digits specify one character
</PRE>

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

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

</P>



<H2><A NAME="SEC165" HREF="spec_toc.html#TOC165">7.9 Expanded strings</A></H2>

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

</P>


<H2><A NAME="SEC166" HREF="spec_toc.html#TOC166">7.10 User and group names</A></H2>

<P>
<A NAME="IDX480"></A>
<A NAME="IDX481"></A>
<A NAME="IDX482"></A>
<A NAME="IDX483"></A>
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 <EM>getpwnam()</EM> or
<EM>getgrnam()</EM> function, as appropriate.

</P>
<P>
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 <EM>$</EM> 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 <EM>getpwnam()</EM> or <EM>getgrnam()</EM>, as
appropriate.

</P>

<P>
<font color=green>


<H2><A NAME="SEC167" HREF="spec_toc.html#TOC167">7.11 List construction</A></H2>

<P>
<A NAME="IDX484"></A>
<A NAME="IDX485"></A>
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 <EM>trusted_users</EM> setting in section 7.8 above is an
example. If a colon is actually needed in an item in a list, it must be entered
as two colons. Leading and trailing white space on each item in a list is
ignored. This makes it possible to include items that start with a colon, and
in particular, certain forms of IPv6 address. For example, the list

<PRE>
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.
IPv6 addresses are going to become more and more common as the new protocol
gets more widely deployed.
<A NAME="IDX486"></A>
<A NAME="IDX487"></A>
Doubling their colons is a unwelcome chore, so a mechanism was introduced to
allow the separator character to be changed. If a list begins with a left angle
bracket, followed by any punctuation character, that character is used instead
of colon as the list separator. For example, the list above can be rewritten to
use a semicolon separator like this:

<PRE>
local_interfaces = &#60;; 127.0.0.1 ; ::1
</PRE>

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

</P>



<H2><A NAME="SEC168" HREF="spec_toc.html#TOC168">7.12 Domain lists</A></H2>

<P>
<A NAME="IDX488"></A>
<A NAME="IDX489"></A>
<A NAME="IDX490"></A>
<font color=green>
Domain lists are constructed as described in section 7.11. They
contain patterns that are to be matched against a mail domain. For example, the
<EM>local_domains</EM> option is a domain list, one of whose patterns must match
every domain that Exim is to treat as local.
</font>

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

<PRE>
relay_domains = !a.b.c : *.b.c
</PRE>

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

<PRE>
relay_domains = !a.b.c
</PRE>

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

</P>
<P>
The following types of item may appear in domain lists:

</P>

<UL>

<LI>

<A NAME="IDX493"></A>
<A NAME="IDX494"></A>
<A NAME="IDX495"></A>
If an item in a domain list is a plain absolute file name (beginning with a
slash character), each line of the file is read and processed as if it were
an independent item in the list, except that further plain file names are not
allowed. This happens each time the list is searched. If a # character appears
anywhere in a line of the file, it and all following characters are ignored.
Blank lines are also ignored. Wild cards, negation, and regular expressions may
be used in the lines of the file, just as in the main list. For example, if

<PRE>
local_domains = /etc/local-domains
</PRE>

then the file could contain lines like

<PRE>
^.*\d{3}\.mydomain\.com$
</PRE>

If a plain file name is preceded by an exclamation mark, the sense of any match
within the file is inverted. For example, if

<PRE>
hold_domains = !/etc/nohold-domains
</PRE>

and the file contains the lines

<PRE>
!a.b.c
*.b.c
</PRE>

then <TT>`a.b.c'</TT> is in the set of domains defined by <EM>hold_domains</EM>, whereas any
domain matching <TT>`*.b.c'</TT> is not.

<LI>

If a pattern consists of a single @ character, it matches the local host name,
as set in the <EM>primary_hostname</EM> option. This makes it possible to use the
same configuration file on several different hosts that differ only in their
names.

<LI>

If a pattern starts with an asterisk, the remaining characters of the
pattern are compared with the terminating characters of the domain. The use of
`*' in domain lists differs from its use in partial matching lookups. In a
domain list, the character following the asterisk need not be a dot, whereas
partial matching works only in terms of dot-separated components. For example,
a domain list item such as <TT>`*key.ex'</TT> matches <TT>`donkey.ex'</TT> as well as
<TT>`cipher.key.ex'</TT>.

<LI>

<A NAME="IDX496"></A>
If a pattern starts with a circumflex character, it is treated as a
regular expression, and matched against the domain using a regular expression
matching function. The circumflex is treated as part of the regular expression.
References to descriptions of the syntax of regular expressions are given in
chapter 8, but note that if a backslash is required in the regular
expression, it must be given as two backslashes if the string is in quotes.

There are some cases where a domain list is the result of string expansion, for
example the <EM>domains</EM> option in routers and directors. In these cases you must
escape any backslash and dollar characters in regular expressions, to
prevent them from being interpreted by the string expander, and if the string
is specified in quotes, the resulting backslashes must themselves also be
escaped.

<LI>

If a pattern starts with the name of a single-key lookup type followed by a
semicolon (for example, `dbm;' or `lsearch;') then the remainder of the pattern
must be a file name in a suitable format for the lookup type. For example, for
`lsearch;' it must be an absolute path. The appropriate type of lookup is done
on the file using the domain name as the key. The data from the lookup is
available in some cases via the expansion variable $<EM>domain_data</EM>. Note that
this is not an `include' facility when the lookup type is `lsearch'. The keys
in the file are not interpreted specially, as they would be if they appeared as
individual items in the domain list,
or as lines in a file referenced without a search type.

<LI>

Any of the single-key lookup type names may be preceded by `partial&#60;<EM>n</EM>&#62;-',
where the &#60;<EM>n</EM>&#62; is optional, for example,

<PRE>
partial-dbm;/partial/domains
</PRE>

This causes partial matching logic to be invoked; a description of how this
works is given in
section 6.7.

<LI>

Any of the single-key lookup types may be followed by an asterisk. This causes
a default lookup for a key consisting of a single asterisk to be done if the
original lookup fails. This is not a useful feature when using a domain list to
select particular domains (because any domain would match), but it might have
value if the result of the lookup is being used via the $<EM>domain_data</EM>
expansion variable.

<LI>

If the pattern starts with the name of a query-style lookup type followed by a
semicolon (for example, `nisplus;' or `ldap;'), the remainder of the pattern
must be an appropriate query for the lookup type, as described in chapter
6.
<A NAME="IDX497"></A>
The query is expanded before use, and the expansion substitution $<EM>key</EM> can be
used to insert the domain that is being tested into the query. The data
returned by a successful query is available in some cases via the expansion
variable $<EM>domain_data</EM>.

<LI>

If none of the above cases apply, a caseless textual comparison is made between
the pattern and the domain.
</UL>

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

<PRE>
local_domains = @:\
                lib.unseen.edu:\
                *.foundation.fict.book:\
                ^[1-2]\d{3}\.fict\.book$:\
                partial-dbm;/opt/data/penguin/book:\
                nis;domains.byname:\
                nisplus;[name=$key,status=local],domains.org_dir
</PRE>

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

</P>



<H2><A NAME="SEC169" HREF="spec_toc.html#TOC169">7.13 Host lists</A></H2>

<P>
<A NAME="IDX498"></A>
<A NAME="IDX499"></A>
<A NAME="IDX500"></A>
<font color=green>
Host lists are constructed as described in section 7.11. They
contain patterns which are matched against host names or IP addresses. Host
lists are used to control what remote hosts are allowed to do (for example, use
the local host as a relay). Their patterns define a set of hosts that the list
matches.
</font>

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

</P>
<P>
The following types of pattern may appear in a host list:

</P>

<UL>

<LI>

If the entire item is `*' it matches any host.

<LI>

If the item is in the form of an IP address, it is matched against the IP
address of the subject host. The presence of a colon is taken as an indication
that it is an IPv6 address (when IPv6 support is compiled into Exim); such
colons have to be doubled when colon is the item separator in the list (the
default).

<LI>

If the item is in the form of an IP address followed by a slash and a mask
length (for example 10.11.0.0/16) then it is matched against the IP address
of the subject host under the given mask, which specifies the number of
address bits that must match, starting from the most significant end. Thus an
entire network of hosts can be included (or excluded) by a single item.

IPv4 addresses are given in the normal `dotted-quad' notation. IPv6 addresses
are given in colon-separated format, but the colons have to be doubled so as
not to be taken as item separators. This example shows both kinds of address:

<PRE>
receiver_unqualified_hosts = 172.16.0.0/12: \
                             5f03::1200::836f::::/48
</PRE>

The doubling of list separator characters applies only when such addresses
appear inline in a host list. It is not required when indirecting via a file.
For example,

<PRE>
receiver_unqualified_hosts = /opt/exim/unqualnets
</PRE>

could make use of a file containing

<PRE>
172.16.0.0/12
5f03:1200:836f::/48
</PRE>

to have exactly the same effect as the previous example.
<font color=green>
When listing small numbers of IPv6 addresses inline, is is usually more
convenient to use the facility for changing separator characters. This list
contains the same two addresses:

<PRE>
receiver_unqualified_hosts = &#60;; 172.16.0.0/12; \
                                5f03:1200:836f::/48
</PRE>

</font>
If an IPv4 host calls an IPv6 host, the incoming address actually appears in
the IPv6 host as `::ffff:&#60;<EM>v4address</EM>&#62;'. When such an address is tested
against a  host list, it is converted into a traditional IPv4 address first.

<LI>

<A NAME="IDX502"></A>
<A NAME="IDX503"></A>
If the item is of the form

<PRE>
net&#60;<EM>number</EM>&#62;-&#60;<EM>search-type</EM>&#62;;&#60;<EM>search-data</EM>&#62;
</PRE>

for example:

<PRE>
net24-dbm;/networks.db
</PRE>

then the IP address of the subject host is masked using &#60;<EM>number</EM>&#62; as the mask
length; a textual string is then constructed from the masked value, followed by
the mask, and this is then used as the key for the lookup. For example, if the
host's IP address is 192.168.34.6 then the key that is looked up for the above
example is `192.168.34.0/24'. IPv6 addresses are converted to a text value
using lower case letters and full stops (periods) as separators instead of the
more usual colon, because colon is the key terminator in <EM>lsearch</EM> files. Full,
unabbreviated IPv6 addresses are always used.

<LI>

If the item is of the form

<PRE>
net-&#60;<EM>search-type</EM>&#62;;&#60;<EM>search-data</EM>&#62;
</PRE>

then the text form of the IP address of the subject host is used unmasked as
the lookup key. This is not the same as specifying <EM>net32</EM> for an IPv4 address
or <EM>net128</EM> for an IPv6 address, because the mask value is not included in the
key. However, IPv6 addresses are still converted to an unabbreviated form,
using lower case letters and full stops as separators.

<LI>

If the entire item is `@' the primary host name is used as the match item, and
the following applies:

<LI>

If the item is a plain domain name, Exim calls <EM>gethostbyname()</EM> to find
its IP address(es). This typically causes a forward DNS lookup of the name. The
result is compared with the IP address of the subject host.
</UL>

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

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

<PRE>
host_reject = +allow_unknown:*.enemy.ex
</PRE>

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

</P>
<P>
<A NAME="IDX508"></A>
<A NAME="IDX509"></A>
As a result of aliasing, hosts may have more than one name. When processing any
of the following items, all the host's names are checked.

</P>

<UL>

<LI>

If the item starts with `*' then the remainder of the item must match the end
of the host name. For example, <TT>`*.b.c'</TT> matches all hosts whose names end in
<TT>`.b.c'</TT>. This special simple form is provided because this is a very common
requirement. Other kinds of wildcarding require the use of a regular
expression.

<LI>

If the item starts with `^' then it is taken to be a regular expression which
is matched against the host name. For example,

<PRE>
^(a|b)\.c\.d$
</PRE>

matches either of the two hosts <EM>a.c.d</EM> or <EM>b.c.d</EM>. If the option string in
which this occurs is given in quotes, the backslash characters must be
doubled, because they are significant in quoted strings. The following two
settings are exactly equivalent:

<PRE>
host_reject = ^(a|b)\.c\.d$
host_reject = "^(a|b)\\.c\\.d$"
</PRE>

<LI>

If the item is of the form

<PRE>
&#60;<EM>search-type</EM>&#62;;&#60;<EM>filename or query</EM>&#62;
</PRE>

for example

<PRE>
dbm;/host/accept/list
</PRE>

then the host name is looked up using the search type and file name or query
(as appropriate). If the lookup succeeds, the host matches the item. The actual
data that is looked up is not used.

<font color=green>
<b>Warning</b>: when using this kind of lookup, you must have host <EM>names</EM> as
keys in the file, not IP addresses. If you want to do lookups based on IP
addresses, you must precede the search type with `net-' (see above). There
is, however, no reason why you could not use two items in a list, one doing an
address lookup and one doing a name lookup, both using the same file.
</font>
</UL>

<P>
<font color=green>


<H2><A NAME="SEC170" HREF="spec_toc.html#TOC170">7.14 Mixing host names and addresses in host lists</A></H2>

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

<PRE>
host_accept_relay = 10.9.8.7 : *.friends.domain
</PRE>

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

</P>



<H2><A NAME="SEC171" HREF="spec_toc.html#TOC171">7.15 Use of RFC 1413 identification in host lists</A></H2>

<P>
<A NAME="IDX510"></A>
<A NAME="IDX511"></A>
Any item in a host list (other than a plain file name or `+allow_unknown') can
optionally be preceded by

<PRE>
&#60;<EM>ident</EM>&#62;@
or
!&#60;<EM>ident</EM>&#62;@
</PRE>

<P>
where &#60;<EM>ident</EM>&#62; is an RFC 1413 identification string. For example,

<PRE>
host_reject = !exim@my.mail.gate:192.168.111.111:!root@public.host
</PRE>

<P>
If an &#60;<EM>ident</EM>&#62; 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 <EM>not</EM> match. The remainder of the item, following the @, may
be either positive or negative.

</P>



<H2><A NAME="SEC172" HREF="spec_toc.html#TOC172">7.16 Address lists</A></H2>

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

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

</P>

<UL>

<LI>

If a pattern starts with ^ then a regular expression match is done against the
complete address, using the entire pattern as the regular expression.

<LI>

Otherwise, if there is no @ in the pattern, it is first matched against the
domain part of the subject address, the local part being ignored. This match is
done exactly as for an entry in a domain list, so, for example, the item may
begin with * or it may be a (partial) lookup (see section 7.12).
If there is no match, and the pattern consists of a single lookup, the entire
subject address is looked up in the file, with partial matching disabled. This
means that an item such as

<PRE>
sender_reject_recipients = partial-dbm;/black/list
</PRE>

can reference a single file whose keys are a mixture of complete domains,
partial domains, and individual mail addresses.

Note that this is not an `include' facility when the lookup type is <EM>lsearch</EM>.
The keys in the file are not interpreted specially, as they would be if they
appeared as individual items in the address list, or lines in a file given as a
plain file name without a search type.

<font color=green>
You might think of using a lookup type ending in *@ (as described in section
6.6) to match entries in a file of the form

<PRE>
*@penguin.book
</PRE>

However, this does not currently work, because the presence of an @ in the
pattern causes Exim to think the item is one of the forms described below. In
some future release this may be changed. Meanwhile, the effect you want
(matching any local part at a particular domain) is achieved by simply listing
the domain name in the file.
</font>

<LI>

If the pattern starts with `@@&#60;lookup-item&#62;' (for example,
`@@lsearch;/some/file'), the address that is being checked is split into a
local part and a domain. The domain is looked up in the file. If it is not
found, there is no match. If it is found, the data that is looked up from the
file is treated as a colon-separated list of local part patterns, each of which
is matched against the subject local part in turn.

The lookup may be a partial one, and/or one involving a search for a default
keyed by `*'. The local part patterns that are looked up can be regular
expressions or begin with `*', or even be further lookups.
They may also be independently negated. For example, with

<PRE>
sender_reject_recipients = @@dbm;/etc/reject-by-domain
</PRE>

the data from which DBM file is built could contain lines like

<PRE>
baddomain.com:  !postmaster : *
</PRE>

<A NAME="IDX516"></A>
If a local part that actually begins with an exclamation mark is required, it
has to be specified using a regular expression.
In <EM>lsearch</EM> files, an entry may be split over several lines by indenting the
second and subsequent lines, but the separating colon must still be included at
line breaks. White space surrounding the colons is ignored. For example:

<PRE>
aol.com:  spammer1 : spammer2 : ^[0-9]+$ :
          spammer3 : spammer4
</PRE>

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, 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

<PRE>
aol.com: spammer1 : spammer 2 : &#62;*
xyz.com: spammer3 : &#62;*
*:       ^\d{8}$
</PRE>

in a file that was searched with <EM>@@dbm*</EM>, to specify a match for 8-digit
local parts for all domains, in addition to the specific local parts listed for
each domain. Of course, using this feature costs another lookup each time a
chain is followed, but the effort needed to maintain the data is reduced.
<A NAME="IDX517"></A>
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.

<LI>

If none of the above cases apply, the local part of the subject address is
compared with the local part of the pattern, which may start with an asterisk.
If the local parts match, the domains are compared in exactly the same way
as entries in a domain list, except that a regular expression is not permitted
for a domain only. However, file lookups are permitted. For example:

<PRE>
sender_reject = *@*.spamming.site:\
                bozo@partial-lsearch;/list/of/dodgy/sites
</PRE>

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@@'.
<A NAME="IDX518"></A>
If a local part that actually begins with an exclamation mark is required, it
has to be specified using a regular expression, as otherwise the exclamation
mark is treated as a sign of negation.
</UL>



<H2><A NAME="SEC173" HREF="spec_toc.html#TOC173">7.17 Case of letters in address lists</A></H2>

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

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

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

</P>

<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_6.html">previous</A>, <A HREF="spec_8.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>