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