    POSTFIX-WRAPPER(5)                                          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  mul-
           tiple  Postfix instances. A trivial but useful implementa-
           tion, with instructions, can be  found  in  $daemon_direc-
           tory/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, includ-
           ing executable files and documentation, are shared between
           Postfix instances.

           Only the default Postfix instance is required.  The  loca-
           tion 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 Post-
           fix 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 con-
           figured:

                  # 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 envi-
           ronment.

           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 Post-
           fix 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  parame-
           ters are listed below in the CONFIGURATION PARAMETERS sec-
           tion.

           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  sin-
           gle-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 dis-
           abled.

    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 Post-
           fix 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_directo-
           ries 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  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   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 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
           $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

                                                                POSTFIX-WRAPPER(5)