summaryrefslogtreecommitdiffstats
path: root/proto/ADDRESS_REWRITING_README.html
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--proto/ADDRESS_REWRITING_README.html1246
1 files changed, 1246 insertions, 0 deletions
diff --git a/proto/ADDRESS_REWRITING_README.html b/proto/ADDRESS_REWRITING_README.html
new file mode 100644
index 0000000..82f870c
--- /dev/null
+++ b/proto/ADDRESS_REWRITING_README.html
@@ -0,0 +1,1246 @@
+<!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) delivery 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>