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