POSTMULTI(1) POSTMULTI(1)
NAME
postmulti - Postfix multi-instance manager
SYNOPSIS
postmulti -l [-aRv] [-g group] [-i name]
postmulti -p [-av] [-g group] [-i name] command...
postmulti -x [-aRv] [-g group] [-i name] command...
postmulti -e init [-v]
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 opera-
tion. 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 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).
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 directory. Specify "-" to
select the primary Postfix instance.
-R 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 -p.
List mode
-l List Postfix instances with their instance name,
instance group name, enable/disable status and con-
figuration directory.
Postfix-wrapper mode
-p Invoke postfix(1) to execute the specified command.
This option implements the postfix-wrapper(5)
interface.
o With "start"-like commands, "postfix check"
is executed for instances that are not
enabled. The full list of commands is speci-
fied with the postmulti_start_commands
parameter.
o 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.
o With "reload" and other commands that
require a started instance, disabled
instances are skipped. The full list of com-
mands is specified with the postmulti_con-
trol_commands parameter.
o 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 Execute the specified command for all Postfix
instances. The command runs with appropriate envi-
ronment settings for MAIL_CONFIG, command_direc-
tory, daemon_directory, config_directory,
queue_directory, data_directory,
multi_instance_name, multi_instance_group and
multi_instance_enable.
Other options
-v Enable verbose logging for debugging purposes. Mul-
tiple -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 manage 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 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 opera-
tion 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 likeli-
hood 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 setting:
multi_instance_wrapper =
${command_directory}/postmulti -p --
multi_instance_enable = yes
You can set these by other means if you pre-
fer.
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 val-
ues for the private directories of the new
instance. The "-G group" 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 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 "post-
fix-" 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 \
data_directory=/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 -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, cre-
ate 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_direc-
tory=/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 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 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 create action will be fully removed by
the destroy 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 destroy 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.
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 directo-
ries.
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 sys-
log_name in the corresponding main.cf file.
enable Mark the selected instance as enabled. This
just sets the multi_instance_enable parame-
ter 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-direc-
tory start".
Other options
-v Enable verbose logging for debugging purposes. Mul-
tiple -v options make the software increasingly
verbose.
ENVIRONMENT
The postmulti(1) command exports the following environment
variables before 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 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 Postfix
process will import from a non-Postfix parent
process.
multi_instance_directories (empty)
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.
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)
The mail system name that is prepended to the
process name in syslog records, so that "smtpd"
becomes, for example, "postfix/smtpd".
FILES
$daemon_directory/main.cf, stock configuration file
$daemon_directory/master.cf, 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
MULTI_INSTANCE_README, Postfix multi-instance management
HISTORY
The postmulti(1) command was introduced with Postfix ver-
sion 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
POSTMULTI(1)