dist/proto/ADDRESS_REWRITING_README.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">

<html>

<head>

<title>Postfix Address Rewriting </title>

<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">

</head>

<body>

<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix
Address Rewriting </h1>

<hr>

<h2> <a name="purpose"> Postfix address rewriting purpose </a> </h2>

<p> Address rewriting is at the heart of the Postfix mail system.
Postfix rewrites addresses for many different purposes. Some are
merely cosmetic, and some are necessary to deliver correctly
formatted mail to the correct destination. Examples of
address rewriting in Postfix are:  </p>

<ul>

<li> <p> Transform an incomplete address into a complete address.
For example, transform "username" into "username@example.com", or
transform "username@hostname" into "username@hostname.example.com".
</p>

<li> <p> Replace an address by an equivalent address.  For example,
replace "username@example.com" by "firstname.lastname@example.com"
when sending mail, and do the reverse transformation when receiving
mail.  </p>

<li> <p> Replace an internal address by an external address.  For
example, replace "username@localdomain.local" by "isp-account@isp.example"
when sending mail from a home computer to the Internet.
</p>

<li> <p> Replace an address by multiple addresses. For example,
replace the address of an alias by the addresses listed under that
alias.  </p>

<li> <p> Determine how and where to deliver mail for a specific
address.  For example, deliver mail for "username@example.com" with
the smtp(8) delivery agent, to the hosts that are listed in the
DNS as the mail servers for the domain "example.com". </p>

</ul>

<p> Although Postfix currently has no address rewriting language,
it can do surprisingly powerful address manipulation via table
lookup.  Postfix typically uses lookup tables with fixed strings
to map one address to one or multiple addresses, and typically uses
regular expressions to map multiple addresses to one or multiple
addresses.  Fixed-string lookup tables may be in the form of local
files, or in the form of NIS, LDAP or SQL databases.  The
DATABASE_README document gives an introduction to Postfix lookup
tables. </p>

<p> Topics covered in this document: </p>

<ul>

<li> <a href="#william"> To rewrite message headers or not, or to label
as invalid </a>

<li> <a href="#overview"> Postfix address rewriting overview </a>

<li> <a href="#receiving"> Address rewriting when mail is received</a>

<ul>

<li> <a href="#standard"> Rewrite addresses to standard form</a>

<li> <a href="#canonical"> Canonical address mapping </a>

<li> <a href="#masquerade"> Address masquerading </a>

<li> <a href="#auto_bcc"> Automatic BCC recipients</a>

<li> <a href="#virtual"> Virtual aliasing </a>

</ul>

<li> <a href="#delivering"> Address rewriting when mail is delivered</a>

<ul>

<li> <a href="#resolve"> Resolve address to destination </a>

<li> <a href="#transport"> Mail transport switch </a>

<li> <a href="#relocated"> Relocated users table </a>

</ul>

<li> <a href="#remote"> Address rewriting with remote delivery </a>

<ul>

<li> <a href="#generic"> Generic mapping for outgoing SMTP mail </a>

</ul>

<li> <a href="#local"> Address rewriting with local delivery </a>

<ul>

<li> <a href="#aliases"> Local alias database </a>

<li> <a href="#forward"> Local per-user .forward files </a>

<li> <a href="#luser_relay"> Local catch-all address </a>

</ul>

<li> <a href="#debugging"> Debugging your address manipulations </a>

</ul>

<h2> <a name="william"> To rewrite message headers or not, or to label
as invalid </a> </h2>

<p> Postfix versions 2.1 and earlier always rewrite message header
addresses, and append Postfix's own domain information to addresses
that Postfix considers incomplete.  While rewriting message header
addresses is OK for mail with a local origin, it is undesirable
for remote mail: </p>

<ul>

<li> Message header address rewriting is frowned upon by mail standards,

<li> Appending Postfix's own domain produces incorrect results with
some incomplete addresses,

<li> Appending Postfix's own domain sometimes creates the appearance
that spam is sent by local users.

</ul>

<p> Postfix versions 2.2 give you the option to either not rewrite
message headers from remote SMTP clients at all, or to label
incomplete addresses in such message headers as invalid. Here is
how it works:  </p>

<ul>

<li> Postfix always rewrites message headers from local SMTP clients
and from the Postfix sendmail command, and appends its own domain
to incomplete addresses.  The local_header_rewrite_clients parameter
controls what SMTP clients Postfix considers local (by default,
only local network interface addresses).

<li> Postfix never rewrites message header addresses from remote
SMTP clients when the remote_header_rewrite_domain parameter value
is empty (the default setting).

<li> Otherwise, Postfix rewrites message headers from remote SMTP
clients, and appends the remote_header_rewrite_domain value to
incomplete addresses.  This feature can be used to append a reserved
domain such as "domain.invalid", so that incomplete addresses cannot
be mistaken for local addresses.

</ul>

<h2> <a name="overview"> Postfix address rewriting overview </a> </h2>

