296 lines
16 KiB
HTML
296 lines
16 KiB
HTML
<!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 - postfix-wrapper(5) </title>
|
|
</head> <body> <pre>
|
|
POSTFIX-WRAPPER(5) POSTFIX-WRAPPER(5)
|
|
|
|
<b>NAME</b>
|
|
postfix-wrapper - Postfix multi-instance API
|
|
|
|
<b>DESCRIPTION</b>
|
|
Support for managing multiple Postfix instances is avail-
|
|
able as of version 2.6. Instances share executable files
|
|
and documentation, but have their own directories for con-
|
|
figuration, 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 coordi-
|
|
nate 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> parameter's default value.
|
|
|
|
<b>GENERAL OPERATION</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 postfix commands in boot scripts, upgrade proce-
|
|
dures, 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 exam-
|
|
ple, 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>MANAGING AN INDIVIDUAL POSTFIX INSTANCE</b>
|
|
To manage a specific Postfix instance, specify its config-
|
|
uration directory 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 configuration directory via the MAIL_CONFIG
|
|
environment variable (the -c command-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 post-
|
|
fix-script file directly (currently installed in the dae-
|
|
mon directory). This file contains the commands that
|
|
start or stop one Postfix instance, that upgrade the con-
|
|
figuration of one Postfix instance, and so on.
|
|
|
|
When the <a href="postfix.1.html">postfix(1)</a> command operates in multi-instance
|
|
mode as discussed 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> parameter; 2) populate the
|
|
<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter with the configura-
|
|
tion 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 pro-
|
|
vides 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> parame-
|
|
ters are listed below in the CONFIGURATION PARAMETERS sec-
|
|
tion.
|
|
|
|
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 opera-
|
|
tion, below is an example of a simple but useful multi-
|
|
instance manager implementation:
|
|
|
|
#!/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 's/,/ /'` || 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>PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS</b>
|
|
Each Postfix instance has its own <a href="postconf.5.html">main.cf</a> file with param-
|
|
eters that control how the multi-instance manager operates
|
|
on that instance. This section discusses the most impor-
|
|
tant 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 corre-
|
|
sponding Postfix instance. For safety reasons, this set-
|
|
ting 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-permissions" or "upgrade-configuration", and
|
|
it will replace "start" by "check" so that problems will
|
|
be reported even when the instance is disabled.
|
|
|
|
<b>MAINTAINING SHARED AND NON-SHARED FILES</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 section 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. Specifically, 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 Post-
|
|
fix instance should be checked and updated before any
|
|
other instances.
|
|
|
|
<b>MULTI-INSTANCE API SUMMARY</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 manager 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> parame-
|
|
ter, 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> parame-
|
|
ter 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 run-
|
|
ning different versions of Postfix, or that are not man-
|
|
aged together with the default Postfix instance.
|
|
|
|
<b>ENVIRONMENT VARIABLES</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">post-</a>
|
|
<a href="postfix.1.html">fix(1)</a> -c option, so that <a href="postfix.1.html">postfix(1)</a> commands in
|
|
descendant processes will work correctly.
|
|
|
|
<b>CONFIGURATION PARAMETERS</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 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_wrapper">multi_instance_wrapper</a> (empty)</b>
|
|
The pathname of a multi-instance manager command
|
|
that the <a href="postfix.1.html"><b>postfix</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>NON-SHARED FILES</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#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 direc-
|
|
tory.
|
|
|
|
<b>SEE ALSO</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>LICENSE</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
|
|
|
|
POSTFIX-WRAPPER(5)
|
|
</pre> </body> </html>
|