diff options
Diffstat (limited to 'html/postfix-wrapper.5.html')
| -rw-r--r-- | html/postfix-wrapper.5.html | 272 |
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..bf84eb8 --- /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=utf-8"> +<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> |