<p> The figure below zooms in on those parts of Postfix that are most
involved with address rewriting activity. See the OVERVIEW document
for an overview of the complete Postfix architecture.  Names followed
by a number are Postfix daemon programs, while unnumbered names
represent Postfix queues or internal sources of mail messages. </p>

<blockquote>

<table>

<tr>

<td colspan="2"> </td>

<td bgcolor="#f0f0ff" align="center"> trivial-<br>rewrite(8)<br>(std
form) </td>

<td colspan="5"> </td>

<td bgcolor="#f0f0ff" align="center"> trivial-<br>rewrite(8)<br>(resolve)
</td>

</tr>

<tr>

<td colspan="2"> </td>

<td align="center"><table><tr><td align="center"> ^<br> <tt> |
</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table>

<td colspan="5"> </td>

<td align="center"><table><tr><td align="center"> ^<br> <tt> |
</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table>

<td colspan="2"> </td>

</tr>

<tr>

<td bgcolor="#f0f0ff" align="center" valign="middle"> smtpd(8)
</td>

<td rowspan="3" align="center" valign="middle"> <tt> &gt;- </tt>
</td>

<td rowspan="3" bgcolor="#f0f0ff" align="center"> cleanup(8) </td>

<td rowspan="3" align="center" valign="middle"> <tt> -&gt; </tt>
</td>

<td rowspan="3" bgcolor="#f0f0ff" align="center"> <a
href="QSHAPE_README.html#incoming_queue"> incoming </a> </td>

<td rowspan="3" align="center" valign="middle"> <tt> -&gt; </tt>
</td>

<td rowspan="3" bgcolor="#f0f0ff" align="center"> <a
href="QSHAPE_README.html#active_queue"> active </a> </td>

<td rowspan="3" align="center" valign="middle"> <tt> -&gt; </tt>
</td>

<td rowspan="3" bgcolor="#f0f0ff" align="center"> qmgr(8) </td>

<td rowspan="3" align="center" valign="middle"> <tt> -&lt; </tt>
</td>

<td bgcolor="#f0f0ff" align="center" valign="middle">
smtp(8) </td>

</tr>

<tr>

<td bgcolor="#f0f0ff" align="center" valign="middle">
qmqpd(8) </td>

<td bgcolor="#f0f0ff" align="center" valign="middle"> lmtp(8) </td>

</tr>

<tr>

<td bgcolor="#f0f0ff" align="center" valign="middle"> pickup(8)
</td>

<td bgcolor="#f0f0ff" align="center" valign="middle"> local(8)
</td>

</tr>

<tr>

<td colspan="2"> </td>

<td align="center"> ^<br> <tt> | </tt> </td>

<td colspan="3"> </td>

<td align="center"><table><tr><td align="center"> ^<br> <tt> |
</tt> </td><td align="center"> <tt> |<br>v </tt> </td></tr></table>

<td colspan="4"> </td>

</tr>

<tr>

<td colspan="2"> </td>

<td align="center"> bounces<br> forwarding<br> notices</td>

<td colspan="3"> </td>

<td bgcolor="#f0f0ff" align="center"> <a
href="QSHAPE_README.html#deferred_queue"> deferred </a>

<td colspan="2"> </td>

</table>

</blockquote>

<p> The table below summarizes all Postfix address manipulations.
If you're reading this document for the first time, skip forward
to "<a href="ADDRESS_REWRITING_README.html#receiving">Address
rewriting when mail is received</a>". Once you've finished reading
the remainder of this document, the table will help you to quickly
find what you need.  </p>

<blockquote>

<table border="1">

<tr> <th nowrap> Address manipulation </th> <th nowrap> Scope </th>
<th> Daemon </th> <th nowrap> Global turn-on control </th> <th nowrap> Selective
turn-off control </th> </tr>

<tr> <td> <a href="#standard"> Rewrite addresses to standard form</a>
</td> <td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td>
<td> append_at_myorigin, append_dot_mydomain, swap_bangpath,
allow_percent_hack </td> <td> local_header_rewrite_clients,
remote_header_rewrite_domain </td> </tr>

<tr> <td> <a href="#canonical"> Canonical address mapping </a> </td>
<td nowrap> all mail </td> <td> cleanup(8) </td> <td> canonical_maps
</td> <td> receive_override_options, local_header_rewrite_clients,
remote_header_rewrite_domain </td> </tr>

<tr> <td> <a href="#masquerade"> Address masquerading </a> </td> <td
nowrap> all mail </td> <td> cleanup(8) </td> <td> masquerade_domains
</td> <td> receive_override_options, local_header_rewrite_clients,
remote_header_rewrite_domain </td> </tr>

<tr> <td> <a href="#auto_bcc"> Automatic BCC recipients </a> </td>
<td nowrap> new mail </td> <td> cleanup(8) </td> <td> always_bcc,
sender_bcc_maps, recipient_bcc_maps </td> <td> receive_override_options
</td> </tr>

