File: spec_23.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 (615 lines) | stat: -rw-r--r-- 20,661 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from spec on 25 November 2000 -->

<TITLE>Exim Specification - 23. The aliasfile director</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_22.html">previous</A>, <A HREF="spec_24.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="SEC631" HREF="spec_toc.html#TOC631">23. The aliasfile director</A></H1>
<P>
<A NAME="IDX1467"></A>
<A NAME="IDX1468"></A>
The <EM>aliasfile</EM> director expands local parts by consulting a file or database
of aliases. An incoming local part is looked up, and the result is a list of
one or more replacement addresses, file names, pipe commands or certain special
items. The expansion may safely contain the same local part as the input as one
of its items, because a director is automatically skipped if it has an
identical ancestor that was processed by that director. For the case of a
new alias address that is identical to the input address, this rule means in
effect that it starts its processing at the following director.

</P>
<P>
The alias list can be obtained from a text file that is searched linearly, a
DBM direct-access file, a NIS or NIS+ map, an LDAP database, or any other kind
of lookup supported by Exim (see chapter 6).

</P>
<P>
<A NAME="IDX1469"></A>
Unless the <EM>locally_caseless</EM> option has been set false, local parts are
forced to lower case, and so the keys in alias files should normally be in
lower case. For linearly searched files this isn't in fact necessary, because
the searching is done in a case-independent manner, but it is relevant for
other forms of alias lookup. The <EM>exim_dbmbuild</EM> utility can be used to
convert a text file into a DBM database; the keys are lower-cased by default.

</P>

<P>



<H2><A NAME="SEC632" HREF="spec_toc.html#TOC632">23.1 Specifying a transport for aliasfile</A></H2>

<P>
The generic <EM>transport</EM> option must not be specified for <EM>aliasfile</EM> when it is
fulfilling a traditional aliasing function. If <EM>transport</EM> is specified,
the director behaves differently, and doesn't really `alias' at all. Its lookup
facilities are used as a means of validating the incoming address, but if it is
successful, the message is directed to the given transport while retaining the
original address. The data that is returned from the lookup is not used. For
example, a file containing a list of cancelled users can be used to direct
messages addressed to them to a particular script.

</P>
<P>
<A NAME="IDX1470"></A>
<A NAME="IDX1471"></A>
Another common use of <EM>aliasfile</EM> with a transport is for handling local
deliveries without reference to <EM>/etc/passwd</EM>. Local parts are validated by
using <EM>aliasfile</EM> to look them up in a file or database, which can also be used
to hold information for use during delivery (for example, the uid to use, or
the location of the mailbox). There is a sample configuration that gives more
detail.

</P>



<H2><A NAME="SEC633" HREF="spec_toc.html#TOC633">23.2 Alias file format</A></H2>

<P>
<A NAME="IDX1472"></A>
A textual alias file to be searched linearly consists of entries that start
with the alias name, terminated by a colon or white space. However, a colon
must be used if data for the alias starts with a colon, because white space is
permitted between the alias name and its terminating colon. This is Exim's
standard <EM>lsearch</EM> format (see chapter 6).

</P>
<P>
The remainder of the entry, up to the end of the line, consists of a list of
addresses, file names, pipe commands, or certain special items (see below). The
items in the list are separated by commas. The list can be continued over
several lines by starting each of the continuation lines with white space.
<font color=green>
A single space is retained at each junction. However,
</font>
a comma is still required following an item that ends at the end of a line,
because the <EM>lsearch</EM> lookup code removes newlines from the string it returns.

</P>
<P>
Lines in textual alias files that start with a # character are comments, and
are ignored, and a # may also appear following a comma in an item list, in
which case everything after the # is ignored. Other forms of alias file (DBM,
NIS, LDAP, etc.) involve lookups using the local part as a key on files and
databases. The value returned is a list of items separated by commas or
newlines. The returned list is normally used exactly as it stands, but if the
<EM>expand</EM> option is set, it is first passed through the string expansion
mechanism.

</P>
<P>
By default, alias names are simple local parts such as `postmaster', but if the
<EM>include_domain</EM> option is set, they must contain both a local part and a
domain, thus allowing aliases for more than one domain to be held in a single
file.

</P>
<P>
<A NAME="IDX1473"></A>
<A NAME="IDX1474"></A>
It is possible to set up a default in an alias file that uses a single-key
lookup type. This matches incoming local parts that do not match any other
entry when the lookup type name is followed by an asterisk, for example
<EM>dbm*</EM> (see section 6.6). For query-style lookups, the
<EM>queries</EM> option specifies a list of queries to be tried.

</P>



<H2><A NAME="SEC634" HREF="spec_toc.html#TOC634">23.3 Types of alias item</A></H2>

<P>
If an item is entirely enclosed in double quotes, these are removed.
Otherwise double quotes are retained because some forms of mail address
require their use (but never to enclose the entire address). In the following
description, `item' refers to what remains after any surrounding double quotes
have been removed. An item may safely be the same as the local part currently
under consideration, because any director is automatically skipped if any
ancestor has the same local part and was processed by that director.

