Rewriting Addresses

Postfix tries to make sense of addresses in email and writes them using the standard RFC 2822 format. Certain address rewriting occurs automatically.

You saw earlier in the chapter how Postfix appends myorigin to a local name that has no domain part. Postfix also appends the value of mydomain to addresses that include only the host portion without the domain name. This fixes addresses that look like kdent@host so they become

Canonical Addresses

Postfix provides another type of address rewriting that lets you map disparate addresses into a standard format for your entire site. The canonical_maps parameter points to a lookup table of address mappings. (While the word canonical has many meanings, among computer professionals it means “the usual, standard, or normal.”) If different mail systems on your network create addresses in different ways, you can relay them all through your Postfix gateway and have it fix up the addresses into your standard format. Canonical maps are often used to change addresses from an internal format to a public one. Include entries like the following in your canonical table:

# /etc/postfix/canonical

They can also rewrite addresses completely.

# /etc/postfix/canonical

In, point the canonical_maps parameter to the canonical file:

canonical_maps = hash:/etc/postfix/canonical

Be sure to execute postmap against your canonical file and reload Postfix so that it recognizes your changes to

# postmap /etc/postfix/canonical
# postfix reload

The canonical_maps parameter affects all of the addresses, including envelope and message headers. If Postfix finds a match, it makes the change. If you want your changes to affect only sender or recipient addresses, Postfix provides the additional parameters sender_canonical_maps and recipient_canonical_maps. They both work the same as canonical_maps, but only on their respective classes of addresses. If you use either of these two parameters in addition to canonical_maps, Postfix first fixes the addresses according to sender_canonical_maps and recipient_canonical_maps, and then canonical_maps.

Masquerading Hostnames

Address masquerading refers to the idea that you can hide the names of internal hosts, and make all addresses appear as if they originated from the gateway system itself. You may have internal systems that use your Postfix server as a gateway. When mail is sent from these systems and the sender addresses include the fully qualified hostname, you may want addresses to appear with the domain name only. The masquerade_domains parameter strips hostnames down to their simpler domain names.

The parameter takes a list of domains. Any address whose fully qualified hostname matches the domain portion is stripped down to just the domain name:

masquerade_domains =

Addresses that look like and are converted to and

You can list multiple domains and subdomains. Postfix processes addresses against masquerade domain names in the order you list them. Consider a network that includes the two subdomains, and You want addresses from these domains to show the subdomain, but you want addresses from any other domain or host in the network to show the parent domain. Set masquerade_domains as follows:

masquerade_domains =

With this setting, the address matches, so that it becomes The address matches, and becomes Finally, matches the last value,, to become

If you want to preserve a domain name that would otherwise be stripped down, you can preface the domain with an exclamation point:

masquerade_domains = !,

In this case, the domain will not be rewritten, so the address stays as it is.

You can exclude specific account names from masquerading. For example, if you want an address like to stay intact, add the account to the masquerade_exceptions parameter:

masquerade_exceptions = admin, root

When you use masquerading, it is normally applied to all envelope and header addresses but not envelope recipient addresses. This allows mail addressed to a specific host to be delivered from the mail gateway to that particular system, while still rewriting addresses for messages sent from the host. If you prefer to have all addresses masqueraded, set the masquerade_classes parameter to include the complete list of address classes recognized by Postfix:

masquerade_classes = envelope_recipient, envelope_sender,
        header_sender, header_recipient

Be aware that if you set masquerade_classes this way, a gateway mail system may no longer know where to deliver a message that was originally addressed to once it has been rewritten as

Relocated Users

The relocated_maps parameter points to a lookup table where you can store a list of addresses or domains that have moved to another location:

relocated_maps = hash:/etc/postfix/relocated

The lookup table uses the old address as the key and its new location as the value. When a message is delivered to a relocated address, Postfix rejects the delivery attempt with a message that includes the user’s new address as specified in the lookup table. You can also list just a domain name to have all recipients at that domain rejected with your specified message.

The file /etc/postfix/relocated contains entries like:

Messages sent to either or are rejected with an error message that gives their respective new addresses. Any messages sent to are rejected regardless of what the local part is. The message reports that the address has moved to

Unknown Users

A local address that is not listed in relocated or other maps, and is not an account on the system is an unknown user. Normally, when Postfix receives mail for an unknown user, it rejects it. If you prefer to capture all of the messages sent to nonexistent accounts, you can use the luser_relay parameter. Set it to any email address to have messages destined for unknown users sent to the address you provide. You must also set local_recipient_maps to blank to prevent Postfix from rejecting mail for unknown users:

luser_relay = catchall
local_recipient_maps =

Assuming catchall is a legitimate address (alias or user account) on your system, it will receive all messages sent to nonexistent users. Be careful when using luser_relay, since spammers often launch dictionary attacks, where they try enormous lists of addresses hoping to find a legitimate one at your site. If luser_relay is configured, it will catch all of the spam.

Get Postfix: The Definitive Guide now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.