1 1.1 tron <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 1.1.1.7 christos "https://www.w3.org/TR/html4/loose.dtd"> 3 1.1 tron <html> <head> 4 1.1.1.5 christos <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5 1.1.1.6 christos <link rel='stylesheet' type='text/css' href='postfix-doc.css'> 6 1.1 tron <title> Postfix manual - postfix-wrapper(5) </title> 7 1.1 tron </head> <body> <pre> 8 1.1 tron POSTFIX-WRAPPER(5) POSTFIX-WRAPPER(5) 9 1.1 tron 10 1.1.1.7 christos <b><a name="name">NAME</a></b> 11 1.1 tron postfix-wrapper - Postfix multi-instance API 12 1.1 tron 13 1.1.1.7 christos <b><a name="description">DESCRIPTION</a></b> 14 1.1.1.3 tron Support for managing multiple Postfix instances is available as of ver- 15 1.1.1.3 tron sion 2.6. Instances share executable files and documentation, but have 16 1.1.1.3 tron their own directories for configuration, queue and data files. 17 1.1.1.3 tron 18 1.1.1.3 tron This document describes how the familiar "postfix start" etc. user 19 1.1.1.3 tron interface can be used to manage one or multiple Postfix instances, and 20 1.1.1.3 tron gives details of an API to coordinate activities between the <a href="postfix.1.html">postfix(1)</a> 21 1.1.1.3 tron command and a multi-instance manager program. 22 1.1.1.3 tron 23 1.1.1.3 tron With multi-instance support, the default Postfix instance is always 24 1.1.1.3 tron required. This instance is identified by the <a href="postconf.5.html#config_directory">config_directory</a> parame- 25 1.1.1.3 tron ter's default value. 26 1.1 tron 27 1.1.1.7 christos <b><a name="general_operation">GENERAL OPERATION</a></b> 28 1.1.1.3 tron Multi-instance support is backwards compatible: when you run only one 29 1.1.1.3 tron Postfix instance, commands such as "postfix start" will not change 30 1.1.1.3 tron behavior at all. 31 1.1.1.3 tron 32 1.1.1.3 tron Even with multiple Postfix instances, you can keep using the same post- 33 1.1.1.3 tron fix commands in boot scripts, upgrade procedures, and other places. The 34 1.1.1.3 tron commands do more work, but humans are not forced to learn new tricks. 35 1.1 tron 36 1.1 tron For example, to start all Postfix instances, use: 37 1.1 tron 38 1.1 tron # postfix start 39 1.1 tron 40 1.1.1.3 tron Other <a href="postfix.1.html">postfix(1)</a> commands also work as expected. For example, to find 41 1.1.1.3 tron out what Postfix instances exist in a multi-instance configuration, 42 1.1.1.3 tron use: 43 1.1 tron 44 1.1 tron # postfix status 45 1.1 tron 46 1.1.1.4 christos This enumerates the status of all Postfix instances within a 47 1.1.1.4 christos multi-instance configuration. 48 1.1 tron 49 1.1.1.7 christos <b><a name="managing_an_individual_postfix_instance">MANAGING AN INDIVIDUAL POSTFIX INSTANCE</a></b> 50 1.1.1.3 tron To manage a specific Postfix instance, specify its configuration direc- 51 1.1.1.3 tron tory on the <a href="postfix.1.html">postfix(1)</a> command line: 52 1.1 tron 53 1.1 tron # postfix -c <i>/path/to/config</i><b>_</b><i>directory command</i> 54 1.1 tron 55 1.1.1.3 tron Alternatively, the <a href="postfix.1.html">postfix(1)</a> command accepts the instance's configura- 56 1.1.1.3 tron tion directory via the MAIL_CONFIG environment variable (the -c com- 57 1.1.1.3 tron mand-line option has higher precedence). 58 1.1 tron 59 1.1.1.3 tron Otherwise, the <a href="postfix.1.html">postfix(1)</a> command will operate on all Postfix 60 1.1.1.3 tron instances. 61 1.1 tron 62 1.1 tron <b>ENABLING POSTFIX(1) MULTI-INSTANCE MODE</b> 63 1.1.1.3 tron By default, the <a href="postfix.1.html">postfix(1)</a> command operates in single-instance mode. In 64 1.1.1.3 tron this mode the command invokes the postfix-script file directly (cur- 65 1.1.1.3 tron rently installed in the daemon directory). This file contains the com- 66 1.1.1.3 tron mands that start or stop one Postfix instance, that upgrade the config- 67 1.1.1.3 tron uration of one Postfix instance, and so on. 68 1.1.1.3 tron 69 1.1.1.3 tron When the <a href="postfix.1.html">postfix(1)</a> command operates in multi-instance mode as dis- 70 1.1.1.3 tron cussed below, the command needs to execute start, stop, etc. commands 71 1.1.1.3 tron for each Postfix instance. This multiplication of commands is handled 72 1.1.1.3 tron by a multi-instance manager program. 73 1.1.1.3 tron 74 1.1.1.3 tron Turning on <a href="postfix.1.html">postfix(1)</a> multi-instance mode goes as follows: in the 75 1.1.1.3 tron default Postfix instance's <a href="postconf.5.html">main.cf</a> file, 1) specify the pathname of a 76 1.1.1.3 tron multi-instance manager program with the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parame- 77 1.1.1.3 tron ter; 2) populate the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter with the con- 78 1.1.1.3 tron figuration directory pathnames of additional Postfix instances. For 79 1.1.1.3 tron example: 80 1.1 tron 81 1.1 tron /etc/postfix/<a href="postconf.5.html">main.cf</a>: 82 1.1 tron <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper 83 1.1 tron <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> = /etc/postfix-test 84 1.1 tron 85 1.1.1.3 tron The $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper file implements a simple manager 86 1.1.1.3 tron and contains instructions for creating Postfix instances by hand. The 87 1.1.1.3 tron <a href="postmulti.1.html">postmulti(1)</a> command provides a more extensive implementation including 88 1.1.1.3 tron support for life-cycle management. 89 1.1.1.3 tron 90 1.1.1.3 tron The <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> and other <a href="postconf.5.html">main.cf</a> parameters are listed 91 1.1.1.3 tron below in the CONFIGURATION PARAMETERS section. 92 1.1.1.3 tron 93 1.1.1.3 tron In multi-instance mode, the <a href="postfix.1.html">postfix(1)</a> command invokes the 94 1.1.1.3 tron $<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> command instead of the postfix-script file. 95 1.1.1.3 tron This multi-instance manager in turn executes the <a href="postfix.1.html">postfix(1)</a> command in 96 1.1.1.3 tron single-instance mode for each Postfix instance. 97 1.1.1.3 tron 98 1.1.1.3 tron To illustrate the main ideas behind multi-instance operation, below is 99 1.1.1.3 tron an example of a simple but useful multi-instance manager implementa- 100 1.1.1.3 tron tion: 101 1.1 tron 102 1.1 tron #!/bin/sh 103 1.1 tron 104 1.1 tron : ${<a href="postconf.5.html#command_directory">command_directory</a>?"do not invoke this command directly"} 105 1.1 tron 106 1.1 tron POSTCONF=$<a href="postconf.5.html#command_directory">command_directory</a>/postconf 107 1.1 tron POSTFIX=$<a href="postconf.5.html#command_directory">command_directory</a>/postfix 108 1.1 tron instance_dirs=`$POSTCONF -h <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> | 109 1.1.1.7 christos sed 'y/,/ /'` || exit 1 110 1.1 tron 111 1.1 tron err=0 112 1.1 tron for dir in $<a href="postconf.5.html#config_directory">config_directory</a> $instance_dirs 113 1.1 tron do 114 1.1 tron case "$1" in 115 1.1 tron stop|abort|flush|reload|drain) 116 1.1 tron test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \ 117 1.1 tron = yes || continue;; 118 1.1 tron start) 119 1.1 tron test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \ 120 1.1 tron = yes || { 121 1.1 tron $POSTFIX -c $dir check || err=$? 122 1.1 tron continue 123 1.1 tron };; 124 1.1 tron esac 125 1.1 tron $POSTFIX -c $dir "$@" || err=$? 126 1.1 tron done 127 1.1 tron 128 1.1 tron exit $err 129 1.1 tron 130 1.1.1.7 christos <b><a name="per-instance_multi-instance_manager_controls">PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS</a></b> 131 1.1.1.3 tron Each Postfix instance has its own <a href="postconf.5.html">main.cf</a> file with parameters that 132 1.1.1.3 tron control how the multi-instance manager operates on that instance. This 133 1.1.1.3 tron section discusses the most important settings. 134 1.1.1.3 tron 135 1.1.1.3 tron The setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes" allows the multi-instance 136 1.1.1.3 tron manager to start (stop, etc.) the corresponding Postfix instance. For 137 1.1.1.3 tron safety reasons, this setting is not the default. 138 1.1.1.3 tron 139 1.1.1.3 tron The default setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no" is useful for manual 140 1.1.1.3 tron testing with "postfix -c <i>/path/name</i> start" etc. The multi-instance 141 1.1.1.3 tron manager will not start such an instance, and it will skip commands such 142 1.1.1.3 tron as "stop" or "flush" that require a running Postfix instance. The 143 1.1.1.3 tron multi-instance manager will execute commands such as "check", "set-per- 144 1.1.1.3 tron missions" or "upgrade-configuration", and it will replace "start" by 145 1.1.1.3 tron "check" so that problems will be reported even when the instance is 146 1.1.1.3 tron disabled. 147 1.1 tron 148 1.1.1.7 christos <b><a name="maintaining_shared_and_non-shared_files">MAINTAINING SHARED AND NON-SHARED FILES</a></b> 149 1.1.1.3 tron Some files are shared between Postfix instances, such as executables 150 1.1.1.3 tron and manpages, and some files are per-instance, such as configuration 151 1.1.1.3 tron files, mail queue files, and data files. See the NON-SHARED FILES sec- 152 1.1.1.3 tron tion below for a list of per-instance files. 153 1.1.1.3 tron 154 1.1.1.3 tron Before Postfix multi-instance support was implemented, the executables, 155 1.1.1.3 tron manpages, etc., have always been maintained as part of the default 156 1.1.1.3 tron Postfix instance. 157 1.1.1.3 tron 158 1.1.1.3 tron With multi-instance support, we simply continue to do this. Specifi- 159 1.1.1.3 tron cally, a Postfix instance will not check or update shared files when 160 1.1.1.3 tron that instance's <a href="postconf.5.html#config_directory">config_directory</a> value is listed with the default 161 1.1.1.3 tron <a href="postconf.5.html">main.cf</a> file's <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter. 162 1.1.1.3 tron 163 1.1.1.3 tron The consequence of this approach is that the default Postfix instance 164 1.1.1.3 tron should be checked and updated before any other instances. 165 1.1 tron 166 1.1.1.7 christos <b><a name="multi-instance_api_summary">MULTI-INSTANCE API SUMMARY</a></b> 167 1.1.1.3 tron Only the multi-instance manager implements support for the 168 1.1.1.3 tron <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> configuration parameter. The multi-instance man- 169 1.1.1.3 tron ager will start only Postfix instances whose <a href="postconf.5.html">main.cf</a> file has 170 1.1.1.3 tron "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". A setting of "no" allows a Postfix 171 1.1.1.3 tron instance to be tested by hand. 172 1.1.1.3 tron 173 1.1.1.3 tron The <a href="postfix.1.html">postfix(1)</a> command operates on only one Postfix instance when the 174 1.1.1.3 tron -c option is specified, or when MAIL_CONFIG is present in the process 175 1.1.1.3 tron environment. This is necessary to terminate recursion. 176 1.1.1.3 tron 177 1.1.1.4 christos Otherwise, when the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter value is 178 1.1.1.4 christos non-empty, the <a href="postfix.1.html">postfix(1)</a> command executes the command specified with 179 1.1.1.4 christos the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parameter, instead of executing the commands 180 1.1.1.4 christos in postfix-script. 181 1.1.1.3 tron 182 1.1.1.3 tron The multi-instance manager skips commands such as "stop" or "reload" 183 1.1.1.3 tron that require a running Postfix instance, when an instance does not have 184 1.1.1.3 tron "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". This avoids false error messages. 185 1.1.1.3 tron 186 1.1.1.3 tron The multi-instance manager replaces a "start" command by "check" when a 187 1.1.1.3 tron 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> = 188 1.1.1.3 tron yes". This substitution ensures that problems will be reported even 189 1.1.1.3 tron when the instance is disabled. 190 1.1.1.3 tron 191 1.1.1.3 tron No Postfix command or script will update or check shared files when its 192 1.1.1.3 tron <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 193 1.1.1.3 tron <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter value. Therefore, the default 194 1.1.1.3 tron instance should be checked and updated before any Postfix instances 195 1.1.1.3 tron that depend on it. 196 1.1.1.3 tron 197 1.1.1.3 tron Set-gid commands such as <a href="postdrop.1.html">postdrop(1)</a> and <a href="postqueue.1.html">postqueue(1)</a> effectively 198 1.1.1.3 tron append the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter value to the legacy 199 1.1.1.3 tron <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter value. The commands use this 200 1.1.1.3 tron information to determine whether a -c option or MAIL_CONFIG environment 201 1.1 tron setting specifies a legitimate value. 202 1.1 tron 203 1.1.1.3 tron The legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter remains necessary for 204 1.1.1.3 tron non-default Postfix instances that are running different versions of 205 1.1.1.3 tron Postfix, or that are not managed together with the default Postfix 206 1.1.1.3 tron instance. 207 1.1 tron 208 1.1.1.7 christos <b><a name="environment_variables">ENVIRONMENT VARIABLES</a></b> 209 1.1 tron MAIL_CONFIG 210 1.1.1.3 tron When present, this forces the <a href="postfix.1.html">postfix(1)</a> command to operate only 211 1.1.1.3 tron on the specified Postfix instance. This environment variable is 212 1.1.1.3 tron exported by the <a href="postfix.1.html">postfix(1)</a> -c option, so that <a href="postfix.1.html">postfix(1)</a> com- 213 1.1.1.3 tron mands in descendant processes will work correctly. 214 1.1 tron 215 1.1.1.7 christos <b><a name="configuration_parameters">CONFIGURATION PARAMETERS</a></b> 216 1.1.1.3 tron The text below provides only a parameter summary. See <a href="postconf.5.html">postconf(5)</a> for 217 1.1.1.3 tron more details. 218 1.1 tron 219 1.1 tron <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b> 220 1.1.1.3 tron An optional list of non-default Postfix configuration directo- 221 1.1.1.3 tron ries; these directories belong to additional Postfix instances 222 1.1.1.3 tron that share the Postfix executable files and documentation with 223 1.1.1.3 tron the default Postfix instance, and that are started, stopped, 224 1.1 tron etc., together with the default Postfix instance. 225 1.1 tron 226 1.1 tron <b><a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> (empty)</b> 227 1.1.1.3 tron The pathname of a multi-instance manager command that the <a href="postfix.1.html"><b>post-</b></a> 228 1.1.1.3 tron <a href="postfix.1.html"><b>fix</b>(1)</a> command invokes when the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> 229 1.1.1.3 tron parameter value is non-empty. 230 1.1 tron 231 1.1 tron <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b> 232 1.1.1.3 tron The optional instance name of this Postfix instance. 233 1.1 tron 234 1.1 tron <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b> 235 1.1.1.3 tron The optional instance group name of this Postfix instance. 236 1.1 tron 237 1.1 tron <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b> 238 1.1.1.3 tron Allow this Postfix instance to be started, stopped, etc., by a 239 1.1.1.3 tron multi-instance manager. 240 1.1 tron 241 1.1.1.7 christos <b><a name="non-shared_files">NON-SHARED FILES</a></b> 242 1.1 tron <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 243 1.1.1.3 tron The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- 244 1.1.1.3 tron figuration files. 245 1.1 tron 246 1.1 tron <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b> 247 1.1.1.3 tron The directory with Postfix-writable data files (for example: 248 1.1.1.3 tron caches, pseudo-random numbers). 249 1.1 tron 250 1.1 tron <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b> 251 1.1.1.3 tron The location of the Postfix top-level queue directory. 252 1.1 tron 253 1.1.1.7 christos <b><a name="see_also">SEE ALSO</a></b> 254 1.1 tron <a href="postfix.1.html">postfix(1)</a> Postfix control program 255 1.1 tron <a href="postmulti.1.html">postmulti(1)</a> full-blown multi-instance manager 256 1.1 tron $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper simple multi-instance manager 257 1.1 tron 258 1.1.1.7 christos <b><a name="license">LICENSE</a></b> 259 1.1.1.3 tron The Secure Mailer license must be distributed with this software. 260 1.1 tron 261 1.1 tron <b>AUTHOR(S)</b> 262 1.1 tron Wietse Venema 263 1.1 tron IBM T.J. Watson Research 264 1.1 tron P.O. Box 704 265 1.1 tron Yorktown Heights, NY 10598, USA 266 1.1 tron 267 1.1.1.4 christos Wietse Venema 268 1.1.1.4 christos Google, Inc. 269 1.1.1.4 christos 111 8th Avenue 270 1.1.1.4 christos New York, NY 10011, USA 271 1.1.1.4 christos 272 1.1 tron POSTFIX-WRAPPER(5) 273 1.1 tron </pre> </body> </html> 274
Indexes created Fri Jun 26 00:24:39 UTC 2026