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