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