postfix-wrapper.5.html   [plain text]

<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
<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)

       postfix-wrapper - Postfix multi-instance API

       Support  for managing multiple Postfix instances is avail-
       able as of version 2.6. 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.  This  instance is identified by the
       <a href="postconf.5.html#config_directory">config_directory</a> parameter's default value.

       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.

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

       Otherwise, the <a href="postfix.1.html">postfix(1)</a>  command  will  operate  on  all
       Postfix instances.

       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"></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"></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"></a>  parame-
       ters are listed below in the CONFIGURATION PARAMETERS sec-

       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:


              : ${<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

              for dir in $<a href="postconf.5.html#config_directory">config_directory</a> $instance_dirs
                  case "$1" in
                      test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
                          = yes || continue;;
                      test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
                          = yes || {
                          $POSTFIX -c $dir check || err=$?
                  $POSTFIX -c $dir "$@" || err=$?

              exit $err

       Each Postfix instance has its own <a href="postconf.5.html"></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.

       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"></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.

       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"></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"></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"></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

       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.

              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.

       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-

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

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

       <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><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"></a> and
              <a href="master.5.html"></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-

<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

       The Secure Mailer license must be  distributed  with  this

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

</pre> </body> </html>