<tr> <td> <a href="#virtual"> Virtual aliasing </a> </td> <td
nowrap> all mail </td> <td> cleanup(8) </td> <td> virtual_alias_maps
</td> <td> receive_override_options </td> </tr>

<tr> <td> <a href="#resolve"> Resolve address to destination </a>
</td> <td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td>
<td> none </td> <td> none </td> </tr>

<tr> <td> <a href="#transport"> Mail transport switch</a> </td>
<td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td> <td>
transport_maps </td> <td> none </td> </tr>

<tr> <td> <a href="#relocated"> Relocated users table</a> </td>
<td nowrap> all mail </td> <td> trivial-<br>rewrite(8) </td> <td>
relocated_maps </td> <td> none </td> </tr>

<tr> <td> <a href="#generic"> Generic mapping table </a> </td> <td>
outgoing SMTP mail </td> <td> smtp(8) </td> <td> smtp_generic_maps
</td> <td> none </td> </tr>

<tr> <td> <a href="#aliases"> Local alias database</a> </td> <td>
local mail only </td> <td> local(8) </td> <td> alias_maps </td> <td> none
</td> </tr>

<tr> <td> <a href="#forward"> Local per-user .forward files</a>
</td> <td> local mail only </td> <td> local(8) </td> <td> forward_path
</td> <td> none </td> </tr>

<tr> <td> <a href="#luser_relay"> Local catch-all address</a> </td>
<td> local mail only </td> <td> local(8) </td> <td> luser_relay </td> <td>
none </td> </tr>

</table>

</blockquote>

<h2> <a name="receiving"> Address rewriting when mail is received</a>
</h2>

<p> The cleanup(8) server receives mail from outside of Postfix as
well as mail from internal sources such as forwarded mail,
undeliverable mail that is bounced to the sender, and postmaster
notifications about problems with the mail system.  </p>

<p> The cleanup(8) server transforms the sender, recipients and
message content into a standard form before writing it to an incoming
queue file. The server cleans up sender and recipient addresses in
message headers and in the envelope, adds missing message headers
such as From: or Date: that are required by mail standards, and
removes message headers such as Bcc: that should not be present.
The cleanup(8) server delegates the more complex address manipulations
to the trivial-rewrite(8) server as described later in this document.
</p>

<p> Address manipulations at this stage are:  </p>

<ul>

<li> <a href="#standard"> Rewrite addresses to standard form</a>

<li> <a href="#canonical"> Canonical address mapping</a>

<li> <a href="#masquerade"> Address masquerading</a>

<li> <a href="#auto_bcc"> Automatic BCC recipients</a>

<li> <a href="#virtual"> Virtual aliasing </a>

</ul>

<h3> <a name="standard"> Rewrite addresses to standard form</a> </h3>

<p> Before the cleanup(8) daemon runs an address through any address
mapping lookup table, it first rewrites the address to the standard
"user@fully.qualified.domain" form, by sending the address to the
trivial-rewrite(8) daemon.  The purpose of rewriting to standard
form is to reduce the number of entries needed in lookup tables.
</p>

<p> The Postfix trivial-rewrite(8) daemon implements the following
hard-coded address manipulations: </p>

<blockquote>

<dl>

<dt>Rewrite "@hosta,@hostb:user@site" to "user@site"</dt>

<dd> <p> In case you wonder what this is, the address form above
is called a route address, and specifies that mail for "user@site"
be delivered via "hosta" and "hostb". Usage of this form has been
deprecated for a long time.  Postfix has no ability to handle route
addresses, other than to strip off the route part.  </p>

<p> NOTE: Postfix versions 2.2 and later rewrite message headers
from remote SMTP clients only if the client matches the
local_header_rewrite_clients parameter, or if the
remote_header_rewrite_domain configuration parameter specifies a
non-empty value. To get the behavior before Postfix 2.2, specify
"local_header_rewrite_clients = static:all".  </p> </dd>

<dt>Rewrite "site!user" to "user@site" </dt>

<dd> <p> This feature is controlled by the boolean swap_bangpath
parameter (default: yes).  The purpose is to rewrite UUCP-style
addresses to domain style. This is useful only when you receive
mail via UUCP, but it probably does not hurt otherwise. </p>

<p> NOTE: Postfix versions 2.2 and later rewrite message headers
from remote SMTP clients only if the client matches the
local_header_rewrite_clients parameter, or if the
remote_header_rewrite_domain configuration parameter specifies a
non-empty value. To get the behavior before Postfix 2.2, specify
"local_header_rewrite_clients = static:all".  </p> </dd>

<dt>Rewrite "user%domain" to "user@domain"</dt>

<dd> <p> This feature is controlled by the boolean allow_percent_hack
parameter (default: yes). Typically, this is used in order to deal
with monstrosities such as "user%domain@otherdomain". </p>

<p> NOTE: Postfix versions 2.2 and later rewrite message headers
from remote SMTP clients only if the client matches the
local_header_rewrite_clients parameter, or if the
remote_header_rewrite_domain configuration parameter specifies a
non-empty value. To get the behavior before Postfix 2.2, specify
"local_header_rewrite_clients = static:all".  </p> </dd>

