Table of Contents for

Postfix: The Definitive Guide

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
#
pabelard@example.com   peter.abelard@example.com
hfulbert@example.com   heloise.fulbert@example.com

They can also rewrite addresses completely.

#
# /etc/postfix/canonical
#
pabelard@example.com   abelard@oreilly.com
hfulbert@example.com   heloise@oreilly.com

In main.cf, 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 main.cf:

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

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 = example.com

Addresses that look like heloise@server1.example.com and frank@server2.example.com are converted to heloise@example.com and frank@example.com.

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, acct.example.com and hr.example.com. 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 = acct.example.com hr.example.com example.com

With this setting, the address heloise@sys3.acct.example.com matches acct.example.com, so that it becomes heloise@acct.example.com. The address frank@db.hr.example.com matches hr.example.com, and becomes frank@hr.example.com. Finally, helene@server1.example.com matches the last value, example.com, to become helene@example.com.

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 = !it.example.com, example.com

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

You can exclude specific account names from masquerading. For example, if you want an address like root@db.example.com 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 kdent@server1.example.com once it has been rewritten as kdent@example.com.

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:

kdent@ora.com      kdent@oreilly.com
heloise@ora.com    hfulbert@oreilly.com
@example.com       oreilly.com

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

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.