Table of Contents
Understanding Postfix Configuration
Postfix is a modular mail transfer agent that is configured mostly through plain text files. The two central configuration files are main.cf and master.cf, located in /etc/postfix on most distributions. You will usually adjust main.cf for general behavior and master.cf for service-level behavior such as how Postfix listens or what extra steps it runs.
Postfix reads its configuration at startup, so when you change these files, you must reload or restart the service. You can check the configuration and basic status with the postfix command and with your system service manager. For example, postfix check looks for obvious errors in the configuration before you reload it.
Always run postfix check after changing configuration files, and reload Postfix only if the check reports no errors.
A minimal but functional configuration tells Postfix what domains it is responsible for, what networks may relay through it, and how it identifies itself to other servers. Everything else refines these basics.
Key Parameters in main.cf
The main.cf file controls global behavior. Each line has the form parameter = value. Whitespace and comments matter, so it is important to keep the syntax clean. If a value is very long, you can continue it on the next line by indenting the continuation line with at least one space or tab.
Several parameters are foundational and appear in almost every setup. The parameter myhostname sets the full hostname Postfix uses when presenting itself. It should match your server’s fully qualified domain name in DNS, for example mail.example.com. The parameter mydomain usually contains the base domain part such as example.com. If you do not define mydomain, Postfix may attempt to guess it from myhostname.
The myorigin parameter controls what domain is appended to locally generated mail that lacks a domain part. For many server setups, it is set to $mydomain. The variable syntax $name allows you to reuse the value of another parameter, and it is common throughout Postfix configuration.
Another essential parameter is mydestination, which lists domains that Postfix treats as local. Messages to addresses in mydestination are delivered into local mailboxes. At minimum, this includes $myhostname and sometimes $mydomain and localhost. Parameters that expect lists often accept them as space or comma separated values. The parameter inet_interfaces controls on which network interfaces Postfix listens for incoming mail. Common values include all, loopback-only, or an explicit IP address.
The myorigin, mydestination, and inet_interfaces trio allows you to restrict a server to local delivery only when desired, for example for systems that send notifications but do not receive internet mail. For an internet facing mail server, you generally accept mail on all public interfaces and specify your domain in mydestination.
Controlling Relaying and Trusted Networks
Postfix must distinguish between clients that may use it as a relay and external systems that may only send to your domains. Relaying means accepting mail from one system and forwarding it to another, for example from a desktop user to some remote destination.
The mynetworks parameter defines which client IP ranges are trusted by default. These addresses may relay through your server without further authentication. A common safe choice is to limit this to localhost and, if relevant, an internal subnet. For example, mynetworks = 127.0.0.0/8 [::1]/128 for a host that should not allow general relaying.
The parameter relayhost tells Postfix to send all outbound mail through another server instead of directly to the destination MX. This is typical in environments that centralize outbound mail through a “smart host”. If you configure a relay host, you will frequently combine it with authenticated relay so that Postfix logs into an upstream mail server before sending.
Improperly set relaying parameters can turn your server into an open relay, which is quickly abused to send spam. Careful control of mynetworks, and later, use of authentication, is essential.
Never allow untrusted networks in mynetworks without additional access controls. A misconfigured mynetworks can create an open relay that will be abused and blacklisted.
Working with master.cf Services
While main.cf defines global settings, master.cf defines the individual Postfix services such as SMTP listeners and local delivery. Each line in master.cf represents a service with fields controlling whether it runs on demand, as a daemon, or with additional processing.
Most basic installations can use the default master.cf with minimal modification. However, you might enable or adjust services there, for example an additional listener on a different port, or an SMTP submission service for authenticated clients on port 587.
Each service entry has a name, type (such as inet for TCP IP based services), private status, unprivileged status, chroot flag, wakeup time, process limit, and the actual command with arguments. Although the syntax is dense, you usually edit it by following commented examples that come with the file.
If you enable extra ports, remember that you will still control behavior through parameters in main.cf such as access restrictions and TLS settings.
Local Delivery and Mailbox Formats
Postfix can deliver local mailboxes in different formats. The two common ones are mbox, where each mailbox is a single file, and Maildir, where each message is an individual file in a directory. You choose the default format with home_mailbox or mailbox_command and related settings.
If you set home_mailbox = Maildir/, Postfix will create a Maildir structure inside each user’s home directory, for example /home/user/Maildir/. Many modern IMAP servers prefer Maildir because it reduces locking issues and scales better with larger mailboxes.
Local delivery is connected with the local_transport and virtual_transport parameters, which direct how mail is handed to the local delivery agent or external delivery system. For simple configurations where system users receive mail directly, you might keep the built in local delivery defaults and focus only on the mailbox format.
Domain Handling and Masquerading
The mydestination parameter tells Postfix which domains belong to this server. Mail for addresses in mydestination is treated as local. When multiple domains must be hosted, you may also use virtual domain mechanisms, which are configured with separate parameters and maps and are handled elsewhere.
Masquerading hides internal hostnames or subdomains to present a cleaner domain in outbound mail. Parameters like masquerade_domains and masquerade_exceptions control this behavior. For example, if your internal host is host.internal.example.com, you might configure Postfix so that outgoing messages appear as user@example.com.
Masquerading is especially useful when you have many internal machines that should all present a single external identity, or when system account mail should appear to come from a consistent domain.
Basic Access Control and Restrictions
Postfix access control centers around “restriction classes” that are evaluated in a particular order. The parameters smtpd_helo_restrictions, smtpd_sender_restrictions, and especially smtpd_recipient_restrictions control SMTP behavior at various stages of a connection.
In many typical setups, smtpd_recipient_restrictions is used to decide whether a given recipient address should be accepted, rejected, or deferred. Within this parameter you list rules like permit_mynetworks, permit_sasl_authenticated, or reject_unauth_destination. These are evaluated in order until a decision is made.
The rule reject_unauth_destination is central, because it instructs Postfix to reject mail that is not destined for a domain you are responsible for unless the client is allowed to relay. Without it, you risk becoming an open relay.
Always include reject_unauth_destination in smtpd_recipient_restrictions for an internet facing Postfix server, unless you have a very specific and controlled reason not to.
Additional restrictions can incorporate access maps, which are external files listing addresses, domains, or networks with actions such as REJECT or OK. These maps are referenced by parameters like smtpd_client_restrictions using lookup mechanisms configured by *_maps parameters.
Using Maps and postmap
Postfix uses lookup tables, called maps, for many features including access rules, virtual aliasing, transport selection, and relay authentication. You configure a map with a type and a path, for example hash:/etc/postfix/access. Plain text source files are typically converted to an indexed database format with the postmap command.
A typical map file consists of lines where a key is followed by a value. For example in an access map, a domain name can be followed by an action. Once you create or edit the text file, you run postmap /etc/postfix/access, which generates a *.db file. Postfix reads the database format during operation.
The type prefix, such as hash: or btree:, defines the backend used for storage. On most systems, hash is the default preferred type for simple key value data. In some cases, you also use other types such as mysql: or ldap: to integrate with external directory services, but simple file based maps are often enough for smaller installations.
Whenever you modify a map file, you must regenerate the database with postmap and reload Postfix to see the change in effect.
TLS and Basic Security Settings
To secure connections, Postfix uses Transport Layer Security (TLS). Configuration for TLS involves setting paths to certificate and key files, and deciding whether TLS is optional or required for certain clients. Parameters such as smtpd_tls_cert_file and smtpd_tls_key_file point to your server certificate and private key.
You also control how aggressively Postfix enforces TLS through parameters like smtpd_tls_security_level. A common starting point sets this to may, which allows TLS but does not require it. Stricter setups may require encryption for authenticated submission or certain networks.
There are separate parameters for outbound TLS, such as smtp_tls_security_level. These determine how Postfix behaves when it acts as a client connecting to remote SMTP servers. You can require or prefer TLS for specific destinations using policy maps, but the fundamental knob is the security level.
Because TLS configuration interacts with authentication and policy behavior, it is helpful to test connectivity using tools that show SSL handshakes, and to consult logs if clients cannot connect. Misconfigured certificate paths or incorrect permissions on key files are common sources of errors.
Relaying through an Upstream Server
In many environments, Postfix does not send mail directly to the internet but instead forwards all outgoing messages to a relay host, sometimes called a smart host. This is controlled with the relayhost parameter. Its value is usually a hostname and optionally a port, for example [smtp.provider.com]:587. Brackets prevent DNS MX lookups and force the use of that exact host.
When the relay host requires authentication, you configure Postfix to use SASL for SMTP client authentication. This involves setting parameters such as smtp_sasl_auth_enable along with a smtp_sasl_password_maps reference that points to a file mapping the relay hostname to username and password. You then run postmap on that file to create the lookup database.
Once configured, any mail that is not destined for your local domains will be sent via the upstream relay, using the credentials you provided. This arrangement is common for servers in data centers, or for small setups that use an ISP or cloud mail provider for actual delivery.
Logging, Testing, and Reloading
Postfix logs activity to the system logging facility. You can observe incoming connections, deliveries, rejections, and errors in log files under /var/log, usually in files like /var/log/mail.log or /var/log/maillog depending on your distribution. Checking these logs is the primary way to understand how your configuration behaves in real time.
After editing configuration files, you verify syntax with postfix check. If that succeeds, you reload configuration with a command such as postfix reload or by using your service manager, for example systemctl reload postfix. A full restart is usually not required, but can be used if reload behaves unexpectedly.
To test basic connectivity, you can connect manually to the SMTP port using tools such as telnet or openssl s_client. This lets you observe the banner, test HELO or EHLO behavior, and see how restrictions apply to example messages. Once you add TLS or authentication, such manual tests help confirm that the paths to certificates and keys are correct and that the server presents the expected identity.
Systematic testing after each change, together with careful attention to logs, reduces the chance of misconfiguration and makes it easier to detect subtle problems like relaying errors or incorrect domain handling.