File: spec_34.html

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

<TITLE>Exim Specification - 34. Address rewriting</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_33.html">previous</A>, <A HREF="spec_35.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC740" HREF="spec_toc.html#TOC740">34. Address rewriting</A></H1>
<P>
<A NAME="IDX1668"></A>
<A NAME="IDX1669"></A>
<font color=green>
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
(for addresses in envelopes, this is permitted only for locally submitted
messages, or messages from hosts that match <EM>sender_unqualified_hosts</EM> or
<EM>receiver_unqualified_hosts</EM>) or when an address contains an abbreviated
domain that is expanded by DNS lookup.

</P>
<P>
One situation in which Exim does <EM>not</EM> 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 `canonical' name, and some MTAs do this. The new
draft RFCs do not contain this suggestion.

</P>
<P>
This chapter is about address rewriting that is explicitly specified in the
configuration.
</font>
Some people believe that configured 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>
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 `regularizing' addresses in your own domains.
Although it can be used as a routing tool, this is definitely not recommended.

</P>
<P>
There are two commonly encountered circumstances where rewriting is used, as
illustrated by these examples:

</P>

<UL>

<LI>

The company whose domain is <TT>`hitch.fict.book'</TT> has a number of machines that exchange mail with
each other behind a firewall, but only a single gateway to the outer world. The
gateway rewrites <TT>`*.hitch.fict.book'</TT> as <TT>`hitch.fict.book'</TT>.

<LI>

A machine rewrites the local parts of its own users so that, for example,
<EM>fp42@hitch.fict.book</EM> becomes <EM>Ford.Prefect@hitch.fict.book</EM>.
</UL>

<P>
<font color=green>
Configured address rewriting can take place at several different stages of a
message's processing. The main rewriting happens when a message is received,
but it can also happen when a new address is generated during directing or
routing (for example, by aliasing), and when a message is transported.

</P>
<P>
The rewriting rules that appear in the rewriting section of the configuration
file (the sixth section) apply to addresses in incoming messages, and to
addresses that are generated from the envelope recipients by aliasing or
forwarding, unless <EM>no_rewrite</EM> is set on the relevant directors. Basically,
they apply to each address the first time Exim sees it. These rules operate
both on envelope addresses and on addresses in header lines. Each rule
specifies to which types of address it applies.

</P>
<P>
At transport time, rewriting addresses in header lines can be specified by
setting the generic <EM>headers_rewrite</EM> option on a transport. This option
contains rules that are identical in form to those in the rewrite section of
the configuration file. In addition, the outgoing envelope sender can be
rewritten by means of the <EM>return_path</EM> transport option, but it is not
possible to rewrite envelope recipients at transport time.

</P>
<P>
Rewriting of addresses in header lines applies only to those headers that
were received with the message, or, in the case of transport rewriting, those
that were added by a system filter. That is, it applies only to those headers
that are common to all copies of the message. Header lines that are added by
individual drivers (and which are therefore specific to individual recipient
addresses) are not rewritten.

</P>
<P>
Unqualified addresses (those without a domain) in header lines are qualified
and then rewritten 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>
The remainder of this chapter describes the rewriting rules that are used in
the rewriting section of the configuration file, and also in the generic
<EM>headers_rewrite</EM> option that can be set on any transport.
</font>

</P>

<P>



<H2><A NAME="SEC741" HREF="spec_toc.html#TOC741">34.1 Testing the rewriting rules that apply on input</A></H2>

