POSTFIX-WRAPPER(5)

NAME
postfix-wrapper - Postfix multi-instance API

DESCRIPTION
This document describes an interface that allows a multi-instance manager to plug into Postfix and to control multiple Postfix instances. A trivial but useful implementation, with instructions, can be found in $daemon_directory/postfix-wrapper. Each Postfix instance is defined by its own configuration directory with its own main.cf and master.cf files, by its own queue and data directories, and by its own myhostname and inet_interfaces settings. Other Postfix files, including executable files and documentation, are shared between Postfix instances. Only the default Postfix instance is required. The location of its configuration files is specified by the built-in default value for the config_directory parameter. Other Postfix instances are optional.

GENERAL OPERATION
First of all, nothing changes when there is only one Postfix instance. Even after multi-instance support has been set up through the mechanisms discussed later, sites can still continue to use the familiar "postfix start / stop / reload / upgrade / etc" commands in boot scripts, build procedures, etc. To start, stop, update, etc., multiple Postfix instances, use:

    # postfix command

For example, to find out what Postfix instances are configured:

    # postfix status

MANAGING AN INDIVIDUAL POSTFIX INSTANCE
To manage an individual Postfix instance, use:

    # postfix -c /path/to/config_directory command

When the postfix(1) command is invoked with the -c option, it will operate only on the specified instance. The same happens when MAIL_CONFIG is specified in the process environment. Otherwise, the postfix(1) command will operate on all applicable Postfix instances.

MULTI-INSTANCE MANAGER EXAMPLE
When the postfix(1) command is invoked without -c option or MAIL_CONFIG environment setting, and non-default Postfix instance directories are defined in main.cf with the multi_instance_directories parameter, postfix(1) invokes the command specified in main.cf with the multi_instance_wrapper parameter, instead of invoking postfix-script. The multi_instance_directories and other main.cf parameters are listed below in the CONFIGURATION PARAMETERS section. A useful wrapper implementation can be as simple as:

    #!/bin/sh
    : ${command_directory?"do not invoke this command directly"}
    POSTCONF=$command_directory/postconf
    POSTFIX=$command_directory/postfix
    instance_dirs=`$POSTCONF -h multi_instance_directories |
                    sed 's/,/ /'` || exit 1
    err=0
    for dir in $config_directory $instance_dirs
    do
        case "$1" in
        stop|abort|flush|reload|drain)
            test "`$POSTCONF -c $dir -h multi_instance_enable`" \
                    = yes || continue;;
        start)
            test "`$POSTCONF -c $dir -h multi_instance_enable`" \
                    = yes || set check;;
        esac
        $POSTFIX -c $dir "$@" || err=$?
    done
    exit $err

The postmulti(1) command implements a more sophisticated approach, based on a combination of C code and scripting.

ENABLING AN INSTANCE FOR MULTI-INSTANCE OPERATION
To enable start/stop/etc. by a multi-instance manager, set the Postfix instance's main.cf multi_instance_enable parameter to "yes". This parameter has no effect on single-instance operation with "postfix -c" or with a MAIL_CONFIG environment setting. The multi-instance manager program will skip commands such as "stop" and "flush" when a Postfix instance is disabled, and will replace "start" by "check" so that problems will still be reported even when the default instance is disabled.

SHARED VERSUS NON-SHARED FILES
Some files are shared between Postfix instances, such as executables and manpages, and some files are per-instance, such as the queue. See the NON-SHARED FILES section below for a list of per-instance files. Before Postfix multi-instance support was implemented, the executables, manpages, etc., have always been checked or updated as part of the default Postfix instance. With multi-instance support, we simply continue to do this. Non-default Postfix instances will check or update only their non-shared files. The consequence of this approach is that the default Postfix instance should be updated before any other instances.

MULTI-INSTANCE API SUMMARY
Only the multi-instance manager implements support for the multi_instance_enable configuration parameter. The multi-instance manager will not start Postfix instances without "multi_instance_enable = yes". This allows a Postfix instance to be tested by hand before it is placed under control of a multi-instance manager. The postfix(1) command ignores the multi_instance_directories and multi_instance_wrapper parameters when the -c option is specified, or when MAIL_CONFIG is present in the process environment. Otherwise, when the multi_instance_directories parameter value is non-empty, the postfix(1) command executes the command specified with the multi_instance_wrapper parameter, instead of executing the commands in postfix-script. The multi-instance manager skips commands such as "stop" or "reload" that require a running Postfix instance, when an instance does not have "multi_instance_enable = yes". This avoids false error messages. The multi-instance manager replaces a "start" command by "check" when a Postfix instance does not have "multi_instance_enable = yes". This substitution ensures that problems will still be reported even when the default instance is disabled. No Postfix command or script will update or check shared files unless it is running in the context of the default Postfix instance. Therefore, the default instance should be updated before any other Postfix instances. Set-gid commands such as postdrop(1) and postqueue(1) effectively append the multi_instance_directories parameter value to the legacy alternate_config_directories parameter value. The commands use this information to determine whether a -c option or MAIL_CONFIG environment setting specifies a legitimate value. The legacy alternate_config_directories parameter remains necessary for non-default Postfix instances that are running different versions of Postfix, or that are not managed together with the default Postfix instance.

ENVIRONMENT VARIABLES

MAIL_CONFIG
    When present, this forces the postfix(1) command to operate only on the specified Postfix instance. This environment variable is exported by the postfix(1) -c option, so that postfix(1) commands in descendant processes will work correctly.

CONFIGURATION PARAMETERS
The text below provides only a parameter summary. See postconf(5) for more details.

multi_instance_directories (empty)
    An optional list of non-default Postfix configuration directories; these directories belong to additional Postfix instances that share the Postfix executable files and documentation with the default Postfix instance, and that are started, stopped, etc., together with the default Postfix instance.

multi_instance_wrapper (empty)
    The pathname of a multi-instance manager command that the postfix(1) command invokes when the multi_instance_directories parameter value is non-empty.

multi_instance_name (empty)
    The optional instance name of this Postfix instance.

multi_instance_group (empty)
    The optional instance group name of this Postfix instance.

multi_instance_enable (no)
    Allow this Postfix instance to be started, stopped, etc., by a multi-instance manager.

NON-SHARED FILES

config_directory (see 'postconf -d' output)
    The default location of the Postfix main.cf and master.cf configuration files.

data_directory (see 'postconf -d' output)
    The directory with Postfix-writable data files (for example: caches, pseudo-random numbers).

queue_directory (see 'postconf -d' output)
    The location of the Postfix top-level queue directory.

SEE ALSO
postfix(1) Postfix control program
$daemon_directory/postfix-wrapper simple multi-instance manager
postmulti(1) full-blown multi-instance manager

LICENSE
The Secure Mailer license must be distributed with this software.

AUTHOR(S)
Wietse Venema
IBM T.J. Watson Research
P.O. Box 704
Yorktown Heights, NY 10598, USA