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.
#!/bin/sh
-# To view the formatted manual page of this file, type:
-# POSTFIXSOURCE/mantools/srctoman - postfix-wrapper | nroff -man
-
#++
# NAME
# postfix-wrapper 1
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"
# 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
with the default Postfix instance. Specify a list of pathnames
separated by comma or whitespace. </p>
-<p> This feature is available in Postfix 2.6 and later. </p>
-
<p> When the list of non-default Postfix configuration directories
is non-empty, the <a href="postfix.1.html">postfix(1)</a> command will invoke the multi-instance
manager specified with the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameter to
<a href="postfix.1.html">postfix(1)</a> command invokes when the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>
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. </p>
+metacharacters such as quotes are not supported in this context.
+</p>
<p> The <a href="postfix.1.html">postfix(1)</a> command invokes the manager command with the
<a href="postfix.1.html">postfix(1)</a> non-option command arguments on the manager command line,
To start, stop, update, etc., multiple Postfix instances,
use:
- # postfix <i>command</i>
+ # postfix <i>command</i>
For example, to find out what Postfix instances are con-
figured:
- # postfix status
+ # postfix status
+<b>MANAGING AN INDIVIDUAL POSTFIX INSTANCE</b>
To manage an individual Postfix instance, use:
- # postfix -c <i>/path/to/config</i><b>_</b><i>directory command</i>
-
-<b>MULTI-INSTANCE DETECTION</b>
- While "postfix start/stop/etc" will remain the primary
- command interface, the <a href="postfix.1.html">postfix(1)</a> 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 <a href="postfix.1.html">postfix(1)</a> 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 <a href="postfix.1.html">postfix(1)</a> command will operate on
- all applicable Postfix instances.
-
-<b>MULTI-INSTANCE MANAGER HOOK</b>
- When the <a href="postfix.1.html">postfix(1)</a> command is invoked without -c option,
- and non-default Postfix instance directories are defined
- in <a href="postconf.5.html">main.cf</a> with <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>, then the post-
- fix(1) command invokes the command specified in <a href="postconf.5.html">main.cf</a>
- with <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a>, instead of invoking postfix-
- script. The <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> and other <a href="postconf.5.html">main.cf</a>
- parameters are listed in the CONFIGURATION PARAMETERS sec-
- tion below.
+ # postfix -c <i>/path/to/config</i><b>_</b><i>directory command</i>
- A useful wrapper implementation can be as simple as:
-
- #!/bin/sh
-
- : ${<a href="postconf.5.html#command_directory">command_directory</a>?"do not invoke this command directly"}
+ When the <a href="postfix.1.html">postfix(1)</a> 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.
- 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
+ Otherwise, the <a href="postfix.1.html">postfix(1)</a> command will operate on all
+ applicable Postfix instances.
- 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 || set check;;
- esac
- $POSTFIX -c $dir "$@" || err=$?
- done
+<b>MULTI-INSTANCE MANAGER EXAMPLE</b>
+ When the <a href="postfix.1.html">postfix(1)</a> command is invoked without -c option
+ or MAIL_CONFIG environment setting, and non-default Post-
+ fix instance directories are defined in <a href="postconf.5.html">main.cf</a> with the
+ <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter, <a href="postfix.1.html">postfix(1)</a> invokes
+ the command specified in <a href="postconf.5.html">main.cf</a> with the
+ <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameter, instead of invoking
+ postfix-script.
- exit $err
+ 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.
- 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.
+ A useful wrapper implementation can be as simple as:
- The postmulti(1) command implements a more sophisticated
- approach, based on a combination of C code and scripting.
+ #!/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 || set check;;
+ esac
+ $POSTFIX -c $dir "$@" || err=$?
+ done
+
+ exit $err
+
+ The postmulti(1) command implements a more sophisticated
+ approach, based on a combination of C code and scripting.
+
+<b>ENABLING AN INSTANCE FOR MULTI-INSTANCE OPERATION</b>
+ To enable start/stop/etc. by a multi-instance manager, set
+ the Postfix instance's <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>
+ 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.
<b>SHARED VERSUS NON-SHARED FILES</b>
- 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
+ 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.
+
+ 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 Post-
fix instance should be updated before any other instances.
-<b>IMPLEMENTATION NOTES</b>
+<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 not start Postfix instances without
+ "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". This allows a Postfix
+ instance to be tested by hand before it is placed under
+ control of a multi-instance manager.
+
The <a href="postfix.1.html">postfix(1)</a> command ignores the <a href="postconf.5.html#multi_instance_directories">multi_instance_directo</a>-
- <a href="postconf.5.html#multi_instance_directories">ries</a> and <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameters when the -c
+ <a href="postconf.5.html#multi_instance_directories">ries</a> and <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameters when the -c
option is specified, or when MAIL_CONFIG is present in the
process environment.
- Otherwise, the <a href="postfix.1.html">postfix(1)</a> command uses the
- <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameter only when the
- <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter value is non-empty.
+ 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 must replace a "start" command
- by "check" when a Postfix instance does not have
+ The multi-instance manager replaces a "start" command by
+ "check" when a Postfix instance does not have
"<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = 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 <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.
+ 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.
- No Postfix command or script will update or check shared
- files unless it is running in the context of 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 post-
-
fix(1) -c option, so that <a href="postfix.1.html">postfix(1)</a> commands in
+ 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-
+ 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.
<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-
+ 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
+ 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
+ The optional instance group name of this Postfix
instance.
<b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b>
<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
+ 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>
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-
+ The location of the Postfix top-level queue direc-
tory.
<b>SEE ALSO</b>
postmulti(1) full-blown multi-instance manager
<b>LICENSE</b>
- The Secure Mailer license must be distributed with this
+ The Secure Mailer license must be distributed with this
software.
<b>AUTHOR(S)</b>
The directory with Postfix-writable data files (for
example: caches, pseudo-random numbers).
+ Other configuration parameters:
+
+ <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#import_environment">import_environment</a> (see 'postconf -d' output)</b>
+ The list of environment parameters that a Postfix
+ process will import from a non-Postfix parent
+ process.
+
+ <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
+ The syslog facility of Postfix logging.
+
+ <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
+ 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:
<b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b>
- 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.
<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-
+ 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_group">multi_instance_group</a> (empty)</b>
- The optional instance group name of this Postfix
+ The optional instance group name of this Postfix
instance.
<b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b>
- The optional instance name of this Postfix
+ The optional instance 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.
- Other configuration parameters:
-
- <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#import_environment">import_environment</a> (see 'postconf -d' output)</b>
- The list of environment parameters that a Postfix
- process will import from a non-Postfix parent
- process.
-
- <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
- The syslog facility of Postfix logging.
-
- <b><a href="postconf.5.html#syslog_name">syslog_name</a> (postfix)</b>
- The mail system name that is prepended to the
- process name in syslog records, so that "smtpd"
- becomes, for example, "postfix/smtpd".
-
<b>FILES</b>
Prior to Postfix version 2.6, all of the following files
were in <b>$<a href="postconf.5.html#config_directory">config_directory</a></b>. Some files are now in <b>$<a href="postconf.5.html#daemon_directory">dae</a>-</b>
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;
.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
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
\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,
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.
-A useful wrapper implementation can be as simple as:
+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
-
- : ${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
-
- 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
-.fi
+#!/bin/sh
+
+: ${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
-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.
+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
+.fi
+.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 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 must replace a "start" command by
+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
.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
s/[<bB>]*postcat[<\/bB>]*\(1\)/<a href="postcat.1.html">$&<\/a>/g;
s/[<bB>]*post[-<\/bB>]*\n*[ <bB>]*conf[<\/bB>]*\(1\)/<a href="postconf.1.html">$&<\/a>/g;
s/[<bB>]*postdrop[<\/bB>]*\(1\)/<a href="postdrop.1.html">$&<\/a>/g;
- s/[<bB>]*postfix[<\/bB>]*\(1\)/<a href="postfix.1.html">$&<\/a>/g;
+ s/[<bB>]*post
[-<\/bB>]*\n* *[<bB>]*fix[<\/bB>]*\(1\)/<a href="postfix.1.html">$&<\/a>/g;
s/[<bB>]*postkick[<\/bB>]*\(1\)/<a href="postkick.1.html">$&<\/a>/g;
s/[<bB>]*postlock[<\/bB>]*\(1\)/<a href="postlock.1.html">$&<\/a>/g;
s/[<bB>]*postlog[<\/bB>]*\(1\)/<a href="postlog.1.html">$&<\/a>/g;
with the default Postfix instance. Specify a list of pathnames
separated by comma or whitespace. </p>
-<p> This feature is available in Postfix 2.6 and later. </p>
-
<p> 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
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. </p>
+metacharacters such as quotes are not supported in this context.
+</p>
<p> The postfix(1) command invokes the manager command with the
postfix(1) non-option command arguments on the manager command line,
#
# 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.
#
-# A useful wrapper implementation can be as simple as:
+# 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
-#
-# : ${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
-#
-# 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
+# #!/bin/sh
+#
+# : ${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
+#
+# 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
# .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
# 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
* 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
/* 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;
/* .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
projects / thirdparty / postfix.git / commitdiff
