410 lines
24 KiB
HTML
410 lines
24 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://www.w3.org/TR/html4/loose.dtd">
|
|
<html> <head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
|
|
<title> Postfix manual - postmulti(1) </title>
|
|
</head> <body> <pre>
|
|
POSTMULTI(1) POSTMULTI(1)
|
|
|
|
<b><a name="name">NAME</a></b>
|
|
postmulti - Postfix multi-instance manager
|
|
|
|
<b><a name="synopsis">SYNOPSIS</a></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>postfix-command...</i>
|
|
|
|
<b>postmulti -x</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>unix-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><a name="description">DESCRIPTION</a></b>
|
|
The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command allows a Postfix administrator to manage mul-
|
|
tiple Postfix instances on a single host.
|
|
|
|
<a href="postmulti.1.html"><b>postmulti</b>(1)</a> implements two fundamental modes of operation. In <b>itera-</b>
|
|
<b>tor</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><a name="background">BACKGROUND</a></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><a name="iterator_mode">ITERATOR MODE</a></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 per-
|
|
formed 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 appropriate when updat-
|
|
ing 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 configuration directory.
|
|
|
|
<b>Postfix-wrapper mode</b>
|
|
<b>-p</b> <i>postfix-command</i>
|
|
Invoke <a href="postfix.1.html"><b>postfix(1)</a></b> to execute <i>postfix-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 com-
|
|
mands is specified 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">post</a>-
|
|
<a href="postconf.5.html#postmulti_stop_commands">multi_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 commands is specified with the <a href="postconf.5.html#postmulti_control_commands">postmulti_control_com</a>-
|
|
<a href="postconf.5.html#postmulti_control_commands">mands</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 fol-
|
|
lows:
|
|
|
|
# postmulti -g msa -p start
|
|
|
|
<b>Command mode</b>
|
|
<b>-x</b> <i>unix-command</i>
|
|
Execute the specified <i>unix-command</i> for all Postfix instances.
|
|
The command runs with appropriate environment settings for
|
|
MAIL_CONFIG, <a href="postconf.5.html#command_directory">command_directory</a>, <a href="postconf.5.html#daemon_directory">daemon_directory</a>, <a href="postconf.5.html#config_directory">config_direc</a>-
|
|
<a href="postconf.5.html#config_directory">tory</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. Multiple <b>-v</b>
|
|
options make the software increasingly verbose.
|
|
|
|
<b><a name="life-cycle_management_mode">LIFE-CYCLE MANAGEMENT MODE</a></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 operation 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 likelihood 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 prefer.
|
|
|
|
<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 values for the private directories of the new
|
|
instance. The "<b>-G</b> <i>group</i>" 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 <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 "postfix-" 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">con</a>-
|
|
<a href="postconf.5.html#config_directory">fig_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 missing pathname(s) by taking
|
|
the corresponding primary instance pathname, and replac-
|
|
ing 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>create</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 pro-
|
|
vided it specifies the new name for the instance and is
|
|
used to define a default location for the instance con-
|
|
figuration 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_directory</a>=</b><i>/path</i>" argument to over-
|
|
ride 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_config_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 <a href="master.5.html">master.cf</a> 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 <b>cre-</b>
|
|
<b>ate</b> action will be fully removed by the <b>destroy</b> 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 <b>destroy</b> 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.
|
|
|
|
<b>deport</b> Deport a secondary instance from the list of managed
|
|
instances. This deletes the instance configuration direc-
|
|
tory from the primary instance's <a href="postconf.5.html#multi_instance_directories">multi_instance_directo</a>-
|
|
<a href="postconf.5.html#multi_instance_directories">ries</a> list, but does not remove any files or directories.
|
|
|
|
<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 <a href="postconf.5.html#syslog_name">syslog_name</a> 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> parameter 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-directory
|
|
start".
|
|
|
|
<b>Other options</b>
|
|
<b>-v</b> Enable verbose logging for debugging purposes. Multiple <b>-v</b>
|
|
options make the software increasingly verbose.
|
|
|
|
<b><a name="environment">ENVIRONMENT</a></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><a name="configuration_parameters">CONFIGURATION PARAMETERS</a></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> con-
|
|
figuration 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 variables that a privileged Postfix
|
|
process will import from a non-Postfix parent process, or
|
|
name=value environment overrides.
|
|
|
|
<b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b>
|
|
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.
|
|
|
|
<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>
|
|
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:
|
|
|
|
<b><a href="postconf.5.html#meta_directory">meta_directory</a> (see 'postconf -d' output)</b>
|
|
The location of non-executable files that are shared among mul-
|
|
tiple Postfix instances, such as postfix-files, dynamicmaps.cf,
|
|
and the multi-instance template files <a href="postconf.5.html">main.cf</a>.proto and <a href="master.5.html">mas-
|
|
ter.cf</a>.proto.
|
|
|
|
<b><a href="postconf.5.html#shlib_directory">shlib_directory</a> (see 'postconf -d' output)</b>
|
|
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.
|
|
|
|
<b><a name="files">FILES</a></b>
|
|
$<a href="postconf.5.html#meta_directory">meta_directory</a>/<a href="postconf.5.html">main.cf</a>.proto, stock configuration file
|
|
$<a href="postconf.5.html#meta_directory">meta_directory</a>/<a href="master.5.html">master.cf</a>.proto, stock configuration file
|
|
$<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postmulti-script, life-cycle helper program
|
|
|
|
<b><a name="see_also">SEE ALSO</a></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><a name="readme_files">README FILES</a></b>
|
|
<a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a>, Postfix multi-instance management
|
|
|
|
<b><a name="history">HISTORY</a></b>
|
|
The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command was introduced with Postfix version 2.6.
|
|
|
|
<b><a name="license">LICENSE</a></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
|
|
|
|
Wietse Venema
|
|
Google, Inc.
|
|
111 8th Avenue
|
|
New York, NY 10011, USA
|
|
|
|
POSTMULTI(1)
|
|
</pre> </body> </html>
|