dist/html/postfix-wrapper.5.html

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html> <head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title> Postfix manual - postfix-wrapper(5) </title>
</head> <body> <pre>
POSTFIX-WRAPPER(5)                                          POSTFIX-WRAPPER(5)

<b>NAME</b>
       postfix-wrapper - Postfix multi-instance API

<b>DESCRIPTION</b>
       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 to  coordi-
       nate  activities  between  the  <a href="postfix.1.html">postfix(1)</a>  command  and a
       multi-instance manager program.

       With multi-instance support, the default Postfix  instance
       is   always  required.  The  <a href="postconf.5.html#config_directory">config_directory</a>  parameter's
       default value specifies that instance's configuration file
       location.

<b>GENERAL OPERATION</b>
       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  proce-
       dures,  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:

              # postfix start

       Other <a href="postfix.1.html">postfix(1)</a> 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.

<b>MANAGING AN INDIVIDUAL POSTFIX INSTANCE</b>
       To manage a specific Postfix instance, specify its config-
       uration directory on the <a href="postfix.1.html">postfix(1)</a> command line:

              # postfix -c <i>/path/to/config</i><b>_</b><i>directory command</i>

       Alternatively,  the   <a href="postfix.1.html">postfix(1)</a>   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
       <a href="postfix.1.html">postfix(1)</a> command will operate on all Postfix  instances.

<b>ENABLING POSTFIX(1) MULTI-INSTANCE MODE</b>
       By  default,  the  <a href="postfix.1.html">postfix(1)</a>  command operates in single-
       instance mode. In this mode the command invokes the  post-
       fix-script  file directly (currently installed in the dae-
       mon directory).  This  file  contains  the  commands  that
       start  or stop one Postfix instance, that upgrade the con-
       figuration of one Postfix instance, and so on.

       When the <a href="postfix.1.html">postfix(1)</a>  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 <a href="postfix.1.html">postfix(1)</a> multi-instance mode goes as follows:
       in the default Postfix instance's <a href="postconf.5.html">main.cf</a> file, 1) specify
       the pathname of a multi-instance manager program with  the
       <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a>    parameter;   2)   populate   the
       <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter with  the  configura-
       tion  directory pathnames of additional Postfix instances.
       For example:

              /etc/postfix/<a href="postconf.5.html">main.cf</a>:
                  <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper
                  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> = /etc/postfix-test

       The $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper  file  implements  a
       simple  manager  and  contains  instructions  for creating
       Postfix instances by hand.  The <a href="postmulti.1.html">postmulti(1)</a> command  pro-
       vides  a  more  extensive implementation including support
       for life-cycle management.

       The <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> and other  <a href="postconf.5.html">main.cf</a>  parame-
       ters are listed below in the CONFIGURATION PARAMETERS sec-
       tion.

       In multi-instance mode, the <a href="postfix.1.html">postfix(1)</a> command invokes the
       $<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a>  command  instead  of the postfix-
       script file. This multi-instance manager in turn  executes
       the  <a href="postfix.1.html">postfix(1)</a>  command  in single-instance mode for each
       Postfix instance.

       To illustrate the main ideas behind multi-instance  opera-
       tion,  below  is  an example of a simple but useful multi-
       instance manager implementation:

              #!/bin/sh

              : ${<a href="postconf.5.html#command_directory">command_directory</a>?"do not invoke this command directly"}

              POSTCONF=$<a href="postconf.5.html#command_directory">command_directory</a>/postconf
              POSTFIX=$<a href="postconf.5.html#command_directory">command_directory</a>/postfix
              instance_dirs=`$POSTCONF -h <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> |
                              sed 's/,/ /'` || exit 1

              err=0
              for dir in $<a href="postconf.5.html#config_directory">config_directory</a> $instance_dirs
              do
                  case "$1" in
                  stop|abort|flush|reload|drain)
                      test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
                          = yes || continue;;
                  start)
                      test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
                          = yes || {
                          $POSTFIX -c $dir check || err=$?
                          continue
                      };;
                  esac
                  $POSTFIX -c $dir "$@" || err=$?
              done

              exit $err

