postmulti.1.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 - postmulti(1) </title>
</head> <body> <pre>
POSTMULTI(1)                                                      POSTMULTI(1)

       postmulti - Postfix multi-instance manager


       <b>postmulti -e init</b> [<b>-v</b>]

       <b>ITERATOR MODE:</b>

       <b>postmulti -l</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>]

       <b>postmulti -p</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>command...</i>

       <b>postmulti -x</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>command...</i>


       <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>]
       [<b>-I</b> <i>name</i>] [<i>param=value</i> ...]

       <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>]
       [<b>-I</b> <i>name</i>] [<b><a href="postconf.5.html#config_directory">config_directory</a>=</b><i>/path</i>]

       <b>postmulti -e destroy</b> [<b>-v</b>] <b>-i</b> <i>name</i>

       <b>postmulti -e deport</b> [<b>-v</b>] <b>-i</b> <i>name</i>

       <b>postmulti -e enable</b> [<b>-v</b>] <b>-i</b> <i>name</i>

       <b>postmulti -e disable</b> [<b>-v</b>] <b>-i</b> <i>name</i>

       <b>postmulti -e assign</b> [<b>-v</b>] <b>-i</b> <i>name</i> [<b>-I</b> <i>name</i>] [-G <i>group</i>]

       The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command allows a Postfix administrator to
       manage multiple Postfix instances on a single host.

       <a href="postmulti.1.html"><b>postmulti</b>(1)</a> implements two fundamental  modes  of  opera-
       tion.   In <b>iterator</b> mode, it executes the same command for
       multiple  Postfix  instances.   In  <b>life-cycle  management</b>
       mode,  it  adds  or  deletes  one instance, or changes the
       multi-instance status of one instance.

       Each mode of operation has its  own  command  syntax.  For
       this  reason, each mode is documented in separate sections

       A multi-instance configuration  consists  of  one  primary
       Postfix  instance,  and  one  or  more secondary instances
       whose configuration directory pathnames  are  recorded  in
       the  primary  instance's  <a href="postconf.5.html"></a>  file. Postfix instances
       share program files and documentation, but have their  own
       configuration, queue and data directories.

       Currently,  only  the default Postfix instance can be used
       as primary instance in a multi-instance configuration. The
       <a href="postmulti.1.html"><b>postmulti</b>(1)</a>  command  does  not  currently  support  a <b>-c</b>
       option to select  an  alternative  primary  instance,  and
       exits  with  a  fatal error if the <b>MAIL_CONFIG</b> environment
       variable is set to a non-default configuration  directory.

       See the <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a> tutorial for a more detailed
       discussion of multi-instance management with <a href="postmulti.1.html"><b>postmulti</b>(1)</a>.

       In iterator mode, <b>postmulti</b> performs the same operation on
       all Postfix instances in turn.

       If multi-instance support is not  enabled,  the  requested
       command is performed just for the primary instance.

       Iterator mode implements the following command options:

<b>Instance selection</b>
       <b>-a</b>     Perform the operation on all instances. This is the

       <b>-g</b> <i>group</i>
              Perform the operation only for members of the named

       <b>-i</b> <i>name</i>
              Perform  the  operation  only for the instance with
              the specified <i>name</i>.  You  can  specify  either  the
              instance  name  or  the  absolute  pathname  of the
              instance's configuration directory.  Specify "-" to
              select the primary Postfix instance.

       <b>-R</b>     Reverse  the iteration order. This may be appropri-
              ate when updating a  multi-instance  system,  where
              "sink"   instances   are  started  before  "source"

              This option cannot be used with <b>-p</b>.

<b>List mode</b>
       <b>-l</b>     List Postfix instances with  their  instance  name,
              instance group name, enable/disable status and con-
              figuration directory.

