Postfix master.cf Explained: What It Does & How to Use It

The master.cf file is the main configuration file that defines every service the Postfix mail server runs, including which daemons start, how they listen, and what limits they enforce. You edit it to change how Postfix delivers mail, add new transport services like SMTP or LMTP, or tune performance and security settings. This file works hand-in-hand with main.cf, but while main.cf sets the server’s overall behavior, master.cf controls the individual processes that do the actual work.

What Is master.cf and Why Does It Matter?

Postfix is built as a modular system: instead of one giant program, it runs a collection of smaller daemons, each with a specific job. The master daemon is the supervisor that starts, stops, and monitors all the others. The master.cf file tells the master daemon which services to run, what command each service uses, and under what conditions (like how many processes to spawn or how long to wait before timing out). Without this file, Postfix wouldn’t know how to start any of its components, so mail delivery would stop entirely.

The file is usually located at /etc/postfix/master.cf on Linux systems. It is read by the master daemon at startup, and after you edit it you must run postfix reload or postfix restart for changes to take effect. Each line in the file describes one service, and the format is strictly column-based, so even a small mistake can prevent Postfix from starting.

How master.cf Is Structured

The file uses a simple text format: each service is defined by a single line with fields separated by whitespace. The fields are:

service: the name of the service (e.g., smtp, submission, pickup).
type: how the service listens — inet for network sockets, unix for Unix domain sockets, fifo for named pipes, or pass for a service that passes to another.
private: whether the service is only accessible to other Postfix processes (n for no, y for yes).
chroot: whether the process runs in a chroot jail (y or n).
wakeup: how often the service wakes up to check for work (in seconds, or 0 for none).
maxproc: maximum number of processes for this service (0 means unlimited).
command: the actual command to run, usually the name of the Postfix daemon plus arguments.

For example, a typical line for the SMTP service looks like:

smtp      inet  n       -       y       -       -       smtpd

This tells Postfix to run an SMTP daemon on a network socket, with no private access, no chroot, no wakeup, unlimited processes, and the command smtpd. The - in the maxproc field means the default limit from main.cf is used.

Common Services Defined in master.cf

Most default installations include several standard services. Understanding them helps you know what you’re editing:

smtp: the inbound SMTP server that receives mail on port 25.
submission: the SMTP server for client mail submission on port 587, often with SASL authentication enabled.
smtps: SMTP over SSL/TLS on port 465 (sometimes commented out by default).
pickup: a Unix socket service that picks up mail dropped into the maildrop directory.
cleanup: processes incoming mail, adding headers and routing information.
qmgr: the queue manager that decides where each message goes next.
local: the local delivery agent that delivers to local mailboxes.

You can also define custom services for special needs, such as a dedicated service that scans for viruses or filters spam before delivery.

How to Edit master.cf Safely

Editing master.cf is straightforward, but mistakes can break mail delivery. Follow these steps to make changes safely:

Back up the original file: cp /etc/postfix/master.cf /etc/postfix/master.cf.bak.
Open the file with a text editor as root (e.g., sudo nano /etc/postfix/master.cf).
Make your changes, respecting the column layout. Use spaces or tabs consistently; the file is not sensitive to which, but mixing can confuse.
Test the configuration with postfix check. This command reports syntax errors and missing files.
Reload Postfix with postfix reload (or postfix restart if you changed service definitions).
Watch the mail log (/var/log/mail.log or journalctl -u postfix) for errors.

If you make a serious mistake, Postfix may refuse to start. In that case, restore the backup and try again.

Common Use Cases and Examples

Here are two typical scenarios where you’d edit master.cf:

1. Enabling submission on port 587. Many default configurations have the submission service commented out. To enable it, uncomment the line that starts with submission and add the necessary options like -o smtpd_sasl_auth_enable=yes. For example:

submission inet n       -       y       -       -       smtpd
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_tls_security_level=encrypt

2. Limiting the number of SMTP processes. To prevent overload, you can set a maximum process count. Change the maxproc field from - to a number like 10:

smtp      inet  n       -       y       -       10      smtpd

This limits the SMTP service to 10 concurrent processes, which can help on busy servers.

Common Mistakes and Troubleshooting

One frequent mistake is breaking the column alignment. Even though Postfix parses fields by whitespace, adding an extra column can shift everything and cause errors. Always run postfix check after editing.

Another issue is forgetting to reload after changes. If you edit master.cf but don’t reload, the old settings remain active, which can confuse you when changes don’t appear to work.

If Postfix fails to start, check the log file. Common errors include missing service definitions, invalid chroot paths, or commands that don’t exist. The postfix check command will catch most of these before you reload.

master.cf vs. main.cf: What’s the Difference?

New administrators often confuse the two. main.cf contains global parameters like myhostname, mydomain, and relayhost. It defines the server’s identity and high-level behavior. master.cf, on the other hand, defines the individual processes and their runtime parameters. You can override main.cf settings in master.cf by using -o options on a service line. For example, you can set a different smtpd_banner for the submission service only.

Think of main.cf as the policy file and master.cf as the process control file. Both are essential, but they serve different roles.

Frequently Asked Questions

What happens if I delete master.cf?

If you delete or rename master.cf, Postfix will not start because the master daemon cannot find its service definitions. You would need to restore it from a backup or reinstall the default configuration.

Can I add a new service to master.cf?

Yes, you can add custom services, such as a dedicated SMTP listener on a different port or a local delivery agent. Just add a new line following the same format, then reload Postfix.

Do I need to restart Postfix after editing master.cf?

You can use postfix reload for most changes, but if you add or remove services, a full postfix restart is safer to ensure the master daemon picks up the new service list.

Why is the submission service commented out by default?

Many distributions comment out submission to reduce the attack surface. It’s only needed if you want clients to send mail through your server on port 587, which is common for authenticated relaying.

What does the chroot column do?

Setting chroot to y makes the service run in a chroot jail, isolating it from the rest of the filesystem. This improves security but requires that all necessary files (like timezone data) be available inside the jail. The default is often y for network services.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →