Postfix
Address Rewriting

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:

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

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.

Replace an address by multiple addresses. For example,
replace the address of an alias by the addresses listed under that
alias.

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

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.

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.

The table below summarizes all Postfix address manipulations.
If you're reading this document for the first time, skip forward
to "Address
rewriting when mail is received". Once you've finished reading
the remainder of this document, the table will help you to quickly
find what you need.

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.

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.

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.

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

Rewrite "@hosta,@hostb:user@site" to "user@site"

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.

Rewrite "site!user" to "user@site"

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.

Rewrite "user%domain" to "user@domain"

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

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

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 virtual
alias table that redirects "user@$myorigin" to
"user@$myhostname". See also the "delivering some
users locally" section in the STANDARD_CONFIGURATION_README
document.

The cleanup(8) daemon uses the canonical(5) tables to rewrite
all addresses in message envelopes and in message headers. This 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.

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.

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

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.

The sender and recipient canonical maps are applied before the
common canonical maps.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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 aliases
may be a more appropriate vehicle. See the VIRTUAL_README document
for an overview of methods to host virtual domains with Postfix.

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.

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.

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

Note: automatic BCC recipients are produced only for new mail.
To avoid mailer loops, automatic BCC recipients are not generated
for mail that is forwarded internally, and are not generated for
mail that is generated by Postfix itself.

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.

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.

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.

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.

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

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.

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.

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.

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.

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

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.

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

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.

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.

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

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

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

$user@other.host

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

$local@other.host

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

sysadmin+$user

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

sysadmin+$local

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

With Postfix version 2.1 and later you can ask Postfix to
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.

Postfix can produce two types of mail delivery reports for
debugging:

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

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.

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.

Content-Description: Notification
Content-Type: text/plain
This is the Postfix program at host spike.porcupine.org.
Enclosed is the mail delivery report that you requested.
The Postfix program
<postfix-users@postfix.org>: delivery via mail.cloud9.net[168.100.1.4]: 250 Ok

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

The envelope sender address (wietse@porcupine.org).

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

The delivery status.

Some details are still preliminary and will change as Postfix
implements the DSN (delivery status notification) standards.

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.