Safely inspect, edit and reload the Postfix master process

You will inspect the Postfix master process, make a controlled change to master.cf, validate it, reload the daemon and confirm 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. The master process does not automatically notice either kind of configuration change: use 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 about to inspect instead of assuming that every host uses /etc/postfix or puts 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. Several master processes can appear on a host using multiple Postfix instances or service supervisors, so do not kill a PID merely because the list is 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 have special meaning. A line beginning with non-whitespace starts a service record; an indented line continues the previous record.

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

Each logical service record has eight fields: service name, service type, private flag, unprivileged flag, chroot flag, wake-up time, process limit, and command with arguments. A dash asks Postfix to use the built-in default. The active file may also contain indented -o name=value overrides for one service.

For example, smtp inet describes a TCP listener, while pickup unix describes a local UNIX-domain service. The service type affects the meaning of the service name. An inet service can expose a port on configured interfaces, so review the host and port before changing one.

3. Make a recoverable edit

Editing master.cf requires elevated privileges and can change how mail is received or delivered. Do this during a maintenance window if the change affects 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. Preserve the eight-field layout and use indentation for continuation lines. Postfix does not treat shell syntax as shell syntax in the command field: > and | are ordinary characters there, and shell quotes do not protect whitespace. On Postfix 3.0 and later, put braces around a command argument containing whitespace.

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 only. Review every override after editing; too many local overrides make the effective configuration harder to reason about.

4. Validate before reloading

Run the Postfix consistency check as root. It can report ownership, permission and configuration problems that a text editor cannot see.

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

A zero status means the check completed successfully. It does not prove that 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 that master is not running. It returns non-zero when the lock is present and locked, or when there is another problem. The binary is normally 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 interpret the exit code without checking the service state and logs. 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 requires 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. The important result is a successful command exit status. On reload, master re-reads its configuration. Services removed from master.cf have their running processes terminated immediately; otherwise existing processes are allowed to finish when convenient, so a changed setting normally affects new service requests.

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 are reported through syslogd or postlogd; 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. Common traps include a continuation line that is not indented, a misspelled daemon name, a service with an invalid process limit, and a network listener that conflicts with another process.

For temporary debugging, master -v enables verbose logging and passes the option to child processes. Multiple -v options increase verbosity. Treat this as diagnostic output, not a permanent setting, and return to the normal invocation after collecting enough evidence.

For an emergency shutdown, the manual distinguishes postfix abort, which sends termination to child processes, from postfix stop, which normally allows work in progress to finish. Do not use abort as a routine recovery step: it can interrupt active mail processing.