<dt>

Rewrite "user" to "user@$myorigin" </dt>

<dd> <p> This feature is controlled by the boolean append_at_myorigin
parameter (default: yes).  You should never turn off this feature,
because a lot of Postfix components expect that all addresses have
the form "user@domain".  </p>

<p> NOTE: Postfix versions 2.2 and later rewrite message headers
from remote SMTP clients only if the client matches the
local_header_rewrite_clients parameter; otherwise they append the
domain name specified with the remote_header_rewrite_domain
configuration parameter, if one is specified. To get the behavior
before Postfix 2.2, specify "local_header_rewrite_clients =
static:all". </p>

<p> If your machine is not the main machine for $myorigin and you
wish to have some users delivered locally without going via that
main machine, make an entry in the <a href="#virtual">virtual
alias</a> table that redirects "user@$myorigin" to
"user@$myhostname". See also the "delivering some
users locally" section in the STANDARD_CONFIGURATION_README
document. </p> </dd>

<dt>

Rewrite "user@host" to "user@host.$mydomain" </dt>

<dd> <p> This feature is controlled by the boolean append_dot_mydomain
parameter (default: yes).  The purpose is to get consistent treatment
of different forms of the same hostname. </p>

<p> NOTE: Postfix versions 2.2 and later rewrite message headers
from remote SMTP clients only if the client matches the
local_header_rewrite_clients parameter; otherwise they append the
domain name specified with the remote_header_rewrite_domain
configuration parameter, if one is specified. To get the behavior
before Postfix 2.2, specify "local_header_rewrite_clients =
static:all". </p>

<p> Some will argue that rewriting "host" to "host.domain"
is bad. That is why it can be turned off. Others like the convenience
of having Postfix's own domain appended automatically. </p> </dd>

<dt>Rewrite "user@site." to "user@site" (without the trailing dot).</dt>

<dd> <p> A single trailing dot is silently removed. However, an
address that ends in multiple dots will be rejected as an invalid
address. </p>

<p> NOTE: Postfix versions 2.2 and later rewrite message headers
from remote SMTP clients only if the client matches the
local_header_rewrite_clients parameter, or if the
remote_header_rewrite_domain configuration parameter specifies a
non-empty value. To get the behavior before Postfix 2.2, specify
"local_header_rewrite_clients = static:all".  </p> </dd>

</dl>

</blockquote>

<h3> <a name="canonical"> Canonical address mapping </a> </h3>

<p> The cleanup(8) daemon uses the canonical(5) tables to rewrite
addresses in message envelopes and in message headers.  By default
all header and envelope addresses are rewritten; this is controlled
with the canonical_classes configuration parameter.  </p>

<p> NOTE: Postfix versions 2.2 and later rewrite message headers
from remote SMTP clients only if the client matches the
local_header_rewrite_clients parameter, or if the
remote_header_rewrite_domain configuration parameter specifies a
non-empty value. To get the behavior before Postfix 2.2, specify
"local_header_rewrite_clients = static:all".  </p>

<p> Address rewriting is
done for local and remote addresses.  The mapping is useful to
replace login names by "Firstname.Lastname" style addresses, or to
clean up invalid domains in mail addresses produced by legacy mail
systems. </p>

<p> Canonical mapping is disabled by default. To enable, edit the
canonical_maps parameter in the main.cf file and specify one or
more lookup tables, separated by whitespace or commas. </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    canonical_maps = hash:/etc/postfix/canonical

/etc/postfix/canonical:
    wietse        Wietse.Venema
</pre>
</blockquote>

<p> For static mappings as shown above, lookup tables such as hash:,
ldap:, mysql:  or pgsql: are sufficient. For dynamic mappings you
can use regular expression tables. This requires that you become
intimately familiar with the ideas expressed in regexp_table(5),
pcre_table(5) and canonical(5).  </p>

<p> In addition to the canonical maps which are applied to both sender
and recipient addresses, you can specify canonical maps that are
applied only to sender addresses or to recipient addresses. </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    sender_canonical_maps = hash:/etc/postfix/sender_canonical
    recipient_canonical_maps = hash:/etc/postfix/recipient_canonical
</pre>
</blockquote>

<p> The sender and recipient canonical maps are applied before the
common canonical maps. The sender_canonical_classes and
recipient_canonical_classes parameters control what addresses are
subject to sender_canonical_maps and recipient_canonical_maps
mappings, respectively. </p>

<p> Sender-specific rewriting is useful when you want to rewrite
ugly sender addresses to pretty ones, and still want to be able to
send mail to the those ugly address without creating a mailer loop.
</p>

<p> Canonical mapping can be turned off selectively for mail received
by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf settings
in the master.cf file.  This feature is available in Postfix version
2.1 and later.  </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/master.cf:
    127.0.0.1:10026    inet  n      -      n      -      -     smtpd
        -o receive_override_options=no_address_mappings
</pre>
</blockquote>

