<?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>22. The redirect router</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="ch21.html" title="21. The queryprogram router" /><link rel="next" href="ch23.html" title="23. Environment for running local transports" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch21.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch23.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#toc0204" id="CHAPredirect">22. The redirect router</a></h2></div>
</div>
</div>
<p>
<a id="IIDredrou1" class="indexterm"></a>
<a id="IIDredrou2" class="indexterm"></a>
<a id="id573492" class="indexterm"></a>
<a id="id573512" class="indexterm"></a>
The <span><strong class="command">redirect</strong></span> router handles several kinds of address redirection. Its most
common uses are for resolving local part aliases from a central alias file
(usually called <em class="filename">/etc/aliases</em>) and for handling users’ personal <em class="filename">.forward</em>
files, but it has many other potential uses. The incoming address can be
redirected in several different ways:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
It can be replaced by one or more new addresses which are themselves routed
independently.
</p>
</li><li><p>
It can be routed to be delivered to a given file or directory.
</p>
</li><li><p>
It can be routed to be delivered to a specified pipe command.
</p>
</li><li><p>
It can cause an automatic reply to be generated.
</p>
</li><li><p>
It can be forced to fail, optionally with a custom error message.
</p>
</li><li><p>
It can be temporarily deferred, optionally with a custom message.
</p>
</li><li><p>
It can be discarded.
</p>
</li></ul></div>
<p>
The generic <span><strong class="option">transport</strong></span> option must not be set for <span><strong class="command">redirect</strong></span> routers.
However, there are some private options which define transports for delivery to
files and pipes, and for generating autoreplies. See the <span><strong class="option">file_transport</strong></span>,
<span><strong class="option">pipe_transport</strong></span> and <span><strong class="option">reply_transport</strong></span> descriptions below.
</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#toc0205" id="SECID124">22.1 Redirection data</a></h3></div>
</div>
</div>
<p>
The router operates by interpreting a text string which it obtains either by
expanding the contents of the <span><strong class="option">data</strong></span> option, or by reading the entire
contents of a file whose name is given in the <span><strong class="option">file</strong></span> option. These two
options are mutually exclusive. The first is commonly used for handling system
aliases, in a configuration like this:
</p>
<pre class="literallayout">system_aliases:
driver = redirect
data = ${lookup{$local_part}lsearch{/etc/aliases}}
</pre><p>
If the lookup fails, the expanded string in this example is empty. When the
expansion of <span><strong class="option">data</strong></span> results in an empty string, the router declines. A forced
expansion failure also causes the router to decline; other expansion failures
cause delivery to be deferred.
</p>
<p>
A configuration using <span><strong class="option">file</strong></span> is commonly used for handling users’
<em class="filename">.forward</em> files, like this:
</p>
<pre class="literallayout">userforward:
driver = redirect
check_local_user
file = $home/.forward
no_verify
</pre><p>
If the file does not exist, or causes no action to be taken (for example, it is
empty or consists only of comments), the router declines. <span class="bold"><strong>Warning</strong></span>: This
is not the case when the file contains syntactically valid items that happen to
yield empty addresses, for example, items containing only RFC 2822 address
comments.
</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#toc0206" id="SECID125">22.2 Forward files and address verification</a></h3></div>
</div>
</div>
<p>
<a id="id573734" class="indexterm"></a>
It is usual to set <span><strong class="option">no_verify</strong></span> on <span><strong class="command">redirect</strong></span> routers which handle users’
<em class="filename">.forward</em> files, as in the example above. There are two reasons for this:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
When Exim is receiving an incoming SMTP message from a remote host, it is
running under the Exim uid, not as root. Exim is unable to change uid to read
the file as the user, and it may not be able to read it as the Exim user. So in
practice the router may not be able to operate.
</p>
</li><li><p>
However, even when the router can operate, the existence of a <em class="filename">.forward</em> file
is unimportant when verifying an address. What should be checked is whether the
local part is a valid user name or not. Cutting out the redirection processing
saves some resources.
</p>
</li></ul></div>
</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#toc0207" id="SECID126">22.3 Interpreting redirection data</a></h3></div>
</div>
</div>
<p>
<a id="id573812" class="indexterm"></a>
<a id="id573826" class="indexterm"></a>
The contents of the data string, whether obtained from <span><strong class="option">data</strong></span> or <span><strong class="option">file</strong></span>,
can be interpreted in two different ways:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
If the <span><strong class="option">allow_filter</strong></span> option is set true, and the data begins with the text
“<span class="quote">#Exim filter</span>” or “<span class="quote">#Sieve filter</span>”, it is interpreted as a list of
<span class="emphasis"><em>filtering</em></span> instructions in the form of an Exim or Sieve filter file,
respectively. Details of the syntax and semantics of filter files are described
in a separate document entitled <span class="emphasis"><em>Exim’s interfaces to mail filtering</em></span>; this
document is intended for use by end users.
</p>
</li><li><p>
Otherwise, the data must be a comma-separated list of redirection items, as
described in the next section.
</p>
</li></ul></div>
<p>
When a message is redirected to a file (a “<span class="quote">mail folder</span>”), the file name given
in a non-filter redirection list must always be an absolute path. A filter may
generate a relative path – how this is handled depends on the transport’s
configuration. See section <a href="ch26.html#SECTfildiropt" title="26.1 The file and directory options">26.1</a> for a discussion of this issue
for the <span><strong class="command">appendfile</strong></span> transport.
</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#toc0208" id="SECTitenonfilred">22.4 Items in a non-filter redirection list</a></h3></div>
</div>
</div>
<p>
<a id="id573933" class="indexterm"></a>
When the redirection data is not an Exim or Sieve filter, for example, if it
comes from a conventional alias or forward file, it consists of a list of
addresses, file names, pipe commands, or certain special items (see section
<a href="ch22.html#SECTspecitredli" title="22.6 Special items in redirection lists">22.6</a> below). The special items can be individually enabled or
disabled by means of options whose names begin with <span><strong class="option">allow_</strong></span> or <span><strong class="option">forbid_</strong></span>,
depending on their default values. The items in the list are separated by
commas or newlines.
If a comma is required in an item, the entire item must be enclosed in double
quotes.
</p>
<p>
Lines starting with a # character are comments, and are ignored, and # may
also appear following a comma, in which case everything between the # and the
next newline character is ignored.
</p>
<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,
“<span class="quote">item</span>” refers to what remains after any surrounding double quotes have been
removed.
</p>
<p>
<a id="id573991" class="indexterm"></a>
<span class="bold"><strong>Warning</strong></span>: If you use an Exim expansion to construct a redirection address,
and the expansion contains a reference to <em class="varname">$local_part</em>, you should make use
of the <span><strong class="option">quote_local_part</strong></span> expansion operator, in case the local part contains
special characters. For example, to redirect all mail for the domain
<span class="emphasis"><em>obsolete.example</em></span>, retaining the existing local part, you could use this
setting:
</p>
<pre class="literallayout">data = ${quote_local_part:$local_part}@newdomain.example
</pre></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#toc0209" id="SECTredlocmai">22.5 Redirecting to a local mailbox</a></h3></div>
</div>
</div>
<p>
<a id="id574048" class="indexterm"></a>
<a id="id574062" class="indexterm"></a>
<a id="id574077" class="indexterm"></a>
A redirection item may safely be the same as the address currently under
consideration. This does not cause a routing loop, because a router is
automatically skipped if any ancestor of the address that is being processed
is the same as the current address and was processed by the current router.
Such an address is therefore passed to the following routers, so it is handled
as if there were no redirection. When making this loop-avoidance test, the
complete local part, including any prefix or suffix, is used.
</p>
<p>
<a id="id574095" class="indexterm"></a>
Specifying the same local part without a domain is a common usage in personal
filter files when the user wants to have messages delivered to the local
mailbox and also forwarded elsewhere. For example, the user whose login is
<span class="emphasis"><em>cleo</em></span> might have a <em class="filename">.forward</em> file containing this:
</p>
<pre class="literallayout">cleo, cleopatra@egypt.example
</pre><p>
<a id="id574135" class="indexterm"></a>
<a id="id574146" class="indexterm"></a>
For compatibility with other MTAs, such unqualified local parts may be
preceded by “<span class="quote">\</span>”, but this is not a requirement for loop prevention. However,
it does make a difference if more than one domain is being handled
synonymously.
</p>
<p>
If an item begins with “<span class="quote">\</span>” and the rest of the item parses as a valid RFC
2822 address that does not include a domain, the item is qualified using the
domain of the incoming address. In the absence of a leading “<span class="quote">\</span>”, unqualified
addresses are qualified using the value in <span><strong class="option">qualify_recipient</strong></span>, but you can
force the incoming domain to be used by setting <span><strong class="option">qualify_preserve_domain</strong></span>.
</p>
<p>
Care must be taken if there are alias names for local users.
Consider an MTA handling a single local domain where the system alias file
contains:
</p>
<pre class="literallayout">Sam.Reman: spqr
</pre><p>
Now suppose that Sam (whose login id is <span class="emphasis"><em>spqr</em></span>) wants to save copies of
messages in the local mailbox, and also forward copies elsewhere. He creates
this forward file:
</p>
<pre class="literallayout">Sam.Reman, spqr@reme.elsewhere.example
</pre><p>
With these settings, an incoming message addressed to <span class="emphasis"><em>Sam.Reman</em></span> fails. The
<span><strong class="command">redirect</strong></span> router for system aliases does not process <span class="emphasis"><em>Sam.Reman</em></span> the
second time round, because it has previously routed it,
and the following routers presumably cannot handle the alias. The forward file
should really contain
</p>
<pre class="literallayout">spqr, spqr@reme.elsewhere.example
</pre><p>
but because this is such a common error, the <span><strong class="option">check_ancestor</strong></span> option (see
below) exists to provide a way to get round it. This is normally set on a
<span><strong class="command">redirect</strong></span> router that is handling users’ <em class="filename">.forward</em> 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#toc0210" id="SECTspecitredli">22.6 Special items in redirection lists</a></h3></div>
</div>
</div>
<p>
In addition to addresses, the following types of item may appear in redirection
lists (that is, in non-filter redirection data):
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
<a id="id574297" class="indexterm"></a>
<a id="id574311" class="indexterm"></a>
An item is treated as a pipe command if it begins with “<span class="quote">|</span>” and does not parse
as a valid RFC 2822 address that includes a domain. A transport for running the
command must be specified by the <span><strong class="option">pipe_transport</strong></span> option.
Normally, either the router or the transport specifies a user and a group under
which to run the delivery. The default is to use the Exim user and group.
</p>
<p>
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:
</p>
<pre class="literallayout">"|/some/command ready,steady,go"
</pre><p>
since items in redirection lists are terminated by commas. Do not, however,
quote just the command. An item such as
</p>
<pre class="literallayout">|"/some/command ready,steady,go"
</pre><p>
is interpreted as a pipe with a rather strange command name, and no arguments.
</p>
</li><li><p>
<a id="id574380" class="indexterm"></a>
<a id="id574394" class="indexterm"></a>
An item is interpreted as a path name if it begins with “<span class="quote">/</span>” and does not
parse as a valid RFC 2822 address that includes a domain. For example,
</p>
<pre class="literallayout">/home/world/minbari
</pre><p>
is treated as a file name, but
</p>
<pre class="literallayout">/s=molari/o=babylon/@x400gate.way
</pre><p>
is treated as an address. For a file name, a transport must be specified using
the <span><strong class="option">file_transport</strong></span> 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 <span><strong class="option">directory_transport</strong></span> is used instead.
</p>
<p>
Normally, either the router or the transport specifies a user and a group under
which to run the delivery. The default is to use the Exim user and group.
</p>
<p>
<a id="id574459" class="indexterm"></a>
However, if a redirection item is the path <em class="filename">/dev/null</em>, delivery to it is
bypassed at a high level, and the log entry shows “<span class="quote">**bypassed**</span>”
instead of a transport name. In this case the user and group are not used.
</p>
</li><li><p>
<a id="id574492" class="indexterm"></a>
<a id="id574504" class="indexterm"></a>
If an item is of the form
</p>
<pre class="literallayout">:include:<path name>
</pre><p>
a list of further items is taken from the given file and included at that
point. <span class="bold"><strong>Note</strong></span>: Such a file can not be a filter file; it is just an
out-of-line addition to the list. The items in the included list are separated
by commas or newlines and are not subject to expansion. If this is the first
item in an alias list in an <span><strong class="command">lsearch</strong></span> file, a colon must be used to terminate
the alias name. This example is incorrect:
</p>
<pre class="literallayout">list1 :include:/opt/lists/list1
</pre><p>
It must be given as
</p>
<pre class="literallayout">list1: :include:/opt/lists/list1
</pre></li><li><p>
<a id="id574575" class="indexterm"></a>
Sometimes you want to throw away mail to a particular local part. Making the
<span><strong class="option">data</strong></span> option expand to an empty string does not work, because that causes
the router to decline. Instead, the alias item
<a id="id574597" class="indexterm"></a>
<a id="id574608" class="indexterm"></a>
<span class="emphasis"><em>:blackhole:</em></span> can be used. It does what its name implies. No delivery is
done, and no error message is generated. This has the same effect as specifing
<em class="filename">/dev/null</em> as a destination, but it can be independently disabled.
</p>
<p>
<span class="bold"><strong>Warning</strong></span>: If <span class="emphasis"><em>:blackhole:</em></span> appears anywhere in a redirection list, no
delivery is done for the original local part, even if other redirection items
are present. If you are generating a multi-item list (for example, by reading a
database) and need the ability to provide a no-op item, you must use
<em class="filename">/dev/null</em>.
</p>
</li><li><p>
<a id="id574660" class="indexterm"></a>
<a id="id574675" class="indexterm"></a>
<a id="id574689" class="indexterm"></a>
<a id="id574704" class="indexterm"></a>
<a id="id574715" class="indexterm"></a>
An attempt to deliver a particular address can be deferred or forced to fail by
redirection items of the form
</p>
<pre class="literallayout">:defer:
:fail:
</pre><p>
respectively. When a redirection list contains such an item, it applies to the
entire redirection; any other items in the list are ignored (<span class="emphasis"><em>:blackhole:</em></span> is
different). Any text following <span class="emphasis"><em>:fail:</em></span> or <span class="emphasis"><em>:defer:</em></span> is placed in the error
text associated with the failure. For example, an alias file might contain:
</p>
<pre class="literallayout">X.Employee: :fail: Gone away, no forwarding address
</pre><p>
In the case of an address that is being verified from an ACL or as the subject
of a
<a id="id574772" class="indexterm"></a>
VRFY command, the text is included in the SMTP error response by
default.
<a id="id574788" class="indexterm"></a>
The text is not included in the response to an EXPN command. In non-SMTP cases
the text is included in the error message that Exim generates.
</p>
<p>
<a id="id574808" class="indexterm"></a>
By default, Exim sends a 451 SMTP code for a <span class="emphasis"><em>:defer:</em></span>, and 550 for
<span class="emphasis"><em>:fail:</em></span>. However, if the message starts with three digits followed by a
space, optionally followed by an extended code of the form <span class="emphasis"><em>n.n.n</em></span>, also
followed by a space, and the very first digit is the same as the default error
code, the code from the message is used instead. If the very first digit is
incorrect, a panic error is logged, and the default code is used. You can
suppress the use of the supplied code in a redirect router by setting the
<span><strong class="option">forbid_smtp_code</strong></span> option true. In this case, any SMTP code is quietly
ignored.
</p>
<p>
<a id="id574849" class="indexterm"></a>
In an ACL, an explicitly provided message overrides the default, but the
default message is available in the variable <em class="varname">$acl_verify_message</em> and can
therefore be included in a custom message if this is desired.
</p>
<p>
Normally the error text is the rest of the redirection list – a comma does
not terminate it – but a newline does act as a terminator. Newlines are not
normally present in alias expansions. In <span><strong class="command">lsearch</strong></span> lookups they are removed
as part of the continuation process, but they may exist in other kinds of
lookup and in <span class="emphasis"><em>:include:</em></span> files.
</p>
<p>
During routing for message delivery (as opposed to verification), a redirection
containing <span class="emphasis"><em>:fail:</em></span> causes an immediate failure of the incoming address,
whereas <span class="emphasis"><em>:defer:</em></span> causes the message to remain on the queue so that a
subsequent delivery attempt can happen at a later time. If an address is
deferred for too long, it will ultimately fail, because the normal retry
rules still apply.
</p>
</li><li><p>
<a id="id574912" class="indexterm"></a>
Sometimes it is useful to use a single-key search type with a default (see
chapter <a href="ch09.html" title="9. File and database lookups">9</a>) to look up aliases. However, there may be a need
for exceptions to the default. These can be handled by aliasing them to
<span class="emphasis"><em>:unknown:</em></span>. This differs from <span class="emphasis"><em>:fail:</em></span> in that it causes the <span><strong class="command">redirect</strong></span>
router to decline, whereas <span class="emphasis"><em>:fail:</em></span> forces routing to fail. A lookup which
results in an empty redirection list has the same effect.
</p>
</li></ul></div>
</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#toc0211" id="SECTdupaddr">22.7 Duplicate addresses</a></h3></div>
</div>
</div>
<p>
<a id="id574969" class="indexterm"></a>
<a id="id574980" class="indexterm"></a>
<a id="id574991" class="indexterm"></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
routed to pipes by different immediate parent addresses, but an indirect
aliasing scheme of the type
</p>
<pre class="literallayout">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 “<span class="quote">pipe</span>” it gets
discarded as being the same as a previously handled address. However, a scheme
such as
</p>
<pre class="literallayout">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>
</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#toc0212" id="SECID128">22.8 Repeated redirection expansion</a></h3></div>
</div>
</div>
<p>
<a id="id575058" class="indexterm"></a>
<a id="id575069" class="indexterm"></a>
When a message cannot be delivered to all of its recipients immediately,
leading to two or more delivery attempts, redirection expansion is carried out
afresh each time for those addresses whose children were not all previously
delivered. If redirection is being used as a mailing list, this can lead to new
members of the list receiving copies of old messages. The <span><strong class="option">one_time</strong></span> option
can be used to avoid this.
</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#toc0213" id="SECID129">22.9 Errors in redirection lists</a></h3></div>
</div>
</div>
<p>
<a id="id575108" class="indexterm"></a>
If <span><strong class="option">skip_syntax_errors</strong></span> 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. Otherwise, if an error is
detected while generating the list of new addresses, the original address is
deferred. See also <span><strong class="option">syntax_errors_to</strong></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#toc0214" id="SECID130">22.10 Private options for the redirect router</a></h3></div>
</div>
</div>
<p>
<a id="id575150" class="indexterm"></a>
The private options for the <span><strong class="command">redirect</strong></span> router are as follows:
</p>
<p>
<a id="id575178" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">allow_defer</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
Setting this option allows the use of <span class="emphasis"><em>:defer:</em></span> in non-filter redirection
data, or the <span><strong class="option">defer</strong></span> command in an Exim filter file.
</p>
<p>
<a id="id575273" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">allow_fail</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id575355" class="indexterm"></a>
If this option is true, the <span class="emphasis"><em>:fail:</em></span> item can be used in a redirection list,
and the <span><strong class="option">fail</strong></span> command may be used in an Exim filter file.
</p>
<p>
<a id="id575382" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">allow_filter</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id575465" class="indexterm"></a>
<a id="id575479" class="indexterm"></a>
Setting this option allows Exim to interpret redirection data that starts with
“<span class="quote">#Exim filter</span>” or “<span class="quote">#Sieve filter</span>” as a set of filtering instructions. There
are some features of Exim filter files that some administrators may wish to
lock out; see the <span><strong class="option">forbid_filter_</strong></span><span class="emphasis"><em>xxx</em></span> options below.
</p>
<p>
It is also possible to lock out Exim filters or Sieve filters while allowing
the other type; see <span><strong class="option">forbid_exim_filter</strong></span> and <span><strong class="option">forbid_sieve_filter</strong></span>.
</p>
<p>
The filter is run using the uid and gid set by the generic <span><strong class="option">user</strong></span> and
<span><strong class="option">group</strong></span> options. These take their defaults from the password data if
<span><strong class="option">check_local_user</strong></span> is set, so in the normal case of users’ personal filter
files, the filter is run as the relevant user. When <span><strong class="option">allow_filter</strong></span> is set
true, Exim insists that either <span><strong class="option">check_local_user</strong></span> or <span><strong class="option">user</strong></span> is set.
</p>
<p>
<a id="id575562" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">allow_freeze</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id575644" class="indexterm"></a>
Setting this option allows the use of the <span><strong class="option">freeze</strong></span> command in an Exim filter.
This command is more normally encountered in system filters, and is disabled by
default for redirection filters because it isn’t something you usually want to
let ordinary users do.
</p>
<p>
<a id="id575673" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">check_ancestor</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
This option is concerned with handling generated addresses that are the same
as some address in the list of redirection ancestors of the current address.
Although it is turned off by default in the code, it is set in the default
configuration file for handling users’ <em class="filename">.forward</em> files. It is recommended
for this use of the <span><strong class="command">redirect</strong></span> router.
</p>
<p>
When <span><strong class="option">check_ancestor</strong></span> is set, if a generated address (including the domain)
is the same as any ancestor of the current address, it is replaced by a copy of
the current address. This helps in the case where local part A is aliased to B,
and B has a <em class="filename">.forward</em> file pointing back to A. For example, within a single
domain, the local part “<span class="quote">Joe.Bloggs</span>” is aliased to “<span class="quote">jb</span>” and
<em class="filename"> jb/.forward</em> contains:
</p>
<pre class="literallayout">\Joe.Bloggs, <other item(s)>
</pre><p>
Without the <span><strong class="option">check_ancestor</strong></span> setting, either local part (“<span class="quote">jb</span>” or
“<span class="quote">joe.bloggs</span>”) gets processed once by each router and so ends up as it was
originally. If “<span class="quote">jb</span>” is the real mailbox name, mail to “<span class="quote">jb</span>” gets delivered
(having been turned into “<span class="quote">joe.bloggs</span>” by the <em class="filename">.forward</em> file and back to
“<span class="quote">jb</span>” by the alias), but mail to “<span class="quote">joe.bloggs</span>” fails. Setting
<span><strong class="option">check_ancestor</strong></span> on the <span><strong class="command">redirect</strong></span> router that handles the <em class="filename">.forward</em>
file prevents it from turning “<span class="quote">jb</span>” back into “<span class="quote">joe.bloggs</span>” when that was the
original address. See also the <span><strong class="option">repeat_use</strong></span> option below.
</p>
<p>
<a id="id575876" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">check_group</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
When the <span><strong class="option">file</strong></span> option is used, the group owner of the file is checked only
when this option is set. The permitted groups are those listed in the
<span><strong class="option">owngroups</strong></span> option, together with the user’s default group if
<span><strong class="option">check_local_user</strong></span> is set. If the file has the wrong group, routing is
deferred. The default setting for this option is true if <span><strong class="option">check_local_user</strong></span>
is set and the <span><strong class="option">modemask</strong></span> option permits the group write bit, or if the
<span><strong class="option">owngroups</strong></span> option is set. Otherwise it is false, and no group check occurs.
</p>
<p>
<a id="id575991" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">check_owner</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>see below</em></span></td></tr></tbody></table></div>
<p>
When the <span><strong class="option">file</strong></span> option is used, the owner of the file is checked only when
this option is set. If <span><strong class="option">check_local_user</strong></span> is set, the local user is
permitted; otherwise the owner must be one of those listed in the <span><strong class="option">owners</strong></span>
option. The default value for this option is true if <span><strong class="option">check_local_user</strong></span> or
<span><strong class="option">owners</strong></span> is set. Otherwise the default is false, and no owner check occurs.
</p>
<p>
<a id="id576101" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">data</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option is mutually exclusive with <span><strong class="option">file</strong></span>. One or other of them must be
set, but not both. The contents of <span><strong class="option">data</strong></span> are expanded, and then used as the
list of forwarding items, or as a set of filtering instructions. If the
expansion is forced to fail, or the result is an empty string or a string that
has no effect (consists entirely of comments), the router declines.
</p>
<p>
When filtering instructions are used, the string must begin with “<span class="quote">#Exim
filter</span>”, and all comments in the string, including this initial one, must be
terminated with newline characters. For example:
</p>
<pre class="literallayout">data = #Exim filter\n\
if $h_to: contains Exim then save $home/mail/exim endif
</pre><p>
If you are reading the data from a database where newlines cannot be included,
you can use the <em class="varname">${sg}</em> expansion item to turn the escape string of your
choice into a newline.
</p>
<p>
<a id="id576231" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">directory_transport</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
A <span><strong class="command">redirect</strong></span> router sets up a direct delivery to a directory when a path name
ending with a slash is specified as a new “<span class="quote">address</span>”. The transport used is
specified by this option, which, after expansion, must be the name of a
configured transport. This should normally be an <span><strong class="command">appendfile</strong></span> transport.
</p>
<p>
<a id="id576338" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">file</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This option specifies the name of a file that contains the redirection data. It
is mutually exclusive with the <span><strong class="option">data</strong></span> option. The string is expanded before
use; if the expansion is forced to fail, the router declines. Other expansion
failures cause delivery to be deferred. The result of a successful expansion
must be an absolute path. The entire file is read and used as the redirection
data. If the data is an empty string or a string that has no effect (consists
entirely of comments), the router declines.
</p>
<p>
<a id="id576438" class="indexterm"></a>
If the attempt to open the file fails with a “<span class="quote">does not exist</span>” error, Exim
runs a check on the containing directory,
unless <span><strong class="option">ignore_enotdir</strong></span> is true (see below).
If the directory does not appear to exist, delivery is deferred. This can
happen when users’ <em class="filename">.forward</em> files are in NFS-mounted directories, and there
is a mount problem. If the containing directory does exist, but the file does
not, the router declines.
</p>
<p>
<a id="id576750" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">file_transport</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id576835" class="indexterm"></a>
A <span><strong class="command">redirect</strong></span> router sets up a direct delivery to a file when a path name not
ending in a slash is specified as a new “<span class="quote">address</span>”. The transport used is
specified by this option, which, after expansion, must be the name of a
configured transport. This should normally be an <span><strong class="command">appendfile</strong></span> transport. When
it is running, the file name is in <em class="varname">$address_file</em>.
</p>
<p>
<a id="id576874" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">filter_prepend_home</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>true</em></span></td></tr></tbody></table></div>
<p>
When this option is true, if a <span><strong class="command">save</strong></span> command in an Exim filter specifies a
relative path, and <em class="varname">$home</em> is defined, it is automatically prepended to the
relative path. If this option is set false, this action does not happen. The
relative path is then passed to the transport unmodified.
</p>
<p>
<a id="id576974" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_blackhole</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, the <span class="emphasis"><em>:blackhole:</em></span> item may not appear in a
redirection list.
</p>
<p>
<a id="id577064" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_exim_filter</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is set true, only Sieve filters are permitted when
<span><strong class="option">allow_filter</strong></span> is true.
</p>
<p>
<a id="id577155" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_file</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id577237" class="indexterm"></a>
<a id="id577252" class="indexterm"></a>
<a id="id577267" class="indexterm"></a>
If this option is true, this router may not generate a new address that
specifies delivery to a local file or directory, either from a filter or from a
conventional forward file. This option is forced to be true if <span><strong class="option">one_time</strong></span> is
set. It applies to Sieve filters as well as to Exim filters, but if true, it
locks out the Sieve’s “<span class="quote">keep</span>” facility.
</p>
<p>
<a id="id577301" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_dlfunc</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id577384" class="indexterm"></a>
If this option is true, string expansions in Exim filters are not allowed to
make use of the <span><strong class="option">dlfunc</strong></span> expansion facility to run dynamically loaded
functions.
</p>
<p>
<a id="id577408" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_existstest</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id577490" class="indexterm"></a>
If this option is true, string expansions in Exim filters are not allowed to
make use of the <span><strong class="option">exists</strong></span> condition or the <span><strong class="option">stat</strong></span> expansion item.
</p>
<p>
<a id="id577518" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_logwrite</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, use of the logging facility in Exim filters is not
permitted. Logging is in any case available only if the filter is being run
under some unprivileged uid (which is normally the case for ordinary users’
<em class="filename">.forward</em> files).
</p>
<p>
<a id="id577619" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_lookup</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, string expansions in Exim filter files are not allowed
to make use of <span><strong class="option">lookup</strong></span> items.
</p>
<p>
<a id="id577710" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_perl</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
This option has an effect only if Exim is built with embedded Perl support. If
it is true, string expansions in Exim filter files are not allowed to make use
of the embedded Perl support.
</p>
<p>
<a id="id577800" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_readfile</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, string expansions in Exim filter files are not allowed
to make use of <span><strong class="option">readfile</strong></span> items.
</p>
<p>
<a id="id577891" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_readsocket</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, string expansions in Exim filter files are not allowed
to make use of <span><strong class="option">readsocket</strong></span> items.
</p>
<p>
<a id="id577982" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_reply</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, this router may not generate an automatic reply
message. Automatic replies can be generated only from Exim or Sieve filter
files, not from traditional forward files. This option is forced to be true if
<span><strong class="option">one_time</strong></span> is set.
</p>
<p>
<a id="id578072" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_filter_run</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, string expansions in Exim filter files are not allowed
to make use of <span><strong class="option">run</strong></span> items.
</p>
<p>
<a id="id578162" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_include</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is true, items of the form
</p>
<pre class="literallayout">:include:<path name>
</pre><p>
are not permitted in non-filter redirection lists.
</p>
<p>
<a id="id578261" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_pipe</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id578343" class="indexterm"></a>
If this option is true, this router may not generate a new address which
specifies delivery to a pipe, either from an Exim filter or from a conventional
forward file. This option is forced to be true if <span><strong class="option">one_time</strong></span> is set.
</p>
<p>
<a id="id578368" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_sieve_filter</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is set true, only Exim filters are permitted when
<span><strong class="option">allow_filter</strong></span> is true.
</p>
<p>
<a id="id578459" class="indexterm"></a>
<a id="id578473" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">forbid_smtp_code</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
If this option is set true, any SMTP error codes that are present at the start
of messages specified for <code class="literal">:defer:</code> or <code class="literal">:fail:</code> are quietly ignored, and
the default codes (451 and 550, respectively) are always used.
</p>
<p>
<a id="id578574" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">hide_child_in_errmsg</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id578657" class="indexterm"></a>
If this option is true, it prevents Exim from quoting a child address if it
generates a bounce or delay message for it. Instead it says “<span class="quote">an address
generated from <<span class="emphasis"><em>the top level address</em></span>></span>”. Of course, this applies only to
bounces generated locally. If a message is forwarded to another host, <span class="emphasis"><em>its</em></span>
bounce may well quote the generated address.
</p>
<p>
<a id="id578692" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">ignore_eacces</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id578774" class="indexterm"></a>
If this option is set and an attempt to open a redirection file yields the
EACCES error (permission denied), the <span><strong class="command">redirect</strong></span> router behaves as if the
file did not exist.
</p>
<p>
<a id="id578796" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">ignore_enotdir</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id578878" class="indexterm"></a>
If this option is set and an attempt to open a redirection file yields the
ENOTDIR error (something on the path is not a directory), the <span><strong class="command">redirect</strong></span>
router behaves as if the file did not exist.
</p>
<p>
Setting <span><strong class="option">ignore_enotdir</strong></span> has another effect as well: When a <span><strong class="command">redirect</strong></span>
router that has the <span><strong class="option">file</strong></span> option set discovers that the file does not exist
(the ENOENT error), it tries to <em class="function">stat()</em> the parent directory, as a check
against unmounted NFS directories. If the parent can not be statted, delivery
is deferred. However, it seems wrong to do this check when <span><strong class="option">ignore_enotdir</strong></span>
is set, because that option tells Exim to ignore “<span class="quote">something on the path is not
a directory</span>” (the ENOTDIR error). This is a confusing area, because it seems
that some operating systems give ENOENT where others give ENOTDIR.
</p>
<p>
<a id="id578940" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">include_directory</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
If this option is set, the path names of any <span class="emphasis"><em>:include:</em></span> items in a
redirection list must start with this directory.
</p>
<p>
<a id="id579031" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">modemask</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>octal integer</em></span></td><td align="right">Default: <span class="emphasis"><em>022</em></span></td></tr></tbody></table></div>
<p>
This specifies mode bits which must not be set for a file specified by the
<span><strong class="option">file</strong></span> option. If any of the forbidden bits are set, delivery is deferred.
</p>
<p>
<a id="id579122" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">one_time</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id579205" class="indexterm"></a>
<a id="id579216" class="indexterm"></a>
<a id="id579231" class="indexterm"></a>
<a id="id579245" class="indexterm"></a>
<a id="id579260" class="indexterm"></a>
Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection
files each time it tries to deliver a message causes a problem when one or more
of the generated addresses fails be delivered at the first attempt. The problem
is not one of duplicate delivery – Exim is clever enough to handle that –
but of what happens when the redirection list changes during the time that the
message is on Exim’s queue. This is particularly true in the case of mailing
lists, where new subscribers might receive copies of messages that were posted
before they subscribed.
</p>
<p>
If <span><strong class="option">one_time</strong></span> is set and any addresses generated by the router fail to
deliver at the first attempt, the failing addresses are added to the message as
“<span class="quote">top level</span>” addresses, and the parent address that generated them is marked
“<span class="quote">delivered</span>”. Thus, redirection does not happen again at the next delivery
attempt.
</p>
<p>
<span class="bold"><strong>Warning 1</strong></span>: Any header line addition or removal that is specified by this
router would be lost if delivery did not succeed at the first attempt. For this
reason, the <span><strong class="option">headers_add</strong></span> and <span><strong class="option">headers_remove</strong></span> generic options are not
permitted when <span><strong class="option">one_time</strong></span> is set.
</p>
<p>
<span class="bold"><strong>Warning 2</strong></span>: To ensure that the router generates only addresses (as opposed
to pipe or file deliveries or auto-replies) <span><strong class="option">forbid_file</strong></span>, <span><strong class="option">forbid_pipe</strong></span>,
and <span><strong class="option">forbid_filter_reply</strong></span> are forced to be true when <span><strong class="option">one_time</strong></span> is set.
</p>
<p>
<span class="bold"><strong>Warning 3</strong></span>: The <span><strong class="option">unseen</strong></span> generic router option may not be set with
<span><strong class="option">one_time</strong></span>.
</p>
<p>
The original top-level address is remembered with each of the generated
addresses, and is output in any log messages. However, any intermediate parent
addresses are not recorded. This makes a difference to the log only if
<span><strong class="option">all_parents</strong></span> log selector is set. It is expected that <span><strong class="option">one_time</strong></span> will
typically be used for mailing lists, where there is normally just one level of
expansion.
</p>
<p>
<a id="id579380" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">owners</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string list</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id579462" class="indexterm"></a>
<a id="id579476" class="indexterm"></a>
<a id="id579490" class="indexterm"></a>
<a id="id579505" class="indexterm"></a>
This specifies a list of permitted owners for the file specified by <span><strong class="option">file</strong></span>.
This list is in addition to the local user when <span><strong class="option">check_local_user</strong></span> is set.
See <span><strong class="option">check_owner</strong></span> above.
</p>
<p>
<a id="id579536" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">owngroups</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string list</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
This specifies a list of permitted groups for the file specified by <span><strong class="option">file</strong></span>.
The list is in addition to the local user’s primary group when
<span><strong class="option">check_local_user</strong></span> is set. See <span><strong class="option">check_group</strong></span> above.
</p>
<p>
<a id="id579636" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">pipe_transport</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id579720" class="indexterm"></a>
A <span><strong class="command">redirect</strong></span> router sets up a direct delivery to a pipe when a string
starting with a vertical bar character is specified as a new “<span class="quote">address</span>”. The
transport used is specified by this option, which, after expansion, must be the
name of a configured transport. This should normally be a <span><strong class="command">pipe</strong></span> transport.
When the transport is run, the pipe command is in <em class="varname">$address_pipe</em>.
</p>
<p>
<a id="id579759" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">qualify_domain</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id579844" class="indexterm"></a>
If this option is set, and an unqualified address (one without a domain) is
generated, and that address would normally be qualified by the global setting
in <span><strong class="option">qualify_recipient</strong></span>, it is instead qualified with the domain specified by
expanding this string. If the expansion fails, the router declines. If you want
to revert to the default, you can have the expansion generate
<em class="varname">$qualify_recipient</em>.
</p>
<p>
This option applies to all unqualified addresses generated by Exim filters,
but for traditional <em class="filename">.forward</em> files, it applies only to addresses that are
not preceded by a backslash. Sieve filters cannot generate unqualified
addresses.
</p>
<p>
<a id="id579886" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">qualify_preserve_domain</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id579969" class="indexterm"></a>
<a id="id579983" class="indexterm"></a>
<a id="id579995" class="indexterm"></a>
If this option is set, the router’s local <span><strong class="option">qualify_domain</strong></span> option must not be
set (a configuration error occurs if it is). If an unqualified address (one
without a domain) is generated, it is qualified with the domain of the parent
address (the immediately preceding ancestor) instead of the global
<span><strong class="option">qualify_recipient</strong></span> value. In the case of a traditional <em class="filename">.forward</em> file,
this applies whether or not the address is preceded by a backslash.
</p>
<p>
<a id="id580033" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">repeat_use</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>true</em></span></td></tr></tbody></table></div>
<p>
If this option is set false, the router is skipped for a child address that has
any ancestor that was routed by this router. This test happens before any of
the other preconditions are tested. Exim’s default anti-looping rules skip
only when the ancestor is the same as the current address. See also
<span><strong class="option">check_ancestor</strong></span> above and the generic <span><strong class="option">redirect_router</strong></span> option.
</p>
<p>
<a id="id580137" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">reply_transport</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
A <span><strong class="command">redirect</strong></span> router sets up an automatic reply when a <span><strong class="option">mail</strong></span> or
<span><strong class="option">vacation</strong></span> command is used in a filter file. The transport used is specified
by this option, which, after expansion, must be the name of a configured
transport. This should normally be an <span><strong class="command">autoreply</strong></span> transport. Other transports
are unlikely to do anything sensible or useful.
</p>
<p>
<a id="id580248" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">rewrite</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>true</em></span></td></tr></tbody></table></div>
<p>
<a id="id580330" class="indexterm"></a>
If this option is set false, addresses generated by the router are not
subject to address rewriting. Otherwise, they are treated like new addresses
and are rewritten according to the global rewriting rules.
</p>
<p>
<a id="id580352" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">sieve_subaddress</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
The value of this option is passed to a Sieve filter to specify the
:subaddress part of an address.
</p>
<p>
<a id="id580442" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">sieve_useraddress</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
The value of this option is passed to a Sieve filter to specify the :user part
of an address. However, if it is unset, the entire original local part
(including any prefix or suffix) is used for :user.
</p>
<p>
<a id="id580531" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">sieve_vacation_directory</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
<a id="id580616" class="indexterm"></a>
To enable the “<span class="quote">vacation</span>” extension for Sieve filters, you must set
<span><strong class="option">sieve_vacation_directory</strong></span> to the directory where vacation databases are held
(do not put anything else in that directory), and ensure that the
<span><strong class="option">reply_transport</strong></span> option refers to an <span><strong class="command">autoreply</strong></span> transport. Each user
needs their own directory; Exim will create it if necessary.
</p>
<p>
<a id="id580655" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">skip_syntax_errors</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>boolean</em></span></td><td align="right">Default: <span class="emphasis"><em>false</em></span></td></tr></tbody></table></div>
<p>
<a id="id580738" class="indexterm"></a>
<a id="id580752" class="indexterm"></a>
<a id="id580767" class="indexterm"></a>
<a id="id580781" class="indexterm"></a>
<a id="id580793" class="indexterm"></a>
<a id="id580804" class="indexterm"></a>
<a id="id580815" class="indexterm"></a>
If <span><strong class="option">skip_syntax_errors</strong></span> is set, syntactically malformed addresses in
non-filter redirection data are skipped, and each failing address is logged. If
<span><strong class="option">syntax_errors_to</strong></span> is set, a message is sent to the address it defines,
giving details of the failures. If <span><strong class="option">syntax_errors_text</strong></span> is set, its contents
are expanded and placed at the head of the error message generated by
<span><strong class="option">syntax_errors_to</strong></span>. Usually it is appropriate to set <span><strong class="option">syntax_errors_to</strong></span> to
be the same address as the generic <span><strong class="option">errors_to</strong></span> option. The
<span><strong class="option">skip_syntax_errors</strong></span> option is often used when handling mailing lists.
</p>
<p>
If all the addresses in a redirection list are skipped because of syntax
errors, the router declines to handle the original address, and it is passed to
the following routers.
</p>
<p>
If <span><strong class="option">skip_syntax_errors</strong></span> is set when an Exim filter is interpreted, any syntax
error in the filter causes filtering to be abandoned without any action being
taken. The incident is logged, and the router declines to handle the address,
so it is passed to the following routers.
</p>
<p>
<a id="id580885" class="indexterm"></a>
Syntax errors in a Sieve filter file cause the “<span class="quote">keep</span>” action to occur. This
action is specified by RFC 3028. The values of <span><strong class="option">skip_syntax_errors</strong></span>,
<span><strong class="option">syntax_errors_to</strong></span>, and <span><strong class="option">syntax_errors_text</strong></span> are not used.
</p>
<p>
<span><strong class="option">skip_syntax_errors</strong></span> can be used to specify that errors in users’ forward
lists or filter files should not prevent delivery. The <span><strong class="option">syntax_errors_to</strong></span>
option, used with an address that does not get redirected, can be used to
notify users of these errors, by means of a router like this:
</p>
<pre class="literallayout">userforward:
driver = redirect
allow_filter
check_local_user
file = $home/.forward
file_transport = address_file
pipe_transport = address_pipe
reply_transport = address_reply
no_verify
skip_syntax_errors
syntax_errors_to = real-$local_part@$domain
syntax_errors_text = \
This is an automatically generated message. An error has\n\
been found in your .forward file. Details of the error are\n\
reported below. While this error persists, you will receive\n\
a copy of this message for every message that is addressed\n\
to you. If your .forward file is a filter file, or if it is\n\
a non-filter file containing no valid forwarding addresses,\n\
a copy of each incoming message will be put in your normal\n\
mailbox. If a non-filter file contains at least one valid\n\
forwarding address, forwarding to the valid addresses will\n\
happen, and those will be the only deliveries that occur.
</pre><p>
You also need a router to ensure that local addresses that are prefixed by
<code class="literal">real-</code> are recognized, but not forwarded or filtered. For example, you could
put this immediately before the <span><strong class="command">userforward</strong></span> router:
</p>
<pre class="literallayout">real_localuser:
driver = accept
check_local_user
local_part_prefix = real-
transport = local_delivery
</pre><p>
For security, it would probably be a good idea to restrict the use of this
router to locally-generated messages, using a condition such as this:
</p>
<pre class="literallayout"> condition = ${if match {$sender_host_address}\
{\N^(|127\.0\.0\.1)$\N}}
</pre><p>
<a id="id580990" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">syntax_errors_text</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span>†<span class="emphasis"><em></em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
See <span><strong class="option">skip_syntax_errors</strong></span> above.
</p>
<p>
<a id="id581083" class="indexterm"></a>
</p>
<div class="informaltable">
<table border="1"><colgroup><col align="left" /><col align="center" /><col align="center" /><col align="right" /></colgroup><tbody><tr><td align="left"><span><strong class="option">syntax_errors_to</strong></span></td><td align="center">Use: <span class="emphasis"><em>redirect</em></span></td><td align="center">Type: <span class="emphasis"><em>string</em></span></td><td align="right">Default: <span class="emphasis"><em>unset</em></span></td></tr></tbody></table></div>
<p>
See <span><strong class="option">skip_syntax_errors</strong></span> above.
<a id="id581170" class="indexterm"></a>
<a id="id581181" class="indexterm"></a>
</p>
</div>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch21.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch23.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>
