Provided by: postfix_3.10.2-1ubuntu1_amd64 bug

NAME

       postmulti - Postfix multi-instance manager

SYNOPSIS

   Enabling multi-instance management:

       postmulti -e init [-v]

   Iterator mode:

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

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

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

   Life-cycle management:

       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 operation.  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 appropriate 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
              configuration directory.

Postfix-wrapper mode

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

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

              •      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.

              •      With "reload" and other commands that require a started instance,  disabled  instances  are
                     skipped.  The  full  list  of  commands  is  specified  with the postmulti_control_commands
                     parameter.

              •      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 unix-command
              Execute  the  specified unix-command for all Postfix instances.  The command runs with appropriate
              environment  settings  for  MAIL_CONFIG,  command_directory,  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. Multiple -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 operation 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 likelihood 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 prefer.

              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 values for the private directories of the new instance.
                     The "-G group" option may be specified to assign the instance to a  group,  otherwise,  the
                     new instance is not a member of any group.

                     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 "postfix-"
                     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  missing
                     pathname(s)  by  taking the corresponding primary instance pathname, and 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, create 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_directory=/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_config_directories  parameter  and  its data, queue and configuration directories
                     are cleaned of files and directories  created  by  the  Postfix  system.  The  main.cf  and
                     master.cf  files  are  removed  from  the  configuration  directory  even if they have been
                     modified since initial creation. Finally, the instance  is  "deported"  from  the  list  of
                     managed instances.

                     If  other  files  are  present  in instance private 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 directories 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 dangerous 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 directories.

              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 syslog_name in the corresponding main.cf file.

              enable Mark the selected instance as enabled. This just sets the  multi_instance_enable  parameter
                     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-directory start".

Other options

       -v     Enable  verbose logging for debugging purposes. Multiple -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 variables that a privileged Postfix process will import from a non-Postfix
              parent process, or name=value environment overrides.

       multi_instance_directories (empty)
              An  optional  list  of  non-default Postfix configuration directories; these directories belong to
              additional 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)
              A  prefix  that  is prepended to the process name in syslog records, so that, for example, "smtpd"
              becomes "prefix/smtpd".

       Available in Postfix 3.0 and later:

       meta_directory (see 'postconf -d' output)
              The location of non-executable files that are shared among multiple  Postfix  instances,  such  as
              postfix-files,   dynamicmaps.cf,   and   the   multi-instance  template  files  main.cf.proto  and
              master.cf.proto.

       shlib_directory (see 'postconf -d' output)
              The location of Postfix dynamically-linked libraries (libpostfix-*.so), and the  default  location
              of  Postfix  database  plugins  (postfix-*.so) that have a relative pathname in the dynamicmaps.cf
              file.

FILES

       $meta_directory/main.cf.proto, stock configuration file
       $meta_directory/master.cf.proto, 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

       Use "postconf readme_directory" or "postconf html_directory" to locate this information.
       MULTI_INSTANCE_README, Postfix multi-instance management

HISTORY

       The postmulti(1) command was introduced with Postfix version 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

       Wietse Venema
       Google, Inc.
       111 8th Avenue
       New York, NY 10011, USA

                                                                                                    POSTMULTI(1)