<p> Note: do not specify whitespace around the "=" here. </p>

<h3> <a name="masquerade"> Address masquerading </a> </h3>

<p> Address masquerading is a method to hide hosts inside a domain
behind their mail gateway, and to make it appear as if the mail
comes from the gateway itself, instead of from individual machines.
</p>

<p> NOTE: Postfix versions 2.2 and later rewrite message headers
from remote SMTP clients only if the client matches the
local_header_rewrite_clients parameter, or if the
remote_header_rewrite_domain configuration parameter specifies a
non-empty value. To get the behavior before Postfix 2.2, specify
"local_header_rewrite_clients = static:all".  </p>

<p> Address masquerading is disabled by default, and is implemented
by the cleanup(8) server. To enable, edit the masquerade_domains
parameter in the main.cf file and specify one or more domain names
separated by whitespace or commas.  When Postfix tries to masquerade
a domain, it processes the list from left to right, and processing
stops at the first match.  </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    masquerade_domains = foo.example.com example.com
</pre>
</blockquote>

<p> strips "any.thing.foo.example.com" to "foo.example.com", but
strips "any.thing.else.example.com" to "example.com". </p>

<p> A domain name prefixed with "<tt>!</tt>" means do not masquerade
this domain or its subdomains: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    masquerade_domains = !foo.example.com example.com
</pre>
</blockquote>

<p> does not change "any.thing.foo.example.com" and "foo.example.com",
but strips "any.thing.else.example.com" to "example.com". </p>

<p> The masquerade_exceptions configuration parameter specifies
what user names should not be subjected to address masquerading.
Specify one or more user names separated by whitespace or commas.
</p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    masquerade_exceptions = root
</pre>
</blockquote>

<p> By default, Postfix makes no exceptions. </p>

<p> Subtle point: by default, address masquerading is applied only to
message headers and to envelope sender addresses, but not to envelope
recipients. This allows you to use address masquerading on a mail
gateway machine, while still being able to forward mail from outside
to users on individual machines. </p>

<p> In order to subject envelope recipient addresses to masquerading,
too, specify (Postfix version 1.1 and later):</p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    masquerade_classes = envelope_sender, envelope_recipient,
        header_sender, header_recipient
</pre>
</blockquote>

<p> If you rewrite the envelope recipient like this, Postfix will
no longer be able to send mail to individual machines. </p>

<p> Address masquerading can be turned off selectively for mail
received by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf
settings in the master.cf file.  This feature is available in
Postfix version 2.1 and later. </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/master.cf:
    127.0.0.1:10026    inet  n      -      n      -      -     smtpd
        -o receive_override_options=no_address_mappings
</pre>
</blockquote>

<p> Note: do not specify whitespace around the "=" here. </p>

<h3> <a name="auto_bcc"> Automatic BCC recipients</a> </h3>

<p> After applying the canonical and masquerade mappings, the
cleanup(8) daemon can generate optional BCC (blind carbon-copy)
recipients. Postfix provides three mechanisms: </p>

<blockquote>

<dl>

<dt> always_bcc = address </dt> <dd> Deliver a copy of all mail to
the specified address. In Postfix versions before 2.1, this feature
is implemented by smtpd(8), qmqpd(8), or pickup(8). </dd>

<dt> sender_bcc_maps = type:table  </dt> <dd> Search the specified
"type:table" lookup table with the envelope sender address for an
automatic BCC address. This feature is available in Postfix 2.1
and later. </dd>

<dt> recipient_bcc_maps = type:table  </dt> <dd> Search the specified
"type:table" lookup table with the envelope recipient address for
an automatic BCC address. This feature is available in Postfix 2.1
and later. </dd>

</dl>

</blockquote>

<p> Note: automatic BCC recipients are produced only for new mail.
To avoid mailer loops, automatic BCC recipients are not generated
for mail that Postfix forwards internally, nor for mail that Postfix
generates itself. </p>

<p> Automatic BCC recipients (including always_bcc) can be turned
off selectively for mail received by smtpd(8), qmqpd(8), or pickup(8),
by overriding main.cf settings in the master.cf file.  This feature
is available in Postfix version 2.1 and later. </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/master.cf:
    127.0.0.1:10026    inet  n      -      n      -      -     smtpd
        -o receive_override_options=no_address_mappings
</pre>
</blockquote>

<p> Note: do not specify whitespace around the "=" here. </p>

<h3> <a name="virtual"> Virtual aliasing </a> </h3>

<p> Before writing the recipients to the queue file, the cleanup(8)
daemon uses the optional virtual(5) alias tables to redirect mail
for recipients.  The mapping affects only envelope recipient
addresses; it has no effect on message headers or envelope sender
addresses.  Virtual alias lookups are useful to redirect mail for
virtual alias domains to real user mailboxes, and to redirect mail
for domains that no longer exist.  Virtual alias lookups can also
be used to transform " Firstname.Lastname " back into UNIX login
names, although it seems that local <a href="#aliases">aliases</a>
may be a more appropriate vehicle. See the VIRTUAL_README document
for an overview of methods to host virtual domains with Postfix.
</p>

