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