#++
# NAME
#	postfix-wrapper 5
# SUMMARY
#	Postfix multi-instance API
# DESCRIPTION
#	Support for managing multiple Postfix instances is available
#	as of version 2.6. Instances share executable files and
#	documentation, but have their own directories for configuration,
#	queue and data files.
#
#	This document describes how the familiar "postfix start"
#	etc. user interface can be used to manage one or multiple
#	Postfix instances, and gives details of an API to coordinate
#	activities between the postfix(1) command and a multi-instance
#	manager program.
#
#	With multi-instance support, the default Postfix instance
#	is always required. This instance is identified by the
#	config_directory parameter's default value.
# GENERAL OPERATION
# .ad
# .fi
#	Multi-instance support is backwards compatible: when you
#	run only one Postfix instance, commands such as "postfix
#	start" will not change behavior at all.
#
#	Even with multiple Postfix instances, you can keep using
#	the same postfix commands in boot scripts, upgrade procedures,
#	and other places. The commands do more work, but humans are
#	not forced to learn new tricks.
#
#	For example, to start all Postfix instances, use:
# .IP
#	# postfix start
# .PP
#	Other postfix(1) commands also work as expected. For example,
#	to find out what Postfix instances exist in a multi-instance
#	configuration, use:
# .IP
#	# postfix status
# .PP
#	This enumerates the status of all Postfix instances within
#	a multi-instance configuration.
# MANAGING AN INDIVIDUAL POSTFIX INSTANCE
# .ad
# .fi
#	To manage a specific Postfix instance, specify its configuration
#	directory on the postfix(1) command line:
# .IP
#	# postfix -c \fI/path/to/config_directory command\fR
# .PP
#	Alternatively, the postfix(1) command accepts the instance's
#	configuration directory via the MAIL_CONFIG environment
#	variable (the -c command-line option has higher precedence).
#
#	Otherwise, the postfix(1) command will operate on all Postfix
#	instances.
# ENABLING POSTFIX(1) MULTI-INSTANCE MODE
# .ad
# .fi
#	By default, the postfix(1) command operates in single-instance
#	mode. In this mode the command invokes the postfix-script
#	file directly (currently installed in the daemon directory).
#	This file contains the commands that start or stop one
#	Postfix instance, that upgrade the configuration of one
#	Postfix instance, and so on.
#
#	When the postfix(1) command operates in multi-instance mode
#	as discussed below, the command needs to execute start,
#	stop, etc.  commands for each Postfix instance.  This
#	multiplication of commands is handled by a multi-instance
#	manager program.
#
#	Turning on postfix(1) multi-instance mode goes as follows:
#	in the default Postfix instance's main.cf file, 1) specify
#	the pathname of a multi-instance manager program with the
#	multi_instance_wrapper parameter; 2) populate the
#	multi_instance_directories parameter with the configuration
#	directory pathnames of additional Postfix instances.  For
#	example:
# .IP
# .nf
#	/etc/postfix/main.cf:
#	    multi_instance_wrapper = $daemon_directory/postfix-wrapper
#	    multi_instance_directories = /etc/postfix-test
# .fi
# .PP
#	The $daemon_directory/postfix-wrapper file implements a
#	simple manager and contains instructions for creating Postfix
#	instances by hand.  The postmulti(1) command provides a
#	more extensive implementation including support for life-cycle
#	management.
#
#	The multi_instance_directories and other main.cf parameters
#	are listed below in the CONFIGURATION PARAMETERS section.
#
#	In multi-instance mode, the postfix(1) command invokes the
#	$multi_instance_wrapper command instead of the postfix-script
#	file. This multi-instance manager in turn executes the
#	postfix(1) command in single-instance mode for each Postfix
#	instance.
#
#	To illustrate the main ideas behind multi-instance operation,
#	below is an example of a simple but useful multi-instance
#	manager implementation:
# .IP
# .nf
#	#!/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\`" \e
#		    = yes || continue;;
#	    start)
#		test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e
#		    = yes || {
#		    $POSTFIX -c $dir check || err=$?
#		    continue
#		};;
#	    esac
#	    $POSTFIX -c $dir "$@" || err=$?
#	done
#
#	exit $err
# .fi
# PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS
# .ad
# .fi
#	Each Postfix instance has its own main.cf file with parameters
#	that control how the multi-instance manager operates on
#	that instance.  This section discusses the most important
#	settings.
#
#	The setting "multi_instance_enable = yes" allows the
#	multi-instance manager to start (stop, etc.) the corresponding
#	Postfix instance. For safety reasons, this setting is not
#	the default.
#
#	The default setting "multi_instance_enable = no" is useful
#	for manual testing with "postfix -c \fI/path/name\fR start"
#	etc.  The multi-instance manager will not start such an
#	instance, and it will skip commands such as "stop" or "flush"
#	that require a running Postfix instance.  The multi-instance
#	manager will execute commands such as "check", "set-permissions"
#	or "upgrade-configuration", and it will replace "start" by
#	"check" so that problems will be reported even when the
#	instance is disabled.
# MAINTAINING SHARED AND NON-SHARED FILES
# .ad
# .fi
#	Some files are shared between Postfix instances, such as
#	executables and manpages, and some files are per-instance,
#	such as configuration files, mail queue files, and data
#	files.  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 maintained
#	as part of the default Postfix instance. 
#
#	With multi-instance support, we simply continue to do this.
#	Specifically, a Postfix instance will not check or update
#	shared files when that instance's config_directory value is
#	listed with the default main.cf file's multi_instance_directories
#	parameter.
#
#	The consequence of this approach is that the default Postfix
#	instance should be checked and updated before any other
#	instances.
# MULTI-INSTANCE API SUMMARY
# .ad
# .fi
#	Only the multi-instance manager implements support for the
#	multi_instance_enable configuration parameter. The
#	multi-instance manager will start only Postfix instances
#	whose main.cf file has "multi_instance_enable = yes". A
#	setting of "no" allows a Postfix instance to be tested by
#	hand.
#
#	The postfix(1) command operates on only one Postfix instance
#	when the -c option is specified, or when MAIL_CONFIG is
#	present in the process environment. This is necessary to
#	terminate recursion.
#
#	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's main.cf file does not
#	have "multi_instance_enable = yes". This substitution ensures
#	that problems will be reported even when the instance is
#	disabled.
#
#	No Postfix command or script will update or check shared
#	files when its config_directory value is listed in the
#	default main.cf's multi_instance_directories parameter
#	value.  Therefore, the default instance should be checked
#	and updated before any Postfix instances that depend on it.
#
#	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
# .ad
# .fi
# .IP 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
# .ad
# .fi
#	The text below provides only a parameter summary. See
#	postconf(5) for more details.
# .IP "\fBmulti_instance_directories (empty)\fR"
#	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.
# .IP "\fBmulti_instance_wrapper (empty)\fR"
#	The pathname of a multi-instance manager command that the
#	\fBpostfix\fR(1) command invokes when the multi_instance_directories
#	parameter value is non-empty.
# .IP "\fBmulti_instance_name (empty)\fR"
#	The optional instance name of this Postfix instance.
# .IP "\fBmulti_instance_group (empty)\fR"
#	The optional instance group name of this Postfix instance.
# .IP "\fBmulti_instance_enable (no)\fR"
#	Allow this Postfix instance to be started, stopped, etc., by a
#	multi-instance manager.
# NON-SHARED FILES
# .ad
# .fi
# .IP "\fBconfig_directory (see 'postconf -d' output)\fR"
#	The default location of the Postfix main.cf and master.cf
#	configuration files.
# .IP "\fBdata_directory (see 'postconf -d' output)\fR"
#	The directory with Postfix-writable data files (for example:
#	caches, pseudo-random numbers).
# .IP "\fBqueue_directory (see 'postconf -d' output)\fR"
#	The location of the Postfix top-level queue directory.
# SEE ALSO
#	postfix(1) Postfix control program
#	postmulti(1) full-blown multi-instance manager
#	$daemon_directory/postfix-wrapper simple multi-instance manager
# LICENSE
# .ad
# .fi
#	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
#
#	Wietse Venema
#	Google, Inc.
#	111 8th Avenue
#	New York, NY 10011, USA
#--