From dfd9dca70b2de95d46c9ad5bf7ef4b846938bdae Mon Sep 17 00:00:00 2001 From: Wietse Venema Date: Sun, 25 Jan 2009 00:00:00 -0500 Subject: [PATCH] postfix-2.6-20090125 --- postfix/HISTORY | 6 + postfix/conf/postfix-wrapper | 7 +- postfix/html/postconf.5.html | 5 +- postfix/html/postfix-wrapper.5.html | 190 ++++++++++++++++------------ postfix/html/postfix.1.html | 66 +++++----- postfix/man/man1/postfix.1 | 30 ++--- postfix/man/man5/postconf.5 | 4 +- postfix/man/man5/postfix-wrapper.5 | 170 ++++++++++++++----------- postfix/mantools/postlink | 2 +- postfix/proto/postconf.proto | 5 +- postfix/proto/postfix-wrapper | 168 +++++++++++++----------- postfix/src/global/mail_version.h | 2 +- postfix/src/postfix/postfix.c | 30 ++--- 13 files changed, 377 insertions(+), 308 deletions(-) diff --git a/postfix/HISTORY b/postfix/HISTORY index 55265c157..86d7e24e5 100644 --- a/postfix/HISTORY +++ b/postfix/HISTORY @@ -14940,3 +14940,9 @@ Apologies for any names omitted. More little fixes in the "trivial but useful" postfix-wrapper including instructions. It's ready for testing in the field. File: conf/postfix-wrapper. + +20090125 + + Documentation: more precise description of multi-instance + manager API, and minor edits of the example program. Files: + conf/postfix-wrapper, proto/postfix-wrapper. diff --git a/postfix/conf/postfix-wrapper b/postfix/conf/postfix-wrapper index ff9afef47..aa5c5af0d 100644 --- a/postfix/conf/postfix-wrapper +++ b/postfix/conf/postfix-wrapper @@ -1,8 +1,5 @@ #!/bin/sh -# To view the formatted manual page of this file, type: -# POSTFIXSOURCE/mantools/srctoman - postfix-wrapper | nroff -man - #++ # NAME # postfix-wrapper 1 @@ -197,7 +194,8 @@ instance_dirs=`$POSTCONF -h multi_instance_directories | sed 's/,/ /'` || exit 1 case "$1" in - stop|abort|drain) all_dirs= + stop|quick-stop|abort|drain) + all_dirs= for dir in $config_directory $instance_dirs do all_dirs="$dir $all_dirs" @@ -209,6 +207,7 @@ esac # instance is disabled, replace "postfix start" by "postfix check" # so that problems will still be reported. +err=0 for dir in $all_dirs do case "$1" in diff --git a/postfix/html/postconf.5.html b/postfix/html/postconf.5.html index ed16ac842..0b57706ec 100644 --- a/postfix/html/postconf.5.html +++ b/postfix/html/postconf.5.html @@ -5810,8 +5810,6 @@ Postfix instance, and that are started, stopped, etc., together with the default Postfix instance. Specify a list of pathnames separated by comma or whitespace.

-

This feature is available in Postfix 2.6 and later.

-

When the list of non-default Postfix configuration directories is non-empty, the postfix(1) command will invoke the multi-instance manager specified with the multi_instance_wrapper parameter to @@ -5867,7 +5865,8 @@ becomes also the default value for the sys postfix(1) command invokes when the multi_instance_directories parameter value is non-empty. The pathname may be followed by initial command arguments separated by whitespace; shell -metacharacters are not supported in this context.

+metacharacters such as quotes are not supported in this context. +

