postconf
Display Postfix configuration parameters
TLDR
Specify the directory of the main.cf configuration file instead of the default configuration directory
Edit the main.cf configuration file and update parameter settings with the "name=value" pairs
Print the default parameter settings of the main.cf instead of the actual settings
Display parameters only from the specified class. The class can be one of builtin, service, user or all
List available SASL plug-in types for the Postfix SMTP server. The plug-in type is selected with the smtpd_sasl_type configuration parameter by specifying cyrus or dovecot as the name
List the names of all supported lookup table types. Lookup tables are specified as type:name in configuration files where the type can be btree, cdb, hash, mysql, etc
SYNOPSIS
postconf [-c config_dir] [-evfhimnopsuvx] [parameter ...]
postconf -e [-c config_dir] [-fv] parameter=value ...
PARAMETERS
-c config_dir
Read configuration files from the specified directory instead of the compiled-in default. This is useful for managing multiple Postfix instances.
-e
Edit mode: update main.cf or master.cf. This option requires parameter=value arguments. By default, postconf attempts a safe update; use -f for forced updates.
-f
Force update. When used with -e, this option forces the update even if the change is potentially unsafe (e.g., attempting to remove a mandatory parameter or change a parameter that is locked by postconf itself).
-h
Display only parameter values, without the 'parameter =' prefix. This format is often useful for scripting purposes.
-i
Display Postfix compatibility information, showing the Postfix version and any compatibility levels set. This helps determine if a configuration is compatible with newer Postfix versions.
-m
Display the Postfix master.cf service types supported by the current Postfix build (e.g., inet, unix, fifo, chroot, pipe, fork, pass).
-n
Display only configuration parameters that have a value different from their default value. This helps in quickly identifying custom settings.
-o parameter=value
Override a main.cf configuration parameter for the current command invocation only. The value is not written to main.cf, allowing for temporary or testing changes.
-p
Display only default configuration parameters and their values. This shows the factory-set values that Postfix uses if no custom value is specified.
-s
Display master.cf parameters. When followed by service names, it displays parameters for those specific services. Without service names, it shows all master.cf entries.
-u
Update master.cf service parameters. This option implies both -e and -f, allowing for adding, modifying, or deleting master.cf entries in a forceful edit mode.
-v
Enable verbose logging for debugging purposes. This displays additional information about postconf's operations and progress.
-x
Display hidden main.cf parameters. These are parameters that Postfix manages internally and are not typically user-modifiable or visible by default, but can be insightful for advanced troubleshooting.
parameter ...
When no options are specified, postconf lists all main.cf parameters and their current values. If specific parameter names are provided as arguments, only their values are displayed.
DESCRIPTION
The postconf command is a powerful utility used to query, display, and update configuration parameters for the Postfix mail transfer agent. It primarily interacts with the main.cf and master.cf configuration files, providing a safe and consistent interface for managing Postfix's behavior.
Administrators use postconf to list all parameters, check specific values, display non-default settings, and set new values. It can also show default parameter values, display compatibility information for Postfix upgrades, and manage services defined in master.cf. Its ability to modify configuration files directly makes it an essential tool for Postfix system administration, helping to avoid manual errors and ensure configuration integrity.
CAVEATS
Most write operations (e.g., with -e or -u) require superuser privileges. Changes made to main.cf via postconf often require a postfix reload or postfix start command for them to take effect and for the Postfix daemon to pick up the new configuration. Directly manual editing of Postfix configuration files is generally discouraged in favor of using postconf to ensure syntax correctness, consistency, and to avoid common errors.
EXIT STATUS
The postconf command returns an exit status of 0 on success, and a non-zero status if an error occurred (e.g., invalid arguments, permission denied, or file access issues). This allows it to be reliably used within scripts and automated tasks.
ENVIRONMENT
The MAIL_CONFIG environment variable can be used to specify an alternate configuration directory for Postfix, overriding the default compiled-in path. This is particularly useful for testing different configurations or managing multiple distinct Postfix instances on the same system.
HISTORY
postconf is an integral part of the Postfix Mail Transfer Agent, which was initially developed by Wietse Venema at IBM Thomas J. Watson Research Center. It emerged as a core utility alongside the Postfix project's inception in the late 1990s, aiming to provide a robust, secure, and easily manageable mail system. Its design reflects Postfix's philosophy of explicit configuration management, allowing administrators a structured way to interact with and modify the system's behavior without directly parsing or risking errors in critical configuration files. Over the years, postconf has evolved with Postfix, gaining more options and capabilities to manage increasingly complex configurations.
SEE ALSO
postfix(1), main.cf(5), master.cf(5), postsuper(1), postalias(1)