<p> Virtual aliasing is disabled by default. To enable, edit the
virtual_alias_maps parameter in the main.cf file and
specify one or more lookup tables, separated by whitespace or
commas. </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    virtual_alias_maps = hash:/etc/postfix/virtual

/etc/postfix/virtual:
    Wietse.Venema        wietse
</pre>
</blockquote>

<p> Addresses found in virtual alias maps are subjected to another
iteration of virtual aliasing, but are not subjected to canonical
mapping, in order to avoid loops. </p>

<p> For static mappings as shown above, lookup tables such as hash:,
ldap:, mysql: or pgsql: are sufficient. For dynamic mappings you
can use regular expression tables. This requires that you become
intimately familiar with the ideas expressed in regexp_table(5),
pcre_table(5) and virtual(5).  </p>

<p> Virtual aliasing can be turned off selectively for mail received
by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf settings
in the master.cf file.  This feature is available in Postfix version
2.1 and later. </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/master.cf:
    127.0.0.1:10026    inet  n      -      n      -      -     smtpd
        -o receive_override_options=no_address_mappings
</pre>
</blockquote>

<p> Note: do not specify whitespace around the "=" here. </p>

<p> At this point the message is ready to be stored into the
Postfix incoming queue. </p>

<h2> <a name="delivering"> Address rewriting when mail is delivered</a> </h2>

<p> The Postfix queue manager sorts mail according to its destination
and gives it to Postfix delivery agents such as local(8), smtp(8),
or lmtp(8). Just like the cleanup(8) server, the Postfix queue
manager delegates the more complex address manipulations to the
trivial-rewrite(8) server. </p>

<p> Address manipulations at this stage are:  </p>

<ul>

<li> <a href="#resolve"> Resolve address to destination </a>

<li> <a href="#transport"> Mail transport switch</a>

<li> <a href="#relocated"> Relocated users table</a>

</ul>

<p> Each Postfix delivery agent tries to deliver the mail to its
destination, while encapsulating the sender, recipients, and message
content according to the rules of the SMTP, LMTP, etc.  protocol.
When mail cannot be delivered, it is either returned to the sender
or moved to the deferred queue and tried again later.  </p>

<p> <a name="remote">Address</a> manipulations when mail is delivered
via the smtp(8) delivery agent: </p>

<ul>

<li> <a href="#generic"> Generic mapping for outgoing SMTP mail </a>

</ul>

<p> <a name="local">Address</a> manipulations when mail is delivered
via the local(8) delivery agent: </p>

<ul>

<li> <a href="#aliases"> Local alias database</a>

<li> <a href="#forward"> Local per-user .forward files</a>

<li> <a href="#luser_relay"> Local catch-all address</a>

</ul>

<p> The remainder of this document presents each address manipulation
step in more detail, with specific examples or with pointers to
documentation with examples. </p>

<h3> <a name="resolve"> Resolve address to destination </a> </h3>

<p> The Postfix qmgr(8) queue manager selects new mail from the
incoming queue or old mail from the deferred queue, and asks the
trivial-rewrite(8) address rewriting and resolving daemon where it
should be delivered. </p>

<p> As of version 2.0, Postfix distinguishes four major address
classes. Each class has its own list of domain names, and each
class has its own default delivery method, as shown in the table
below.  See the ADDRESS_CLASS_README document for the fine details.
Postfix versions before 2.0 only distinguish between local delivery
and everything else.  </p>

<blockquote>

<table border="1">

<tr><th align="left">Destination domain list </th> <th
align="left">Default delivery method </th> <th>Availability
</th> </tr>

<tr><td>$mydestination, $inet_interfaces, $proxy_interfaces </td>
<td>$local_transport </td> <td>Postfix 1.0</td></tr>

<tr><td>$virtual_mailbox_domains </td> <td>$virtual_transport </td>
<td>Postfix 2.0</td> </tr>

<tr><td>$relay_domains </td> <td>$relay_transport </td> <td>Postfix
2.0</td> </tr>

<tr><td>none </td> <td>$default_transport </td> <td>Postfix 1.0</td>
</tr>

</table>

</blockquote>

<h3> <a name="transport"> Mail transport switch </a> </h3>

<p> Once the trivial-rewrite(8) daemon has determined a default
delivery method it searches the optional transport(5) table for
information that overrides the message destination and/or delivery
method.  Typical use of the transport(5) table is to send mail to
a system
that is not connected to the Internet, or to use a special SMTP
client configuration for destinations that have special requirements.
See, for example, the STANDARD_CONFIGURATION_README and UUCP_README
documents, and the examples in the transport(5) manual page.  </p>

<p> Transport table lookups are disabled by default. To enable,
edit the transport_maps parameter in the main.cf file and specify
one or more lookup tables, separated by whitespace or commas. </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    transport_maps = hash:/etc/postfix/transport
</pre>
</blockquote>

<h3> <a name="relocated"> Relocated users table </a> </h3>

