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