The postfix(1) command invokes the manager command with the postfix(1) non-option command arguments on the manager command line, diff --git a/postfix/html/postfix-wrapper.5.html b/postfix/html/postfix-wrapper.5.html index b92315e8f..1e3282fce 100644 --- a/postfix/html/postfix-wrapper.5.html +++ b/postfix/html/postfix-wrapper.5.html @@ -41,85 +41,91 @@ POSTFIX-WRAPPER(5) POSTFIX-WRAPPER(5) To start, stop, update, etc., multiple Postfix instances, use: - # postfix command + # postfix command For example, to find out what Postfix instances are con- figured: - # postfix status + # postfix status +MANAGING AN INDIVIDUAL POSTFIX INSTANCE To manage an individual Postfix instance, use: - # postfix -c /path/to/config_directory command + # postfix -c /path/to/config_directory command -MULTI-INSTANCE DETECTION - While "postfix start/stop/etc" will remain the primary - command interface, the postfix(1) command itself will need - to figure out if a command targets multiple Postfix - instances or just a specific Postfix instance. This deci- - sion can be made with information that is already avail- - able: + When the postfix(1) command is invoked with the -c option, + it will operate only on the specified instance. The same + happens when MAIL_CONFIG is specified in the process envi- + ronment. - When the postfix(1) command is invoked with the -c - option, it will operate only on the specified - instance. We do the same when MAIL_CONFIG is spec- - ified in the process environment. + Otherwise, the postfix(1) command will operate on all + applicable Postfix instances. - Otherwise, the postfix(1) command will operate on - all applicable Postfix instances. +MULTI-INSTANCE MANAGER EXAMPLE + When the postfix(1) command is invoked without -c option + or MAIL_CONFIG environment setting, and non-default Post- + fix instance directories are defined in main.cf with the + multi_instance_directories parameter, postfix(1) invokes + the command specified in main.cf with the + multi_instance_wrapper parameter, instead of invoking + postfix-script. -MULTI-INSTANCE MANAGER HOOK - When the postfix(1) command is invoked without -c option, - and non-default Postfix instance directories are defined - in main.cf with multi_instance_directories, then the post- - fix(1) command invokes the command specified in main.cf - with multi_instance_wrapper, instead of invoking postfix- - script. The multi_instance_wrapper and other main.cf - parameters are listed in the CONFIGURATION PARAMETERS sec- - tion below. + The multi_instance_directories and other main.cf parame- + ters are listed below in the CONFIGURATION PARAMETERS sec- + tion. A useful wrapper implementation can be as simple as: - #!/bin/sh + #!/bin/sh - : ${command_directory?"do not invoke this command directly"} + : ${command_directory?"do not invoke this command directly"} - POSTCONF=$command_directory/postconf - POSTFIX=$command_directory/postfix - instance_dirs=`$POSTCONF -h multi_instance_directories | - sed 's/,/ /'` || exit 1 + POSTCONF=$command_directory/postconf + POSTFIX=$command_directory/postfix + instance_dirs=`$POSTCONF -h multi_instance_directories | + sed 's/,/ /'` || exit 1 - for dir in $config_directory $instance_dirs - do - case "$1" in - stop|abort|flush|reload|drain) - test "`$POSTCONF -c $dir -h multi_instance_enable`" - = yes || continue;; - start) - test "`$POSTCONF -c $dir -h multi_instance_enable`" - = yes || set check;; - esac - $POSTFIX -c $dir "$@" || err=$? - done + err=0 + for dir in $config_directory $instance_dirs + do + case "$1" in + stop|abort|flush|reload|drain) + test "`$POSTCONF -c $dir -h multi_instance_enable`" \ + = yes || continue;; + start) + test "`$POSTCONF -c $dir -h multi_instance_enable`" \ + = yes || set check;; + esac + $POSTFIX -c $dir "$@" || err=$? + done - exit $err + exit $err - This wrapper skips commands such as "stop" that require a - running Postfix instance when a Postfix instance is dis- - abled, and replaces "start" by "check" so that problems - will still be reported. + The postmulti(1) command implements a more sophisticated + approach, based on a combination of C code and scripting. - The postmulti(1) command implements a more sophisticated - approach, based on a combination of C code and scripting. +ENABLING AN INSTANCE FOR MULTI-INSTANCE OPERATION + To enable start/stop/etc. by a multi-instance manager, set + the Postfix instance's main.cf multi_instance_enable + parameter to "yes". This parameter has no effect on sin- + gle-instance operation with "postfix -c" or with a + MAIL_CONFIG environment setting. + + The multi-instance manager program will skip commands such + as "stop" and "flush" when a Postfix instance is disabled, + and will replace "start" by "check" so that problems will + still be reported even when the default instance is dis- + abled. SHARED VERSUS NON-SHARED FILES - Some files are shared between Postfix instances (such as - executables and manpages) and some files are per-instance - (such as the queue). See the NON-SHARED FILES section - below for a list of per-instance files. + Some files are shared between Postfix instances, such as + executables and manpages, and some files are per-instance, + such as the queue. See the NON-SHARED FILES section below + for a list of per-instance files. - Until now, executables, manpages, etc., have been checked - or updated as part of the default Postfix instance. With + Before Postfix multi-instance support was implemented, the + executables, manpages, etc., have always been checked or + updated as part of the default Postfix instance. With multi-instance support, we simply continue to do this. Non-default Postfix instances will check or update only their non-shared files. @@ -127,64 +133,84 @@ POSTFIX-WRAPPER(5) POSTFIX-WRAPPER(5) The consequence of this approach is that the default Post- fix instance should be updated before any other instances. -IMPLEMENTATION NOTES +MULTI-INSTANCE API SUMMARY + Only the multi-instance manager implements support for the + multi_instance_enable configuration parameter. The multi- + instance manager will not start Postfix instances without + "multi_instance_enable = yes". This allows a Postfix + instance to be tested by hand before it is placed under + control of a multi-instance manager. + The postfix(1) command ignores the multi_instance_directo- - ries and multi_instance_wrapper parameters when the -c + ries and multi_instance_wrapper parameters when the -c option is specified, or when MAIL_CONFIG is present in the process environment. - Otherwise, the postfix(1) command uses the - multi_instance_wrapper parameter only when the - multi_instance_directories parameter value is non-empty. + Otherwise, when the multi_instance_directories parameter + value is non-empty, the postfix(1) command executes the + command specified with the multi_instance_wrapper parame- + ter, instead of executing the commands in postfix-script. - The multi-instance manager must replace a "start" command - by "check" when a Postfix instance does not have + The multi-instance manager skips commands such as "stop" + or "reload" that require a running Postfix instance, when + an instance does not have "multi_instance_enable = yes". + This avoids false error messages. + + The multi-instance manager replaces a "start" command by + "check" when a Postfix instance does not have "multi_instance_enable = yes". This substitution ensures - that problems will still be reported. + that problems will still be reported even when the default + instance is disabled. + + No Postfix command or script will update or check shared + files unless it is running in the context of the default + Postfix instance. Therefore, the default instance should + be updated before any other Postfix instances. Set-gid commands such as postdrop(1) and postqueue(1) effectively append the multi_instance_directories parame- ter value to the legacy alternate_config_directories - parameter value. + parameter value. The commands use this information to + determine whether a -c option or MAIL_CONFIG environment + setting specifies a legitimate value. The legacy alternate_config_directories 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. - No Postfix command or script will update or check shared - files unless it is running in the context of the default - Postfix instance. - ENVIRONMENT VARIABLES MAIL_CONFIG When present, this forces the postfix(1) command to operate only on the specified Postfix instance. - This environment variable is exported by the post- - fix(1) -c option, so that postfix(1) commands in + This environment variable is exported by the post- + fix(1) -c option, so that postfix(1) commands in descendant processes will work correctly. CONFIGURATION PARAMETERS + The text below provides only a parameter summary. See + postconf(5) for more details. + multi_instance_directories (empty) - An optional list of non-default Postfix configura- + An optional list of non-default Postfix configura- tion directories; these directories belong to addi- - tional Postfix instances that share the Postfix + tional Postfix instances that share the Postfix executable files and documentation with the default - Postfix instance, and that are started, stopped, + Postfix instance, and that are started, stopped, etc., together with the default Postfix instance. multi_instance_wrapper (empty) - The pathname of a multi-instance manager command - that the postfix(1) command invokes when the - multi_instance_directories parameter value is non- + The pathname of a multi-instance manager command + that the postfix(1) command invokes when the + multi_instance_directories parameter value is non- empty. multi_instance_name (empty) - The optional instance name of this Postfix + The optional instance name of this Postfix instance. multi_instance_group (empty) - The optional instance group name of this Postfix + The optional instance group name of this Postfix instance. multi_instance_enable (no) @@ -193,7 +219,7 @@ POSTFIX-WRAPPER(5) POSTFIX-WRAPPER(5) NON-SHARED FILES config_directory (see 'postconf -d' output) - The default location of the Postfix main.cf and + The default location of the Postfix main.cf and master.cf configuration files. data_directory (see 'postconf -d' output) @@ -201,7 +227,7 @@ POSTFIX-WRAPPER(5) POSTFIX-WRAPPER(5) example: caches, pseudo-random numbers). queue_directory (see 'postconf -d' output) - The location of the Postfix top-level queue direc- + The location of the Postfix top-level queue direc- tory. SEE ALSO @@ -210,7 +236,7 @@ POSTFIX-WRAPPER(5) POSTFIX-WRAPPER(5) postmulti(1) full-blown multi-instance manager LICENSE - The Secure Mailer license must be distributed with this + The Secure Mailer license must be distributed with this software. AUTHOR(S) diff --git a/postfix/html/postfix.1.html b/postfix/html/postfix.1.html index ffc4a7b98..ccef49f0c 100644 --- a/postfix/html/postfix.1.html +++ b/postfix/html/postfix.1.html @@ -197,53 +197,53 @@ POSTFIX(1) POSTFIX(1) The directory with Postfix-writable data files (for example: caches, pseudo-random numbers). - Available in Postfix version 2.6 and later: - - 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_wrapper (empty) - The pathname of a multi-instance manager command - that the postfix(1) command invokes when the - multi_instance_directories parameter value is non- - empty. - - 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. - Other configuration parameters: config_directory (see 'postconf -d' output) - The default location of the Postfix main.cf and + The default location of the Postfix main.cf and master.cf configuration files. import_environment (see 'postconf -d' output) - The list of environment parameters that a Postfix + The list of environment parameters that a Postfix process will import from a non-Postfix parent process. syslog_facility (mail) The syslog facility of Postfix logging. - syslog_name (postfix) - The mail system name that is prepended to the - process name in syslog records, so that "smtpd" + 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". + Available in Postfix version 2.6 and later: + + 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_wrapper (empty) + The pathname of a multi-instance manager command + that the postfix(1) command invokes when the + multi_instance_directories parameter value is non- + empty. + + 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. + FILES Prior to Postfix version 2.6, all of the following files were in $config_directory. Some files are now in $dae- diff --git a/postfix/man/man1/postfix.1 b/postfix/man/man1/postfix.1 index 1557775db..f1d59b8c7 100644 --- a/postfix/man/man1/postfix.1 +++ b/postfix/man/man1/postfix.1 @@ -164,6 +164,19 @@ Available in Postfix version 2.5 and later: The directory with Postfix-writable data files (for example: caches, pseudo-random numbers). .PP +Other configuration parameters: +.IP "\fBconfig_directory (see 'postconf -d' output)\fR" +The default location of the Postfix main.cf and master.cf +configuration files. +.IP "\fBimport_environment (see 'postconf -d' output)\fR" +The list of environment parameters that a Postfix process will +import from a non-Postfix parent process. +.IP "\fBsyslog_facility (mail)\fR" +The syslog facility of Postfix logging. +.IP "\fBsyslog_name (see 'postconf -d' output)\fR" +The mail system name that is prepended to the process name in syslog +records, so that "smtpd" becomes, for example, "postfix/smtpd". +.PP Available in Postfix version 2.6 and later: .IP "\fBmulti_instance_directories (empty)\fR" An optional list of non-default Postfix configuration directories; @@ -180,21 +193,8 @@ The optional instance group name of this Postfix instance. .IP "\fBmulti_instance_name (empty)\fR" The optional instance name of this Postfix instance. .IP "\fBmulti_instance_enable (no)\fR" -Allow this Postfix instance to be started, stopped, etc., by -a multi-instance manager. -.PP -Other configuration parameters: -.IP "\fBconfig_directory (see 'postconf -d' output)\fR" -The default location of the Postfix main.cf and master.cf -configuration files. -.IP "\fBimport_environment (see 'postconf -d' output)\fR" -The list of environment parameters that a Postfix process will -import from a non-Postfix parent process. -.IP "\fBsyslog_facility (mail)\fR" -The syslog facility of Postfix logging. -.IP "\fBsyslog_name (postfix)\fR" -The mail system name that is prepended to the process name in syslog -records, so that "smtpd" becomes, for example, "postfix/smtpd". +Allow this Postfix instance to be started, stopped, etc., by a +multi-instance manager. .SH "FILES" .na .nf diff --git a/postfix/man/man5/postconf.5 b/postfix/man/man5/postconf.5 index 6a3bf7dec..73d2e56c0 100644 --- a/postfix/man/man5/postconf.5 +++ b/postfix/man/man5/postconf.5 @@ -3219,8 +3219,6 @@ Postfix instance, and that are started, stopped, etc., together with the default Postfix instance. Specify a list of pathnames separated by comma or whitespace. .PP -This feature is available in Postfix 2.6 and later. -.PP When the list of non-default Postfix configuration directories is non-empty, the \fBpostfix\fR(1) command will invoke the multi-instance manager specified with the multi_instance_wrapper parameter to @@ -3252,7 +3250,7 @@ The pathname of a multi-instance manager command that the \fBpostfix\fR(1) command invokes when the multi_instance_directories parameter value is non-empty. The pathname may be followed by initial command arguments separated by whitespace; shell -metacharacters are not supported in this context. +metacharacters such as quotes are not supported in this context. .PP The \fBpostfix\fR(1) command invokes the manager command with the \fBpostfix\fR(1) non-option command arguments on the manager command line, diff --git a/postfix/man/man5/postfix-wrapper.5 b/postfix/man/man5/postfix-wrapper.5 index 179c31cc7..e09e5f065 100644 --- a/postfix/man/man5/postfix-wrapper.5 +++ b/postfix/man/man5/postfix-wrapper.5 @@ -40,137 +40,157 @@ to use the familiar "postfix start / stop / reload / upgrade To start, stop, update, etc., multiple Postfix instances, use: - -.nf - # postfix \fIcommand\fR -.fi - +.IP +# postfix \fIcommand\fR +.PP For example, to find out what Postfix instances are configured: - -.nf - # postfix status - -To manage an individual Postfix instance, use: - -.nf - # postfix -c \fI/path/to/config_directory command\fR -.fi -.SH "MULTI-INSTANCE DETECTION" +.IP +# postfix status +.SH "MANAGING AN INDIVIDUAL POSTFIX INSTANCE" .na .nf .ad .fi -While "postfix start/stop/etc" will remain the primary -command interface, the postfix(1) command itself will need -to figure out if a command targets multiple Postfix instances -or just a specific Postfix instance. This decision can be -made with information that is already available: +To manage an individual Postfix instance, use: .IP -When the postfix(1) command is invoked with the -c -option, it will operate only on the specified instance. -We do the same when MAIL_CONFIG is specified in the -process environment. +# postfix -c \fI/path/to/config_directory command\fR +.PP +When the postfix(1) command is invoked with the -c option, +it will operate only on the specified instance. The same +happens when MAIL_CONFIG is specified in the process +environment. Otherwise, the postfix(1) command will operate on all applicable Postfix instances. -.SH "MULTI-INSTANCE MANAGER HOOK" +.SH "MULTI-INSTANCE MANAGER EXAMPLE" .na .nf .ad .fi -When the postfix(1) command is invoked without -c option, -and non-default Postfix instance directories are defined -in main.cf with multi_instance_directories, then the -postfix(1) command invokes the command specified in main.cf -with multi_instance_wrapper, instead of invoking postfix-script. -The multi_instance_wrapper and other main.cf parameters are -listed in the CONFIGURATION PARAMETERS section below. +When the postfix(1) command is invoked without -c option +or MAIL_CONFIG environment setting, and non-default Postfix +instance directories are defined in main.cf with the +multi_instance_directories parameter, postfix(1) invokes +the command specified in main.cf with the multi_instance_wrapper +parameter, instead of invoking postfix-script. + +The multi_instance_directories and other main.cf parameters +are listed below in the CONFIGURATION PARAMETERS section. A useful wrapper implementation can be as simple as: - +.IP .nf - #!/bin/sh +#!/bin/sh - : ${command_directory?"do not invoke this command directly"} +: ${command_directory?"do not invoke this command directly"} - POSTCONF=$command_directory/postconf - POSTFIX=$command_directory/postfix - instance_dirs=`$POSTCONF -h multi_instance_directories | - sed 's/,/ /'` || exit 1 +POSTCONF=$command_directory/postconf +POSTFIX=$command_directory/postfix +instance_dirs=\`$POSTCONF -h multi_instance_directories | + sed 's/,/ /'\` || exit 1 - for dir in $config_directory $instance_dirs - do - case "$1" in - stop|abort|flush|reload|drain) - test "`$POSTCONF -c $dir -h multi_instance_enable`" - = yes || continue;; - start) - test "`$POSTCONF -c $dir -h multi_instance_enable`" - = yes || set check;; - esac - $POSTFIX -c $dir "$@" || err=$? - done +err=0 +for dir in $config_directory $instance_dirs +do + case "$1" in + stop|abort|flush|reload|drain) + test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e + = yes || continue;; + start) + test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e + = yes || set check;; + esac + $POSTFIX -c $dir "$@" || err=$? +done - exit $err +exit $err .fi - -This wrapper skips commands such as "stop" that require a -running Postfix instance when a Postfix instance is disabled, -and replaces "start" by "check" so that problems will still -be reported. - +.PP The postmulti(1) command implements a more sophisticated approach, based on a combination of C code and scripting. +.SH "ENABLING AN INSTANCE FOR MULTI-INSTANCE OPERATION" +.na +.nf +.ad +.fi +To enable start/stop/etc. by a multi-instance manager, set +the Postfix instance's main.cf multi_instance_enable parameter +to "yes". This parameter has no effect on single-instance +operation with "postfix -c" or with a MAIL_CONFIG environment +setting. + +The multi-instance manager program will skip commands such +as "stop" and "flush" when a Postfix instance is disabled, +and will replace "start" by "check" so that problems will +still be reported even when the default instance is disabled. .SH "SHARED VERSUS NON-SHARED FILES" .na .nf .ad .fi -Some files are shared between Postfix instances (such as -executables and manpages) and some files are per-instance -(such as the queue). See the NON-SHARED FILES section below +Some files are shared between Postfix instances, such as +executables and manpages, and some files are per-instance, +such as the queue. See the NON-SHARED FILES section below for a list of per-instance files. -Until now, executables, manpages, etc., have been checked -or updated as part of the default Postfix instance. With +Before Postfix multi-instance support was implemented, the +executables, manpages, etc., have always been checked or +updated as part of the default Postfix instance. With multi-instance support, we simply continue to do this. Non-default Postfix instances will check or update only their non-shared files. The consequence of this approach is that the default Postfix instance should be updated before any other instances. -.SH "IMPLEMENTATION NOTES" +.SH "MULTI-INSTANCE API SUMMARY" .na .nf .ad .fi +Only the multi-instance manager implements support for the +multi_instance_enable configuration parameter. The +multi-instance manager will not start Postfix instances +without "multi_instance_enable = yes". This allows a Postfix +instance to be tested by hand before it is placed under +control of a multi-instance manager. + The postfix(1) command ignores the multi_instance_directories and multi_instance_wrapper parameters when the -c option is specified, or when MAIL_CONFIG is present in the process environment. -Otherwise, the postfix(1) command uses the multi_instance_wrapper -parameter only when the multi_instance_directories parameter -value is non-empty. +Otherwise, when the multi_instance_directories parameter +value is non-empty, the postfix(1) command executes the +command specified with the multi_instance_wrapper parameter, +instead of executing the commands in postfix-script. -The multi-instance manager must replace a "start" command by +The multi-instance manager skips commands such as "stop" +or "reload" that require a running Postfix instance, when +an instance does not have "multi_instance_enable = yes". +This avoids false error messages. + +The multi-instance manager replaces a "start" command by "check" when a Postfix instance does not have "multi_instance_enable = yes". This substitution ensures -that problems will still be reported. +that problems will still be reported even when the default +instance is disabled. + +No Postfix command or script will update or check shared +files unless it is running in the context of the default +Postfix instance. Therefore, the default instance should +be updated before any other Postfix instances. Set-gid commands such as postdrop(1) and postqueue(1) effectively append the multi_instance_directories parameter value to the legacy alternate_config_directories parameter -value. +value. The commands use this information to determine whether +a -c option or MAIL_CONFIG environment setting specifies a +legitimate value. The legacy alternate_config_directories 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. - -No Postfix command or script will update or check shared -files unless it is running in the context of the default -Postfix instance. .SH "ENVIRONMENT VARIABLES" .na .nf @@ -187,6 +207,8 @@ correctly. .nf .ad .fi +The text below provides only a parameter summary. See +postconf(5) for more details. .IP "\fBmulti_instance_directories (empty)\fR" An optional list of non-default Postfix configuration directories; these directories belong to additional Postfix instances that share diff --git a/postfix/mantools/postlink b/postfix/mantools/postlink index 591a7ebef..ddf7e951a 100755 --- a/postfix/mantools/postlink +++ b/postfix/mantools/postlink @@ -715,7 +715,7 @@ while (<>) { s/[]*postcat[<\/bB>]*\(1\)/$&<\/a>/g; s/[]*post[-<\/bB>]*\n*[ ]*conf[<\/bB>]*\(1\)/$&<\/a>/g; s/[]*postdrop[<\/bB>]*\(1\)/$&<\/a>/g; - s/[]*postfix[<\/bB>]*\(1\)/$&<\/a>/g; + s/[]*post[-<\/bB>]*\n* *[]*fix[<\/bB>]*\(1\)/$&<\/a>/g; s/[]*postkick[<\/bB>]*\(1\)/$&<\/a>/g; s/[]*postlock[<\/bB>]*\(1\)/$&<\/a>/g; s/[]*postlog[<\/bB>]*\(1\)/$&<\/a>/g; diff --git a/postfix/proto/postconf.proto b/postfix/proto/postconf.proto index 71ff51181..435a35fea 100644 --- a/postfix/proto/postconf.proto +++ b/postfix/proto/postconf.proto @@ -12033,8 +12033,6 @@ Postfix instance, and that are started, stopped, etc., together with the default Postfix instance. Specify a list of pathnames separated by comma or whitespace.