<p> Next, the trivial-rewrite(8) address rewriting and resolving
daemon runs each recipient through the relocated(5) database.  This
table provides information on how to reach users that no longer
have an account, or what to do with mail for entire domains that
no longer exist.  When mail is sent to an address that is listed
in this table, the message is returned to the sender with an
informative message.  </p>

<p> The relocated(5) database is searched after transport(5)
table lookups, in anticipation of transport(5) tables that
can replace one recipient address by a different one. </p>

<p> Lookups of relocated users are disabled by default. To enable,
edit the relocated_maps parameter in the main.cf file and specify
one or more lookup tables, separated by whitespace or commas. </p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    relocated_maps = hash:/etc/postfix/relocated

/etc/postfix/relocated:
    username@example.com      otheruser@elsewhere.tld
</pre>
</blockquote>

<p> As of Postfix version 2, mail for a relocated user will be
rejected by the SMTP server with the reason "user has moved to
otheruser@elsewhere.tld". Older Postfix versions will receive the
mail first, and then return it to the sender as undeliverable, with
the same reason.  </p>

<h3> <a name="generic"> Generic mapping for outgoing SMTP mail </a> </h3>

<p> Some hosts have no valid Internet domain name, and instead use
a name such as <i>localdomain.local</i>. This can be a problem when
you want to send mail over the Internet, because many mail servers
reject mail addresses with invalid domain names. </p>

<p> With the smtp_generic_maps parameter you can specify generic(5)
lookup tables that replace local mail addresses by valid Internet
addresses when mail leaves the machine via SMTP. The generic(5)
mapping replaces envelope and header addresses, and is non-recursive.
It does not happen when you send mail between addresses on the
local machine. </p>

<p> This feature is available in Postfix version 2.2 and later.</p>

<p> Example: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    smtp_generic_maps = hash:/etc/postfix/generic

/etc/postfix/generic:
    his@localdomain.local		hisaccount@hisisp.example
    her@localdomain.local		heraccount@herisp.example
    @localdomain.local			hisaccount+local@hisisp.example
</pre>
</blockquote>

<p> When mail is sent to a remote host via SMTP, this replaces
<i>his@localdomain.local</i> by his ISP mail address, replaces
<i>her@localdomain.local</i> by her ISP mail address, and replaces
other local addresses by his ISP account, with an address extension
of +<i>local</i> (this example assumes that the ISP supports "+"
style address extensions).  </p>

<h3> <a name="aliases"> Local alias database </a> </h3>

<p> When mail is to be delivered locally, the local(8) delivery
agent runs each local recipient name through the aliases(5) database.
The mapping does not affect addresses in message headers. Local
aliases are typically used to implement distribution lists, or to
direct mail for standard aliases such as postmaster to real people.
The table can also be used to map "Firstname.Lastname" addresses
to login names. </p>

<p> Alias lookups are enabled by default. The default configuration
depends on the operating system environment, but it is typically
one of the following: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    alias_maps = hash:/etc/aliases
    alias_maps = dbm:/etc/aliases, nis:mail.aliases
</pre>
</blockquote>

<p> The pathname of the alias database file is controlled with the
alias_database configuration parameter. The value is system dependent.
Usually it is one of the following: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    alias_database = hash:/etc/aliases (4.4BSD, LINUX)
    alias_database = dbm:/etc/aliases (4.3BSD, SYSV&lt;4)
    alias_database = dbm:/etc/mail/aliases (SYSV4)
</pre>
</blockquote>

<p> An aliases(5) file can specify that mail should be delivered
to a local file, or to a command that receives the message in the
standard input stream.  For security reasons, deliveries to command
and file destinations are performed with the rights of the alias
database owner.  A default userid, default_privs, is used for
deliveries to commands or files in "root"-owned aliases. </p>

<h3> <a name="forward"> Local per-user .forward files </a> </h3>

<p> With delivery via the local(8) deliver agent, users can control
their own mail delivery by specifying destinations in a file called
.forward in their home directories. The syntax of these files is
the same as with the local aliases(5) file, except that the left-hand
side of the alias (lookup key and colon) are not present. </p>

<h3> <a name="luser_relay"> Local catch-all address </a> </h3>