<b>Postfix-wrapper mode</b>
       <b>-p</b>     Invoke <a href="postfix.1.html"><b>postfix(1)</a></b> to execute the specified <i>command</i>.
              This   option   implements  the  <a href="postfix-wrapper.5.html"><b>postfix-wrapper</b>(5)</a>

              <b>o</b>      With "start"-like commands, "postfix  check"
                     is  executed  for  instances  that  are  not
                     enabled. The full list of commands is speci-
                     fied   with   the   <a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a>

              <b>o</b>      With  "stop"-like  commands,  the  iteration
                     order  is  reversed,  and disabled instances
                     are skipped. The full list  of  commands  is
                     specified  with  the <a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a>

              <b>o</b>      With  "reload"  and  other   commands   that
                     require   a   started   instance,   disabled
                     instances are skipped. The full list of com-
                     mands  is  specified with the <a href="postconf.5.html#postmulti_control_commands">postmulti_con</a>-
                     <a href="postconf.5.html#postmulti_control_commands">trol_commands</a> parameter.

              <b>o</b>      With "status" and other commands that  don't
                     require  a  started instance, the command is
                     executed for all instances.

              The <b>-p</b> option can also  be  used  interactively  to
              start/stop/etc.    a  named  instance  or  instance
              group. For example, to start just the instances  in
              the group "msa", invoke <a href="postmulti.1.html"><b>postmulti</b>(1)</a> as follows:

                     # postmulti -g msa -p start

<b>Command mode</b>
       <b>-x</b>     Execute  the  specified  <i>command</i>  for  all  Postfix
              instances.  The command runs with appropriate envi-
              ronment  settings  for  MAIL_CONFIG, <a href="postconf.5.html#command_directory">command_direc</a>-
              <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>,
              <a href="postconf.5.html#queue_directory">queue_directory</a>,                    <a href="postconf.5.html#data_directory">data_directory</a>,
              <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
              <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>.

<b>Other options</b>
       <b>-v</b>     Enable verbose logging for debugging purposes. Mul-
              tiple <b>-v</b> options  make  the  software  increasingly

       With  the  <b>-e</b>  option  <a href="postmulti.1.html"><b>postmulti</b>(1)</a>  can be used to add or
       delete a  Postfix  instance,  and  to  manage  the  multi-
       instance status of an existing instance.

       The following options are implemented:

<b>Existing instance selection</b>
       <b>-a</b>     When  creating  or importing an instance, place the
              new instance at the front of the secondary instance

       <b>-g</b> <i>group</i>
              When  creating  or importing an instance, place the
              new instance before the  first  secondary  instance
              that is a member of the specified group.

       <b>-i</b> <i>name</i>
              When  creating  or importing an instance, place the
              new  instance   before   the   matching   secondary

              With  other life-cycle operations, apply the opera-
              tion to the named existing instance.   Specify  "-"
              to select the primary Postfix instance.

<b>New or existing instance name assignment</b>
       <b>-I</b> <i>name</i>
              Assign  the  specified instance <i>name</i> to an existing
              instance,  newly-created  instance,   or   imported
              instance.   Instance  names  other  than "-" (which
              makes the  instance  "nameless")  must  start  with
              "postfix-".   This  restriction reduces the likeli-
              hood of name collisions with system files.

       <b>-G</b> <i>group</i>
              Assign the specified  <i>group</i>  name  to  an  existing
              instance   or   to  a  newly  created  or  imported

