summaryrefslogtreecommitdiffstats
path: root/html/postfix-wrapper.5.html
diff options
context:
space:
mode:
Diffstat (limited to 'html/postfix-wrapper.5.html')
-rw-r--r--html/postfix-wrapper.5.html272
1 files changed, 272 insertions, 0 deletions
diff --git a/html/postfix-wrapper.5.html b/html/postfix-wrapper.5.html
new file mode 100644
index 0000000..d9a8ba4
--- /dev/null
+++ b/html/postfix-wrapper.5.html
@@ -0,0 +1,272 @@
+<!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 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>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 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>MANAGING AN INDIVIDUAL POSTFIX INSTANCE</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 '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 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>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 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>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 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>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">postfix(1)</a> -c option, so that <a href="postfix.1.html">postfix(1)</a> com-
+ mands 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 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>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> 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>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
+
+ Wietse Venema
+ Google, Inc.
+ 111 8th Avenue
+ New York, NY 10011, USA
+
+ POSTFIX-WRAPPER(5)
+</pre> </body> </html>