</P>

<UL>

<LI>

<A NAME="IDX1475"></A>
<A NAME="IDX1476"></A>
If an item begins with `\' and the rest of the item parses as a valid RFC 822
address that does not include a domain, the item is qualified using the domain
of the incoming address. The use of `\' makes a difference only if there is
more than one local domain. In the absence of a leading `\', unqualified
addresses are qualified using the value in <EM>qualify_recipient</EM>, unless
<EM>qualify_preserve_domain</EM> is set.
<A NAME="IDX1477"></A>
<A NAME="IDX1478"></A>
It is not necessary to include `\' in aliases to prevent directing loops,
because Exim has its own method of loop detection.

<LI>

An item is treated as a pipe command if it begins with `|' and does not parse
as a valid RFC 822 address that includes a domain. A transport for running the
command must be specified by the <EM>pipe_transport</EM> option. Either the director
or the transport must specify a user and group under which to run the delivery.

Either single or double quotes can be used for enclosing the individual
arguments of the pipe command; no interpretation of escapes is done for single
quotes. If the command contains a comma character, it is necessary to put the
whole item in double quotes, for example:

<PRE>
"|/some/command ready,steady,go"
</PRE>

since items are terminated by commas. Do not, however, quote just the command.
An item such as

<PRE>
|"/some/command ready,steady,go"
</PRE>

is interpreted as a pipe with a rather strange command name, and no arguments.

<LI>

An item is interpreted as a path name if it begins with `/' and does not parse
as a valid RFC 822 address that includes a domain. For example,

<PRE>
/home/world/minbari
</PRE>

is treated as a file name, but

<PRE>
/s=molari/o=babylon/@x400gate.way
</PRE>

is treated as an address. For a file name, a transport must be specified using
the <EM>file_transport</EM> option. However, if the generated path name ends with a
forward slash character, it is interpreted as a directory name rather than a
file name, and <EM>directory_transport</EM> is used instead. If it ends with two
slashes, <EM>directory2_transport</EM> is required. This makes it possible to support
two different kinds of directory delivery simultaneously.

