diff options
Diffstat (limited to '')
| -rw-r--r-- | proto/ADDRESS_REWRITING_README.html | 1246 |
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> >- </tt> +</td> + +<td rowspan="3" bgcolor="#f0f0ff" align="center"> cleanup(8) </td> + +<td rowspan="3" align="center" valign="middle"> <tt> -> </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> -> </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> -> </tt> +</td> + +<td rowspan="3" bgcolor="#f0f0ff" align="center"> qmgr(8) </td> + +<td rowspan="3" align="center" valign="middle"> <tt> -< </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<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 <your login name>. +</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 <your login name>. +</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 + +<postfix-users@postfix.org>: 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: <20061126220101.84863BC0E5@spike.porcupine.org> +Date: Sun, 26 Nov 2006 17:01:01 -0500 (EST) +From: wietse@porcupine.org (Wietse Venema) +</pre> +</blockquote> + +</body> + +</html> |