<b>Instance creation/deletion/status change</b>
       <b>-e</b> <i>action</i>
              "Edit" managed instances. The following actions are

              <b>init</b>   This command is required before <a href="postmulti.1.html"><b>postmulti</b>(1)</a>
                     can be used  to  manage  Postfix  instances.
                     The  "postmulti -e init" command updates the
                     primary instance's <a href="postconf.5.html"></a> file by setting:

                            <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> =
                                    ${<a href="postconf.5.html#command_directory">command_directory</a>}/postmulti -p --
                            <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes

                     You can set these by other means if you pre-

              <b>create</b> Create  a new Postfix instance and add it to
                     the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter  of
                     the  primary instance.  The "<b>-I</b> <i>name</i>" option
                     is recommended to give the instance a  short
                     name  that is used to construct default val-
                     ues for the private directories of  the  new
                     instance. The "<b>-G</b> <i>group</i>" option may be spec-
                     ified to assign the  instance  to  a  group,
                     otherwise,  the new instance is not a member
                     of any groups.

                     The  new  instance  <a href="postconf.5.html"></a>  is  the   stock
                     <a href="postconf.5.html"></a> with the parameters that specify the
                     locations of shared files  cloned  from  the
                     primary instance.  For "nameless" instances,
                     you should manually adjust "<a href="postconf.5.html#syslog_name">syslog_name</a>"  to
                     yield a unique "logtag" starting with "post-
                     fix-"  that  will  uniquely   identify   the
                     instance  in the mail logs. It is simpler to
                     assign the instance a short  name  with  the
                     "<b>-I</b> <i>name</i>" option.

                     Optional  "name=value" arguments specify the
                     instance  <a href="postconf.5.html#config_directory">config_directory</a>,  <a href="postconf.5.html#queue_directory">queue_directory</a>
                     and <a href="postconf.5.html#data_directory">data_directory</a>.  For example:

                            # postmulti -I postfix-mumble \
                                    -G mygroup -e create \
                                    <a href="postconf.5.html#config_directory">config_directory</a>=/my/config/dir \
                                    <a href="postconf.5.html#queue_directory">queue_directory</a>=/my/queue/dir \
                                    <a href="postconf.5.html#data_directory">data_directory</a>=/my/data/dir

                     If  any  of these pathnames is not supplied,
                     the program attempts to generate  the  path-
                     name  by  taking  the  corresponding primary
                     instance pathname, and by replacing the last
                     pathname  component  by  the value of the <b>-I</b>

                     If  the  instance  configuration   directory
                     already  exists, and contains both a <a href="postconf.5.html"></a>
                     and <a href="master.5.html"></a> file, <b>create</b> will "import" the
                     instance as-is. For existing instances, <b>cre-</b>
                     <b>ate</b> and <b>import</b> are identical.

              <b>import</b> Import an existing instance into the list of
                     instances managed by the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> multi-
                     instance manager.  This adds the instance to
                     the  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  list of the
                     primary instance.  If the "<b>-I</b>  <i>name</i>"  option
                     is  provided  it  specifies the new name for
                     the instance and is used to define a default
                     location   for  the  instance  configuration
                     directory (as with <b>create</b> above).   The  "<b>-G</b>
                     <i>group</i>"  option  may  be  used  to assign the
                     instance to a group.  Add  a  "<b><a href="postconf.5.html#config_directory">config_direc</a>-</b>
                     <b><a href="postconf.5.html#config_directory">tory</a>=</b><i>/path</i>"  argument  to override a default
                     pathname based on "<b>-I</b> <i>name</i>".

                     Destroy a secondary Postfix instance. To  be
                     a candidate for destruction an instance must
                     be disabled, stopped and its queue must  not
                     contain  any  messages.  Attempts to destroy
                     the primary Postfix instance trigger a fatal
                     error, without destroying the instance.

                     The  instance  is  removed  from the primary
                     instance   <a href="postconf.5.html"></a>   file's   <a href="postconf.5.html#alternate_config_directories">alternate_con</a>-
                     <a href="postconf.5.html#alternate_config_directories">fig_directories</a>   parameter  and  its  data,
                     queue  and  configuration  directories   are
                     cleaned  of files and directories created by
                     the Postfix system.  The  <a href="postconf.5.html"></a>  and  mas-
            files are removed from the configura-
                     tion directory even if they have been  modi-
                     fied  since  initial  creation. Finally, the
                     instance is "deported" from the list of man-
                     aged instances.

                     If  other files are present in instance pri-
                     vate directories, the directories may not be
                     fully  removed, a warning is logged to alert
                     the administrator. It is  expected  that  an
                     instance built using "fresh" directories via
                     the <b>create</b> action will be fully  removed  by
                     the  <b>destroy</b>  action (if first disabled). If
                     the instance configuration and queue  direc-
                     tories  are  populated with additional files
                     (access and rewriting  tables,  chroot  jail
                     content, etc.) the instance directories will
                     not be fully removed.

                     The <b>destroy</b> action triggers potentially dan-
                     gerous  file  removal  operations. Make sure
                     the instance's data, queue and configuration
                     directories  are  set  correctly  and do not
                     contain any valuable files.

              <b>deport</b> Deport a secondary instance from the list of
                     managed instances. This deletes the instance
                     configuration  directory  from  the  primary
                     instance's  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> list,
                     but does not remove any  files  or  directo-

              <b>assign</b> Assign  a  new  instance name or a new group
                     name to the selected instance.  Use  "<b>-G  -</b>"
                     to  specify "no group" and "<b>-I -</b>" to specify
                     "no  name".   If  you  choose  to  make   an
                     instance  "nameless",  set  a  suitable sys-
                     log_name in the corresponding <a href="postconf.5.html"></a>  file.

              <b>enable</b> Mark  the selected instance as enabled. This
                     just sets the <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  parame-
                     ter to "yes" in the instance's <a href="postconf.5.html"></a> file.

                     Mark the selected instance as disabled. This
                     means  that the instance will not be started
                     etc. with  "postfix  start",  "postmulti  -p
                     start"  and so on. The instance can still be
                     started etc. with "postfix -c  config-direc-
                     tory start".

