external/ibm-public/postfix/dist/html/postmulti.1.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 - postmulti(1) </title>
   6 </head> <body> <pre>
   7 POSTMULTI(1)                                                      POSTMULTI(1)
   8
   9 <b>NAME</b>
  10        postmulti - Postfix multi-instance manager
  11
  12 <b>SYNOPSIS</b>
  13        <b>postmulti -l</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>]
  14
  15        <b>postmulti -p</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>command...</i>
  16
  17        <b>postmulti -x</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>command...</i>
  18
  19        <b>postmulti -e init</b> [<b>-v</b>]
  20
  21        <b>postmulti -e create</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] [<b>-G</b> <i>group</i>]
  22        [<b>-I</b> <i>name</i>] [<i>param=value</i> ...]
  23
  24        <b>postmulti -e import</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] [<b>-G</b> <i>group</i>]
  25        [<b>-I</b> <i>name</i>] [<b><a href="postconf.5.html#config_directory">config_directory</a>=</b><i>/path</i>]
  26
  27        <b>postmulti -e destroy</b> [<b>-v</b>] <b>-i</b> <i>name</i>
  28
  29        <b>postmulti -e deport</b> [<b>-v</b>] <b>-i</b> <i>name</i>
  30
  31        <b>postmulti -e enable</b> [<b>-v</b>] <b>-i</b> <i>name</i>
  32
  33        <b>postmulti -e disable</b> [<b>-v</b>] <b>-i</b> <i>name</i>
  34
  35        <b>postmulti -e assign</b> [<b>-v</b>] <b>-i</b> <i>name</i> [<b>-I</b> <i>name</i>] [-G <i>group</i>]
  36
  37 <b>DESCRIPTION</b>
  38        The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command allows a Postfix administrator to
  39        manage multiple Postfix instances on a single host.
  40
  41        <a href="postmulti.1.html"><b>postmulti</b>(1)</a> implements two fundamental  modes  of  opera-
  42        tion.   In <b>iterator</b> mode, it executes the same command for
  43        multiple  Postfix  instances.   In  <b>life-cycle  management</b>
  44        mode,  it  adds  or  deletes  one instance, or changes the
  45        multi-instance status of one instance.
  46
  47        Each mode of operation has its  own  command  syntax.  For
  48        this  reason, each mode is documented in separate sections
  49        below.
  50
  51 <b>BACKGROUND</b>
  52        A multi-instance configuration  consists  of  one  primary
  53        Postfix  instance,  and  one  or  more secondary instances
  54        whose configuration directory pathnames  are  recorded  in
  55        the  primary  instance's  <a href="postconf.5.html">main.cf</a>  file. Postfix instances
  56        share program files and documentation, but have their  own
  57        configuration, queue and data directories.
  58
  59        Currently,  only  the default Postfix instance can be used
  60        as primary instance in a multi-instance configuration. The
  61        <a href="postmulti.1.html"><b>postmulti</b>(1)</a>  command  does  not  currently  support  a <b>-c</b>
  62        option to select  an  alternative  primary  instance,  and
  63        exits  with  a  fatal error if the <b>MAIL_CONFIG</b> environment
  64        variable is set to a non-default configuration  directory.
  65
  66        See the <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a> tutorial for a more detailed
  67        discussion of multi-instance management with <a href="postmulti.1.html"><b>postmulti</b>(1)</a>.
  68
  69 <b>ITERATOR MODE</b>
  70        In iterator mode, <b>postmulti</b> performs the same operation on
  71        all Postfix instances in turn.
  72
  73        If multi-instance support is not  enabled,  the  requested
  74        command is performed just for the primary instance.
  75
  76        Iterator mode implements the following command options:
  77
  78 <b>Instance selection</b>
  79        <b>-a</b>     Perform the operation on all instances. This is the
  80               default.
  81
  82        <b>-g</b> <i>group</i>
  83               Perform the operation only for members of the named
  84               <i>group</i>.
  85
  86        <b>-i</b> <i>name</i>
  87               Perform  the  operation  only for the instance with
  88               the specified <i>name</i>.  You  can  specify  either  the
  89               instance  name  or  the  absolute  pathname  of the
  90               instance's configuration directory.  Specify "-" to
  91               select the primary Postfix instance.
  92
  93        <b>-R</b>     Reverse  the iteration order. This may be appropri-
  94               ate when updating a  multi-instance  system,  where
  95               "sink"   instances   are  started  before  "source"
  96               instances.
  97
  98               This option cannot be used with <b>-p</b>.
  99
 100 <b>List mode</b>
 101        <b>-l</b>     List Postfix instances with  their  instance  name,
 102               instance group name, enable/disable status and con-
 103               figuration directory.
 104
 105 <b>Postfix-wrapper mode</b>
 106        <b>-p</b>     Invoke <a href="postfix.1.html"><b>postfix(1)</a></b> to execute the specified <i>command</i>.
 107               This   option   implements  the  <a href="postfix-wrapper.5.html"><b>postfix-wrapper</b>(5)</a>
 108               interface.
 109
 110               <b>o</b>      With "start"-like commands, "postfix  check"
 111                      is  executed  for  instances  that  are  not
 112                      enabled. The full list of commands is speci-
 113                      fied   with   the   <a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a>
 114                      parameter.
 115
 116               <b>o</b>      With  "stop"-like  commands,  the  iteration
 117                      order  is  reversed,  and disabled instances
 118                      are skipped. The full list  of  commands  is
 119                      specified  with  the <a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a>
 120                      parameter.
 121
 122               <b>o</b>      With  "reload"  and  other   commands   that
 123                      require   a   started   instance,   disabled
 124                      instances are skipped. The full list of com-
 125                      mands  is  specified with the <a href="postconf.5.html#postmulti_control_commands">postmulti_con</a>-
 126                      <a href="postconf.5.html#postmulti_control_commands">trol_commands</a> parameter.
 127
 128               <b>o</b>      With "status" and other commands that  don't
 129                      require  a  started instance, the command is
 130                      executed for all instances.
 131
 132               The <b>-p</b> option can also  be  used  interactively  to
 133               start/stop/etc.    a  named  instance  or  instance
 134               group. For example, to start just the instances  in
 135               the group "msa", invoke <a href="postmulti.1.html"><b>postmulti</b>(1)</a> as follows:
 136
 137                      # postmulti -g msa -p start
 138
 139 <b>Command mode</b>
 140        <b>-x</b>     Execute  the  specified  <i>command</i>  for  all  Postfix
 141               instances.  The command runs with appropriate envi-
 142               ronment  settings  for  MAIL_CONFIG, <a href="postconf.5.html#command_directory">command_direc</a>-
 143               <a href="postconf.5.html#command_directory">tory</a>,      <a href="postconf.5.html#daemon_directory">daemon_directory</a>,      <a href="postconf.5.html#config_directory">config_directory</a>,
 144               <a href="postconf.5.html#queue_directory">queue_directory</a>,                    <a href="postconf.5.html#data_directory">data_directory</a>,
 145               <a href="postconf.5.html#multi_instance_name">multi_instance_name</a>,    <a href="postconf.5.html#multi_instance_group">multi_instance_group</a>    and
 146               <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>.
 147
 148 <b>Other options</b>
 149        <b>-v</b>     Enable verbose logging for debugging purposes. Mul-
 150               tiple <b>-v</b> options  make  the  software  increasingly
 151               verbose.
 152
 153 <b>LIFE-CYCLE MANAGEMENT MODE</b>
 154        With  the  <b>-e</b>  option  <a href="postmulti.1.html"><b>postmulti</b>(1)</a>  can be used to add or
 155        delete a  Postfix  instance,  and  to  manage  the  multi-
 156        instance status of an existing instance.
 157
 158        The following options are implemented:
 159
 160 <b>Existing instance selection</b>
 161        <b>-a</b>     When  creating  or importing an instance, place the
 162               new instance at the front of the secondary instance
 163               list.
 164
 165        <b>-g</b> <i>group</i>
 166               When  creating  or importing an instance, place the
 167               new instance before the  first  secondary  instance
 168               that is a member of the specified group.
 169
 170        <b>-i</b> <i>name</i>
 171               When  creating  or importing an instance, place the
 172               new  instance   before   the   matching   secondary
 173               instance.
 174
 175               With  other life-cycle operations, apply the opera-
 176               tion to the named existing instance.   Specify  "-"
 177               to select the primary Postfix instance.
 178
 179 <b>New or existing instance name assignment</b>
 180        <b>-I</b> <i>name</i>
 181               Assign  the  specified instance <i>name</i> to an existing
 182               instance,  newly-created  instance,   or   imported
 183               instance.   Instance  names  other  than "-" (which
 184               makes the  instance  "nameless")  must  start  with
 185               "postfix-".   This  restriction reduces the likeli-
 186               hood of name collisions with system files.
 187
 188        <b>-G</b> <i>group</i>
 189               Assign the specified  <i>group</i>  name  to  an  existing
 190               instance   or   to  a  newly  created  or  imported
 191               instance.
 192
 193 <b>Instance creation/deletion/status change</b>
 194        <b>-e</b> <i>action</i>
 195               "Edit" managed instances. The following actions are
 196               supported:
 197
 198               <b>init</b>   This command is required before <a href="postmulti.1.html"><b>postmulti</b>(1)</a>
 199                      can be used  to  manage  Postfix  instances.
 200                      The  "postmulti -e init" command updates the
 201                      primary instance's <a href="postconf.5.html">main.cf</a> file by setting:
 202
 203                             <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> =
 204                                     ${<a href="postconf.5.html#command_directory">command_directory</a>}/postmulti -p --
 205                             <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes
 206
 207                      You can set these by other means if you pre-
 208                      fer.
 209
 210               <b>create</b> Create  a new Postfix instance and add it to
 211                      the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter  of
 212                      the  primary instance.  The "<b>-I</b> <i>name</i>" option
 213                      is recommended to give the instance a  short
 214                      name  that is used to construct default val-
 215                      ues for the private directories of  the  new
 216                      instance. The "<b>-G</b> <i>group</i>" option may be spec-
 217                      ified to assign the  instance  to  a  group,
 218                      otherwise,  the new instance is not a member
 219                      of any groups.
 220
 221                      The  new  instance  <a href="postconf.5.html">main.cf</a>  is  the   stock
 222                      <a href="postconf.5.html">main.cf</a> with the parameters that specify the
 223                      locations of shared files  cloned  from  the
 224                      primary instance.  For "nameless" instances,
 225                      you should manually adjust "<a href="postconf.5.html#syslog_name">syslog_name</a>"  to
 226                      yield a unique "logtag" starting with "post-
 227                      fix-"  that  will  uniquely   identify   the
 228                      instance  in the mail logs. It is simpler to
 229                      assign the instance a short  name  with  the
 230                      "<b>-I</b> <i>name</i>" option.
 231
 232                      Optional  "name=value" arguments specify the
 233                      instance  <a href="postconf.5.html#config_directory">config_directory</a>,  <a href="postconf.5.html#queue_directory">queue_directory</a>
 234                      and <a href="postconf.5.html#data_directory">data_directory</a>.  For example:
 235
 236                             # postmulti -I postfix-mumble \
 237                                     -G mygroup -e create \
 238                                     <a href="postconf.5.html#config_directory">config_directory</a>=/my/config/dir \
 239                                     <a href="postconf.5.html#queue_directory">queue_directory</a>=/my/queue/dir \
 240                                     <a href="postconf.5.html#data_directory">data_directory</a>=/my/data/dir
 241
 242                      If  any  of these pathnames is not supplied,
 243                      the program attempts to generate  the  path-
 244                      name  by  taking  the  corresponding primary
 245                      instance pathname, and by replacing the last
 246                      pathname  component  by  the value of the <b>-I</b>
 247                      option.
 248
 249                      If  the  instance  configuration   directory
 250                      already  exists, and contains both a <a href="postconf.5.html">main.cf</a>
 251                      and <a href="master.5.html">master.cf</a> file, <b>create</b> will "import" the
 252                      instance as-is. For existing instances, <b>cre-</b>
 253                      <b>ate</b> and <b>import</b> are identical.
 254
 255               <b>import</b> Import an existing instance into the list of
 256                      instances managed by the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> multi-
 257                      instance manager.  This adds the instance to
 258                      the  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  list of the
 259                      primary instance.  If the "<b>-I</b>  <i>name</i>"  option
 260                      is  provided  it  specifies the new name for
 261                      the instance and is used to define a default
 262                      location   for  the  instance  configuration
 263                      directory (as with <b>create</b> above).   The  "<b>-G</b>
 264                      <i>group</i>"  option  may  be  used  to assign the
 265                      instance to a group.  Add  a  "<b><a href="postconf.5.html#config_directory">config_direc</a>-</b>
 266                      <b><a href="postconf.5.html#config_directory">tory</a>=</b><i>/path</i>"  argument  to override a default
 267                      pathname based on "<b>-I</b> <i>name</i>".
 268
 269               <b>destroy</b>
 270                      Destroy a secondary Postfix instance. To  be
 271                      a candidate for destruction an instance must
 272                      be disabled, stopped and its queue must  not
 273                      contain  any  messages.  Attempts to destroy
 274                      the primary Postfix instance trigger a fatal
 275                      error, without destroying the instance.
 276
 277                      The  instance  is  removed  from the primary
 278                      instance   <a href="postconf.5.html">main.cf</a>   file's   <a href="postconf.5.html#alternate_config_directories">alternate_con</a>-
 279                      <a href="postconf.5.html#alternate_config_directories">fig_directories</a>   parameter  and  its  data,
 280                      queue  and  configuration  directories   are
 281                      cleaned  of files and directories created by
 282                      the Postfix system.  The  <a href="postconf.5.html">main.cf</a>  and  mas-
 283                      ter.cf files are removed from the configura-
 284                      tion directory even if they have been  modi-
 285                      fied  since  initial  creation. Finally, the
 286                      instance is "deported" from the list of man-
 287                      aged instances.
 288
 289                      If  other files are present in instance pri-
 290                      vate directories, the directories may not be
 291                      fully  removed, a warning is logged to alert
 292                      the administrator. It is  expected  that  an
 293                      instance built using "fresh" directories via
 294                      the <b>create</b> action will be fully  removed  by
 295                      the  <b>destroy</b>  action (if first disabled). If
 296                      the instance configuration and queue  direc-
 297                      tories  are  populated with additional files
 298                      (access and rewriting  tables,  chroot  jail
 299                      content, etc.) the instance directories will
 300                      not be fully removed.
 301
 302                      The <b>destroy</b> action triggers potentially dan-
 303                      gerous  file  removal  operations. Make sure
 304                      the instance's data, queue and configuration
 305                      directories  are  set  correctly  and do not
 306                      contain any valuable files.
 307
 308               <b>deport</b> Deport a secondary instance from the list of
 309                      managed instances. This deletes the instance
 310                      configuration  directory  from  the  primary
 311                      instance's  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> list,
 312                      but does not remove any  files  or  directo-
 313                      ries.
 314
 315               <b>assign</b> Assign  a  new  instance name or a new group
 316                      name to the selected instance.  Use  "<b>-G  -</b>"
 317                      to  specify "no group" and "<b>-I -</b>" to specify
 318                      "no  name".   If  you  choose  to  make   an
 319                      instance  "nameless",  set  a  suitable sys-
 320                      log_name in the corresponding <a href="postconf.5.html">main.cf</a>  file.
 321
 322               <b>enable</b> Mark  the selected instance as enabled. This
 323                      just sets the <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  parame-
 324                      ter to "yes" in the instance's <a href="postconf.5.html">main.cf</a> file.
 325
 326               <b>disable</b>
 327                      Mark the selected instance as disabled. This
 328                      means  that the instance will not be started
 329                      etc. with  "postfix  start",  "postmulti  -p
 330                      start"  and so on. The instance can still be
 331                      started etc. with "postfix -c  config-direc-
 332                      tory start".
 333
 334 <b>Other options</b>
 335        <b>-v</b>     Enable verbose logging for debugging purposes. Mul-
 336               tiple <b>-v</b> options  make  the  software  increasingly
 337               verbose.
 338
 339 <b>ENVIRONMENT</b>
 340        The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command exports the following environment
 341        variables before executing the  requested  <i>command</i>  for  a
 342        given instance:
 343
 344        <b>MAIL_VERBOSE</b>
 345               This  is  set  when  the  -v command-line option is
 346               present.
 347
 348        <b>MAIL_CONFIG</b>
 349               The location of the configuration directory of  the
 350               instance.
 351
 352 <b>CONFIGURATION PARAMETERS</b>
 353        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 354               The  default  location  of  the Postfix <a href="postconf.5.html">main.cf</a> and
 355               <a href="master.5.html">master.cf</a> configuration files.
 356
 357        <b><a href="postconf.5.html#daemon_directory">daemon_directory</a> (see 'postconf -d' output)</b>
 358               The directory with  Postfix  support  programs  and
 359               daemon programs.
 360
 361        <b><a href="postconf.5.html#import_environment">import_environment</a> (see 'postconf -d' output)</b>
 362               The  list  of environment parameters that a Postfix
 363               process  will  import  from  a  non-Postfix  parent
 364               process.
 365
 366        <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b>
 367               An  optional list of non-default Postfix configura-
 368               tion directories; these directories belong to addi-
 369               tional  Postfix  instances  that  share the Postfix
 370               executable files and documentation with the default
 371               Postfix  instance,  and  that are started, stopped,
 372               etc., together with the default Postfix instance.
 373
 374        <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b>
 375               The optional instance group name  of  this  Postfix
 376               instance.
 377
 378        <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b>
 379               The   optional   instance   name  of  this  Postfix
 380               instance.
 381
 382        <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b>
 383               Allow this Postfix instance to be started, stopped,
 384               etc., by a multi-instance manager.
 385
 386        <b><a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a> (start)</b>
 387               The   <a href="postfix.1.html"><b>postfix</b>(1)</a>  commands  that  the  <a href="postmulti.1.html"><b>postmulti</b>(1)</a>
 388               instance manager treats as "start" commands.
 389
 390        <b><a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a> (see 'postconf -d' output)</b>
 391               The  <a href="postfix.1.html"><b>postfix</b>(1)</a>  commands  that  the   <a href="postmulti.1.html"><b>postmulti</b>(1)</a>
 392               instance manager treats as "stop" commands.
 393
 394        <b><a href="postconf.5.html#postmulti_control_commands">postmulti_control_commands</a> (reload flush)</b>
 395               The   <a href="postfix.1.html"><b>postfix</b>(1)</a>  commands  that  the  <a href="postmulti.1.html"><b>postmulti</b>(1)</a>
 396               instance manager treats as "control" commands, that
 397               operate on running instances.
 398
 399        <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
 400               The syslog facility of Postfix logging.
 401
 402        <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
 403               The  mail  system  name  that  is  prepended to the
 404               process name in syslog  records,  so  that  "smtpd"
 405               becomes, for example, "postfix/smtpd".
 406
 407 <b>FILES</b>
 408        $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/<a href="postconf.5.html">main.cf</a>, stock configuration file
 409        $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/<a href="master.5.html">master.cf</a>, stock configuration file
 410        $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postmulti-script, life-cycle helper program
 411
 412 <b>SEE ALSO</b>
 413        <a href="postfix.1.html">postfix(1)</a>, Postfix control program
 414        <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a>, Postfix multi-instance API
 415
 416 <b>README FILES</b>
 417        <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a>, Postfix multi-instance management
 418
 419 <b>HISTORY</b>
 420        The  <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command was introduced with Postfix ver-
 421        sion 2.6.
 422
 423 <b>LICENSE</b>
 424        The Secure Mailer license must be  distributed  with  this
 425        software.
 426
 427 <b>AUTHOR(S)</b>
 428        Victor Duchovni
 429        Morgan Stanley
 430
 431        Wietse Venema
 432        IBM T.J. Watson Research
 433        P.O. Box 704
 434        Yorktown Heights, NY 10598, USA
 435
 436                                                                   POSTMULTI(1)
 437 </pre> </body> </html>