<A NAME="IDX1479"></A>
If a generated path is <EM>/dev/null</EM>, delivery to it is bypassed at a high level,
and the log entry shows `**bypassed**' instead of a transport name.
This avoids the need to specify a user and group, which are necessary for a
genuine delivery to a file. When the file name is not <EM>/dev/null</EM>, either the
director or the transport must specify a user and group under which to run the
delivery.

<LI>

<A NAME="IDX1480"></A>
An item of the form

<PRE>
:include:&#60;<EM>path name</EM>&#62;
</PRE>

may appear in an alias file, in which case a list of further items is taken
from the given file and included at that point. The items in the list are
separated by commas or newlines and are not subject to expansion, even when the
<EM>expand</EM> option is set. If this is the first item in an alias list, a colon
must be used to terminate the alias name.
<font color=green>
This example is incorrect:

<PRE>
list1    :include:/opt/lists/list1
</PRE>

It must be given as

<PRE>
list1:   :include:/opt/lists/list1
</PRE>

</font>

<LI>

Sometimes you want to throw away mail to a particular local part.
<A NAME="IDX1481"></A>
<A NAME="IDX1482"></A>
An alias entry with no addresses causes Exim to generate an error, so that
cannot be used. However, another special item that may appear in an alias file
is

<PRE>
:blackhole:
</PRE>

which does what its name implies. No delivery is done for it, and no error
message is generated. If this is the first item in an alias list, a colon must
be used to terminate the alias name.

This used to be more efficient than directing a message to <EM>/dev/null</EM> because
it happens at directing time, and also there was no need to specify a user and
group to run the transport process for delivery to a file. However, from Exim
version 1.90 onwards <EM>/dev/null</EM> is recognized specially, and handled in
essentially the same way as <EM>:blackhole:</EM>.

<LI>

<A NAME="IDX1483"></A>
<A NAME="IDX1484"></A>
<A NAME="IDX1485"></A>
<A NAME="IDX1486"></A>
An attempt to deliver to a particular local part can be deferred or forced to
fail by aliasing the local part to

<PRE>
:defer:
or
:fail:
</PRE>

respectively. As this is normally the only item in an alias list, a colon must
be used to terminate the alias name. When an alias list contains such an item,
it applies to the entire alias; any other items in the list are ignored
(<EM>:blackhole:</EM> is different). Any text following <EM>:fail:</EM> or <EM>:defer:</EM> is
placed in the error
text associated with the failure.
For example:

<PRE>
X.Employee:  :fail: Gone away, no forwarding address
</PRE>

In the case of an address that is being verified for the SMTP RCPT or
VRFY commands, the text is included in the SMTP error response,
which has a 451 code for a <EM>:defer:</EM> failure, and 550 for <EM>:fail:</EM>.
In other cases it is included in the error message that Exim generates.

Normally the error text is the rest of the alias entry -- a comma does not
terminate it -- but a newline does act as a terminator. Newlines are not
normally present in alias expansions. In <EM>lsearch</EM> lookups they are removed as
part of the continuation process, but they may exist in other kinds of lookup
and in <EM>:include:</EM>d files.

During message delivery, an alias containing <EM>:fail:</EM> causes an immediate
failure of the incoming address, whereas <EM>:defer:</EM> causes the message to remain
on the queue so that a subsequent delivery attempt can happen at a later time.
If an address is <EM>:defer:</EM>red for too long, it will ultimately fail, since
normal retry rules apply.

<LI>

<A NAME="IDX1487"></A>
Sometimes it is useful to use a search type with a default (see chapter
6) for aliases. However, there may be a need for exceptions to the
default. These can be handled by aliasing them to

<PRE>
:unknown:
</PRE>

This differs from <EM>:fail:</EM> in that it causes <EM>aliasfile</EM> to pass the address on
to the next director, whereas <EM>:fail:</EM> forces directing to fail immediately. If
<EM>:unknown:</EM> is the first item in an alias list, a colon must be used to
terminate the alias name.
</UL>



<H2><A NAME="SEC635" HREF="spec_toc.html#TOC635">23.4 Duplicate addresses</A></H2>

<P>
<A NAME="IDX1488"></A>
<A NAME="IDX1489"></A>
<A NAME="IDX1490"></A>
Exim removes duplicate addresses from the list to which it is delivering, so as
to deliver just one copy to each address. This does not apply to deliveries
directed at pipes by different immediate parent addresses, but an indirect
aliasing scheme of the type

<PRE>
pipe:       |/some/command ${local_part}
localpart1: pipe
localpart2: pipe
</PRE>

<P>
does not work with a message that is addressed to both local parts, because
when the second is aliased to the intermediate local part `pipe' it gets
discarded as being the same as a previously handled address. However, a scheme
such as

<PRE>
localpart1: |/some/command ${local_part}
localpart2: |/some/command ${local_part}
</PRE>

<P>
does result in two different pipe deliveries, because the immediate parents of
the pipes are distinct.

</P>



<H2><A NAME="SEC636" HREF="spec_toc.html#TOC636">23.5 Repeated alias expansion</A></H2>

<P>
<A NAME="IDX1491"></A>
<A NAME="IDX1492"></A>
When a message cannot be delivered to all of its recipients immediately,
leading to two or more delivery attempts, alias expansion is carried out afresh
each time for those addresses whose children were not all previously delivered.
If an alias is being used as a mailing list, this can lead to new members of
the list receiving copies of old messages. The <EM>one_time</EM> option can be used
to avoid this.

</P>


<H2><A NAME="SEC637" HREF="spec_toc.html#TOC637">23.6 Errors in alias files</A></H2>

<P>
<A NAME="IDX1493"></A>
If <EM>skip_syntax_errors</EM> is set, a malformed address that causes a parsing
error is skipped, and an entry is written to the main log. This may be useful
for mailing lists that are automatically managed, but note the inherent danger.
Otherwise, if an error is detected while generating the list of new addresses,
the message is frozen, except for the special case of inability to open an
included file, when <EM>no_freeze_missing_include</EM> is set. In this case,
delivery is simply deferred.

</P>



<H2><A NAME="SEC638" HREF="spec_toc.html#TOC638">23.7 Aliasfile private options</A></H2>

<P>
<A NAME="IDX1494"></A>
<font color=green>
This section lists the private options that <EM>aliasfile</EM> does not have in common
with <EM>forwardfile</EM>. Those that they share are given in chapter
22.
</font>

</P>

<P>

<P>
<A NAME="IDX1495"></A>


