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