external/ibm-public/postfix/dist/html/postfix-wrapper.5.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3 <html> <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   5 <title> Postfix manual - postfix-wrapper(5) </title>
   6 </head> <body> <pre>
   7 POSTFIX-WRAPPER(5)                                          POSTFIX-WRAPPER(5)
   8
   9 <b>NAME</b>
  10        postfix-wrapper - Postfix multi-instance API
  11
  12 <b>DESCRIPTION</b>
  13        Postfix  versions 2.6 and later provide support for multi-
  14        ple Postfix instances. Instances  share  executable  files
  15        and documentation, but have their own directories for con-
  16        figuration, queue and data files.
  17
  18        This document describes how the familiar  "postfix  start"
  19        etc.  user interface can be used to manage one or multiple
  20        Postfix instances, and gives details of an API to  coordi-
  21        nate  activities  between  the  <a href="postfix.1.html">postfix(1)</a>  command  and a
  22        multi-instance manager program.
  23
  24        With multi-instance support, the default Postfix  instance
  25        is   always  required.  The  <a href="postconf.5.html#config_directory">config_directory</a>  parameter's
  26        default value specifies that instance's configuration file
  27        location.
  28
  29 <b>GENERAL OPERATION</b>
  30        Multi-instance  support  is backwards compatible: when you
  31        run only one Postfix instance, commands such  as  "postfix
  32        start" will not change behavior at all.
  33
  34        Even  with  multiple Postfix instances, you can keep using
  35        the same postfix commands in boot scripts, upgrade  proce-
  36        dures,  and  other  places. The commands do more work, but
  37        humans are not forced to learn new tricks.
  38
  39        For example, to start all Postfix instances, use:
  40
  41               # postfix start
  42
  43        Other <a href="postfix.1.html">postfix(1)</a> commands also work as expected. For exam-
  44        ple,  to find out what Postfix instances exist in a multi-
  45        instance configuration, use:
  46
  47               # postfix status
  48
  49        This enumerates the status of all Postfix instances within
  50        a multi-instance configuration.
  51
  52 <b>MANAGING AN INDIVIDUAL POSTFIX INSTANCE</b>
  53        To manage a specific Postfix instance, specify its config-
  54        uration directory on the <a href="postfix.1.html">postfix(1)</a> command line:
  55
  56               # postfix -c <i>/path/to/config</i><b>_</b><i>directory command</i>
  57
  58        Alternatively,  the   <a href="postfix.1.html">postfix(1)</a>   command   accepts   the
  59        instance's  configuration  directory  via  the MAIL_CONFIG
  60        environment  variable  (the  -c  command-line  option  has
  61        higher precedence).
  62
  63        When  no  Postfix  instance  information is specified, the
  64        <a href="postfix.1.html">postfix(1)</a> command will operate on all Postfix  instances.
  65
  66 <b>ENABLING POSTFIX(1) MULTI-INSTANCE MODE</b>
  67        By  default,  the  <a href="postfix.1.html">postfix(1)</a>  command operates in single-
  68        instance mode. In this mode the command invokes the  post-
  69        fix-script  file directly (currently installed in the dae-
  70        mon directory).  This  file  contains  the  commands  that
  71        start  or stop one Postfix instance, that upgrade the con-
  72        figuration of one Postfix instance, and so on.
  73
  74        When the <a href="postfix.1.html">postfix(1)</a>  command  operates  in  multi-instance
  75        mode  as  discussed  below,  the  command needs to execute
  76        start, stop, etc.  commands  for  each  Postfix  instance.
  77        This  multiplication  of  commands  is handled by a multi-
  78        instance manager program.
  79
  80        Turning on <a href="postfix.1.html">postfix(1)</a> multi-instance mode goes as follows:
  81        in the default Postfix instance's <a href="postconf.5.html">main.cf</a> file, 1) specify
  82        the pathname of a multi-instance manager program with  the
  83        <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a>    parameter;   2)   populate   the
  84        <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter with  the  configura-
  85        tion  directory pathnames of additional Postfix instances.
  86        For example:
  87
  88               /etc/postfix/<a href="postconf.5.html">main.cf</a>:
  89                   <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper
  90                   <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> = /etc/postfix-test
  91
  92        The $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper  file  implements  a
  93        simple  manager  and  contains  instructions  for creating
  94        Postfix instances by hand.  The <a href="postmulti.1.html">postmulti(1)</a> command  pro-
  95        vides  a  more  extensive implementation including support
  96        for life-cycle management.
  97
  98        The <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> and other  <a href="postconf.5.html">main.cf</a>  parame-
  99        ters are listed below in the CONFIGURATION PARAMETERS sec-
 100        tion.
 101
 102        In multi-instance mode, the <a href="postfix.1.html">postfix(1)</a> command invokes the
 103        $<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a>  command  instead  of the postfix-
 104        script file. This multi-instance manager in turn  executes
 105        the  <a href="postfix.1.html">postfix(1)</a>  command  in single-instance mode for each
 106        Postfix instance.
 107
 108        To illustrate the main ideas behind multi-instance  opera-
 109        tion,  below  is  an example of a simple but useful multi-
 110        instance manager implementation:
 111
 112               #!/bin/sh
 113
 114               : ${<a href="postconf.5.html#command_directory">command_directory</a>?"do not invoke this command directly"}
 115
 116               POSTCONF=$<a href="postconf.5.html#command_directory">command_directory</a>/postconf
 117               POSTFIX=$<a href="postconf.5.html#command_directory">command_directory</a>/postfix
 118               instance_dirs=`$POSTCONF -h <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> |
 119                               sed 's/,/ /'` || exit 1
 120
 121               err=0
 122               for dir in $<a href="postconf.5.html#config_directory">config_directory</a> $instance_dirs
 123               do
 124                   case "$1" in
 125                   stop|abort|flush|reload|drain)
 126                       test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
 127                           = yes || continue;;
 128                   start)
 129                       test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
 130                           = yes || {
 131                           $POSTFIX -c $dir check || err=$?
 132                           continue
 133                       };;
 134                   esac
 135                   $POSTFIX -c $dir "$@" || err=$?
 136               done
 137
 138               exit $err
 139
 140 <b>PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS</b>
 141        Each Postfix instance has its own <a href="postconf.5.html">main.cf</a> file with param-
 142        eters that control how the multi-instance manager operates
 143        on that instance.  This section discusses the most  impor-
 144        tant settings.
 145
 146        The  setting  "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  =  yes"  allows  the
 147        multi-instance manager to start (stop,  etc.)  the  corre-
 148        sponding  Postfix  instance. For safety reasons, this set-
 149        ting is not the default.
 150
 151        The default setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no" is useful
 152        for manual testing with "postfix -c <i>/path/name</i> start" etc.
 153        The  multi-instance  manager  will  not  start   such   an
 154        instance,  and  it  will  skip  commands such as "stop" or
 155        "flush" that require  a  running  Postfix  instance.   The
 156        multi-instance  manager  will  execute  commands  such  as
 157        "check", "set-permissions" or "upgrade-configuration", and
 158        it  will  replace "start" by "check" so that problems will
 159        be reported even when the instance is disabled.
 160
 161 <b>MAINTAINING SHARED AND NON-SHARED FILES</b>
 162        Some files are shared between Postfix instances,  such  as
 163        executables and manpages, and some files are per-instance,
 164        such as configuration files, mail queue  files,  and  data
 165        files.   See the NON-SHARED FILES section below for a list
 166        of per-instance files.
 167
 168        Before Postfix multi-instance support was implemented, the
 169        executables,  manpages,  etc., have always been maintained
 170        as part of the default Postfix instance.
 171
 172        With multi-instance support,  we  simply  continue  to  do
 173        this.   Specifically, a Postfix instance will not check or
 174        update shared files when that instance's  <a href="postconf.5.html#config_directory">config_directory</a>
 175        value   is   listed   with   the  default  <a href="postconf.5.html">main.cf</a>  file's
 176        <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter.
 177
 178        The consequence of this approach is that the default Post-
 179        fix  instance  should  be  checked  and updated before any
 180        other instances.
 181
 182 <b>MULTI-INSTANCE API SUMMARY</b>
 183        Only the multi-instance manager implements support for the
 184        <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  configuration parameter. The multi-
 185        instance manager will start only Postfix  instances  whose
 186        <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
 187        of "no" allows a Postfix instance to be tested by hand.
 188
 189        The  <a href="postfix.1.html">postfix(1)</a>  command  operates  on  only  one  Postfix
 190        instance   when  the  -c  option  is  specified,  or  when
 191        MAIL_CONFIG is present in the process environment. This is
 192        necessary to terminate recursion.
 193
 194        Otherwise,  when  the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter
 195        value is non-empty, the <a href="postfix.1.html">postfix(1)</a>  command  executes  the
 196        command  specified with the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parame-
 197        ter, instead of executing the commands in  postfix-script.
 198
 199        The  multi-instance  manager skips commands such as "stop"
 200        or "reload" that require a running Postfix instance,  when
 201        an  instance  does not have "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes".
 202        This avoids false error messages.
 203
 204        The multi-instance manager replaces a "start"  command  by
 205        "check"  when  a  Postfix instance's <a href="postconf.5.html">main.cf</a> file does not
 206        have  "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  =  yes".  This  substitution
 207        ensures  that  problems  will  be  reported  even when the
 208        instance is disabled.
 209
 210        No Postfix command or script will update or  check  shared
 211        files  when  its  <a href="postconf.5.html#config_directory">config_directory</a>  value is listed in the
 212        default  <a href="postconf.5.html">main.cf</a>'s  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>   parameter
 213        value.   Therefore, the default instance should be checked
 214        and updated before any Postfix instances  that  depend  on
 215        it.
 216
 217        Set-gid  commands  such  as  <a href="postdrop.1.html">postdrop(1)</a>  and <a href="postqueue.1.html">postqueue(1)</a>
 218        effectively append the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  parame-
 219        ter   value  to  the  legacy  <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a>
 220        parameter value. The  commands  use  this  information  to
 221        determine  whether  a -c option or MAIL_CONFIG environment
 222        setting specifies a legitimate value.
 223
 224        The legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter  remains
 225        necessary  for non-default Postfix instances that are run-
 226        ning different versions of Postfix, or that are  not  man-
 227        aged together with the default Postfix instance.
 228
 229 <b>ENVIRONMENT VARIABLES</b>
 230        MAIL_CONFIG
 231               When present, this forces the <a href="postfix.1.html">postfix(1)</a> command to
 232               operate only on  the  specified  Postfix  instance.
 233               This  environment variable is exported by the <a href="postfix.1.html">post-</a>
 234               <a href="postfix.1.html">fix(1)</a> -c option, so that  <a href="postfix.1.html">postfix(1)</a>  commands  in
 235               descendant processes will work correctly.
 236
 237 <b>CONFIGURATION PARAMETERS</b>
 238        The  text  below  provides  only  a parameter summary. See
 239        <a href="postconf.5.html">postconf(5)</a> for more details.
 240
 241        <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b>
 242               An optional list of non-default Postfix  configura-
 243               tion directories; these directories belong to addi-
 244               tional Postfix instances  that  share  the  Postfix
 245               executable files and documentation with the default
 246               Postfix instance, and that  are  started,  stopped,
 247               etc., together with the default Postfix instance.
 248
 249        <b><a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> (empty)</b>
 250               The  pathname  of  a multi-instance manager command
 251               that  the  <a href="postfix.1.html"><b>postfix</b>(1)</a>  command  invokes  when   the
 252               <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  parameter value is non-
 253               empty.
 254
 255        <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b>
 256               The  optional  instance  name   of   this   Postfix
 257               instance.
 258
 259        <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b>
 260               The  optional  instance  group name of this Postfix
 261               instance.
 262
 263        <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b>
 264               Allow this Postfix instance to be started, stopped,
 265               etc., by a multi-instance manager.
 266
 267 <b>NON-SHARED FILES</b>
 268        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 269               The  default  location  of  the Postfix <a href="postconf.5.html">main.cf</a> and
 270               <a href="master.5.html">master.cf</a> configuration files.
 271
 272        <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b>
 273               The directory with Postfix-writable data files (for
 274               example: caches, pseudo-random numbers).
 275
 276        <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
 277               The  location of the Postfix top-level queue direc-
 278               tory.
 279
 280 <b>SEE ALSO</b>
 281        <a href="postfix.1.html">postfix(1)</a> Postfix control program
 282        <a href="postmulti.1.html">postmulti(1)</a> full-blown multi-instance manager
 283        $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper simple multi-instance manager
 284
 285 <b>LICENSE</b>
 286        The Secure Mailer license must be  distributed  with  this
 287        software.
 288
 289 <b>AUTHOR(S)</b>
 290        Wietse Venema
 291        IBM T.J. Watson Research
 292        P.O. Box 704
 293        Yorktown Heights, NY 10598, USA
 294
 295                                                             POSTFIX-WRAPPER(5)
 296 </pre> </body> </html>