Postfix manual - postmulti(1)

    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)