Postfix Standard Configuration Examples


Purpose of this document

This document presents a number of typical Postfix configurations. This document should be reviewed after you have followed the basic configuration steps as described in the BASIC_CONFIGURATION_README document. In particular, do not proceed here if you don't already have Postfix working for local mail submission and for local mail delivery.

The first part of this document presents standard configurations that each solve one specific problem.

The second part of this document presents additional configurations for hosts in specific environments.

Postfix on a stand-alone Internet host

Postfix should work out of the box without change on a stand-alone machine that has direct Internet access. At least, that is how Postfix installs when you download the Postfix source code via http://www.postfix.org/.

You can use the command "postconf -n" to find out what settings are overruled by your main.cf. Besides a few pathname settings, few parameters should be set on a stand-alone box, beyond what is covered in the BASIC_CONFIGURATION_README document:

/etc/postfix/main.cf:
    # Optional: send mail as user@domainname instead of user@hostname.
    #myorigin = $mydomain

    # Optional: specify NAT/proxy external address.
    #proxy_interfaces = 1.2.3.4

    # Alternative 1: don't relay mail from other hosts.
    mynetworks_style = host
    relay_domains =

    # Alternative 2: relay mail from local clients only.
    # mynetworks = 192.168.1.0/28
    # relay_domains =

See also the section "Postfix on hosts without a real Internet hostname" if this is applicable to your configuration.

Postfix on a null client

A null client is a machine that can only send mail. It receives no mail from the network, and it does not deliver any mail locally. A null client typically uses POP, IMAP or NFS for mailbox access.

In this example we assume that the Internet domain name is "example.com" and that the machine is named "nullclient.example.com". As usual, the examples show only parameters that are not left at their default settings.

1 /etc/postfix/main.cf:
2     myorigin = $mydomain
3     relayhost = $mydomain
4     inet_interfaces = loopback-only
5     local_transport = error:local delivery is disabled
6 
7 /etc/postfix/master.cf:
8     Comment out the local delivery agent entry

Translation:

Postfix on a local network

This section describes a local area network environment of one main server and multiple other systems that send and receive email. As usual we assume that the Internet domain name is "example.com". All systems are configured to send mail as "user@example.com", and all systems receive mail for "user@hostname.example.com". The main server also receives mail for "user@example.com". We call this machine by the name of mailhost.example.com.

A drawback of sending mail as "user@example.com" is that mail for "root" and other system accounts is also sent to the central mailhost. See the section "Delivering some but not all accounts locally" below for possible solutions.

As usual, the examples show only parameters that are not left at their default settings.

First we present the non-mailhost configuration, because it is the simpler one. This machine sends mail as "user@example.com" and is final destination for "user@hostname.example.com".

1 /etc/postfix/main.cf:
2     myorigin = $mydomain
3     mynetworks = 127.0.0.0/8 10.0.0.0/24
4     relay_domains =
5     # Optional: forward all non-local mail to mailhost
6     #relayhost = $mydomain

Translation:

Next we present the mailhost configuration. This machine sends mail as "user@example.com" and is final destination for "user@hostname.example.com" as well as "user@example.com".

 1 DNS:
 2     example.com    IN    MX  10 mailhost.example.com.
 3 
 4 /etc/postfix/main.cf:
 5     myorigin = $mydomain
 6     mydestination = $myhostname localhost.$mydomain localhost $mydomain
 7     mynetworks = 127.0.0.0/8 10.0.0.0/24
 8     relay_domains =
 9     # Optional: forward all non-local mail to firewall
10     #relayhost = [firewall.example.com]

Translation:

In an environment like this, users access their mailbox in one or more of the following ways:

In the latter case, each user has an alias on the mailhost that forwards mail to her preferred machine:

/etc/aliases:
    joe:    joe@joes.preferred.machine
    jane:   jane@janes.preferred.machine

On some systems the alias database is not in /etc/aliases. To find out the location for your system, execute the command "postconf alias_maps".

Execute the command "newaliases" whenever you change the aliases file.

Postfix email firewall/gateway

The idea is to set up a Postfix email firewall/gateway that forwards mail for "example.com" to an inside gateway machine but rejects mail for "anything.example.com". There is only one problem: with "relay_domains = example.com", the firewall normally also accepts mail for "anything.example.com". That would not be right.

Note: this example requires Postfix version 2.0 and later. To find out what Postfix version you have, execute the command "postconf mail_version".

The solution is presented in multiple parts. This first part gets rid of local mail delivery on the firewall, making the firewall harder to break.

1 /etc/postfix/main.cf:
2     myorigin = example.com
3     mydestination =
4     local_recipient_maps =
5     local_transport = error:local mail delivery is disabled
6 
7 /etc/postfix/master.cf:
8     Comment out the local delivery agent

Translation:

For the sake of technical correctness the firewall must be able to receive mail for postmaster@[firewall ip address]. Reportedly, some things actually expect this ability to exist. The second part of the solution therefore adds support for postmaster@[firewall ip address], and as a bonus we do abuse@[firewall ip address] as well. All the mail to these two accounts is forwarded to an inside address.

1 /etc/postfix/main.cf:
2     virtual_alias_maps = hash:/etc/postfix/virtual
3 
4 /etc/postfix/virtual:
5     postmaster      postmaster@example.com
6     abuse           abuse@example.com

Translation:

The last part of the solution does the email forwarding, which is the real purpose of the firewall email function.

 1 /etc/postfix/main.cf:
 2     mynetworks = 127.0.0.0/8 12.34.56.0/24
 3     relay_domains = example.com
 4     parent_domain_matches_subdomains = 
 5         debug_peer_list smtpd_access_maps
 6     smtpd_recipient_restrictions =
 7         permit_mynetworks reject_unauth_destination
 8 
 9     relay_recipient_maps = hash:/etc/postfix/relay_recipients
10     transport_maps = hash:/etc/postfix/transport
11 
12 /etc/postfix/relay_recipients:
13     user1@example.com   x
14     user2@example.com   x
15      . . .
16 
17 /etc/postfix/transport:
18     example.com   smtp:[inside-gateway.example.com]

Translation:

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m".

Execute the command "postmap /etc/postfix/relay_recipients" whenever you change the relay_recipients table.

Execute the command "postmap /etc/postfix/transport" whenever you change the transport table.

In some installations, there may be separate instances of Postfix processing inbound and outbound mail on a multi-homed firewall. The inbound Postfix instance has an SMTP server listening on the external firewall interface, and the outbound Postfix instance has an SMTP server listening on the internal interface. In such a configuration is it is tempting to configure $inet_interfaces in each instance with just the corresponding interface address.

In most cases, using inet_interfaces in this way will not work, because as documented in the $inet_interfaces reference manual, the smtp(8) delivery agent will also use the specified interface address as the source address for outbound connections and will be unable to reach hosts on "the other side" of the firewall. The symptoms are that the firewall is unable to connect to hosts that are in fact up. See the inet_interfaces parameter documentation for suggested work-arounds.

Delivering some but not all accounts locally

A drawback of sending mail as "user@example.com" (instead of "user@hostname.example.com") is that mail for "root" and other system accounts is also sent to the central mailhost. In order to deliver such accounts locally, you can set up virtual aliases as follows:

1 /etc/postfix/main.cf:
2     virtual_alias_maps = hash:/etc/postfix/virtual
3 
4 /etc/postfix/virtual:
5     root     root@localhost
6     . . .

Translation:

Running Postfix behind a firewall

The simplest way to set up Postfix on a host behind a firewalled network is to send all mail to a gateway host, and to let that mail host take care of internal and external forwarding. Examples of that are shown in the local area network section above. A more sophisticated approach is to send only external mail to the gateway host, and to send intranet mail directly. That's what Wietse does at work.

Note: this example requires Postfix version 2.0 and later. To find out what Postfix version you have, execute the command "postconf mail_version".

The following example presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.

 1 /etc/postfix/main.cf:
 2     transport_maps = hash:/etc/postfix/transport
 3     relayhost =
 4     # Optional for a machine that isn't "always on"
 5     #fallback_relay = [gateway.example.com]
 6 
 7 /etc/postfix/transport:
 8     # Internal delivery.
 9     example.com      :
10     .example.com     :
11     # External delivery.
12     *                smtp:[gateway.example.com]

Translation:

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m".

Execute the command "postmap /etc/postfix/transport" whenever you edit the transport table.

