<?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>31. Address rewriting</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="ch30.html" title="30. The smtp transport" /><link rel="next" href="ch32.html" title="32. Retry configuration" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch30.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch32.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#toc0248" id="CHAPrewrite">31. Address rewriting</a></h2></div>
</div>
</div>
<p>
<a id="IIDaddrew" class="indexterm"></a>
There are some circumstances in which Exim automatically rewrites domains in
addresses. The two most common are when an address is given without a domain
(referred to as an “<span class="quote">unqualified address</span>”) or when an address contains an
abbreviated domain that is expanded by DNS lookup.
</p>
<p>
Unqualified envelope addresses are accepted only for locally submitted
messages, or for messages that are received from hosts matching
<span><strong class="option">sender_unqualified_hosts</strong></span> or <span><strong class="option">recipient_unqualified_hosts</strong></span>, as
appropriate. Unqualified addresses in header lines are qualified if they are in
locally submitted messages, or messages from hosts that are permitted to send
unqualified envelope addresses. Otherwise, unqualified addresses in header
lines are neither qualified nor rewritten.
</p>
<p>
One situation in which Exim does <span class="emphasis"><em>not</em></span> automatically rewrite a domain is
when it is the name of a CNAME record in the DNS. The older RFCs suggest that
such a domain should be rewritten using the “<span class="quote">canonical</span>” name, and some MTAs
do this. The new RFCs do not contain this suggestion.
</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#toc0249" id="SECID147">31.1 Explicitly configured address rewriting</a></h3></div>
</div>
</div>
<p>
This chapter describes the rewriting rules that can be used in the
main rewrite section of the configuration file, and also in the generic
<span><strong class="option">headers_rewrite</strong></span> option that can be set on any transport.
</p>
<p>
Some people believe that configured address rewriting is a Mortal Sin.
Others believe that life is not possible without it. Exim provides the
facility; you do not have to use it.
</p>
<p>
The main rewriting rules that appear in the “<span class="quote">rewrite</span>” section of the
configuration file are applied to addresses in incoming messages, both envelope
addresses and addresses in header lines. Each rule specifies the types of
address to which it applies.
</p>
<p>
Whether or not addresses in header lines are rewritten depends on the origin of
the headers and the type of rewriting. Global rewriting, that is, rewriting
rules from the rewrite section of the configuration file, is applied only to
those headers that were received with the message. Header lines that are added
by ACLs or by a system filter or by individual routers or transports (which
are specific to individual recipient addresses) are not rewritten by the global
rules.
</p>
<p>
Rewriting at transport time, by means of the <span><strong class="option">headers_rewrite</strong></span> option,
applies all headers except those added by routers and transports. That is, as
well as the headers that were received with the message, it also applies to
headers that were added by an ACL or a system filter.
</p>
<p>
In general, rewriting addresses from your own system or domain has some
legitimacy. Rewriting other addresses should be done only with great care and
in special circumstances. The author of Exim believes that rewriting should be
used sparingly, and mainly for “<span class="quote">regularizing</span>” addresses in your own domains.
Although it can sometimes be used as a routing tool, this is very strongly
discouraged.
</p>
<p>
There are two commonly encountered circumstances where rewriting is used, as
illustrated by these examples:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
The company whose domain is <span class="emphasis"><em>hitch.fict.example</em></span> has a number of hosts that
exchange mail with each other behind a firewall, but there is only a single
gateway to the outer world. The gateway rewrites <span class="emphasis"><em>*.hitch.fict.example</em></span> as
<span class="emphasis"><em>hitch.fict.example</em></span> when sending mail off-site.
</p>
</li><li><p>
A host rewrites the local parts of its own users so that, for example,
<span class="emphasis"><em>fp42@hitch.fict.example</em></span> becomes <span class="emphasis"><em>Ford.Prefect@hitch.fict.example</em></span>.
</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#toc0250" id="SECID148">31.2 When does rewriting happen?</a></h3></div>
</div>
</div>
<p>
<a id="id609335" class="indexterm"></a>
<a id="id609349" class="indexterm"></a>
Configured address rewriting can take place at several different stages of a
message’s processing.
</p>
<p>
<a id="id609372" class="indexterm"></a>
At the start of an ACL for MAIL, the sender address may have been rewritten
by a special SMTP-time rewrite rule (see section <a href="ch31.html#SECTrewriteS" title="31.9 The SMTP-time rewriting flag">31.9</a>), but no
ordinary rewrite rules have yet been applied. If, however, the sender address
is verified in the ACL, it is rewritten before verification, and remains
rewritten thereafter. The subsequent value of <em class="varname">$sender_address</em> is the
rewritten address. This also applies if sender verification happens in a
RCPT ACL. Otherwise, when the sender address is not verified, it is
rewritten as soon as a message’s header lines have been received.
</p>
<p>
<a id="id609411" class="indexterm"></a>
<a id="id609422" class="indexterm"></a>
Similarly, at the start of an ACL for RCPT, the current recipient’s address
may have been rewritten by a special SMTP-time rewrite rule, but no ordinary
rewrite rules have yet been applied to it. However, the behaviour is different
from the sender address when a recipient is verified. The address is rewritten
for the verification, but the rewriting is not remembered at this stage. The
value of <em class="varname">$local_part</em> and <em class="varname">$domain</em> after verification are always the same
as they were before (that is, they contain the unrewritten – except for
SMTP-time rewriting – address).
</p>
<p>
As soon as a message’s header lines have been received, all the envelope
recipient addresses are permanently rewritten, and rewriting is also applied to
the addresses in the header lines (if configured). This happens before adding
any header lines that were specified in MAIL or RCPT ACLs, and
<a id="id609448" class="indexterm"></a>
before the DATA ACL and <em class="function">local_scan()</em> functions are run.
</p>
<p>
When an address is being routed, either for delivery or for verification,
rewriting is applied immediately to child addresses that are generated by
redirection, unless <span><strong class="option">no_rewrite</strong></span> is set on the router.
</p>
<p>
<a id="id609484" class="indexterm"></a>
<a id="id609498" class="indexterm"></a>
<a id="id609513" class="indexterm"></a>
At transport time, additional rewriting of addresses in header lines can be
specified by setting the generic <span><strong class="option">headers_rewrite</strong></span> option on a transport.
This option contains rules that are identical in form to those in the rewrite
section of the configuration file. They are applied to the original message
header lines and any that were added by ACLs or a system filter. They are not
applied to header lines that are added by routers or the transport.
</p>
<p>
The outgoing envelope sender can be rewritten by means of the <span><strong class="option">return_path</strong></span>
transport option. However, it is not possible to rewrite envelope recipients at
transport time.
</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#toc0251" id="SECID149">31.3 Testing the rewriting rules that apply on input</a></h3></div>
</div>
</div>
<p>
<a id="id609562" class="indexterm"></a>
<a id="id609576" class="indexterm"></a>
Exim’s input rewriting configuration appears in a part of the run time
configuration file headed by “<span class="quote">begin rewrite</span>”. It can be tested by the
<span><strong class="option">-brw</strong></span> command line option. This takes an address (which can be a full RFC
2822 address) as its argument. The output is a list of how the address would be
transformed by the rewriting rules for each of the different places it might
appear in an incoming message, that is, for each different header and for the
envelope sender and recipient fields. For example,
</p>
<pre class="literallayout">exim -brw ph10@exim.workshop.example
</pre><p>
might produce the output
</p>
<pre class="literallayout">sender: Philip.Hazel@exim.workshop.example
from: Philip.Hazel@exim.workshop.example
to: ph10@exim.workshop.example
cc: ph10@exim.workshop.example
bcc: ph10@exim.workshop.example
reply-to: Philip.Hazel@exim.workshop.example
env-from: Philip.Hazel@exim.workshop.example
env-to: ph10@exim.workshop.example
</pre><p>
which shows that rewriting has been set up for that address when used in any of
the source fields, but not when it appears as a recipient address. At the
present time, there is no equivalent way of testing rewriting rules that are
set for a particular 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#toc0252" id="SECID150">31.4 Rewriting rules</a></h3></div>
</div>
</div>
<p>
<a id="id609654" class="indexterm"></a>
The rewrite section of the configuration file consists of lines of rewriting
rules in the form
</p>
<div class="literallayout">
<<span class="emphasis"><em>source pattern</em></span>> <<span class="emphasis"><em>replacement</em></span>> <<span class="emphasis"><em>flags</em></span>><br />
</div>
<p>
Rewriting rules that are specified for the <span><strong class="option">headers_rewrite</strong></span> generic
transport option are given as a colon-separated list. Each item in the list
takes the same form as a line in the main rewriting configuration (except that
any colons must be doubled, of course).
</p>
<p>
The formats of source patterns and replacement strings are described below.
Each is terminated by white space, unless enclosed in double quotes, in which
case normal quoting conventions apply inside the quotes. The flags are single
characters which may appear in any order. Spaces and tabs between them are
ignored.
</p>
<p>
For each address that could potentially be rewritten, the rules are scanned in
order, and replacements for the address from earlier rules can themselves be
replaced by later rules (but see the “<span class="quote">q</span>” and “<span class="quote">R</span>” flags).
</p>
<p>
The order in which addresses are rewritten is undefined, may change between
releases, and must not be relied on, with one exception: when a message is
received, the envelope sender is always rewritten first, before any header
lines are rewritten. For example, the replacement string for a rewrite of an
address in <span class="emphasis"><em>To:</em></span> must not assume that the message’s address in <span class="emphasis"><em>From:</em></span> has
(or has not) already been rewritten. However, a rewrite of <span class="emphasis"><em>From:</em></span> may assume
that the envelope sender has already been rewritten.
</p>
<p>
<a id="id609749" class="indexterm"></a>
<a id="id609761" class="indexterm"></a>
The variables <em class="varname">$local_part</em> and <em class="varname">$domain</em> can be used in the replacement
string to refer to the address that is being rewritten. Note that lookup-driven
rewriting can be done by a rule of the form
</p>
<pre class="literallayout">*@* ${lookup ...
</pre><p>
where the lookup key uses <em class="varname">$1</em> and <em class="varname">$2</em> or <em class="varname">$local_part</em> and <em class="varname">$domain</em> to
refer to the address that is being rewritten.
</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#toc0253" id="SECID151">31.5 Rewriting patterns</a></h3></div>
</div>
</div>
<p>
<a id="id609824" class="indexterm"></a>
<a id="id609838" class="indexterm"></a>
The source pattern in a rewriting rule is any item which may appear in an
address list (see section <a href="ch10.html#SECTaddresslist" title="10.19 Address lists">10.19</a>). It is in fact processed as a
single-item address list, which means that it is expanded before being tested
against the address. As always, if you use a regular expression as a pattern,
you must take care to escape dollar and backslash characters, or use the <code class="literal">\N</code>
facility to suppress string expansion within the regular expression.
</p>
<p>
Domains in patterns should be given in lower case. Local parts in patterns are
case-sensitive. If you want to do case-insensitive matching of local parts, you
can use a regular expression that starts with <code class="literal">^(?i)</code>.
</p>
<p>
<a id="id609886" class="indexterm"></a>
After matching, the numerical variables <em class="varname">$1</em>, <em class="varname">$2</em>, etc. may be set,
depending on the type of match which occurred. These can be used in the
replacement string to insert portions of the incoming address. <em class="varname">$0</em> always
refers to the complete incoming address. When a regular expression is used, the
numerical variables are set from its capturing subexpressions. For other types
of pattern they are set as follows:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
If a local part or domain starts with an asterisk, the numerical variables
refer to the character strings matched by asterisks, with <em class="varname">$1</em> associated with
the first asterisk, and <em class="varname">$2</em> with the second, if present. For example, if the
pattern
</p>
<pre class="literallayout">*queen@*.fict.example
</pre><p>
is matched against the address <span class="emphasis"><em>hearts-queen@wonderland.fict.example</em></span> then
</p>
<pre class="literallayout">$0 = hearts-queen@wonderland.fict.example
$1 = hearts-
$2 = wonderland
</pre><p>
Note that if the local part does not start with an asterisk, but the domain
does, it is <em class="varname">$1</em> that contains the wild part of the domain.
</p>
</li><li><p>
If the domain part of the pattern is a partial lookup, the wild and fixed parts
of the domain are placed in the next available numerical variables. Suppose,
for example, that the address <span class="emphasis"><em>foo@bar.baz.example</em></span> is processed by a
rewriting rule of the form
</p>
<div class="literallayout">
<code class="literal">*@partial-dbm;/some/dbm/file</code> <<span class="emphasis"><em>replacement string</em></span>><br />
</div>
<p>
and the key in the file that matches the domain is <code class="literal">*.baz.example</code>. Then
</p>
<pre class="literallayout">$1 = foo
$2 = bar
$3 = baz.example
</pre><p>
If the address <span class="emphasis"><em>foo@baz.example</em></span> is looked up, this matches the same
wildcard file entry, and in this case <em class="varname">$2</em> is set to the empty string, but
<em class="varname">$3</em> is still set to <span class="emphasis"><em>baz.example</em></span>. If a non-wild key is matched in a
partial lookup, <em class="varname">$2</em> is again set to the empty string and <em class="varname">$3</em> is set to the
whole domain. For non-partial domain lookups, no numerical variables are set.
</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#toc0254" id="SECID152">31.6 Rewriting replacements</a></h3></div>
</div>
</div>
<p>
<a id="id610072" class="indexterm"></a>
If the replacement string for a rule is a single asterisk, addresses that
match the pattern and the flags are <span class="emphasis"><em>not</em></span> rewritten, and no subsequent
rewriting rules are scanned. For example,
</p>
<pre class="literallayout">hatta@lookingglass.fict.example * f
</pre><p>
specifies that <span class="emphasis"><em>hatta@lookingglass.fict.example</em></span> is never to be rewritten in
<span class="emphasis"><em>From:</em></span> headers.
</p>
<p>
<a id="id610115" class="indexterm"></a>
<a id="id610127" class="indexterm"></a>
If the replacement string is not a single asterisk, it is expanded, and must
yield a fully qualified address. Within the expansion, the variables
<em class="varname">$local_part</em> and <em class="varname">$domain</em> refer to the address that is being rewritten.
Any letters they contain retain their original case – they are not lower
cased. The numerical variables are set up according to the type of pattern that
matched the address, as described above. If the expansion is forced to fail by
the presence of “<span class="quote">fail</span>” in a conditional or lookup item, rewriting by the
current rule is abandoned, but subsequent rules may take effect. Any other
expansion failure causes the entire rewriting operation to be abandoned, and an
entry written to the panic log.
</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#toc0255" id="SECID153">31.7 Rewriting flags</a></h3></div>
</div>
</div>
<p>
There are three different kinds of flag that may appear on rewriting rules:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
Flags that specify which headers and envelope addresses to rewrite: E, F, T, b,
c, f, h, r, s, t.
</p>
</li><li><p>
A flag that specifies rewriting at SMTP time: S.
</p>
</li><li><p>
Flags that control the rewriting process: Q, q, R, w.
</p>
</li></ul></div>
<p>
For rules that are part of the <span><strong class="option">headers_rewrite</strong></span> generic transport option,
E, F, T, and S are not permitted.
</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#toc0256" id="SECID154">31.8 Flags specifying which headers and envelope addresses to rewrite</a></h3></div>
</div>
</div>
<p>
<a id="id610226" class="indexterm"></a>
If none of the following flag letters, nor the “<span class="quote">S</span>” flag (see section
<a href="ch31.html#SECTrewriteS" title="31.9 The SMTP-time rewriting flag">31.9</a>) are present, a main rewriting rule applies to all headers
and to both the sender and recipient fields of the envelope, whereas a
transport-time rewriting rule just applies to all headers. Otherwise, the
rewriting rule is skipped unless the relevant addresses are being processed.
</p>
<div class="literallayout">
<code class="literal">E</code> rewrite all envelope fields<br />
<code class="literal">F</code> rewrite the envelope From field<br />
<code class="literal">T</code> rewrite the envelope To field<br />
<code class="literal">b</code> rewrite the <span class="emphasis"><em>Bcc:</em></span> header<br />
<code class="literal">c</code> rewrite the <span class="emphasis"><em>Cc:</em></span> header<br />
<code class="literal">f</code> rewrite the <span class="emphasis"><em>From:</em></span> header<br />
<code class="literal">h</code> rewrite all headers<br />
<code class="literal">r</code> rewrite the <span class="emphasis"><em>Reply-To:</em></span> header<br />
<code class="literal">s</code> rewrite the <span class="emphasis"><em>Sender:</em></span> header<br />
<code class="literal">t</code> rewrite the <span class="emphasis"><em>To:</em></span> header<br />
</div>
<div xmlns="" class="changed">
<p xmlns="http://www.w3.org/1999/xhtml">
"All headers" means all of the headers listed above that can be selected
individually, plus their <span class="emphasis"><em>Resent-</em></span> versions. It does not include
other headers such as <span class="emphasis"><em>Subject:</em></span> etc.
</p>
</div>
<p>
You should be particularly careful about rewriting <span class="emphasis"><em>Sender:</em></span> headers, and
restrict this to special known cases in your own domains.
</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#toc0257" id="SECTrewriteS">31.9 The SMTP-time rewriting flag</a></h3></div>
</div>
</div>
<p>
<a id="id610381" class="indexterm"></a>
<a id="id610396" class="indexterm"></a>
<a id="id610410" class="indexterm"></a>
The rewrite flag “<span class="quote">S</span>” specifies a rewrite of incoming envelope addresses at
SMTP time, as soon as an address is received in a MAIL or RCPT command, and
before any other processing; even before syntax checking. The pattern is
required to be a regular expression, and it is matched against the whole of the
data for the command, including any surrounding angle brackets.
</p>
<p>
<a id="id610438" class="indexterm"></a>
<a id="id610450" class="indexterm"></a>
This form of rewrite rule allows for the handling of addresses that are not
compliant with RFCs 2821 and 2822 (for example, “<span class="quote">bang paths</span>” in batched SMTP
input). Because the input is not required to be a syntactically valid address,
the variables <em class="varname">$local_part</em> and <em class="varname">$domain</em> are not available during the
expansion of the replacement string. The result of rewriting replaces the
original address in the MAIL or RCPT command.
</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#toc0258" id="SECID155">31.10 Flags controlling the rewriting process</a></h3></div>
</div>
</div>
<p>
There are four flags which control the way the rewriting process works. These
take effect only when a rule is invoked, that is, when the address is of the
correct type (matches the flags) and matches the pattern:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
If the “<span class="quote">Q</span>” flag is set on a rule, the rewritten address is permitted to be an
unqualified local part. It is qualified with <span><strong class="option">qualify_recipient</strong></span>. In the
absence of “<span class="quote">Q</span>” the rewritten address must always include a domain.
</p>
</li><li><p>
If the “<span class="quote">q</span>” flag is set on a rule, no further rewriting rules are considered,
even if no rewriting actually takes place because of a “<span class="quote">fail</span>” in the
expansion. The “<span class="quote">q</span>” flag is not effective if the address is of the wrong type
(does not match the flags) or does not match the pattern.
</p>
</li><li><p>
The “<span class="quote">R</span>” flag causes a successful rewriting rule to be re-applied to the new
address, up to ten times. It can be combined with the “<span class="quote">q</span>” flag, to stop
rewriting once it fails to match (after at least one successful rewrite).
</p>
</li><li><p>
<a id="id610563" class="indexterm"></a>
When an address in a header is rewritten, the rewriting normally applies only
to the working part of the address, with any comments and RFC 2822 “<span class="quote">phrase</span>”
left unchanged. For example, rewriting might change
</p>
<pre class="literallayout">From: Ford Prefect <fp42@restaurant.hitch.fict.example>
</pre><p>
into
</p>
<pre class="literallayout">From: Ford Prefect <prefectf@hitch.fict.example>
</pre><p>
<a id="id610613" class="indexterm"></a>
Sometimes there is a need to replace the whole address item, and this can be
done by adding the flag letter “<span class="quote">w</span>” to a rule. If this is set on a rule that
causes an address in a header line to be rewritten, the entire address is
replaced, not just the working part. The replacement must be a complete RFC
2822 address, including the angle brackets if necessary. If text outside angle
brackets contains a character whose value is greater than 126 or less than 32
(except for tab), the text is encoded according to RFC 2047. The character set
is taken from <span><strong class="option">headers_charset</strong></span>, which defaults to ISO-8859-1.
</p>
<p>
When the “<span class="quote">w</span>” flag is set on a rule that causes an envelope address to be
rewritten, all but the working part of the replacement address is discarded.
</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#toc0259" id="SECID156">31.11 Rewriting examples</a></h3></div>
</div>
</div>
<p>
Here is an example of the two common rewriting paradigms:
</p>
<pre class="literallayout">*@*.hitch.fict.example $1@hitch.fict.example
*@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\
{$value}fail}@hitch.fict.example bctfrF
</pre><p>
Note the use of “<span class="quote">fail</span>” in the lookup expansion in the second rule, forcing
the string expansion to fail if the lookup does not succeed. In this context it
has the effect of leaving the original address unchanged, but Exim goes on to
consider subsequent rewriting rules, if any, because the “<span class="quote">q</span>” flag is not
present in that rule. An alternative to “<span class="quote">fail</span>” would be to supply <em class="varname">$1</em>
explicitly, which would cause the rewritten address to be the same as before,
at the cost of a small bit of processing. Not supplying either of these is an
error, since the rewritten address would then contain no local part.
</p>
<p>
The first example above replaces the domain with a superior, more general
domain. This may not be desirable for certain local parts. If the rule
</p>
<pre class="literallayout">root@*.hitch.fict.example *
</pre><p>
were inserted before the first rule, rewriting would be suppressed for the
local part <span class="emphasis"><em>root</em></span> at any domain ending in <span class="emphasis"><em>hitch.fict.example</em></span>.
</p>
<p>
Rewriting can be made conditional on a number of tests, by making use of
<em class="varname">${if</em> in the expansion item. For example, to apply a rewriting rule only to
messages that originate outside the local host:
</p>
<pre class="literallayout">*@*.hitch.fict.example "${if !eq {$sender_host_address}{}\
{$1@hitch.fict.example}fail}"
</pre><p>
The replacement string is quoted in this example because it contains white
space.
</p>
<p>
<a id="id610757" class="indexterm"></a>
<a id="id610772" class="indexterm"></a>
Exim does not handle addresses in the form of “<span class="quote">bang paths</span>”. If it sees such
an address it treats it as an unqualified local part which it qualifies with
the local qualification domain (if the source of the message is local or if the
remote host is permitted to send unqualified addresses). Rewriting can
sometimes be used to handle simple bang paths with a fixed number of
components. For example, the rule
</p>
<pre class="literallayout">\N^([^!]+)!(.*)@your.domain.example$\N $2@$1
</pre><p>
rewrites a two-component bang path <span class="emphasis"><em>host.name!user</em></span> as the domain address
<span class="emphasis"><em>user@host.name</em></span>. However, there is a security implication in using this as
a global rewriting rule for envelope addresses. It can provide a backdoor
method for using your system as a relay, because the incoming addresses appear
to be local. If the bang path addresses are received via SMTP, it is safer to
use the “<span class="quote">S</span>” flag to rewrite them as they are received, so that relay checking
can be done on the rewritten addresses.
<a id="id610826" 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="ch30.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch32.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>
