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