<html> <head> <title> Postfix Configuration - Address Manipulation</title> </head> <body> <h1><a href="big-picture.html"><img src="small-picture.gif" width="115" height="45"></a> Postfix Configuration - Address Manipulation</h1> <hr> <a href="index.html">Up one level</a> | <a href="basic.html"> Basic Configuration</a> | <a href="uce.html">UCE Controls</a> | <a href="rate.html"> Rate Controls</a> | <a href="resource.html"> Resource Controls</a> | Address Manipulation <h2> Introduction</h2> Although the initial Postfix release has no address rewriting language, it can do quite a bit of address manipulation via table lookup. While a message flows through the Postfix system, its addresses are mangled in the order described in this document. <p> Unless indicated otherwise, all parameters described here are in the <b>main.cf</b> file. If you change parameters of a running Postfix system, don't forget to issue a <b>postfix reload</b> command. <p> All mail: <p> <ul> <li> <a href="#standard"> Rewrite addresses to standard form</a> <p> <li> <a href="#canonical"> Canonical address mapping</a> <p> <li> <a href="#masquerade"> Address masquerading</a> <p> <li> <a href="#virtual"> Virtual address mapping</a> <p> <li> <a href="#transport"> Mail transport switch</a> <p> <li> <a href="#relocated"> Relocated users table</a> </ul> <p> Local delivery: <p> <ul> <li> <a href="#aliases"> Alias database</a> <p> <li> <a href="#forward"> Per-user .forward files</a> <p> <li> <a href="#luser_relay"> Non-existent users</a> </ul> <a name="standard"> <h2> Rewrite addresses to standard form</h2> Before the <a href="cleanup.8.html">cleanup</a> daemon runs an address through any lookup table, it first rewrites the address to the standard <i>user@fully.qualified.domain</i> form, by sending the address to the <a href="trivial-rewrite.8.html">trivial-rewrite</a> daemon. The purpose of rewriting to standard form is to reduce the number of entries needed in lookup tables. The Postfix <a href="trivial-rewrite.8.html">trivial-rewrite </a> program implements the following hard-coded address manipulations: <dl> <dt>Rewrite <i>@hosta,@hostb:user@site</i> to <i>user@site</i> <dd>The source route feature has been deprecated. Postfix has no ability to handle such addresses, other than to strip off the source route. <p> <a name="swap_bangpath"> <dt>Rewrite <i>site!user</i> to <i>user@site</i> <dd> This feature is controlled by the boolean <b>swap_bangpath</b> parameter (default: <b>yes</b>). The purpose is to rewrite <b>UUCP</b>-style addresses to domain style. This is useful only when you receive mail via <b>UUCP</b>, but it probably does not hurt otherwise. <p> <a name="percent_hack"> <dt>Rewrite <i>user%domain</i> to <i>user@domain</i> <dd> This feature is controlled by the boolean <b>allow_percent_hack</b> parameter (default: <b>yes</b>). Typically, this is used in order to deal with monstrosities such as <i>user%domain@otherdomain</i>. <p> <a name="append_at_myorigin"> <dt>Rewrite <i>user</i> to <i>user@<a href="basic.html#myorigin">$myorigin</a></i> <dd> This feature is controlled by the boolean <b>append_at_myorigin</b> parameter (default: <b>yes</b>). The purpose is to get consistent treatment of <i>user</i> on every machine in <b>$myorigin</b>. <p> You probably should never turn off this feature, because a lot of Postfix components expect that all addresses have the form <i>user@domain</i>. <p> If your machine is not the main machine for <b>$myorigin</b> and you wish to have some users delivered locally without going via that main machine, make an entry in the <a href="#virtual">virtual</a> table that redirects <i>user@$myorigin</i> to <i>user@$myhostname</i>. <p> <a name="append_dot_mydomain"> <dt>Rewrite <i>user@host</i> to <i>user@host.<a href="basic.html#mydomain">$mydomain</a></i> <dd> This feature is controlled by the boolean <b>append_dot_mydomain</b> parameter (default: <b>yes</b>). The purpose is to get consistent treatment of different forms of the same hostname. <p> Some will argue that rewriting <i>host</i> to <i>host.$mydomain</i> is bad. That is why it can be turned off. Others like the convenience of having the local domain appended automatically. <p> <a name="strip_trailing_dot"> <dt>Rewrite <i>user@site.</i> to <i>user@site</i> (without the trailing dot). </dl> <a name="canonical"> <h2> Canonical address mapping</h2> Before the <a href="cleanup.8.html">cleanup</a> daemon stores inbound mail into the <b>incoming</b> queue, it uses the <a href="canonical.5.html">canonical</a> table to rewrite all addresses in message envelopes and in message headers, local or remote. The mapping is useful to replace login names by <i>Firstname.Lastname</i> style addresses, or to clean up invalid domains in mail addresses produced by legacy mail systems. <p> Canonical mapping is disabled by default. To enable, edit the <b> canonical_maps</b> parameter in the <b>main.cf</b> file and specify one or more lookup tables, separated by whitespace or commas. For example: <dl> <dd><b>canonical_maps = hash:/etc/postfix/canonical</b> </dl> <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. For example: <dl> <dd><b>sender_canonical_maps = hash:/etc/postfix/sender_canonical</b> <p> <dd><b>recipient_canonical_maps = hash:/etc/postfix/recipient_canonical</b> </dl> <p> The sender and recipient canonical maps are applied before the common canonical maps. <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. <a name="masquerade"> <h2> Address masquerading</h2> Address masquerading is a method to hide all 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> Address masquerading is disabled by default. To enable, edit the <b>masquerade_domains</b> parameter in the <b>main.cf</b> file and specify one or more domain names separated by whitespace or commas. The list is processed left to right, and processing stops at the first match. Thus, <blockquote> <b>masquerade_domains = foo.example.com example.com</b> </blockquote> strips any.thing.foo.example.com to foo.example.com, but strips any.thing.else.example.com to example.com. <p> A domain name prefixed with ! means do not masquerade this domain or its subdomains. Thus, <blockquote> <b>masquerade_domains = !foo.example.com example.com</b> </blockquote> does not change any.thing.foo.example.com and foo.example.com, but strips any.thing.else.example.com to example.com. <p> The <b>masquerade_exceptions</b> configuration parameter specifies what user names should not be subjected to address masquerading. Specify one or more user names separated by whitespace or commas. For example, <dl> <dd><b>masquerade_exceptions = root</b> </dl> <p> By default, Postfix makes no exceptions. <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> In order to subject envelope recipient addresses to masquerading, too, specify (only available with Postfix versions after 20010802): <dl> <dd><b>masquerade_classes = envelope_sender, envelope_recipient, header_sender, header_recipient</b> </dl> <p> If you do this, Postfix will no longer be able to send mail to individual machines. <a name="virtual"> <h2> Virtual address aliasing</h2> After applying the canonical and masquerade mappings, the <a href="cleanup.8.html">cleanup</a> daemon uses the <a href="virtual.5.html">virtual alias</a> table to redirect mail for all recipients, local or remote. The mapping affects only envelope recipients; it has no effect on message headers or envelope senders. Virtual alias lookups are useful to redirect mail for simulated virtual domains to real user mailboxes, and to redirect mail for domains that no longer exist. Virtual alias lookups can also be used to transform <i> Firstname.Lastname </i> back into UNIX login names, although it seems that local <a href="#aliases">aliases</a> are a more appropriate vehicle. <p> Virtual aliasing is disabled by default. To enable, edit the <b> virtual_alias_maps</b> parameter in the <b>main.cf</b> file and specify one or more lookup tables, separated by whitespace or commas. For example: <dl> <dd><b>virtual_alias_maps = hash:/etc/postfix/virtual</b> </dl> <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. <a name="transport"> <h2> Mail transport switch</h2> Once the address rewriting and resolving daemon has established the destination of a message, it determines the default delivery method for that destination. Postfix distinguishes four major address classes, each with its own default delivery method. <blockquote> <table border="1"> <tr><th align="left">Destination matches<th align="left">Default delivery agent <th align="left">Controlling parameter <tr><td><a href="basic.html#mydestination">$mydestination</a> or <a href="basic.html#inet_interfaces">$inet_interfaces</a> <td><a href="local.8.html">local</a> <td><b>$local_transport</b> <tr><td><b>$virtual_mailbox_domains</b> <td><a href="virtual.8.html">virtual</a> <td><b>$virtual_transport</b> <tr><td><a href="uce.html#relay_domains">$relay_domains</a> <td>relay (clone of <a href="smtp.8.html">smtp</a>) <td><b>$relay_transport</b> <tr><td>none <td><a href="smtp.8.html">smtp</a> <td><b>$default_transport</b> </table> </blockquote> The optional <a href="transport.5.html">transport</a> table overrides the default message delivery method (this table is used by the address rewriting and resolving daemon). The transport table can be used to send mail to specific sites via <b>UUCP</b>, or to send mail to a really broken mail system that can handle only one SMTP connection at a time (yes, such systems exist and people used to pay real money for them). <p> Transport table lookups are disabled by default. To enable, edit the <b>transport_maps</b> parameter in the <b>main.cf</b> file and specify one or more lookup tables, separated by whitespace or commas. For example: <dl> <dd><b>transport_maps = hash:/etc/postfix/transport</b> </dl> <a name="relocated"> <h2> Relocated users table</h2> Next, the address rewriting and resolving daemon runs each recipient name through the <a href="relocated.5.html">relocated</a> 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 bounced with an informative message. <p> Lookups of relocated users are disabled by default. To enable, edit the <b>relocated_maps</b> parameter in the <b>main.cf</b> file and specify one or more lookup tables, separated by whitespace or commas. For example: <dl> <dd><b>relocated_maps = hash:/etc/postfix/relocated</b> </dl> <a name="aliases"> <h2> Alias database</h2> When mail is to be delivered locally, the <a href="local.8.html">local</a> delivery agent runs each local recipient name through the <a href="aliases.5.html"> aliases</a> 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 <b>postmaster</b> to real people. The table can also be used to map <i>Firstname.Lastname</i> addresses to login names. <p> Alias lookups are enabled by default. The default configuration depends on the system environment, but it is typically one of the following: <p> <dl> <dd> <b>alias_maps = hash:/etc/aliases</b> <dd> <b>alias_maps = dbm:/etc/aliases, nis:mail.aliases</b> </dl> <p> The path to the alias database file is controlled via the <b>alias_database</b> configuration parameter. The value is system dependent. Usually it is one of the following: <dl> <dd> <b>alias_database = hash:/etc/aliases</b> (4.4BSD, LINUX) <dd> <b>alias_database = dbm:/etc/aliases</b> (4.3BSD, SYSV<4) <dd> <b>alias_database = dbm:/etc/mail/aliases</b> (SYSV4) </dl> <p> For security reasons, deliveries to command and file destinations are performed with the rights of the alias database owner. A default userid, <b>default_privs</b>, is used for deliveries to commands/files in <i>root</i>-owned aliases. <a name="forward"> <h2> Per-user .forward files</h2> Users can control their own mail delivery by specifying destinations in a file called <b>.forward</b> in their home directories. The syntax of these files is the same as with system aliases, except that the lookup key and colon are not present. <a name="luser_relay"> <h2> Non-existent users</h2> When the local delivery agent finds that a message recipient does not exist, the message is normally bounced 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 <b>luser_relay</b> configuration parameter. <p> Alternatively, mail for non-existent recipients can be delegated to an entirely different message transport, as specified with the <b>fallback_transport</b> configuration parameter. For details, see the <a href="local.8.html"> local</a> delivery agent. <p> Note: if you use the <b>luser_relay</b> feature in order to receive mail for non-UNIX accounts, then you must specify: <blockquote> <pre> <b>local_recipient_maps =</b> </pre> </blockquote> (i.e. empty) in the <b>main.cf</b> file, otherwise the Postfix SMTP server will reject mail for non-UNIX accounts with "User unknown in local recipient table". <p> <b>luser_relay</b> can specify one address. It is subjected to <i>$name</i> expansions. The most useful examples are: <p> <dl> <dt><b>$user@other.host</b> <dd>The bare username, without address extension, is prepended to <i>@other.host</i>. For example, mail for <i>username+foo</i> is sent to <i>username@other.host</i>. <p> <dt><b>$mailbox@other.host</b> <dd>The entire original recipient localpart, including address extension, is prepended to <i>@other.host</i>. For example, mail for <i>username+foo</i> is sent to <i>username+foo@other.host</i>. <p> <dt><b>sysadmin+$user</b> <dd>The bare username, without address extension, is appended to <i>sysadmin</i>. For example, mail for <i>username+foo</i> is sent to <i>sysadmin+username</i>. <dt><b>sysadmin+$mailbox</b> <dd>The entire original recipient localpart, including address extension, is appended to <i>sysadmin</i>. For example, mail for <i>username+foo</i> is sent to <i>sysadmin+username+foo</i>. </dl> <hr> <a href="index.html">Up one level</a> | <a href="basic.html"> Basic Configuration</a> | <a href="uce.html">UCE Controls</a> | <a href="rate.html"> Rate Controls</a> | <a href="resource.html"> Resource Controls</a> | Address Manipulation </body> </html>