    POSTFIX-WRAPPER(5)                                          POSTFIX-WRAPPER(5)

    NAME
           postfix-wrapper - Postfix multi-instance API

    DESCRIPTION
           Postfix  versions 2.6 and later provide support for multi-
           ple Postfix instances. Instances  share  executable  files
           and documentation, but have their own directories for con-
           figuration, 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 that allows
           the  postfix(1)  command  to  coordinate activities with a
           multi-instance manager program.

           A trivial but useful multi-instance manager implementation
           is  described  below,  and  can be found in the file $dae-
           mon_directory/postfix-wrapper. The latter file  also  con-
           tains instructions for setting up multiple instances.

           With  multi-instance support, the default Postfix instance
           is required. The location of its  configuration  files  is
           specified  by  the  built-in  default  value  for the con-
           fig_directory parameter.

    GENERAL OPERATION
           Multi-instance support is backwards compatible: when there
           is  only  one  Postfix instance, commands such as "postfix
           start" keep doing what they have always done.

           Even after multi-instance support has been set up  through
           the  mechanisms discussed later, sites can continue to use
           the familiar postfix commands  in  boot  scripts,  upgrade
           procedures, and other places.

           To start all applicable Postfix instances, use:

                  # postfix start

           Other postfix(1) commands also work as expected. For exam-
           ple, to find out what Postfix instances exist in a  multi-
           instance configuration, use:

                  # postfix status

           This enumerates the status of all Postfix instances within
           a multi-instance configuration.

    MANAGING AN INDIVIDUAL POSTFIX INSTANCE
           To operate on a specific  Postfix  instance,  specify  its
           configuration directory on the postfix(1) command line:

                  # postfix -c /path/to/config_directory command

           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).

           When no Postfix instance  information  is  specified,  the
           postfix(1)  command will operate on all applicable Postfix
           instances.

    MULTI-INSTANCE MANAGER IMPLEMENTATION
           Historically, the postfix(1) command invokes the  postfix-
           script file (currently installed in the daemon directory).
           This file contains the commands that start or  stop  Post-
           fix, upgrade the configuration and so on.

           When  multi-instance  support is turned on, the postfix(1)
           command needs to execute these commands for each  applica-
           ble  Postfix  instance. This multiplication of commands is
           handled by a multi-instance manager program.

           Turning on multi-instance support goes as follows:  update
           the  default Postfix instance's main.cf file, and populate
           the multi_instance_directories parameter with the configu-
           ration   directory   pathnames   of   additional   Postfix
           instances.

           With multi-instance support turned on, the postfix(1) com-
           mand  invokes  a multi-instance manager command instead of
           the postfix-script file. The multi-instance  manager  exe-
           cutes  the  postfix(1) command for each applicable Postfix
           instance.  The pathname of the multi-instance  manager  is
           specified   in   the   default   main.cf   file  with  the
           multi_instance_wrapper parameter.

           The multi_instance_directories and other  main.cf  parame-
           ters are listed below in the CONFIGURATION PARAMETERS sec-
           tion.

           A useful multi-instance manager 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 || {
                              $POSTFIX -c $dir check || err=$?
                              continue
                          };;
                      esac
                      $POSTFIX -c $dir "$@" || err=$?
                  done

                  exit $err

           A  sample  implementation, with instructions, can be found
           in $daemon_directory/postfix-wrapper.

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

    ENABLING A SPECIFIC INSTANCE FOR MULTI-INSTANCE OPERATION
           Each Postfix instance has its own main.cf file with param-
           eters  that  control  multi-instance  operation.  The most
           important settings are discussed here.

           The  setting  "multi_instance_enable  =  yes"  allows  the
           multi-instance manager to start (and stop) the correspond-
           ing Postfix instance. For safety reasons, this setting  is
           not the default.

           The  setting  "multi_instance_enable  =  no" is useful for
           manual testing.  With  this,  the  multi-instance  manager
           will not start the Postfix instance, and it will skip com-
           mands 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.

    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  directory.  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.

           Specifically,  Postfix  instances will not check or update
           shared files when their config_directory value  is  listed
           with   the  default  main.cf's  multi_instance_directories
           parameter.

           The consequence of this approach is that the default Post-
           fix  instance  should  be  checked  and 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 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 parame-
           ter, 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  parame-
           ter   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 run-
           ning different versions of Postfix, or that are  not  man-
           aged 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 post-
                  fix(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  configura-
                  tion directories; these directories belong to addi-
                  tional 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 direc-
                  tory.

    SEE ALSO
           postfix(1) Postfix control program
           postmulti(1) full-blown multi-instance manager
           $daemon_directory/postfix-wrapper simple 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

                                                                POSTFIX-WRAPPER(5)