search..
No manual entry for -- in section 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 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 con-
       figuration, 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
       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 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 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 updat-
	      ing 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 imple-
	      ments the postfix-wrapper(5) interface.

	      o	     With "start"-like commands, "postfix  check"  is  executed
		     for  instances that are not enabled. The full list of com-
		     mands is specified with the postmulti_start_commands para-
		     meter.

	      o	     With "stop"-like commands,	 the  iteration	 order	is  re-
		     versed,  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
		     commands is specified with the  postmulti_control_commands
		     parameter.

	      o	     With  "status"  and  other	 commands  that don't require a
		     started instance, the command  is	executed  for  all  in-
		     stances.

	      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_direc-
	      tory,   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 op-
	      tions 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 in-
       stance.

       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 spec-
	      ified 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 Post-
	      fix 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" com-
		     mand updates the primary instance's main.cf file  by  set-
		     ting:

			    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 pa-
		     rameters 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 iden-
		     tify the instance in the mail logs. It is simpler	to  as-
		     sign 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
		     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 at-
		     tempts  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  pro-
		     vided  it	specifies  the new name for the instance and is
		     used to define a default location for the instance config-
		     uration 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 de-
		     stroy 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 configu-
		     ration 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 directo-
		     ries, 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 in-
		     stance 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
		     contain 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  in-
		     stance  "nameless", set a suitable syslog_name in the cor-
		     responding 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 op-
	      tions make the software increasingly verbose.

ENVIRONMENT
       The postmulti(1) command exports the following environment variables be-
       fore 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 config-
	      uration 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  directo-
	      ries;  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 multi-
	      ple Postfix instances, such as postfix-files, dynamicmaps.cf, and
	      the  multi-instance  template  files   main.cf.proto   and   mas-
	      ter.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 dynam-
	      icmaps.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)