<b>Other options</b>
       <b>-v</b>     Enable verbose logging for debugging purposes. Mul-
              tiple <b>-v</b> options  make  the  software  increasingly

       The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command exports the following environment
       variables before executing the  requested  <i>command</i>  for  a
       given instance:

              This  is  set  when  the  -v command-line option is

              The location of the configuration directory of  the

       <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#daemon_directory">daemon_directory</a> (see 'postconf -d' output)</b>
              The directory with  Postfix  support  programs  and
              daemon programs.

       <b><a href="postconf.5.html#import_environment">import_environment</a> (see 'postconf -d' output)</b>
              The  list  of environment parameters that a Postfix
              process  will  import  from  a  non-Postfix  parent

       <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_group">multi_instance_group</a> (empty)</b>
              The optional instance group name  of  this  Postfix

       <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_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#postmulti_start_commands">postmulti_start_commands</a> (start)</b>
              The   <a href="postfix.1.html"><b>postfix</b>(1)</a>  commands  that  the  <a href="postmulti.1.html"><b>postmulti</b>(1)</a>
              instance manager treats as "start" commands.

       <b><a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a> (see 'postconf -d' output)</b>
              The  <a href="postfix.1.html"><b>postfix</b>(1)</a>  commands  that  the   <a href="postmulti.1.html"><b>postmulti</b>(1)</a>
              instance manager treats as "stop" commands.

       <b><a href="postconf.5.html#postmulti_control_commands">postmulti_control_commands</a> (reload flush)</b>
              The   <a href="postfix.1.html"><b>postfix</b>(1)</a>  commands  that  the  <a href="postmulti.1.html"><b>postmulti</b>(1)</a>
              instance manager treats as "control" commands, that
              operate on running instances.

       <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
              The syslog facility of Postfix logging.

       <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
              The  mail  system  name  that  is  prepended to the
              process name in syslog  records,  so  that  "smtpd"
              becomes, for example, "postfix/smtpd".

       $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/<a href="postconf.5.html"></a>, stock configuration file
       $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/<a href="master.5.html"></a>, stock configuration file
       $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postmulti-script, life-cycle helper program

<b>SEE ALSO</b>
       <a href="postfix.1.html">postfix(1)</a>, Postfix control program
       <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a>, Postfix multi-instance API

       <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a>, Postfix multi-instance management

       The  <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command was introduced with Postfix ver-
       sion 2.6.

       The Secure Mailer license must be  distributed  with  this

       Victor Duchovni
       Morgan Stanley

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

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