<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <title> Postfix manual - postmulti(1) </title> </head> <body> <pre> POSTMULTI(1) POSTMULTI(1) <b>NAME</b> postmulti - Postfix multi-instance manager <b>SYNOPSIS</b> <b>ENABLING MULTI-INSTANCE MANAGEMENT:</b> <b>postmulti -e init</b> [<b>-v</b>] <b>ITERATOR MODE:</b> <b>postmulti -l</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <b>postmulti -p</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>command...</i> <b>postmulti -x</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>command...</i> <b>LIFE-CYCLE MANAGEMENT:</b> <b>postmulti -e create</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] [<b>-G</b> <i>group</i>] [<b>-I</b> <i>name</i>] [<i>param=value</i> ...] <b>postmulti -e import</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] [<b>-G</b> <i>group</i>] [<b>-I</b> <i>name</i>] [<b><a href="postconf.5.html#config_directory">config_directory</a>=</b><i>/path</i>] <b>postmulti -e destroy</b> [<b>-v</b>] <b>-i</b> <i>name</i> <b>postmulti -e deport</b> [<b>-v</b>] <b>-i</b> <i>name</i> <b>postmulti -e enable</b> [<b>-v</b>] <b>-i</b> <i>name</i> <b>postmulti -e disable</b> [<b>-v</b>] <b>-i</b> <i>name</i> <b>postmulti -e assign</b> [<b>-v</b>] <b>-i</b> <i>name</i> [<b>-I</b> <i>name</i>] [-G <i>group</i>] <b>DESCRIPTION</b> The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command allows a Postfix administrator to manage multiple Postfix instances on a single host. <a href="postmulti.1.html"><b>postmulti</b>(1)</a> implements two fundamental modes of opera- tion. In <b>iterator</b> mode, it executes the same command for multiple Postfix instances. In <b>life-cycle management</b> 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. <b>BACKGROUND</b> 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 <a href="postconf.5.html">main.cf</a> 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 <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command does not currently support a <b>-c</b> option to select an alternative primary instance, and exits with a fatal error if the <b>MAIL_CONFIG</b> environment variable is set to a non-default configuration directory. See the <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a> tutorial for a more detailed discussion of multi-instance management with <a href="postmulti.1.html"><b>postmulti</b>(1)</a>. <b>ITERATOR MODE</b> In iterator mode, <b>postmulti</b> 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: <b>Instance selection</b> <b>-a</b> Perform the operation on all instances. This is the default. <b>-g</b> <i>group</i> Perform the operation only for members of the named <i>group</i>. <b>-i</b> <i>name</i> Perform the operation only for the instance with the specified <i>name</i>. You can specify either the instance name or the absolute pathname of the instance's configuration directory. Specify "-" to select the primary Postfix instance. <b>-R</b> Reverse the iteration order. This may be appropri- ate when updating a multi-instance system, where "sink" instances are started before "source" instances. This option cannot be used with <b>-p</b>. <b>List mode</b> <b>-l</b> List Postfix instances with their instance name, instance group name, enable/disable status and con- figuration directory. <b>Postfix-wrapper mode</b> <b>-p</b> Invoke <a href="postfix.1.html"><b>postfix(1)</a></b> to execute the specified <i>command</i>. This option implements the <a href="postfix-wrapper.5.html"><b>postfix-wrapper</b>(5)</a> interface. <b>o</b> With "start"-like commands, "postfix check" is executed for instances that are not enabled. The full list of commands is speci- fied with the <a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a> parameter. <b>o</b> With "stop"-like commands, the iteration order is reversed, and disabled instances are skipped. The full list of commands is specified with the <a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a> parameter. <b>o</b> With "reload" and other commands that require a started instance, disabled instances are skipped. The full list of com- mands is specified with the <a href="postconf.5.html#postmulti_control_commands">postmulti_con</a>- <a href="postconf.5.html#postmulti_control_commands">trol_commands</a> parameter. <b>o</b> With "status" and other commands that don't require a started instance, the command is executed for all instances. The <b>-p</b> 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 <a href="postmulti.1.html"><b>postmulti</b>(1)</a> as follows: # postmulti -g msa -p start <b>Command mode</b> <b>-x</b> Execute the specified <i>command</i> for all Postfix instances. The command runs with appropriate envi- ronment settings for MAIL_CONFIG, <a href="postconf.5.html#command_directory">command_direc</a>- <a href="postconf.5.html#command_directory">tory</a>, <a href="postconf.5.html#daemon_directory">daemon_directory</a>, <a href="postconf.5.html#config_directory">config_directory</a>, <a href="postconf.5.html#queue_directory">queue_directory</a>, <a href="postconf.5.html#data_directory">data_directory</a>, <a href="postconf.5.html#multi_instance_name">multi_instance_name</a>, <a href="postconf.5.html#multi_instance_group">multi_instance_group</a> and <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>. <b>Other options</b> <b>-v</b> Enable verbose logging for debugging purposes. Mul- tiple <b>-v</b> options make the software increasingly verbose. <b>LIFE-CYCLE MANAGEMENT MODE</b> With the <b>-e</b> option <a href="postmulti.1.html"><b>postmulti</b>(1)</a> 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: <b>Existing instance selection</b> <b>-a</b> When creating or importing an instance, place the new instance at the front of the secondary instance list. <b>-g</b> <i>group</i> When creating or importing an instance, place the new instance before the first secondary instance that is a member of the specified group. <b>-i</b> <i>name</i> When creating or importing an instance, place the new instance before the matching secondary instance. With other life-cycle operations, apply the opera- tion to the named existing instance. Specify "-" to select the primary Postfix instance. <b>New or existing instance name assignment</b> <b>-I</b> <i>name</i> Assign the specified instance <i>name</i> 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 likeli- hood of name collisions with system files. <b>-G</b> <i>group</i> Assign the specified <i>group</i> name to an existing instance or to a newly created or imported instance. <b>Instance creation/deletion/status change</b> <b>-e</b> <i>action</i> "Edit" managed instances. The following actions are supported: <b>init</b> This command is required before <a href="postmulti.1.html"><b>postmulti</b>(1)</a> can be used to manage Postfix instances. The "postmulti -e init" command updates the primary instance's <a href="postconf.5.html">main.cf</a> file by setting: <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = ${<a href="postconf.5.html#command_directory">command_directory</a>}/postmulti -p -- <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes You can set these by other means if you pre- fer. <b>create</b> Create a new Postfix instance and add it to the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter of the primary instance. The "<b>-I</b> <i>name</i>" option is recommended to give the instance a short name that is used to construct default val- ues for the private directories of the new instance. The "<b>-G</b> <i>group</i>" option may be spec- ified to assign the instance to a group, otherwise, the new instance is not a member of any groups. The new instance <a href="postconf.5.html">main.cf</a> is the stock <a href="postconf.5.html">main.cf</a> with the parameters that specify the locations of shared files cloned from the primary instance. For "nameless" instances, you should manually adjust "<a href="postconf.5.html#syslog_name">syslog_name</a>" to yield a unique "logtag" starting with "post- fix-" that will uniquely identify the instance in the mail logs. It is simpler to assign the instance a short name with the "<b>-I</b> <i>name</i>" option. Optional "name=value" arguments specify the instance <a href="postconf.5.html#config_directory">config_directory</a>, <a href="postconf.5.html#queue_directory">queue_directory</a> and <a href="postconf.5.html#data_directory">data_directory</a>. For example: # postmulti -I postfix-mumble \ -G mygroup -e create \ <a href="postconf.5.html#config_directory">config_directory</a>=/my/config/dir \ <a href="postconf.5.html#queue_directory">queue_directory</a>=/my/queue/dir \ <a href="postconf.5.html#data_directory">data_directory</a>=/my/data/dir If any of these pathnames is not supplied, the program attempts to generate the path- name by taking the corresponding primary instance pathname, and by replacing the last pathname component by the value of the <b>-I</b> option. If the instance configuration directory already exists, and contains both a <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> file, <b>create</b> will "import" the instance as-is. For existing instances, <b>cre-</b> <b>ate</b> and <b>import</b> are identical. <b>import</b> Import an existing instance into the list of instances managed by the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> multi- instance manager. This adds the instance to the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> list of the primary instance. If the "<b>-I</b> <i>name</i>" 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 <b>create</b> above). The "<b>-G</b> <i>group</i>" option may be used to assign the instance to a group. Add a "<b><a href="postconf.5.html#config_directory">config_direc</a>-</b> <b><a href="postconf.5.html#config_directory">tory</a>=</b><i>/path</i>" argument to override a default pathname based on "<b>-I</b> <i>name</i>". <b>destroy</b> 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 <a href="postconf.5.html">main.cf</a> file's <a href="postconf.5.html#alternate_config_directories">alternate_con</a>- <a href="postconf.5.html#alternate_config_directories">fig_directories</a> parameter and its data, queue and configuration directories are cleaned of files and directories created by the Postfix system. The <a href="postconf.5.html">main.cf</a> and mas- ter.cf files are removed from the configura- tion directory even if they have been modi- fied since initial creation. Finally, the instance is "deported" from the list of man- aged instances. If other files are present in instance pri- vate 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 <b>create</b> action will be fully removed by the <b>destroy</b> action (if first disabled). If the instance configuration and queue direc- tories are populated with additional files (access and rewriting tables, chroot jail content, etc.) the instance directories will not be fully removed. The <b>destroy</b> action triggers potentially dan- gerous file removal operations. Make sure the instance's data, queue and configuration directories are set correctly and do not contain any valuable files. <b>deport</b> Deport a secondary instance from the list of managed instances. This deletes the instance configuration directory from the primary instance's <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> list, but does not remove any files or directo- ries. <b>assign</b> Assign a new instance name or a new group name to the selected instance. Use "<b>-G -</b>" to specify "no group" and "<b>-I -</b>" to specify "no name". If you choose to make an instance "nameless", set a suitable sys- log_name in the corresponding <a href="postconf.5.html">main.cf</a> file. <b>enable</b> Mark the selected instance as enabled. This just sets the <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> parame- ter to "yes" in the instance's <a href="postconf.5.html">main.cf</a> file. <b>disable</b> 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-direc- tory start". <b>Other options</b> <b>-v</b> Enable verbose logging for debugging purposes. Mul- tiple <b>-v</b> options make the software increasingly verbose. <b>ENVIRONMENT</b> The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command exports the following environment variables before executing the requested <i>command</i> for a given instance: <b>MAIL_VERBOSE</b> This is set when the -v command-line option is present. <b>MAIL_CONFIG</b> The location of the configuration directory of the instance. <b>CONFIGURATION PARAMETERS</b> <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> configuration files. <b><a href="postconf.5.html#daemon_directory">daemon_directory</a> (see 'postconf -d' output)</b> The directory with Postfix support programs and daemon programs. <b><a href="postconf.5.html#import_environment">import_environment</a> (see 'postconf -d' output)</b> The list of environment parameters that a Postfix process will import from a non-Postfix parent process. <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b> An optional list of non-default Postfix configura- tion directories; these directories belong to addi- tional 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. <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b> The optional instance group name of this Postfix instance. <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b> The optional instance name of this Postfix instance. <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b> Allow this Postfix instance to be started, stopped, etc., by a multi-instance manager. <b><a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a> (start)</b> The <a href="postfix.1.html"><b>postfix</b>(1)</a> commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> instance manager treats as "start" commands. <b><a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a> (see 'postconf -d' output)</b> The <a href="postfix.1.html"><b>postfix</b>(1)</a> commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> instance manager treats as "stop" commands. <b><a href="postconf.5.html#postmulti_control_commands">postmulti_control_commands</a> (reload flush)</b> The <a href="postfix.1.html"><b>postfix</b>(1)</a> commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> instance manager treats as "control" commands, that operate on running instances. <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> The syslog facility of Postfix logging. <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> The mail system name that is prepended to the process name in syslog records, so that "smtpd" becomes, for example, "postfix/smtpd". <b>FILES</b> $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/<a href="postconf.5.html">main.cf</a>, stock configuration file $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/<a href="master.5.html">master.cf</a>, stock configuration file $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postmulti-script, life-cycle helper program <b>SEE ALSO</b> <a href="postfix.1.html">postfix(1)</a>, Postfix control program <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a>, Postfix multi-instance API <b>README FILES</b> <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a>, Postfix multi-instance management <b>HISTORY</b> The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command was introduced with Postfix ver- sion 2.6. <b>LICENSE</b> The Secure Mailer license must be distributed with this software. <b>AUTHOR(S)</b> Victor Duchovni Morgan Stanley Wietse Venema IBM T.J. Watson Research P.O. Box 704 Yorktown Heights, NY 10598, USA POSTMULTI(1) </pre> </body> </html>