<P>
<A NAME="IDX1670"></A>
<A NAME="IDX1671"></A>
Exim's input rewriting configuration appears as the sixth part of the run time
configuration file. It can be tested by the -<EM>brw</EM> command line option. This
takes an address (which can be a full RFC 822 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,

<PRE>
exim -brw ph10@exim.work.shop
</PRE>

<P>
might produce the output

<PRE>
  sender: Philip.Hazel@exim.work.shop
    from: Philip.Hazel@exim.work.shop
      to: ph10@exim.work.shop
      cc: ph10@exim.work.shop
     bcc: ph10@exim.work.shop
reply-to: Philip.Hazel@exim.work.shop
env-from: Philip.Hazel@exim.work.shop
  env-to: ph10@exim.work.shop
</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.

</P>


<H2><A NAME="SEC742" HREF="spec_toc.html#TOC742">34.2 Rewriting rules</A></H2>

<P>
<A NAME="IDX1672"></A>
The rewriting section of the configuration file consists of lines of rewriting
rules in the form

<PRE>
&#60;<EM>source pattern</EM>&#62;  &#60;<EM>replacement</EM>&#62;  &#60;<EM>flags</EM>&#62;
</PRE>

<P>
The flags are single characters which may appear in any order. Spaces and tabs
between them are ignored.

</P>
<P>
<font color=green>
Rewriting rules that are specified for the <EM>headers_rewrite</EM> generic transport
option are given as a colon-separated list; each item in the list takes the
same format as a line in the main rewriting configuration.
</font>

</P>
<P>
The formats of source patterns and replacement strings are described below.
Each is terminated by white space. If a replacement string contains spaces,
which can happen for certain forms of expansion expression, it must be enclosed
in double quotes, and the normal quoting conventions apply inside them.

</P>
<P>
For each address that could potentially be rewritten, the rules are scanned in
order, and replacements from earlier rules can themselves be replaced as a
result of later rules (but see the `q' and `R' flags).

</P>
<P>
The order in which header and envelope addresses are rewritten is undefined,
may change between releases, and must not be relied on,
<font color=green>
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 <EM>To:</EM> must not assume that
the message's address in <EM>From:</EM> has (or has not) already been rewritten.
However, a rewrite of <EM>From:</EM> may assume that the envelope sender has already
been rewritten.
</font>

</P>
<P>
$<EM>local_part</EM> and $<EM>domain</EM> can be used in the replacement string to refer
the address that is being rewritten. Note that complete lookup-driven
rewriting can be done by a rule of the form

<PRE>
*@*   ${lookup ...
</PRE>

<P>
where the lookup key is derived from $<EM>1</EM> and $<EM>2</EM> or $<EM>local_part</EM> and
$<EM>domain</EM>.

</P>


<H2><A NAME="SEC743" HREF="spec_toc.html#TOC743">34.3 Rewriting patterns</A></H2>

<P>
<A NAME="IDX1673"></A>
The source pattern can be in one of the following forms. It is not enclosed in
quotes, and there is no special processing of any characters. It is not
expanded. If it is a regular expression, backslash characters should not be
doubled.

</P>

<UL>

<LI>

An address containing a local part and a domain, either of which may start with
an asterisk, implying independent wildcard matching, for example

<PRE>
*@orchestra-land.fict.book
</PRE>

If the domain is specified as a single @ character, it matches the primary
host name. After matching, the numerical variables refer to the character
strings matched by asterisks, with $<EM>1</EM> associated with the first asterisk,
while $<EM>0</EM> refers to the entire address. For example, if the pattern

<PRE>
*queen@*.fict.book
</PRE>

is matched against the address <EM>hearts-queen@wonderland.fict.book</EM> then

<PRE>
$0 = hearts-queen@wonderland.fict.book
$1 = hearts-
$2 = wonderland
</PRE>

Note that if the local part does not start with an asterisk, but the domain
does, it is $<EM>1</EM> that contains the wild part of the domain.

<LI>

A local part, possibly starting with an asterisk, and a lookup item (as
in a domain list), for example

<PRE>
root@lsearch;/special/domains
</PRE>

If there is an asterisk in the local part, the value of the wild part is placed
in the first numerical variable. If the lookup is a partial one, the wild part
of the domain is placed in the next numerical variable, and the fixed part of
the domain is placed in the succeeding variable. Supposed, for example, that
the address <EM>foo@bar.baz.com</EM> is processed by a rewriting rule of the form

<PRE>
*@partial-dbm;/some/dbm/file    &#60;<EM>replacement string</EM>&#62;
</PRE>

and the key in the file that matches the domain is <TT>`*.baz.com'</TT>. Then

<PRE>
$1 = foo
$2 = bar
$3 = baz.com
</PRE>

If the address <EM>foo@baz.com</EM> is looked up, this matches the same wildcard file
entry, and in this case $<EM>2</EM> is set to the empty string, but $<EM>3</EM> is still
set to <EM>baz.com</EM>. If a non-wild key is matched in a partial lookup,
$<EM>2</EM> is again set to the empty string and $<EM>3</EM> is set to the whole domain.
For non-partial lookups, no numerical variables are set.

<LI>

A local part, possibly starting with an asterisk, and a regular expression (as
in a domain list), for example

<PRE>
*.queen@^(wonderland|lookingglass)\.fict\.book$
</PRE>

If there is an asterisk in the local part, the value of the wild part is placed
in the first numerical variable. Any substrings captured by the regular
expression are placed in numerical variables starting at $<EM>1</EM> if there is no
asterisk in the local part, or at $<EM>2</EM> if there is.

<LI>

A lookup without a local part, for example

<PRE>
partial-dbm;/rewrite/database
</PRE>

This works as for an <EM>address list</EM> configuration item -- the domain is first
looked up, possibly partially, and if that fails, the whole address is then
looked up (not partially). When a partial lookup succeeds, the numerical
variable $<EM>1</EM> contains the wild part of the domain, and $<EM>2</EM> contains the
fixed part. The `@@' form of address list lookup can also be used.

<LI>

<A NAME="IDX1674"></A>
A single regular expression. This is matched against the entire address, with
the domain part lower-cased. After matching, the numerical variables refer to
the bracketed `capturing' sub-expressions, with $<EM>0</EM> referring to the entire
address. For example, if the pattern

<PRE>
^(red|white)\.king@(wonderland|lookingglass)\.fict\.book$
</PRE>

is matched against the address <EM>red.king@lookingglass.fict.book</EM> then

<PRE>
$0 = <EM>red.king@lookingglass.fict.book</EM>
$1 = <EM>red</EM>
$2 = <EM>lookingglass</EM>
</PRE>

Note that because the pattern part of a rewriting rule is terminated by white
space, no white space may be present in the regular expression.
</UL>



<H2><A NAME="SEC744" HREF="spec_toc.html#TOC744">34.4 Rewriting replacements</A></H2>

<P>
<A NAME="IDX1675"></A>
If the replacement string for a rule is a single asterisk, addresses that
match the pattern and flags are <EM>not</EM> rewritten, and no subsequent rewriting
rules are scanned. For example,

<PRE>
hatta@lookingglass.fict.book  *  f
</PRE>

<P>
specifies that <EM>hatta@lookingglass.fict.book</EM> is never to be rewritten in
<EM>From:</EM> headers.

</P>
<P>
Otherwise, the replacement string is expanded and must yield a fully qualified
address. Within the expansion, the variables $<EM>local_part</EM> and $<EM>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 `fail' in a
conditional or lookup item, rewriting by the current rule is abandoned. Any
other expansion failure causes the entire rewriting operation to be abandoned,
and an entry written to the panic log.

</P>



<H2><A NAME="SEC745" HREF="spec_toc.html#TOC745">34.5 Rewriting flags</A></H2>

<P>
There are four different kinds of flag that may appear on rewriting rules:

</P>

<UL>

<LI>

Flags that specify which headers and envelope addresses to rewrite: E, F, T, b,
c, f, h, r, s, t.

<LI>

A flag that specifies rewriting at SMTP time: S.

<LI>

Flags that control the rewriting process: Q, q, R, w.

<LI>

A special-purpose flag for additional relay checking: X.
</UL>

<P>
<font color=green>
For rules that are part of the <EM>headers_rewrite</EM> generic transport option,
E, F, T, S, and X are not permitted.
</font>

</P>



<H2><A NAME="SEC746" HREF="spec_toc.html#TOC746">34.6 Flags specifying which headers and envelope addresses to rewrite</A></H2>

<P>
<A NAME="IDX1676"></A>
If none of the following flag letters, nor the `S' flag (see section
34.7) are present,
<font color=green>
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.
</font>
Otherwise, the rewriting rule is skipped unless the relevant addresses are
being processed.

<PRE>
E       rewrite all envelope fields
F       rewrite the envelope From field
T       rewrite the envelope To field
b       rewrite the <EM>Bcc:</EM> header
c       rewrite the <EM>Cc:</EM> header
f       rewrite the <EM>From:</EM> header
h       rewrite all headers
r       rewrite the <EM>Reply-To:</EM> header
s       rewrite the <EM>Sender:</EM> header
t       rewrite the <EM>To:</EM> header
</PRE>

<P>
You should be particularly careful about rewriting <EM>Sender:</EM> headers, and
restrict this to special known cases in your own domains.

</P>


<H2><A NAME="SEC747" HREF="spec_toc.html#TOC747">34.7 The SMTP-time rewriting flag</A></H2>

<P>
<A NAME="IDX1677"></A>
The rewrite flag `S' 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,
<font color=green>
and it is matched against the whole of the data for the command, including any
surrounding angle brackets.
</font>
This form of rewrite rule allows for the handling of addresses that are not
compliant with RFCs 821 and 822 (for example, `bang paths' in batched SMTP
input). Because the input is not required to be a syntactically valid address,
the variables $<EM>local_part</EM> and $<EM>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>


<H2><A NAME="SEC748" HREF="spec_toc.html#TOC748">34.8 Flags controlling the rewriting process</A></H2>

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

<UL>

<LI>

If the `Q' flag is set on a rule, the rewritten address is permitted to be
an unqualified local part. It is qualified with <EM>qualify_recipient</EM>. In the
absence of `Q' the rewritten address must always include a domain.

<LI>

If the `q' flag is set on a rule, no further rewriting rules are
considered, even if no rewriting actually takes place because of a `fail' in
the expansion. The `q' flag is not effective if the address is of the wrong
type (does not match the flags) or does not match the pattern.

<LI>

The `R' flag causes a successful rewriting rule to be re-applied to
the new address, up to ten times. It can be combined with the `q' flag, to stop
rewriting once it fails to match (after at least one successful rewrite).

<LI>

<A NAME="IDX1678"></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 822
`phrase' left unchanged. For example, rewriting might change

<PRE>
From: Ford Prefect &#60;fp42@restaurant.hitch.fict.book&#62;
</PRE>

into

<PRE>
From: Ford Prefect &#60;prefectf@hitch.fict.book&#62;
</PRE>

Sometimes there is a need to replace the whole address item, and this can be
done by adding the flag letter `w' to a rule. If this is set on a rule that
causes an address in a header to be rewritten, the entire address is replaced,
not just the working part. The replacement must be a complete RFC 822 address,
including the angle brackets if necessary. When the `w' 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.
</UL>



<H2><A NAME="SEC749" HREF="spec_toc.html#TOC749">34.9 The additional relay checking flag</A></H2>

<P>
The `X' flag is a slightly strange oddity that adds additional checking to
<EM>sender_address_relay</EM>. Whenever an address passes the
<EM>sender_address_relay</EM> check, if there are any rewriting rules with the `X'
flag set, the address is rewritten and if this makes any change to the address,
it must verify successfully for the relaying to be permitted.

</P>
<P>
We use this in Cambridge as follows: users have a centrally registered address
in the virtual domain <EM>cam.ac.uk</EM>, but there are a number of different hosts
where they actually have their accounts and from which they can read mail using
IMAP or POP. It is desirable to prevent them using hosts other than those on
which they have accounts as outgoing relays, and yet to permit the sending
addresses to contain the <EM>cam.ac.uk</EM> domain. Since the user names are the same
on the relay hosts as in the <EM>cam.ac.uk</EM> domain, a rewriting rule of the form

<PRE>
*@cam.ac.uk  $1@${qualify_domain}  X
</PRE>

<P>
means that any sender address of the form <EM>user@cam.ac.uk</EM> is acceptable only
if <EM>user</EM> has an account on the local host. This also has the virtue of
detecting typos in the configurations of users' MUAs.

</P>



<H2><A NAME="SEC750" HREF="spec_toc.html#TOC750">34.10 Rewriting examples</A></H2>

<P>
Here is an example of the two common rewriting paradigms:

<PRE>
*@*.hitch.book.fict  $1@hitch.book.fict
*@hitch.book.fict    ${lookup{$1}dbm{/etc/realnames}\
                     {$value}fail}@hitch.book.fict bctfrF
</PRE>

<P>
Note the use of `fail' in the lookup expansion. This causes the string
expansion to fail, and in this context it has the effect of leaving the
original address unchanged, but Exim goes on to consider subsequent rewriting
rules, if any, since the `q' flag is not present in that rule. An alternative
to `fail' would be to supply $<EM>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

<PRE>
root@*.hitch.book.fict  *
</PRE>

<P>
were inserted as the first rule, rewriting would be suppressed for the local
part <EM>root</EM> at any domain ending in <EM>hitch.book.fict</EM>.

</P>
<P>
Rewriting can be made conditional on a number of tests, by making use of
$<EM>{if</EM> in the expansion item. For example, to apply a rewriting rule only to
messages that originate outside the local host:

<PRE>
*@*.hitch.book.fict  "${if !eq {$sender_host_address}{}\
                      {$1@hitch.book.fict}fail}"
</PRE>

<P>
The replacement string is quoted in this example because it contains white
space.

</P>
<P>
<A NAME="IDX1679"></A>
<A NAME="IDX1680"></A>
Exim does not handle addresses in the form of `bang paths'. 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

<PRE>
^([^!]+)!(.*)@your\.domain$   $2@$1
</PRE>

<P>
rewrites a two-component bang path `host.name!user' as the domain address
`user@host.name'. However, there is a security implication in doing this as a
normal rewriting rule for envelope addresses. It can provide a backdoor method
for using your system as a relay, since the incoming addresses appear to be
local. If the bang path addresses are received via SMTP, it is safer to use the
`S' flag to rewrite them as they are received, so that relay checking can be
done on the rewritten addresses.

</P>

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