<p> When the local(8) delivery agent finds that a message recipient
does not exist, the message is normally returned to the sender ("user
unknown").  Sometimes it is desirable to forward mail for non-existing
recipients to another machine.  For this purpose you can specify
an alternative destination with the luser_relay configuration
parameter. </p>

<p> Alternatively, mail for non-existent recipients can be delegated
to an entirely different message transport, as specified with the
fallback_transport configuration parameter. For details, see the
local(8) delivery agent documentation. </p>

<p> Note: if you use the luser_relay feature in order to receive
mail for non-UNIX accounts, then you must specify: </p>

<blockquote>
<pre>
/etc/postfix/main.cf:
    local_recipient_maps =
</pre>
</blockquote>

<p> (i.e. empty) in the main.cf file, otherwise the Postfix SMTP
server will reject mail for non-UNIX accounts with "User unknown
in local recipient table". See the LOCAL_RECIPIENT_README file
for more information on this.
</p>

<p> luser_relay can specify one address. It is subjected to "$name"
expansions. Examples: </p>

<blockquote>

<dl>

<dt>$user@other.host </dt>

<dd> <p> The bare username, without address extension, is prepended
to "@other.host". For example, mail for "username+foo" is sent to
"username@other.host". </p> </dd>

<dt>$local@other.host </dt>

<dd> <p> The entire original recipient localpart, including address
extension, is prepended to "@other.host". For example, mail for
"username+foo" is sent to "username+foo@other.host". </p> </dd>

<dt>sysadmin+$user </dt>

<dd> <p> The bare username, without address extension, is appended
to "sysadmin". For example, mail for "username+foo" is sent to
"sysadmin+username". </p> </dd>

<dt>sysadmin+$local </dt>

<dd> <p> The entire original recipient localpart, including address
extension, is appended to "sysadmin". For example, mail for
"username+foo" is sent to "sysadmin+username+foo". </p> </dd>

</dl>

</blockquote>

<h2> <a name="debugging"> Debugging your address manipulations </a> </h2>

<p> Postfix version 2.1 and later can
produce mail delivery reports for debugging purposes. These reports
not only show sender/recipient addresses after address rewriting
and alias expansion or forwarding, they also show information about
delivery to mailbox, delivery to non-Postfix command, responses
from remote SMTP servers, and so on.  </p>

<p> Postfix can produce two types of mail delivery reports for
debugging: </p>

<ul>

<li> <p> What-if: report what would happen, but do not actually
deliver mail. This mode of operation is requested with: </p>

<pre>
$ <b>/usr/sbin/sendmail -bv address...</b>
Mail Delivery Status Report will be mailed to &lt;your login name&gt;.
</pre>

<li> <p> What happened: deliver mail and report successes and/or
failures, including replies from remote SMTP servers.  This mode
of operation is requested with: </p>

<pre>
$ <b>/usr/sbin/sendmail -v address...</b>
Mail Delivery Status Report will be mailed to &lt;your login name&gt;.
</pre>

</ul>

<p> These reports contain information that is generated by Postfix
delivery agents. Since these run as daemon processes and do not
interact with users directly, the result is sent as mail to the
sender of the test message. The format of these reports is practically
identical to that of ordinary non-delivery notifications. </p>

<p> As an example, below is the delivery report that is produced
with the command "sendmail -bv postfix-users@postfix.org".  The
first part of the report contains human-readable text. In this
case, mail would be delivered via mail.cloud9.net, and the SMTP
server replies with "250 Ok". Other reports may show delivery
to mailbox, or delivery to non-Postfix command. </p>

<blockquote>
<pre>
Content-Description: Notification
Content-Type: text/plain

This is the mail system at host spike.porcupine.org.

Enclosed is the mail delivery report that you requested.

                        The mail system

&lt;postfix-users@postfix.org&gt;: delivery via mail.cloud9.net[168.100.1.4]: 250 2.1.5 Ok
</pre>
</blockquote>

<p> The second part of the report is in machine-readable form, and
includes the following information: </p>

<ul>

<li> The envelope sender address (wietse@porcupine.org).

<li> The envelope recipient address (postfix-users@postfix.org).
If the recipient address was changed by Postfix then Postfix also
includes the original recipient address.

<li> The delivery status.

</ul>

<p> Some details depend on Postfix version. The example below is
for Postfix version 2.3 and later. </p>

<blockquote>
<pre>
Content-Description: Delivery report
Content-Type: message/delivery-status

Reporting-MTA: dns; spike.porcupine.org
X-Postfix-Queue-ID: 84863BC0E5
X-Postfix-Sender: rfc822; wietse@porcupine.org
Arrival-Date: Sun, 26 Nov 2006 17:01:01 -0500 (EST)

Final-Recipient: rfc822; postfix-users@postfix.org
Action: deliverable
Status: 2.1.5
Remote-MTA: dns; mail.cloud9.net
Diagnostic-Code: smtp; 250 2.1.5 Ok
</pre>
</blockquote>

<p> The third part of the report contains the message that Postfix
would have delivered, including From:  and To: message headers, so
that you can see any effects of address rewriting on those. Mail
submitted with "sendmail -bv" has no body content so none is shown
in the example below. </p>

<blockquote>
<pre>
Content-Description: Message
Content-Type: message/rfc822

Received: by spike.porcupine.org (Postfix, from userid 1001)
        id 84863BC0E5; Sun, 26 Nov 2006 17:01:01 -0500 (EST)
Subject: probe
To: postfix-users@postfix.org
Message-Id: &lt;20061126220101.84863BC0E5@spike.porcupine.org&gt;
Date: Sun, 26 Nov 2006 17:01:01 -0500 (EST)
From: wietse@porcupine.org (Wietse Venema)
</pre>
</blockquote>

</body>

</html>