phpman > man > postmulti(1)

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 [-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 sec‐
       ondary instances whose configuration directory pathnames are  recorded  in  the  primary  in‐
       stance'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-in‐
       stance  configuration. The postmulti(1) command does not currently support a -c option to se‐
       lect an alternative primary instance, and exits with a fatal error if the  MAIL_CONFIG  envi‐
       ronment variable is set to a non-default configuration directory.

       See  the MULTI_INSTANCE_README tutorial for a more detailed discussion of multi-instance man‐
       agement 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  di‐
              rectory.  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 post‐‐
              fix-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  post‐
                     multi_start_commands parameter.

              •      With "stop"-like commands, the iteration order is reversed,  and  disabled  in‐
                     stances  are  skipped.  The  full  list of commands is specified with the post‐
                     multi_stop_commands parameter.

              •      With "reload" and other commands that require a started instance, disabled  in‐
                     stances  are  skipped.  The  full  list of commands is specified with the post‐
                     multi_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_in‐
              stance_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 man‐
       age 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 sec‐
              ondary 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 "name‐
              less") 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 im‐
              ported 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  in‐
                     stances.   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  pa‐
                     rameter  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 pri‐
                     vate 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" op‐
                     tion.

                     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
                     pathname by taking the corresponding primary instance pathname, and by  replac‐
                     ing 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 exist‐
                     ing instances, create and import are identical.

              import Import  an  existing  instance  into the list of instances managed by the post‐‐
                     multi(1) multi-instance manager.  This  adds  the  instance  to  the  multi_in‐
                     stance_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 de‐
                     fault 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  in‐
                     stance  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
                     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 ex‐
                     pected that an instance built using "fresh" directories via the  create  action
                     will  be  fully  removed  by the destroy action (if first disabled). If the in‐
                     stance configuration and queue directories are populated with additional  files
                     (access  and rewriting tables, chroot jail content, etc.) the instance directo‐
                     ries 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_in‐
                     stance_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 in‐
                     stance 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 re‐
       quested 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 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"  com‐
              mands.

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

       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 exam‐
              ple, "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  de‐
              fault  location  of Postfix database plugins (postfix-*.so) that have a relative path‐
              name 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)