Inspect, Edit and Reload the Postfix master Process

Mail stops flowing and someone says "just restart Postfix", but the safer fix usually lives in master.cf and a proper reload. This guide inspects the Postfix master process, makes a controlled change to master.cf, validates it, reloads the daemon and confirms what changed. Allow about 15 minutes for an inspection, or 30 minutes if you are editing a live mail service. The examples target Postfix 3.8.6 on this machine.

Postfix master is the resident process that starts mail daemons when their services are needed. It reads the global settings from main.cf and the service definitions from master.cf. Here is the part that catches people out: master does not notice either kind of configuration change on its own. You must run postfix reload after editing.

1. Check the installed paths and running state

Start with ordinary, read-only commands. They tell you which installation you are actually inspecting, instead of assuming every host puts things at /etc/postfix or has the master binary on your shell path.

$ postconf mail_version
mail_version = 3.8.6
$ postconf config_directory daemon_directory queue_directory data_directory
config_directory = /etc/postfix
daemon_directory = /usr/lib/postfix/sbin
queue_directory = /var/spool/postfix
data_directory = /var/lib/postfix
$ ps -eo pid,user,comm,args | grep '[m]aster'

The last command should show the resident master process if Postfix is running. A host with multiple Postfix instances or service supervisors can show several master processes, so do not kill a PID just because the list looks longer than expected. Ask the service manager or the Postfix administrator which instance owns the configuration you are changing.

2. Read the active service definitions

Inspect the file without editing it. Blank lines, comments and indented continuation lines all carry meaning: a line starting with non-whitespace opens a service record, an indented line continues the record above it.

$ config_dir=$(postconf -h config_directory)
$ sed -n '1,220p' "$config_dir/master.cf"
$ awk 'NF && $1 !~ /^#/ {print}' "$config_dir/master.cf" | head -30

• Eight fields per record: service name, service type, private flag, unprivileged flag, chroot flag, wake-up time, process limit, and command with arguments. A dash means "use the built-in default".
• Overrides live indented: the active file can also hold indented -o name=value lines that override one setting for one service.
• Service type changes the meaning of the name: smtp inet describes a TCP listener, while pickup unix describes a local UNIX-domain service. An inet service can expose a port on configured interfaces, so check the host and port before touching one.

3. Make a recoverable edit

Editing master.cf needs elevated privileges and can change how mail is received or delivered. Do this in a maintenance window if the change touches a network listener, authentication, TLS, chrooting or process limits. Keep the original file until the new configuration has passed its checks.

$ config_dir=$(postconf -h config_directory)
$ sudo cp --preserve=mode,ownership,timestamps \
    "$config_dir/master.cf" "$config_dir/master.cf.bak"
$ sudoedit "$config_dir/master.cf"

Use sudoedit rather than opening a root shell. Keep the eight-field layout intact and indent continuation lines properly. Postfix does not treat shell syntax as shell syntax in the command field: > and | are just ordinary characters there, and shell quotes will not protect whitespace for you. On Postfix 3.0 and later, wrap a command argument that contains whitespace in braces.

A per-service override is often less invasive than changing a global value. For instance, an indented line such as -o syslog_name=postfix/$service_name applies to that service alone. Review every override after editing; too many local overrides make the effective configuration much harder to reason about.

4. Validate before reloading

Run the Postfix consistency check as root. It catches ownership, permission and configuration problems a text editor never will:

$ sudo postfix check
$ printf 'check exit status: %s\n' "$?"
check exit status: 0

A zero status only means the check completed successfully. It does not prove an SMTP client will authenticate, that a remote host will accept delivery, or that your new policy expresses the intention you had. Test those separately.

For a read-only lock-state check, the master manual documents the -t option. It returns zero when the master.pid lock does not exist or is not locked, which is evidence master is not running. It returns non-zero when the lock is present and locked, or when something else is wrong. The binary normally lives under the configured daemon directory:

$ daemon_dir=$(postconf -h daemon_directory)
$ sudo "$daemon_dir/master" -t
$ printf 'master test exit status: %s\n' "$?"

Do not read that exit code on its own; check the service state and logs too. A running host is expected to have a locked master PID file.

5. Reload the new configuration

Once the check succeeds, ask Postfix to reload. This needs elevated privileges and sends the master process a reload request.

$ sudo postfix reload
$ printf 'reload exit status: %s\n' "$?"
reload exit status: 0

The exact status text varies with the package and service wrapper, but a successful command exit status is what matters. On reload, master re-reads its configuration. Services removed from master.cf have their running processes terminated immediately; otherwise existing processes finish when convenient, so a changed setting normally affects new service requests only.

6. Diagnose a failed start or reload

If validation or reload fails, stop changing files and read the service logs. The master manual says problems get reported through syslogd or postlogd, so the exact journal or log file depends on the host.

$ sudo journalctl -u postfix --since '10 minutes ago' --no-pager
$ sudo journalctl -k --since '10 minutes ago' --no-pager | grep -i postfix

Use your system's configured mail log if the Postfix unit does not write useful journal entries. Look for the first error after the edit, not just the last repeated child-process warning.

• An unindented continuation line. The parser reads it as a new service record instead of a continuation.
• A misspelled daemon name. The service record points at a binary that does not exist.
• An invalid process limit. A malformed number in that field breaks the whole record.
• A network listener that conflicts with another process. Two services cannot bind the same port.

For temporary debugging, master -v turns on verbose logging and passes the option to child processes; multiple -v flags add more detail. Treat this as diagnostic output, not a permanent setting, and return to the normal invocation once you have enough evidence.