Postfix Configuration - Basics

Note: this web page is no longer maintained. It exists only to avoid breaking links in web pages that describe earlier versions of the Postfix mail system.

Introduction

Postfix has several hundred configuration parameters that are controlled via the main.cf file. Fortunately, they have sensible default values. In most cases, you need to configure only two or three parameters before you can use the Postfix mail system:

What domain to use in outbound mail
What domains to receive mail for
What clients to relay mail for

The default values for many other configuration parameters are derived from just these.

The next parameter of interest controls the amount of mail sent to the local postmaster:

What trouble to report to the postmaster

Be sure to set the following correctly if you're behind a proxy or network address translator, and you are running a backup MX host for some other domain:

Proxy/NAT network addresses

By the way, if you change parameters of a running Postfix system, don't forget to issue a postfix reload command.

If you run Postfix on a virtual network interface, or if your machine runs other mailers on virtual interfaces, you'll have to look at the other parameters listed here as well:

My own hostname
My own domain name
My own networks
My own network addresses

What domain to use in outbound mail

The myorigin parameter specifies the domain that appears in mail that is posted on this machine. The default is to use the local machine name, $myhostname, which defaults to the name of the machine. Unless you are running a really small site, you probably want to change that into $mydomain, which defaults to the parent domain of the machine name.

For the sake of consistency between sender and recipient addresses, myorigin also specifies the default domain name that is appended to an unqualified recipient address.

Examples:: myorigin = $myhostname (default); myorigin = $mydomain (probably desirable)

What domains to receive mail for

The mydestination parameter specifies what domains this machine will deliver locally, instead of forwarding to another machine. The default is to receive mail for the machine itself.

You can specify zero or more domain names, /file/name patterns and/or type:name lookup tables, separated by whitespace and/or commas. A /file/name is replaced by its contents; type:name requests that a table lookup is done.

If your machine is a mail server for its entire domain, you must list $mydomain as well.

Examples:

Default setting:: mydestination = $myhostname localhost.$mydomain
Domain-wide mail server:: mydestination = $myhostname localhost.$mydomain $mydomain
Host with multiple DNS A records:: mydestination = $myhostname localhost.$mydomain www.$mydomain ftp.$mydomain

Caution: in order to avoid mail delivery loops, you must list all hostnames of the machine, including $myhostname, and localhost.$mydomain.

What clients to relay mail for

By default, Postfix will relay mail for clients in authorized networks.

Authorized client networks are defined by the mynetworks parameter. The default is to authorize all clients in the IP subnetworks that the local machine is attached to.

What trouble to report to the postmaster

You should set up a postmaster alias that points to a human person. This alias is required to exist, so that people can report mail delivery problems.

The Postfix system itself also reports problems to the postmaster alias. You may not be interested in all types of trouble reports, so this reporting mechanism is configurable. The default is to report only serious problems (resource, software) to postmaster:

Default:: notify_classes = resource, software
The meaning of the classes is as follows:

bounce
Send postmaster copies of undeliverable mail. If mail is undeliverable, a so-called single bounce message is sent, with a copy of the message that was not delivered. For privacy reasons, the postmaster copy of a single bounce message is truncated after the original message headers. If a single bounce message is undeliverable, the postmaster receives a double bounce message with a copy of the entire single bounce message. See also the luser_relay feature.

2bounce
Send double bounces to the postmaster.

delay
Inform the postmaster of delayed mail. In this case, the postmaster receives message headers only.

policy
Inform the postmaster of client requests that were rejected because of (UCE) policy restrictions. The postmaster receives a transcript of the entire SMTP session.

protocol
Inform the postmaster of protocol errors (client or server side) or attempts by a client to execute unimplemented commands. The postmaster receives a transcript of the entire SMTP session.

resource
Inform the postmaster of mail not delivered due to resource problems (for example, queue file write errors).

software
Inform the postmaster of mail not delivered due to software problems.

Proxy/NAT network addresses

The proxy_interfaces parameter specifies all network addresses that the Postfix receives mail on by way of a proxy or network address translation unit. You may specify symbolic hostnames instead of network addresses.

You must specify your proxy/NAT addresses when your system is a backup MX host for other domains, otherwise mail delivery loops will happen when the primary MX host is down.

Examples:

Default:
proxy_interfaces =

Host running backup MTA:
proxy_interfaces = 1.2.3.4 (the proxy/NAT network address)

My own hostname

The myhostname parameter describes the fully-qualified domain name of the machine running the Postfix system. $myhostname appears as the default value in many other Postfix configuration parameters.

By default, myhostname is set to the local machine name. If your machine name is not in fully-qualified domain name form, or if you run Postfix on a virtual interface, you will have to specify the fully-qualified domain name that the mail system should use.

Examples:: myhostname = host.local.domain (local hostname is not FQDN); myhostname = host.virtual.domain (virtual interface); myhostname = virtual.domain (virtual interface)

My own domain name

The mydomain parameter specifies the parent domain of $myhostname. By default it is derived from $myhostname by stripping off the first part (unless the result would be a top-level domain).

Examples:: mydomain = local.domain; mydomain = virtual.domain (virtual interface)

My own networks

The mynetworks parameter lists all networks that this machine somehow trusts. This information can be used by the anti-UCE features to recognize trusted SMTP clients that are allowed to relay mail through Postfix.

You can specify the list of trusted networks in the main.cf file, or you can let Postfix deduce the list for you. The default is to let Postfix do the work for you.

Default:: mynetworks_style = subnet
The meaning of the styles is as follows:

class
Trust SMTP clients in the class A/B/C networks that Postfix is connected to. Don't do this with a dialup site - it would cause Postfix to "trust" your entire provider's network. Instead, specify an explicit mynetworks list by hand, as described below.

subnet (default)
Trust SMTP clients in the IP subnetworks that Postfix is connected to.

host
Trust only the local machine.

Alternatively, you can specify the mynetworks list by hand, in which case Postfix ignores the mynetworks_style setting. To specify the list of trusted networks by hand, specify network blocks in CIDR (network/mask) notation, for example:

mynetworks = 168.100.189.0/28, 127.0.0.0/8

You can also specify the absolute pathname of a pattern file instead of listing the patterns in the main.cf file.

My own network addresses

The inet_interfaces parameter specifies all network interface addresses that the Postfix system should listen on; mail addressed to user@[network address] will be delivered locally, as if it is addressed to a domain listed in $mydestination.

The default is to listen on all active interfaces. If you run mailers on virtual interfaces, you will have to specify what interfaces to listen on.

You even have to specify explicit machine interfaces for the non-virtual mailer that receives mail for the machine itself: the non-virtual mailer should never listen on the virtual interfaces or you would have a mailer loop.

Examples:

Default:
inet_interfaces = all

Host running virtual mailers:
inet_interfaces = virtual.host.tld (virtual domain)
inet_interfaces = $myhostname localhost.$mydomain (non-virtual mailer)

Note: you need to stop and start Postfix when this parameter changes.