273 lines
16 KiB
HTML
273 lines
16 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 - postfix-wrapper(5) </title>
|
|
</head> <body> <pre>
|
|
POSTFIX-WRAPPER(5) POSTFIX-WRAPPER(5)
|
|
|
|
<b><a name="name">NAME</a></b>
|
|
postfix-wrapper - Postfix multi-instance API
|
|
|
|
<b><a name="description">DESCRIPTION</a></b>
|
|
Support for managing multiple Postfix instances is available as of ver-
|
|
sion 2.6. Instances share executable files and documentation, but have
|
|
their own directories for configuration, queue and data files.
|
|
|
|
This document describes how the familiar "postfix start" etc. user
|
|
interface can be used to manage one or multiple Postfix instances, and
|
|
gives details of an API to coordinate activities between the <a href="postfix.1.html">postfix(1)</a>
|
|
command and a multi-instance manager program.
|
|
|
|
With multi-instance support, the default Postfix instance is always
|
|
required. This instance is identified by the <a href="postconf.5.html#config_directory">config_directory</a> parame-
|
|
ter's default value.
|
|
|
|
<b><a name="general_operation">GENERAL OPERATION</a></b>
|
|
Multi-instance support is backwards compatible: when you run only one
|
|
Postfix instance, commands such as "postfix start" will not change
|
|
behavior at all.
|
|
|
|
Even with multiple Postfix instances, you can keep using the same post-
|
|
fix commands in boot scripts, upgrade procedures, and other places. The
|
|
commands do more work, but humans are not forced to learn new tricks.
|
|
|
|
For example, to start all Postfix instances, use:
|
|
|
|
# postfix start
|
|
|
|
Other <a href="postfix.1.html">postfix(1)</a> commands also work as expected. For example, to find
|
|
out what Postfix instances exist in a multi-instance configuration,
|
|
use:
|
|
|
|
# postfix status
|
|
|
|
This enumerates the status of all Postfix instances within a
|
|
multi-instance configuration.
|
|
|
|
<b><a name="managing_an_individual_postfix_instance">MANAGING AN INDIVIDUAL POSTFIX INSTANCE</a></b>
|
|
To manage a specific Postfix instance, specify its configuration direc-
|
|
tory on the <a href="postfix.1.html">postfix(1)</a> command line:
|
|
|
|
# postfix -c <i>/path/to/config</i><b>_</b><i>directory command</i>
|
|
|
|
Alternatively, the <a href="postfix.1.html">postfix(1)</a> command accepts the instance's configura-
|
|
tion directory via the MAIL_CONFIG environment variable (the -c com-
|
|
mand-line option has higher precedence).
|
|
|
|
Otherwise, the <a href="postfix.1.html">postfix(1)</a> command will operate on all Postfix
|
|
instances.
|
|
|
|
<b>ENABLING POSTFIX(1) MULTI-INSTANCE MODE</b>
|
|
By default, the <a href="postfix.1.html">postfix(1)</a> command operates in single-instance mode. In
|
|
this mode the command invokes the postfix-script file directly (cur-
|
|
rently installed in the daemon directory). This file contains the com-
|
|
mands that start or stop one Postfix instance, that upgrade the config-
|
|
uration of one Postfix instance, and so on.
|
|
|
|
When the <a href="postfix.1.html">postfix(1)</a> command operates in multi-instance mode as dis-
|
|
cussed below, the command needs to execute start, stop, etc. commands
|
|
for each Postfix instance. This multiplication of commands is handled
|
|
by a multi-instance manager program.
|
|
|
|
Turning on <a href="postfix.1.html">postfix(1)</a> multi-instance mode goes as follows: in the
|
|
default Postfix instance's <a href="postconf.5.html">main.cf</a> file, 1) specify the pathname of a
|
|
multi-instance manager program with the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parame-
|
|
ter; 2) populate the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter with the con-
|
|
figuration directory pathnames of additional Postfix instances. For
|
|
example:
|
|
|
|
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
|
|
<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper
|
|
<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> = /etc/postfix-test
|
|
|
|
The $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper file implements a simple manager
|
|
and contains instructions for creating Postfix instances by hand. The
|
|
<a href="postmulti.1.html">postmulti(1)</a> command provides a more extensive implementation including
|
|
support for life-cycle management.
|
|
|
|
The <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> and other <a href="postconf.5.html">main.cf</a> parameters are listed
|
|
below in the CONFIGURATION PARAMETERS section.
|
|
|
|
In multi-instance mode, the <a href="postfix.1.html">postfix(1)</a> command invokes the
|
|
$<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> command instead of the postfix-script file.
|
|
This multi-instance manager in turn executes the <a href="postfix.1.html">postfix(1)</a> command in
|
|
single-instance mode for each Postfix instance.
|
|
|
|
To illustrate the main ideas behind multi-instance operation, below is
|
|
an example of a simple but useful multi-instance manager implementa-
|
|
tion:
|
|
|
|
#!/bin/sh
|
|
|
|
: ${<a href="postconf.5.html#command_directory">command_directory</a>?"do not invoke this command directly"}
|
|
|
|
POSTCONF=$<a href="postconf.5.html#command_directory">command_directory</a>/postconf
|
|
POSTFIX=$<a href="postconf.5.html#command_directory">command_directory</a>/postfix
|
|
instance_dirs=`$POSTCONF -h <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> |
|
|
sed 'y/,/ /'` || exit 1
|
|
|
|
err=0
|
|
for dir in $<a href="postconf.5.html#config_directory">config_directory</a> $instance_dirs
|
|
do
|
|
case "$1" in
|
|
stop|abort|flush|reload|drain)
|
|
test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
|
|
= yes || continue;;
|
|
start)
|
|
test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
|
|
= yes || {
|
|
$POSTFIX -c $dir check || err=$?
|
|
continue
|
|
};;
|
|
esac
|
|
$POSTFIX -c $dir "$@" || err=$?
|
|
done
|
|
|
|
exit $err
|
|
|
|
<b><a name="per-instance_multi-instance_manager_controls">PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS</a></b>
|
|
Each Postfix instance has its own <a href="postconf.5.html">main.cf</a> file with parameters that
|
|
control how the multi-instance manager operates on that instance. This
|
|
section discusses the most important settings.
|
|
|
|
The setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes" allows the multi-instance
|
|
manager to start (stop, etc.) the corresponding Postfix instance. For
|
|
safety reasons, this setting is not the default.
|
|
|
|
The default setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no" is useful for manual
|
|
testing with "postfix -c <i>/path/name</i> start" etc. The multi-instance
|
|
manager will not start such an instance, and it will skip commands such
|
|
as "stop" or "flush" that require a running Postfix instance. The
|
|
multi-instance manager will execute commands such as "check", "set-per-
|
|
missions" or "upgrade-configuration", and it will replace "start" by
|
|
"check" so that problems will be reported even when the instance is
|
|
disabled.
|
|
|
|
<b><a name="maintaining_shared_and_non-shared_files">MAINTAINING SHARED AND NON-SHARED FILES</a></b>
|
|
Some files are shared between Postfix instances, such as executables
|
|
and manpages, and some files are per-instance, such as configuration
|
|
files, mail queue files, and data files. See the NON-SHARED FILES sec-
|
|
tion below for a list of per-instance files.
|
|
|
|
Before Postfix multi-instance support was implemented, the executables,
|
|
manpages, etc., have always been maintained as part of the default
|
|
Postfix instance.
|
|
|
|
With multi-instance support, we simply continue to do this. Specifi-
|
|
cally, a Postfix instance will not check or update shared files when
|
|
that instance's <a href="postconf.5.html#config_directory">config_directory</a> value is listed with the default
|
|
<a href="postconf.5.html">main.cf</a> file's <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter.
|
|
|
|
The consequence of this approach is that the default Postfix instance
|
|
should be checked and updated before any other instances.
|
|
|
|
<b><a name="multi-instance_api_summary">MULTI-INSTANCE API SUMMARY</a></b>
|
|
Only the multi-instance manager implements support for the
|
|
<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> configuration parameter. The multi-instance man-
|
|
ager will start only Postfix instances whose <a href="postconf.5.html">main.cf</a> file has
|
|
"<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". A setting of "no" allows a Postfix
|
|
instance to be tested by hand.
|
|
|
|
The <a href="postfix.1.html">postfix(1)</a> command operates on only one Postfix instance when the
|
|
-c option is specified, or when MAIL_CONFIG is present in the process
|
|
environment. This is necessary to terminate recursion.
|
|
|
|
Otherwise, when the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter value is
|
|
non-empty, the <a href="postfix.1.html">postfix(1)</a> command executes the command specified with
|
|
the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameter, instead of executing the commands
|
|
in postfix-script.
|
|
|
|
The multi-instance manager skips commands such as "stop" or "reload"
|
|
that require a running Postfix instance, when an instance does not have
|
|
"<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". This avoids false error messages.
|
|
|
|
The multi-instance manager replaces a "start" command by "check" when a
|
|
Postfix instance's <a href="postconf.5.html">main.cf</a> file does not have "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> =
|
|
yes". This substitution ensures that problems will be reported even
|
|
when the instance is disabled.
|
|
|
|
No Postfix command or script will update or check shared files when its
|
|
<a href="postconf.5.html#config_directory">config_directory</a> value is listed in the default <a href="postconf.5.html">main.cf</a>'s
|
|
<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter value. Therefore, the default
|
|
instance should be checked and updated before any Postfix instances
|
|
that depend on it.
|
|
|
|
Set-gid commands such as <a href="postdrop.1.html">postdrop(1)</a> and <a href="postqueue.1.html">postqueue(1)</a> effectively
|
|
append the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter value to the legacy
|
|
<a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter value. The commands use this
|
|
information to determine whether a -c option or MAIL_CONFIG environment
|
|
setting specifies a legitimate value.
|
|
|
|
The legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter remains necessary for
|
|
non-default Postfix instances that are running different versions of
|
|
Postfix, or that are not managed together with the default Postfix
|
|
instance.
|
|
|
|
<b><a name="environment_variables">ENVIRONMENT VARIABLES</a></b>
|
|
MAIL_CONFIG
|
|
When present, this forces the <a href="postfix.1.html">postfix(1)</a> command to operate only
|
|
on the specified Postfix instance. This environment variable is
|
|
exported by the <a href="postfix.1.html">postfix(1)</a> -c option, so that <a href="postfix.1.html">postfix(1)</a> com-
|
|
mands in descendant processes will work correctly.
|
|
|
|
<b><a name="configuration_parameters">CONFIGURATION PARAMETERS</a></b>
|
|
The text below provides only a parameter summary. See <a href="postconf.5.html">postconf(5)</a> for
|
|
more details.
|
|
|
|
<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_wrapper">multi_instance_wrapper</a> (empty)</b>
|
|
The pathname of a multi-instance manager command that the <a href="postfix.1.html"><b>post-</b></a>
|
|
<a href="postfix.1.html"><b>fix</b>(1)</a> command invokes when the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>
|
|
parameter value is non-empty.
|
|
|
|
<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_group">multi_instance_group</a> (empty)</b>
|
|
The optional instance group 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 name="non-shared_files">NON-SHARED FILES</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#data_directory">data_directory</a> (see 'postconf -d' output)</b>
|
|
The directory with Postfix-writable data files (for example:
|
|
caches, pseudo-random numbers).
|
|
|
|
<b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
|
|
The location of the Postfix top-level queue directory.
|
|
|
|
<b><a name="see_also">SEE ALSO</a></b>
|
|
<a href="postfix.1.html">postfix(1)</a> Postfix control program
|
|
<a href="postmulti.1.html">postmulti(1)</a> full-blown multi-instance manager
|
|
$<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper simple multi-instance manager
|
|
|
|
<b><a name="license">LICENSE</a></b>
|
|
The Secure Mailer license must be distributed with this software.
|
|
|
|
<b>AUTHOR(S)</b>
|
|
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
|
|
|
|
POSTFIX-WRAPPER(5)
|
|
</pre> </body> </html>
|