-

This feature is available in Postfix 2.6 and later.

-

When the list of non-default Postfix configuration directories is non-empty, the postfix(1) command will invoke the multi-instance manager specified with the multi_instance_wrapper parameter to @@ -12049,7 +12047,8 @@ Postfix instances.

postfix(1) command invokes when the multi_instance_directories parameter value is non-empty. The pathname may be followed by initial command arguments separated by whitespace; shell -metacharacters are not supported in this context.

+metacharacters such as quotes are not supported in this context. +

The postfix(1) command invokes the manager command with the postfix(1) non-option command arguments on the manager command line, diff --git a/postfix/proto/postfix-wrapper b/postfix/proto/postfix-wrapper index 5b5a845c0..7b608c473 100644 --- a/postfix/proto/postfix-wrapper +++ b/postfix/proto/postfix-wrapper @@ -34,129 +34,147 @@ # # To start, stop, update, etc., multiple Postfix instances, # use: -# -# .nf -# # postfix \fIcommand\fR -# .fi -# +# .IP +# # postfix \fIcommand\fR +# .PP # For example, to find out what Postfix instances are configured: -# -# .nf -# # postfix status -# -# To manage an individual Postfix instance, use: -# -# .nf -# # postfix -c \fI/path/to/config_directory command\fR -# .fi -# MULTI-INSTANCE DETECTION +# .IP +# # postfix status +# MANAGING AN INDIVIDUAL POSTFIX INSTANCE # .ad # .fi -# While "postfix start/stop/etc" will remain the primary -# command interface, the postfix(1) command itself will need -# to figure out if a command targets multiple Postfix instances -# or just a specific Postfix instance. This decision can be -# made with information that is already available: +# To manage an individual Postfix instance, use: # .IP -# When the postfix(1) command is invoked with the -c -# option, it will operate only on the specified instance. -# We do the same when MAIL_CONFIG is specified in the -# process environment. +# # postfix -c \fI/path/to/config_directory command\fR +# .PP +# When the postfix(1) command is invoked with the -c option, +# it will operate only on the specified instance. The same +# happens when MAIL_CONFIG is specified in the process +# environment. # # Otherwise, the postfix(1) command will operate on all # applicable Postfix instances. -# MULTI-INSTANCE MANAGER HOOK +# MULTI-INSTANCE MANAGER EXAMPLE # .ad # .fi -# When the postfix(1) command is invoked without -c option, -# and non-default Postfix instance directories are defined -# in main.cf with multi_instance_directories, then the -# postfix(1) command invokes the command specified in main.cf -# with multi_instance_wrapper, instead of invoking postfix-script. -# The multi_instance_wrapper and other main.cf parameters are -# listed in the CONFIGURATION PARAMETERS section below. +# When the postfix(1) command is invoked without -c option +# or MAIL_CONFIG environment setting, and non-default Postfix +# instance directories are defined in main.cf with the +# multi_instance_directories parameter, postfix(1) invokes +# the command specified in main.cf with the multi_instance_wrapper +# parameter, instead of invoking postfix-script. +# +# The multi_instance_directories and other main.cf parameters +# are listed below in the CONFIGURATION PARAMETERS section. # # A useful wrapper implementation can be as simple as: -# +# .IP # .nf -# #!/bin/sh +# #!/bin/sh # -# : ${command_directory?"do not invoke this command directly"} +# : ${command_directory?"do not invoke this command directly"} # -# POSTCONF=$command_directory/postconf -# POSTFIX=$command_directory/postfix -# instance_dirs=`$POSTCONF -h multi_instance_directories | -# sed 's/,/ /'` || exit 1 +# POSTCONF=$command_directory/postconf +# POSTFIX=$command_directory/postfix +# instance_dirs=\`$POSTCONF -h multi_instance_directories | +# sed 's/,/ /'\` || exit 1 # -# for dir in $config_directory $instance_dirs -# do -# case "$1" in -# stop|abort|flush|reload|drain) -# test "`$POSTCONF -c $dir -h multi_instance_enable`" -# = yes || continue;; -# start) -# test "`$POSTCONF -c $dir -h multi_instance_enable`" -# = yes || set check;; -# esac -# $POSTFIX -c $dir "$@" || err=$? -# done +# err=0 +# for dir in $config_directory $instance_dirs +# do +# case "$1" in +# stop|abort|flush|reload|drain) +# test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e +# = yes || continue;; +# start) +# test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e +# = yes || set check;; +# esac +# $POSTFIX -c $dir "$@" || err=$? +# done # -# exit $err +# exit $err # .fi -# -# This wrapper skips commands such as "stop" that require a -# running Postfix instance when a Postfix instance is disabled, -# and replaces "start" by "check" so that problems will still -# be reported. -# +# .PP # The postmulti(1) command implements a more sophisticated # approach, based on a combination of C code and scripting. +# ENABLING AN INSTANCE FOR MULTI-INSTANCE OPERATION +# .ad +# .fi +# To enable start/stop/etc. by a multi-instance manager, set +# the Postfix instance's main.cf multi_instance_enable parameter +# to "yes". This parameter has no effect on single-instance +# operation with "postfix -c" or with a MAIL_CONFIG environment +# setting. +# +# The multi-instance manager program will skip commands such +# as "stop" and "flush" when a Postfix instance is disabled, +# and will replace "start" by "check" so that problems will +# still be reported even when the default instance is disabled. # SHARED VERSUS NON-SHARED FILES # .ad # .fi -# Some files are shared between Postfix instances (such as -# executables and manpages) and some files are per-instance -# (such as the queue). See the NON-SHARED FILES section below +# Some files are shared between Postfix instances, such as +# executables and manpages, and some files are per-instance, +# such as the queue. See the NON-SHARED FILES section below # for a list of per-instance files. # -# Until now, executables, manpages, etc., have been checked -# or updated as part of the default Postfix instance. With +# Before Postfix multi-instance support was implemented, the +# executables, manpages, etc., have always been checked or +# updated as part of the default Postfix instance. With # multi-instance support, we simply continue to do this. # Non-default Postfix instances will check or update only # their non-shared files. # # The consequence of this approach is that the default Postfix # instance should be updated before any other instances. -# IMPLEMENTATION NOTES +# MULTI-INSTANCE API SUMMARY # .ad # .fi +# Only the multi-instance manager implements support for the +# multi_instance_enable configuration parameter. The +# multi-instance manager will not start Postfix instances +# without "multi_instance_enable = yes". This allows a Postfix +# instance to be tested by hand before it is placed under +# control of a multi-instance manager. +# # The postfix(1) command ignores the multi_instance_directories # and multi_instance_wrapper parameters when the -c option # is specified, or when MAIL_CONFIG is present in the process # environment. # -# Otherwise, the postfix(1) command uses the multi_instance_wrapper -# parameter only when the multi_instance_directories parameter -# value is non-empty. +# Otherwise, when the multi_instance_directories parameter +# value is non-empty, the postfix(1) command executes the +# command specified with the multi_instance_wrapper parameter, +# instead of executing the commands in postfix-script. # -# The multi-instance manager must replace a "start" command by +# The multi-instance manager skips commands such as "stop" +# or "reload" that require a running Postfix instance, when +# an instance does not have "multi_instance_enable = yes". +# This avoids false error messages. +# +# The multi-instance manager replaces a "start" command by # "check" when a Postfix instance does not have # "multi_instance_enable = yes". This substitution ensures -# that problems will still be reported. +# that problems will still be reported even when the default +# instance is disabled. +# +# No Postfix command or script will update or check shared +# files unless it is running in the context of the default +# Postfix instance. Therefore, the default instance should +# be updated before any other Postfix instances. # # Set-gid commands such as postdrop(1) and postqueue(1) # effectively append the multi_instance_directories parameter # value to the legacy alternate_config_directories parameter -# value. +# value. The commands use this information to determine whether +# a -c option or MAIL_CONFIG environment setting specifies a +# legitimate value. # # The legacy alternate_config_directories 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. -# -# No Postfix command or script will update or check shared -# files unless it is running in the context of the default -# Postfix instance. # ENVIRONMENT VARIABLES # .ad # .fi @@ -169,6 +187,8 @@ # CONFIGURATION PARAMETERS # .ad # .fi +# The text below provides only a parameter summary. See +# postconf(5) for more details. # .IP "\fBmulti_instance_directories (empty)\fR" # An optional list of non-default Postfix configuration directories; # these directories belong to additional Postfix instances that share diff --git a/postfix/src/global/mail_version.h b/postfix/src/global/mail_version.h index 9c6992a30..1594f2f8d 100644 --- a/postfix/src/global/mail_version.h +++ b/postfix/src/global/mail_version.h @@ -20,7 +20,7 @@ * Patches change both the patchlevel and the release date. Snapshots have no * patchlevel; they change the release date only. */ -#define MAIL_RELEASE_DATE "20090123" +#define MAIL_RELEASE_DATE "20090125" #define MAIL_VERSION_NUMBER "2.6" #ifdef SNAPSHOT diff --git a/postfix/src/postfix/postfix.c b/postfix/src/postfix/postfix.c index 4f33c22f7..3747e7800 100644 --- a/postfix/src/postfix/postfix.c +++ b/postfix/src/postfix/postfix.c @@ -154,6 +154,19 @@ /* The directory with Postfix-writable data files (for example: /* caches, pseudo-random numbers). /* .PP +/* Other configuration parameters: +/* .IP "\fBconfig_directory (see 'postconf -d' output)\fR" +/* The default location of the Postfix main.cf and master.cf +/* configuration files. +/* .IP "\fBimport_environment (see 'postconf -d' output)\fR" +/* The list of environment parameters that a Postfix process will +/* import from a non-Postfix parent process. +/* .IP "\fBsyslog_facility (mail)\fR" +/* The syslog facility of Postfix logging. +/* .IP "\fBsyslog_name (see 'postconf -d' output)\fR" +/* The mail system name that is prepended to the process name in syslog +/* records, so that "smtpd" becomes, for example, "postfix/smtpd". +/* .PP /* Available in Postfix version 2.6 and later: /* .IP "\fBmulti_instance_directories (empty)\fR" /* An optional list of non-default Postfix configuration directories; @@ -170,21 +183,8 @@ /* .IP "\fBmulti_instance_name (empty)\fR" /* The optional instance name of this Postfix instance. /* .IP "\fBmulti_instance_enable (no)\fR" -/* Allow this Postfix instance to be started, stopped, etc., by -/* a multi-instance manager. -/* .PP -/* Other configuration parameters: -/* .IP "\fBconfig_directory (see 'postconf -d' output)\fR" -/* The default location of the Postfix main.cf and master.cf -/* configuration files. -/* .IP "\fBimport_environment (see 'postconf -d' output)\fR" -/* The list of environment parameters that a Postfix process will -/* import from a non-Postfix parent process. -/* .IP "\fBsyslog_facility (mail)\fR" -/* The syslog facility of Postfix logging. -/* .IP "\fBsyslog_name (postfix)\fR" -/* The mail system name that is prepended to the process name in syslog -/* records, so that "smtpd" becomes, for example, "postfix/smtpd". +/* Allow this Postfix instance to be started, stopped, etc., by a +/* multi-instance manager. /* FILES /* .ad /* .fi