POSTMULTI(1)                                                      POSTMULTI(1)

NAME
       postmulti - Postfix multi-instance manager

SYNOPSIS
       postmulti -l [-aRv] [-g group] [-i name]

       postmulti -p [-av] [-g group] [-i name] command...

       postmulti -x [-aRv] [-g group] [-i name] command...

       postmulti -e init [-v]

       postmulti -e create [-av] [-g group] [-i name] [-G group]
       [-I name] [param=value ...]

       postmulti -e import [-av] [-g group] [-i name] [-G group]
       [-I name] [config_directory=/path]

       postmulti -e destroy [-v] -i name

       postmulti -e deport [-v] -i name

       postmulti -e enable [-v] -i name

       postmulti -e disable [-v] -i name

       postmulti -e assign [-v] -i name [-I name] [-G group]

DESCRIPTION
       The postmulti(1) command allows a Postfix administrator to
       manage multiple Postfix instances on a single host.

       postmulti(1) implements two fundamental  modes  of  opera-
       tion.   In iterator mode, it executes the same command for
       multiple  Postfix  instances.   In  life-cycle  management
       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
       below.

BACKGROUND
       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  main.cf  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
       postmulti(1)  command  does  not  currently  support  a -c
       option to select  an  alternative  primary  instance,  and
       exits  with  a  fatal error if the MAIL_CONFIG environment
       variable is set to a non-default configuration  directory.

       See the MULTI_INSTANCE_README tutorial for a more detailed
       discussion of multi-instance management with postmulti(1).

ITERATOR MODE
       In iterator mode, postmulti 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:

Instance selection
       -a     Perform the operation on all instances. This is the
              default.

       -g group
              Perform the operation only for members of the named
              group.

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

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

              This option cannot be used with -p.

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

Postfix-wrapper mode
       -p     Invoke postfix(1) to execute the specified command.
              This   option   implements  the  postfix-wrapper(5)
              interface.

              o      With "start"-like commands, "postfix  check"
                     is  executed  for  instances  that  are  not
                     enabled. The full list of commands is speci-
                     fied   with   the   postmulti_start_commands
                     parameter.

              o      With  "stop"-like  commands,  the  iteration
                     order  is  reversed,  and disabled instances
                     are skipped. The full list  of  commands  is
                     specified  with  the postmulti_stop_commands
                     parameter.

              o      With  "reload"  and  other   commands   that
                     require   a   started   instance,   disabled
                     instances are skipped. The full list of com-
                     mands  is  specified with the postmulti_con-
                     trol_commands parameter.

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

              The -p 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 postmulti(1) as follows:

                     # postmulti -g msa -p start

Command mode
       -x     Execute  the  specified  command  for  all  Postfix
              instances.  The command runs with appropriate envi-
              ronment  settings  for  MAIL_CONFIG, command_direc-
              tory,      daemon_directory,      config_directory,
              queue_directory,                    data_directory,
              multi_instance_name,    multi_instance_group    and
              multi_instance_enable.

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

LIFE-CYCLE MANAGEMENT MODE
       With  the  -e  option  postmulti(1)  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:

Existing instance selection
       -a     When  creating  or importing an instance, place the
              new instance at the front of the secondary instance
              list.

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

       -i name
              When  creating  or importing an instance, place the
              new  instance   before   the   matching   secondary
              instance.

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

New or existing instance name assignment
       -I name
              Assign  the  specified instance name 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.

       -G group
              Assign the specified  group  name  to  an  existing
              instance   or   to  a  newly  created  or  imported
              instance.

Instance creation/deletion/status change
       -e action
              "Edit" managed instances. The following actions are
              supported:

              init   This command is required before postmulti(1)
                     can be used  to  manage  Postfix  instances.
                     The  "postmulti -e init" command updates the
                     primary instance's main.cf file by setting:

                            multi_instance_wrapper =
                                    ${command_directory}/postmulti -p --
                            multi_instance_enable = yes

                     You can set these by other means if you pre-
                     fer.

              create Create  a new Postfix instance and add it to
                     the multi_instance_directories parameter  of
                     the  primary instance.  The "-I name" 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 "-G group" 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  main.cf  is  the   stock
                     main.cf with the parameters that specify the
                     locations of shared files  cloned  from  the
                     primary instance.  For "nameless" instances,
                     you should manually adjust "syslog_name"  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
                     "-I name" option.

                     Optional  "name=value" arguments specify the
                     instance  config_directory,  queue_directory
                     and data_directory.  For example:

                            # postmulti -I postfix-mumble \
                                    -G mygroup -e create \
                                    config_directory=/my/config/dir \
                                    queue_directory=/my/queue/dir \
                                    data_directory=/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 -I
                     option.

                     If  the  instance  configuration   directory
                     already  exists, and contains both a main.cf
                     and master.cf file, create will "import" the
                     instance as-is. For existing instances, cre-
                     ate and import are identical.

              import Import an existing instance into the list of
                     instances managed by the postmulti(1) multi-
                     instance manager.  This adds the instance to
                     the  multi_instance_directories  list of the
                     primary instance.  If the "-I  name"  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 create above).   The  "-G
                     group"  option  may  be  used  to assign the
                     instance to a group.  Add  a  "config_direc-
                     tory=/path"  argument  to override a default
                     pathname based on "-I name".

              destroy
                     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   main.cf   file's   alternate_con-
                     fig_directories   parameter  and  its  data,
                     queue  and  configuration  directories   are
                     cleaned  of files and directories created by
                     the Postfix system.  The  main.cf  and  mas-
                     ter.cf 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 create action will be fully  removed  by
                     the  destroy  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 destroy 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.

              deport Deport a secondary instance from the list of
                     managed instances. This deletes the instance
                     configuration  directory  from  the  primary
                     instance's  multi_instance_directories list,
                     but does not remove any  files  or  directo-
                     ries.

              assign Assign  a  new  instance name or a new group
                     name to the selected instance.  Use  "-G  -"
                     to  specify "no group" and "-I -" to specify
                     "no  name".   If  you  choose  to  make   an
                     instance  "nameless",  set  a  suitable sys-
                     log_name in the corresponding main.cf  file.

              enable Mark  the selected instance as enabled. This
                     just sets the multi_instance_enable  parame-
                     ter to "yes" in the instance's main.cf file.

              disable
                     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".

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

ENVIRONMENT
       The postmulti(1) command exports the following environment
       variables before executing the  requested  command  for  a
       given instance:

       MAIL_VERBOSE
              This  is  set  when  the  -v command-line option is
              present.

       MAIL_CONFIG
              The location of the configuration directory of  the
              instance.

CONFIGURATION PARAMETERS
       config_directory (see 'postconf -d' output)
              The  default  location  of  the Postfix main.cf and
              master.cf configuration files.

       daemon_directory (see 'postconf -d' output)
              The directory with  Postfix  support  programs  and
              daemon programs.

       import_environment (see 'postconf -d' output)
              The  list  of environment parameters that a Postfix
              process  will  import  from  a  non-Postfix  parent
              process.

       multi_instance_directories (empty)
              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.

       multi_instance_group (empty)
              The optional instance group name  of  this  Postfix
              instance.

       multi_instance_name (empty)
              The   optional   instance   name  of  this  Postfix
              instance.

       multi_instance_enable (no)
              Allow this Postfix instance to be started, stopped,
              etc., by a multi-instance manager.

       postmulti_start_commands (start)
              The   postfix(1)  commands  that  the  postmulti(1)
              instance manager treats as "start" commands.

       postmulti_stop_commands (see 'postconf -d' output)
              The  postfix(1)  commands  that  the   postmulti(1)
              instance manager treats as "stop" commands.

       postmulti_control_commands (reload flush)
              The   postfix(1)  commands  that  the  postmulti(1)
              instance manager treats as "control" commands, that
              operate on running instances.

       syslog_facility (mail)
              The syslog facility of Postfix logging.

       syslog_name (see 'postconf -d' output)
              The  mail  system  name  that  is  prepended to the
              process name in syslog  records,  so  that  "smtpd"
              becomes, for example, "postfix/smtpd".

FILES
       $daemon_directory/main.cf, stock configuration file
       $daemon_directory/master.cf, stock configuration file
       $daemon_directory/postmulti-script, life-cycle helper program

SEE ALSO
       postfix(1), Postfix control program
       postfix-wrapper(5), Postfix multi-instance API

README FILES
       MULTI_INSTANCE_README, Postfix multi-instance management

HISTORY
       The  postmulti(1) command was introduced with Postfix ver-
       sion 2.6.

LICENSE
       The Secure Mailer license must be  distributed  with  this
       software.

AUTHOR(S)
       Victor Duchovni
       Morgan Stanley

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

                                                                  POSTMULTI(1)