<b>PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS</b>
       Each Postfix instance has its own <a href="postconf.5.html">main.cf</a> file with param-
       eters that control how the multi-instance manager operates
       on that instance.  This section discusses the most  impor-
       tant settings.

       The  setting  "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  =  yes"  allows  the
       multi-instance manager to start (stop,  etc.)  the  corre-
       sponding  Postfix  instance. For safety reasons, this set-
       ting is not the default.

       The default setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no" is useful
       for manual testing with "postfix -c <i>/path/name</i> 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.

<b>MAINTAINING SHARED AND NON-SHARED FILES</b>
       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  <a href="postconf.5.html#config_directory">config_directory</a>
       value   is   listed   with   the  default  <a href="postconf.5.html">main.cf</a>  file's
       <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter.

       The consequence of this approach is that the default Post-
       fix  instance  should  be  checked  and updated before any
       other instances.

<b>MULTI-INSTANCE API SUMMARY</b>
       Only the multi-instance manager implements support for the
       <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  configuration parameter. The multi-
       instance manager will start only Postfix  instances  whose
       <a href="postconf.5.html">main.cf</a>  file has "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". A setting
       of "no" allows a Postfix instance to be tested by hand.

       The  <a href="postfix.1.html">postfix(1)</a>  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 <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter
       value is non-empty, the <a href="postfix.1.html">postfix(1)</a>  command  executes  the
       command  specified with the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> 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 "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes".
       This avoids false error messages.

       The multi-instance manager replaces a "start"  command  by
       "check"  when  a  Postfix instance's <a href="postconf.5.html">main.cf</a> file does not
       have  "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  =  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  <a href="postconf.5.html#config_directory">config_directory</a>  value is listed in the
       default  <a href="postconf.5.html">main.cf</a>'s  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>   parameter
       value.   Therefore, the default instance should be checked
       and updated before any Postfix instances  that  depend  on
       it.

       Set-gid  commands  such  as  <a href="postdrop.1.html">postdrop(1)</a>  and <a href="postqueue.1.html">postqueue(1)</a>
       effectively append the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  parame-
       ter   value  to  the  legacy  <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a>
       parameter value. The  commands  use  this  information  to
       determine  whether  a -c option or MAIL_CONFIG environment
       setting specifies a legitimate value.

       The legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> 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.

<b>ENVIRONMENT VARIABLES</b>
       MAIL_CONFIG
              When present, this forces the <a href="postfix.1.html">postfix(1)</a> command to
              operate only on  the  specified  Postfix  instance.
              This  environment variable is exported by the <a href="postfix.1.html">post-</a>
              <a href="postfix.1.html">fix(1)</a> -c option, so that  <a href="postfix.1.html">postfix(1)</a>  commands  in
              descendant processes will work correctly.

<b>CONFIGURATION PARAMETERS</b>
       The  text  below  provides  only  a parameter summary. See
       <a href="postconf.5.html">postconf(5)</a> for more details.

       <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b>
              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.

       <b><a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> (empty)</b>
              The  pathname  of  a multi-instance manager command
              that  the  <a href="postfix.1.html"><b>postfix</b>(1)</a>  command  invokes  when   the
              <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  parameter value is non-
              empty.

       <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b>
              The  optional  instance  name   of   this   Postfix
              instance.

       <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b>
              The  optional  instance  group name of this Postfix
              instance.

       <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b>
              Allow this Postfix instance to be started, stopped,
              etc., by a multi-instance manager.

<b>NON-SHARED FILES</b>
       <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
              The  default  location  of  the Postfix <a href="postconf.5.html">main.cf</a> and
              <a href="master.5.html">master.cf</a> configuration files.

       <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b>
              The directory with Postfix-writable data files (for
              example: caches, pseudo-random numbers).

       <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
              The  location of the Postfix top-level queue direc-
              tory.

<b>SEE ALSO</b>
       <a href="postfix.1.html">postfix(1)</a> Postfix control program
       <a href="postmulti.1.html">postmulti(1)</a> full-blown multi-instance manager
       $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper simple multi-instance manager

<b>LICENSE</b>
       The Secure Mailer license must be  distributed  with  this
       software.

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

                                                            POSTFIX-WRAPPER(5)
</pre> </body> </html>