Inspect and Change Postfix Configuration with postconf

You will use postconf to see effective Postfix settings, distinguish explicit values from built-in defaults, inspect a master.cf service, and make one reversible configuration change. The examples target the installed Postfix 3.8.6 package on Debian-like Linux systems.

Allow about 10 minutes for inspection. A configuration edit needs root privileges, a way to capture the old value, and a short service check afterwards. Do not run the write examples on a production mail server during an active delivery incident.

1. Check the command and configuration directory

Start by confirming which Postfix is installed and where it reads its files. These commands only read configuration.

postconf mail_version config_directory
postconf -h myhostname

Typical output includes:

mail_version = 3.8.6
config_directory = /etc/postfix
server.dixon.cx

The normal files are main.cf and master.cf below that directory. You can select another configuration directory with -c DIRECTORY, or with the MAIL_CONFIG environment variable. Be explicit when troubleshooting a container or staging copy so that you do not inspect one installation and edit another.

2. Inspect effective and explicit settings

With no parameter names, postconf prints main.cf settings with the name and value. Ask for named values when you need a compact answer, and add -h when a script needs only the value.

postconf myhostname mydestination home_mailbox
postconf -h myhostname

The distinction between defaults and local policy is usually the useful part. -d prints built-in defaults, while -n prints only parameters explicitly set in main.cf.

postconf -d myhostname
postconf -n | less

A value can be inherited from a parameter expansion rather than written literally. Use -x when you want $name expressions expanded in displayed main.cf or master.cf values. Do not treat postconf -n as a complete security review: an unset parameter can still have a significant built-in default.

For a quick comparison of explicit settings that differ from defaults, Bash can compare the two sorted outputs:

LANG=C comm -23 <(postconf -n) <(postconf -d)

That process substitution is a shell feature, not a postconf feature. Run it in Bash.

Checkpoint: record the value before writing

Before changing a parameter, save both its current value and the relevant file. This makes an undo command precise rather than guesswork.

parameter=myhostname
old_value=$(postconf -h "$parameter")
printf 'old %s = %s\n' "$parameter" "$old_value"
sudo cp -p /etc/postfix/main.cf "/etc/postfix/main.cf.before-postconf-$(date +%Y%m%d%H%M%S)"

The assignment and display are ordinary user commands. Reading /etc/postfix/main.cf may be allowed without elevation, but the backup and later edit normally require root.

3. Change one main.cf parameter

Use -e with a quoted name=value pair. Postfix 2.8 and later infer edit mode when a value is supplied, but keeping -e makes the intent visible. This example changes a harmless local identity value; substitute a hostname that is valid for your server.

sudo postconf -e 'myhostname=mail.example.test'
postconf myhostname

The second command should report:

myhostname = mail.example.test

postconf copies the configuration to a temporary file and renames it into place. That protects the file from a partial write, but it does not validate your mail design or undo a bad value. Quote values containing whitespace or shell metacharacters. Do not put secrets in a command line that could be exposed through shell history or process inspection.

For a parameter that should return to its built-in default, use -# to comment out its setting:

sudo postconf -# myhostname
postconf -n myhostname

There is no postconf command that reverses -# or -X automatically. The saved copy gives you a recovery path:

sudo cp -p /etc/postfix/main.cf.before-postconf-TIMESTAMP /etc/postfix/main.cf
postconf myhostname

Replace TIMESTAMP with the actual suffix printed by ls -t /etc/postfix/main.cf.before-postconf-*. Check the file before copying it. A full restore also restores unrelated edits made after the backup, so prefer postconf -e 'name=old-value' when only one parameter needs undoing.

4. Inspect master.cf without editing it

main.cf holds general parameters. Service definitions and per-service overrides live in master.cf. Use -M to list service entries and narrow it to a service/type pair.

postconf -Mf smtp/inet
postconf -P 'submission/inet/smtpd_tls_security_level'

On this installation, the first command prints the SMTP service entry and the second prints a setting in the submission service in the form service/type/parameter=value. The slash matters: current Postfix uses smtp/inet, not the older dotted form.

To inspect fields rather than -o parameter=value overrides, use -F:

postconf -F 'smtp/inet/command'

Use -f with -M, -F or -P when long lines need folding for a terminal. Use -H when you need names without values, available from Postfix 3.1 onward.

5. Apply a service override only with a rollback plan

Per-service changes are easy to misread because they affect one entry in master.cf, not the global parameter. First back up the file, then make the smallest possible change. This example sets an explicit TLS requirement on an existing submission entry. Confirm that certificates, authentication and the intended clients are ready before using it on a live server.

sudo cp -p /etc/postfix/master.cf "/etc/postfix/master.cf.before-postconf-$(date +%Y%m%d%H%M%S)"
sudo postconf -P 'submission/inet/smtpd_tls_security_level=encrypt'
postconf -P 'submission/inet/smtpd_tls_security_level'

Changing service parameters can disrupt mail submission. Restore the backup if the result is wrong, or remove that exact override with -PX after checking the target:

sudo postconf -PX 'submission/inet/smtpd_tls_security_level'
postconf -P 'submission/inet/smtpd_tls_security_level'

Unlike -#, -PX removes the setting. The manpage documents no reverse operation for removal, so keep the backup until the service has passed its checks.

6. Validate and reload deliberately

postconf reports malformed or unknown configuration problems on standard error, but a successful edit is not proof that the mail service behaves as intended. Re-read the exact setting, inspect the relevant service, then ask Postfix to check and reload the configuration. These actions require root.

sudo postfix check
sudo postfix reload
sudo postfix status

If the check fails, do not reload. Restore the affected file or set the old parameter value, run sudo postfix check again, and inspect the Postfix log. A reload is service-disrupting in the operational sense even though it does not stop the daemon, because new processes may start with the changed policy.

For TLS capability checks, the installed command can report the runtime OpenSSL version and supported public-key algorithms:

postconf -T run-version
postconf -T public-key-algorithms

Those checks describe the Postfix build and linked library. They do not prove that every configured protocol or certificate path is correct.