multi-instance manager program.
With multi-instance support, the default Postfix instance
- is always required. The <a href="postconf.5.html#config_directory">config_directory</a> parameter's
- default value specifies that instance's configuration file
- location.
+ is always required. This instance is identified by the
+ <a href="postconf.5.html#config_directory">config_directory</a> parameter's default value.
<b>GENERAL OPERATION</b>
- Multi-instance support is backwards compatible: when you
- run only one Postfix instance, commands such as "postfix
+ Multi-instance support is backwards compatible: when you
+ run only one Postfix instance, commands such as "postfix
start" will not change behavior at all.
- Even with multiple Postfix instances, you can keep using
- the same postfix commands in boot scripts, upgrade proce-
- dures, and other places. The commands do more work, but
+ Even with multiple Postfix instances, you can keep using
+ the same postfix commands in boot scripts, upgrade proce-
+ dures, and other places. The commands do more work, but
humans are not forced to learn new tricks.
For example, to start all Postfix instances, use:
# postfix start
Other <a href="postfix.1.html">postfix(1)</a> commands also work as expected. For exam-
- ple, to find out what Postfix instances exist in a multi-
+ ple, to find out what Postfix instances exist in a multi-
instance configuration, use:
# postfix status
# postfix -c <i>/path/to/config</i><b>_</b><i>directory command</i>
- Alternatively, the <a href="postfix.1.html">postfix(1)</a> command accepts the
- instance's configuration directory via the MAIL_CONFIG
+ Alternatively, the <a href="postfix.1.html">postfix(1)</a> command accepts the
+ instance's configuration directory via the MAIL_CONFIG
environment variable (the -c command-line option has
higher precedence).
- When no Postfix instance information is specified, the
- <a href="postfix.1.html">postfix(1)</a> command will operate on all Postfix instances.
+ When no Postfix instance information is specified, the
+ <a href="postfix.1.html">postfix(1)</a> command will operate on all Postfix instances.
<b>ENABLING POSTFIX(1) MULTI-INSTANCE MODE</b>
- By default, the <a href="postfix.1.html">postfix(1)</a> command operates in single-
- instance mode. In this mode the command invokes the post-
- fix-script file directly (currently installed in the dae-
- mon directory). This file contains the commands that
- start or stop one Postfix instance, that upgrade the con-
+ By default, the <a href="postfix.1.html">postfix(1)</a> command operates in single-
+ instance mode. In this mode the command invokes the post-
+ fix-script file directly (currently installed in the dae-
+ mon directory). This file contains the commands that
+ start or stop one Postfix instance, that upgrade the con-
figuration of one Postfix instance, and so on.
- When the <a href="postfix.1.html">postfix(1)</a> command operates in multi-instance
- mode as discussed below, the command needs to execute
- start, stop, etc. commands for each Postfix instance.
- This multiplication of commands is handled by a multi-
+ When the <a href="postfix.1.html">postfix(1)</a> command operates in multi-instance
+ mode as discussed below, the command needs to execute
+ start, stop, etc. commands for each Postfix instance.
+ This multiplication of commands is handled by a multi-
instance manager program.
Turning on <a href="postfix.1.html">postfix(1)</a> multi-instance mode goes as follows:
in the default Postfix instance's <a href="postconf.5.html">main.cf</a> file, 1) specify
- the pathname of a multi-instance manager program with the
- <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameter; 2) populate the
- <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter with the configura-
- tion directory pathnames of additional Postfix instances.
+ the pathname of a multi-instance manager program with the
+ <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameter; 2) populate the
+ <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter with the configura-
+ tion directory pathnames of additional Postfix instances.
For example:
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper
<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> = /etc/postfix-test
- The $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper file implements a
- simple manager and contains instructions for creating
- Postfix instances by hand. The <a href="postmulti.1.html">postmulti(1)</a> command pro-
- vides a more extensive implementation including support
+ The $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper file implements a
+ simple manager and contains instructions for creating
+ Postfix instances by hand. The <a href="postmulti.1.html">postmulti(1)</a> command pro-
+ vides a more extensive implementation including support
for life-cycle management.
- The <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> and other <a href="postconf.5.html">main.cf</a> parame-
+ The <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> and other <a href="postconf.5.html">main.cf</a> parame-
ters are listed below in the CONFIGURATION PARAMETERS sec-
tion.
In multi-instance mode, the <a href="postfix.1.html">postfix(1)</a> command invokes the
- $<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> command instead of the postfix-
- script file. This multi-instance manager in turn executes
- the <a href="postfix.1.html">postfix(1)</a> command in single-instance mode for each
+ $<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> command instead of the postfix-
+ script file. This multi-instance manager in turn executes
+ the <a href="postfix.1.html">postfix(1)</a> command in single-instance mode for each
Postfix instance.
- To illustrate the main ideas behind multi-instance opera-
- tion, below is an example of a simple but useful multi-
+ To illustrate the main ideas behind multi-instance opera-
+ tion, below is an example of a simple but useful multi-
instance manager implementation:
#!/bin/sh
<b>PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS</b>
Each Postfix instance has its own <a href="postconf.5.html">main.cf</a> file with param-
eters that control how the multi-instance manager operates
- on that instance. This section discusses the most impor-
+ on that instance. This section discusses the most impor-
tant settings.
The setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes" allows the
- multi-instance manager to start (stop, etc.) the corre-
- sponding Postfix instance. For safety reasons, this set-
+ multi-instance manager to start (stop, etc.) the corre-
+ sponding Postfix instance. For safety reasons, this set-
ting is not the default.
The default setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no" is useful
for manual testing with "postfix -c <i>/path/name</i> start" etc.
- The multi-instance manager will not start such an
- instance, and it will skip commands such as "stop" or
- "flush" that require a running Postfix instance. The
+ The multi-instance manager will not start such an
+ instance, and it will skip commands such as "stop" or
+ "flush" that require a running Postfix instance. The
multi-instance manager will execute commands such as
"check", "set-permissions" or "upgrade-configuration", and
- it will replace "start" by "check" so that problems will
+ 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
+ Some files are shared between Postfix instances, such as
executables and manpages, and some files are per-instance,
- such as configuration files, mail queue files, and data
- files. See the NON-SHARED FILES section below for a list
+ such as configuration files, mail queue files, and data
+ files. See the NON-SHARED FILES section below for a list
of per-instance files.
Before Postfix multi-instance support was implemented, the
- executables, manpages, etc., have always been maintained
+ executables, manpages, etc., have always been maintained
as part of the default Postfix instance.
- With multi-instance support, we simply continue to do
- this. Specifically, a Postfix instance will not check or
- update shared files when that instance's <a href="postconf.5.html#config_directory">config_directory</a>
- value is listed with the default <a href="postconf.5.html">main.cf</a> file's
+ With multi-instance support, we simply continue to do
+ this. Specifically, a Postfix instance will not check or
+ update shared files when that instance's <a href="postconf.5.html#config_directory">config_directory</a>
+ value is listed with the default <a href="postconf.5.html">main.cf</a> file's
<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter.
The consequence of this approach is that the default Post-
- fix instance should be checked and updated before any
+ fix instance should be checked and updated before any
other instances.
<b>MULTI-INSTANCE API SUMMARY</b>
Only the multi-instance manager implements support for the
- <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> configuration parameter. The multi-
- instance manager will start only Postfix instances whose
- <a href="postconf.5.html">main.cf</a> file has "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". A setting
+ <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> configuration parameter. The multi-
+ instance manager will start only Postfix instances whose
+ <a href="postconf.5.html">main.cf</a> file has "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". A setting
of "no" allows a Postfix instance to be tested by hand.
The <a href="postfix.1.html">postfix(1)</a> command operates on only one Postfix
- instance when the -c option is specified, or when
+ instance when the -c option is specified, or when
MAIL_CONFIG is present in the process environment. This is
necessary to terminate recursion.
- Otherwise, when the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter
- value is non-empty, the <a href="postfix.1.html">postfix(1)</a> command executes the
- command specified with the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parame-
- ter, instead of executing the commands in postfix-script.
+ 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".
+ 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
+ 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
+ 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
+ No Postfix command or script will update or check shared
+ files when its <a href="postconf.5.html#config_directory">config_directory</a> value is listed in the
+ default <a href="postconf.5.html">main.cf</a>'s <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter
+ value. Therefore, the default instance should be checked
+ and updated before any Postfix instances that depend on
it.
- Set-gid commands such as <a href="postdrop.1.html">postdrop(1)</a> and <a href="postqueue.1.html">postqueue(1)</a>
- effectively append the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parame-
- ter value to the legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a>
- parameter value. The commands use this information to
- determine whether a -c option or MAIL_CONFIG environment
+ Set-gid commands such as <a href="postdrop.1.html">postdrop(1)</a> and <a href="postqueue.1.html">postqueue(1)</a>
+ effectively append the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parame-
+ ter value to the legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a>
+ parameter value. The commands use this information to
+ determine whether a -c option or MAIL_CONFIG environment
setting specifies a legitimate value.
- The legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter remains
- necessary for non-default Postfix instances that are run-
- ning different versions of Postfix, or that are not man-
+ The legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter remains
+ necessary for non-default Postfix instances that are run-
+ ning different versions of Postfix, or that are not man-
aged together with the default Postfix instance.
<b>ENVIRONMENT VARIABLES</b>
MAIL_CONFIG
When present, this forces the <a href="postfix.1.html">postfix(1)</a> command to
- operate only on the specified Postfix instance.
- This environment variable is exported by the <a href="postfix.1.html">post-</a>
- <a href="postfix.1.html">fix(1)</a> -c option, so that <a href="postfix.1.html">postfix(1)</a> commands in
+ operate only on the specified Postfix instance.
+ This environment variable is exported by the <a href="postfix.1.html">post-</a>
+ <a href="postfix.1.html">fix(1)</a> -c option, so that <a href="postfix.1.html">postfix(1)</a> commands in
descendant processes will work correctly.
<b>CONFIGURATION PARAMETERS</b>
- The text below provides only a parameter summary. See
+ 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>
$<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
+ The Secure Mailer license must be distributed with this
software.
<b>AUTHOR(S)</b>