<H3><A NAME="SEC639" HREF="spec_toc.html#TOC639">expand (aliasfile)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1496"></A>
If this option is set true, the text obtained by looking up the local part
is passed through the string expansion mechanism before being interpreted as a
list of alias items. Addresses that are subsequently added by means of the
`include' mechanism are <EM>not</EM> expanded.

</P>
<P>
<A NAME="IDX1497"></A>


<H3><A NAME="SEC640" HREF="spec_toc.html#TOC640">file (aliasfile)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
This option specifies the name of the alias file, and it must be set if
<EM>search_type</EM> specifies a single-key lookup; if it does not, an error occurs.
(For query-style lookups, <EM>query</EM> must be set instead.) See chapter
6 for details of different lookup styles.
The string is expanded before use; if expansion fails, Exim panics. The
resulting string must be an absolute path for linear search and DBM lookups. If
the original string does not start with `/' or `$' in these cases, Exim gives
a configuration error when it starts up; otherwise, if an expanded string does
not begin with `/' delivery is frozen.

</P>
<P>
<font color=green>
<A NAME="IDX1498"></A>


<H3><A NAME="SEC641" HREF="spec_toc.html#TOC641">forbid_special (aliasfile)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is set, the special items <EM>:defer:</EM>, <EM>:fail:</EM>, <EM>:blackhole:</EM> and
<EM>:unknown:</EM> are forbidden. If any are encountered, delivery is deferred.
</font>

</P>
<P>
<A NAME="IDX1499"></A>


<H3><A NAME="SEC642" HREF="spec_toc.html#TOC642">include_domain (aliasfile)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1500"></A>
<A NAME="IDX1501"></A>
Setting this option true causes the key that is looked up to be
`local-part@domain' instead of just `local-part'. Thus a single file can be
used to hold aliases for many local domains. This option has no effect if the
search type specifies a query-style lookup.

</P>
<P>
If you want include defaults for each domain in an alias file in the form

<PRE>
*@domain1:  default@domain1
*@domain2:  default@domain2
</PRE>

<P>
then you need to include `*@' in the search type (for example, <EM>dbm*@</EM>).
See section 6.1 for details of this kind of search.

</P>
<P>
<A NAME="IDX1502"></A>


<H3><A NAME="SEC643" HREF="spec_toc.html#TOC643">optional (aliasfile)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<font color=green>
For a single-key lookup type,
if the file cannot be opened because it does not exist (the ENOENT error)
and this option is set, the director simply declines to handle the address.
Otherwise any failure to open the file causes an entry to be written to the log
and delivery to be deferred.

</P>
<P>
For a query-style lookup type, <EM>optional</EM> causes the director to decline if no
query can be completed (for example, all databases are down). Without
<EM>optional</EM>, delivery is deferred.
</font>

</P>
<P>
<A NAME="IDX1503"></A>


<H3><A NAME="SEC644" HREF="spec_toc.html#TOC644">queries (aliasfile)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
This option is an alternative to <EM>query</EM>; the two options are mutually
exclusive. The difference is that <EM>queries</EM> contains a colon-separated list of
queries, which are tried in order until one succeeds or defers, or all fail.
Any colon characters actually required in an individual query must be doubled,
in order that they not be treated as query separators.

</P>
<P>
<A NAME="IDX1504"></A>


<H3><A NAME="SEC645" HREF="spec_toc.html#TOC645">query (aliasfile)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
This option specifies a database query, and
either it or <EM>queries</EM>
must be set if <EM>search_type</EM> specifies a query-style lookup; if neither is
set, an error occurs. (For single-key lookups, <EM>file</EM> must be set instead.) See
chapter 6 for details of different lookup styles. The query is
expanded before use, and would normally contain a reference to the local part.
For example,

<PRE>
search_type = nisplus
query = [alias=${local_part}],mail_aliases.org_dir:expansion
</PRE>

<P>
could be used for a NIS+ lookup.
Sometimes a lookup cannot be completed (for example, a NIS+ database might be
inaccessible) and in this case the director causes delivery to be deferred.

</P>
<P>
<A NAME="IDX1505"></A>


<H3><A NAME="SEC646" HREF="spec_toc.html#TOC646">search_type (aliasfile)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
This option must be set to the name of a supported search type
(`lsearch', `dbm', etc.), specifying the type of data lookup. For query-style
lookups, the <EM>query</EM> option specifies the search query, and <EM>file</EM> must
not be set.
For the other search types, <EM>file</EM> is required and <EM>query</EM> must not be set. See
chapter 6 for details of the different lookup styles.

</P>
<P>
Single-key search types for <EM>aliasfile</EM> can be preceded by <TT>`partial-'</TT> and/or
followed by <TT>`*'</TT>. The former isn't likely to be useful very often, but the
latter provides a default facility. Note, however, that if two addresses in the
same message provoke the use of the default, only one copy gets delivered, but
any added <EM>Envelope-to:</EM> header
<A NAME="IDX1506"></A>
contains all the original addresses.
Exceptions to the default can be set up by aliasing them to <EM>:unknown:</EM>.

</P>

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