Configuring Postfix as primary or backup MX host for a remote site

This section presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.

When your system is SECONDARY MX host for a remote site this is all you need:

 1 DNS:
 2     the.backed-up.domain.tld        IN      MX 100 your.machine.tld.
 3 
 4 /etc/postfix/main.cf:
 5     relay_domains = . . . the.backed-up.domain.tld
 6     smtpd_recipient_restrictions = 
 7         permit_mynetworks reject_unauth_destination
 8 
 9     # You must specify your NAT/proxy external address.
10     #proxy_interfaces = 1.2.3.4
11 
12     relay_recipient_maps = hash:/etc/postfix/relay_recipients
13 
14 /etc/postfix/relay_recipients:
15     user1@the.backed-up.domain.tld   x
16     user2@the.backed-up.domain.tld   x
17      . . .

When your system is PRIMARY MX host for a remote site you need the above, plus:

18 /etc/postfix/main.cf:
19     transport_maps = hash:/etc/postfix/transport
20 
21 /etc/postfix/transport:
22     the.backed-up.domain.tld       relay:[their.mail.host.tld]

Important notes:

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m".

Execute the command "postmap /etc/postfix/transport" whenever you change the transport table.

NOTE for Postfix < 2.2: Do not use the fallback_relay feature when relaying mail for a backup or primary MX domain. Mail would loop between the Postfix MX host and the fallback_relay host when the final destination is unavailable.

These are default settings in Postfix version 2.2 and later.

Postfix on a dialup machine

This section applies to dialup connections that are down most of the time. For dialup connections that are up 24x7, see the local area network section above.

This section presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.

If you do not have your own hostname and IP address (usually with dialup, cable TV or DSL connections) then you should also study the section on "Postfix on hosts without a real Internet hostname".

Postfix on hosts without a real Internet hostname

This section is for hosts that don't have their own Internet hostname. Typically these are systems that get a dynamic IP address via DHCP or via dialup. Postfix will let you send and receive mail just fine between accounts on a machine with a fantasy name. However, you cannot use a fantasy hostname in your email address when sending mail into the Internet, because no-one would be able to reply to your mail. In fact, more and more sites refuse mail addresses with non-existent domain names.

Note: the following information is Postfix version dependent. To find out what Postfix version you have, execute the command "postconf mail_version".

Solution 1: Postfix version 2.2 and later

Postfix 2.2 uses the generic(5) address mapping to replace local fantasy email addresses by valid Internet addresses. This mapping happens ONLY when mail leaves the machine; not when you send mail between users on the same machine.

The following example presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.

1 /etc/postfix/main.cf:
2     smtp_generic_maps = hash:/etc/postfix/generic
3 
4 /etc/postfix/generic:
5     his@localdomain.local             hisaccount@hisisp.example
6     her@localdomain.local             heraccount@herisp.example
7     @localdomain.local                hisaccount+local@hisisp.example

When mail is sent to a remote host via SMTP:

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m".

Execute the command "postmap /etc/postfix/generic" whenever you change the generic table.

Solution 2: Postfix version 2.1 and earlier

The solution with older Postfix systems is to use valid Internet addresses where possible, and to let Postfix map valid Internet addresses to local fantasy addresses. With this, you can send mail to the Internet and to local fantasy addresses, including mail to local fantasy addresses that don't have a valid Internet address of their own.

The following example presents additional configuration. You need to combine this with basic configuration information as discussed the first half of this document.

 1 /etc/postfix/main.cf:
 2     myhostname = hostname.localdomain
 3     mydomain = localdomain
 4 
 5     canonical_maps = hash:/etc/postfix/canonical
 6 
 7     virtual_alias_maps = hash:/etc/postfix/virtual
 8 
 9 /etc/postfix/canonical:
10     your-login-name    your-account@your-isp.com
11 
12 /etc/postfix/virtual:
13     your-account@your-isp.com       your-login-name

Translation:

Specify dbm instead of hash if your system uses dbm files instead of db files. To find out what lookup tables Postfix supports, use the command "postconf -m".

Execute the command "postmap /etc/postfix/canonical" whenever you change the canonical table.

Execute the command "postmap /etc/postfix/virtual" whenever you change the virtual table.