Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

POSTMULTI(1)                General Commands Manual               POSTMULTI(1)

       postmulti - Postfix multi-instance manager

   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]

       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]

       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.

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

       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

              ⊕      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

              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

                     # 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

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

       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

       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

                            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 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 "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 \

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

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

                     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

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

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

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

              The location of the configuration directory of the instance.


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

       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.

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

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

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

       The postmulti(1) command was introduced with Postfix version 2.6.

       The Secure Mailer license must be distributed with this software.

       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