    POSTMULTI(1)                 General Commands Manual                POSTMULTI(1)

    NAME
         postmulti - Postfix multi-instance manager

    SYNOPSIS
     Enabling multi-instance management:

         postmulti -e init [-v]

     Iterator mode:

         postmulti -l [-ajRv] [-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] [con‐
         fig_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 multi‐
         ple 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 path‐
         names are recorded in the primary instance's main.cf  file.  Postfix  in‐
         stances share program files and documentation, but have their own config‐
         uration, queue and data directories.

         Currently,  only  the default Postfix instance can be used as primary in‐
         stance in a multi-instance configuration. The postmulti(1)  command  does
         not  currently  support  a -c option to select an alternative primary in‐
         stance, and exits with a fatal error if the MAIL_CONFIG environment vari‐
         able 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  per‐
         formed 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 namePerform 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
         -j     Produce JSON output. See JSON OBJECT FORMAT below.

                This feature is available in Postfix version 3.11 and later.

         -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  imple‐
                ments 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  in‐
                       stance, disabled instances are skipped. The full list of com‐
                       mands  is specified with the postmulti_control_commands para‐
                       meter.

                •      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 in‐
                stances 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_direc‐
                tory, 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  in‐
         stance, 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  be‐
                fore  the first secondary instance that is a member of the specified
                group.

         -i nameWhen creating or importing an instance, place the new  instance  be‐
                fore the matching secondary instance.

                With  other  life-cycle operations, apply the operation to the named
                existing instance.  Specify "-" to select the  primary  Postfix  in‐
                stance.

    New or existing instance name assignment
         -I nameAssign   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  colli‐
                sions 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_in‐
                       stance_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  para‐
                       meters 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 in‐
                       stance 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  con‐
                       fig_directory, queue_directory and data_directory.  For exam‐
                       ple:

                              # 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 at‐
                       tempts to generate the missing pathname(s) by taking the cor‐
                       responding 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  "im‐
                       port"  the instance as-is. For existing instances, create and
                       import are identical.

                import Import an existing instance into the list of  instances  man‐
                       aged  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".

                destroyDestroy  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  de‐
                       stroying 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.  Fi‐
                       nally,  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 popu‐
                       lated with additional files (access and rewriting tables, ch‐
                       root jail content, etc.) the instance directories will not be
                       fully removed.

                       The destroy action triggers potentially  dangerous  file  re‐
                       moval  operations.  Make  sure the instance's data, queue and
                       configuration directories are set correctly and do  not  con‐
                       tain any valuable files.

                deport Deport  a  secondary  instance  from  the list of managed in‐
                       stances. 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  se‐
                       lected 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.

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

    JSON OBJECT FORMAT
         The output consists of a sequence of lines. Each line contains one JSON ob‐
         ject that represents settings in a corresponding instance's main.cf file.

         Object  members  have  string  values unless indicated otherwise.  Programs
         should ignore members that are not listed here, as  members  may  be  added
         over time.

         name   The value of the corresponding multi_instance_name parameter, or "-"
                if no name is specified.

         group  The  value  of  the corresponding multi_instance_group parameter, or
                "-" if no group is specified.

         enabledEither "y" or "n", depending on whether the corresponding  multi_in‐
                stance_enable parameter value is "yes" or "no".

                Note:  this  reports "y" for a primary instance, when multi-instance
                support is not enabled.

         config_directory
                The value of the corresponding config_directory parameter.

    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 configura‐
                tion 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 envi‐
                ronment 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  (libpost‐
                fix-*.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
         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)