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 - postmulti(1) </title> 6</head> <body> <pre> 7POSTMULTI(1) POSTMULTI(1) 8 9<b>NAME</b> 10 postmulti - Postfix multi-instance manager 11 12<b>SYNOPSIS</b> 13 <b>ENABLING MULTI-INSTANCE MANAGEMENT:</b> 14 15 <b>postmulti -e init</b> [<b>-v</b>] 16 17 <b>ITERATOR MODE:</b> 18 19 <b>postmulti -l</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] 20 21 <b>postmulti -p</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>command...</i> 22 23 <b>postmulti -x</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>command...</i> 24 25 <b>LIFE-CYCLE MANAGEMENT:</b> 26 27 <b>postmulti -e create</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] [<b>-G</b> <i>group</i>] 28 [<b>-I</b> <i>name</i>] [<i>param=value</i> ...] 29 30 <b>postmulti -e import</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] [<b>-G</b> <i>group</i>] 31 [<b>-I</b> <i>name</i>] [<b><a href="postconf.5.html#config_directory">config_directory</a>=</b><i>/path</i>] 32 33 <b>postmulti -e destroy</b> [<b>-v</b>] <b>-i</b> <i>name</i> 34 35 <b>postmulti -e deport</b> [<b>-v</b>] <b>-i</b> <i>name</i> 36 37 <b>postmulti -e enable</b> [<b>-v</b>] <b>-i</b> <i>name</i> 38 39 <b>postmulti -e disable</b> [<b>-v</b>] <b>-i</b> <i>name</i> 40 41 <b>postmulti -e assign</b> [<b>-v</b>] <b>-i</b> <i>name</i> [<b>-I</b> <i>name</i>] [-G <i>group</i>] 42 43<b>DESCRIPTION</b> 44 The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command allows a Postfix administrator to 45 manage multiple Postfix instances on a single host. 46 47 <a href="postmulti.1.html"><b>postmulti</b>(1)</a> implements two fundamental modes of opera- 48 tion. In <b>iterator</b> mode, it executes the same command for 49 multiple Postfix instances. In <b>life-cycle management</b> 50 mode, it adds or deletes one instance, or changes the 51 multi-instance status of one instance. 52 53 Each mode of operation has its own command syntax. For 54 this reason, each mode is documented in separate sections 55 below. 56 57<b>BACKGROUND</b> 58 A multi-instance configuration consists of one primary 59 Postfix instance, and one or more secondary instances 60 whose configuration directory pathnames are recorded in 61 the primary instance's <a href="postconf.5.html">main.cf</a> file. Postfix instances 62 share program files and documentation, but have their own 63 configuration, queue and data directories. 64 65 Currently, only the default Postfix instance can be used 66 as primary instance in a multi-instance configuration. The 67 <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command does not currently support a <b>-c</b> 68 option to select an alternative primary instance, and 69 exits with a fatal error if the <b>MAIL_CONFIG</b> environment 70 variable is set to a non-default configuration directory. 71 72 See the <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a> tutorial for a more detailed 73 discussion of multi-instance management with <a href="postmulti.1.html"><b>postmulti</b>(1)</a>. 74 75<b>ITERATOR MODE</b> 76 In iterator mode, <b>postmulti</b> performs the same operation on 77 all Postfix instances in turn. 78 79 If multi-instance support is not enabled, the requested 80 command is performed just for the primary instance. 81 82 Iterator mode implements the following command options: 83 84<b>Instance selection</b> 85 <b>-a</b> Perform the operation on all instances. This is the 86 default. 87 88 <b>-g</b> <i>group</i> 89 Perform the operation only for members of the named 90 <i>group</i>. 91 92 <b>-i</b> <i>name</i> 93 Perform the operation only for the instance with 94 the specified <i>name</i>. You can specify either the 95 instance name or the absolute pathname of the 96 instance's configuration directory. Specify "-" to 97 select the primary Postfix instance. 98 99 <b>-R</b> Reverse the iteration order. This may be appropri- 100 ate when updating a multi-instance system, where 101 "sink" instances are started before "source" 102 instances. 103 104 This option cannot be used with <b>-p</b>. 105 106<b>List mode</b> 107 <b>-l</b> List Postfix instances with their instance name, 108 instance group name, enable/disable status and con- 109 figuration directory. 110 111<b>Postfix-wrapper mode</b> 112 <b>-p</b> Invoke <a href="postfix.1.html"><b>postfix(1)</a></b> to execute the specified <i>command</i>. 113 This option implements the <a href="postfix-wrapper.5.html"><b>postfix-wrapper</b>(5)</a> 114 interface. 115 116 <b>o</b> With "start"-like commands, "postfix check" 117 is executed for instances that are not 118 enabled. The full list of commands is speci- 119 fied with the <a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a> 120 parameter. 121 122 <b>o</b> With "stop"-like commands, the iteration 123 order is reversed, and disabled instances 124 are skipped. The full list of commands is 125 specified with the <a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a> 126 parameter. 127 128 <b>o</b> With "reload" and other commands that 129 require a started instance, disabled 130 instances are skipped. The full list of com- 131 mands is specified with the <a href="postconf.5.html#postmulti_control_commands">postmulti_con</a>- 132 <a href="postconf.5.html#postmulti_control_commands">trol_commands</a> parameter. 133 134 <b>o</b> With "status" and other commands that don't 135 require a started instance, the command is 136 executed for all instances. 137 138 The <b>-p</b> option can also be used interactively to 139 start/stop/etc. a named instance or instance 140 group. For example, to start just the instances in 141 the group "msa", invoke <a href="postmulti.1.html"><b>postmulti</b>(1)</a> as follows: 142 143 # postmulti -g msa -p start 144 145<b>Command mode</b> 146 <b>-x</b> Execute the specified <i>command</i> for all Postfix 147 instances. The command runs with appropriate envi- 148 ronment settings for MAIL_CONFIG, <a href="postconf.5.html#command_directory">command_direc</a>- 149 <a href="postconf.5.html#command_directory">tory</a>, <a href="postconf.5.html#daemon_directory">daemon_directory</a>, <a href="postconf.5.html#config_directory">config_directory</a>, 150 <a href="postconf.5.html#queue_directory">queue_directory</a>, <a href="postconf.5.html#data_directory">data_directory</a>, 151 <a href="postconf.5.html#multi_instance_name">multi_instance_name</a>, <a href="postconf.5.html#multi_instance_group">multi_instance_group</a> and 152 <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>. 153 154<b>Other options</b> 155 <b>-v</b> Enable verbose logging for debugging purposes. Mul- 156 tiple <b>-v</b> options make the software increasingly 157 verbose. 158 159<b>LIFE-CYCLE MANAGEMENT MODE</b> 160 With the <b>-e</b> option <a href="postmulti.1.html"><b>postmulti</b>(1)</a> can be used to add or 161 delete a Postfix instance, and to manage the multi- 162 instance status of an existing instance. 163 164 The following options are implemented: 165 166<b>Existing instance selection</b> 167 <b>-a</b> When creating or importing an instance, place the 168 new instance at the front of the secondary instance 169 list. 170 171 <b>-g</b> <i>group</i> 172 When creating or importing an instance, place the 173 new instance before the first secondary instance 174 that is a member of the specified group. 175 176 <b>-i</b> <i>name</i> 177 When creating or importing an instance, place the 178 new instance before the matching secondary 179 instance. 180 181 With other life-cycle operations, apply the opera- 182 tion to the named existing instance. Specify "-" 183 to select the primary Postfix instance. 184 185<b>New or existing instance name assignment</b> 186 <b>-I</b> <i>name</i> 187 Assign the specified instance <i>name</i> to an existing 188 instance, newly-created instance, or imported 189 instance. Instance names other than "-" (which 190 makes the instance "nameless") must start with 191 "postfix-". This restriction reduces the likeli- 192 hood of name collisions with system files. 193 194 <b>-G</b> <i>group</i> 195 Assign the specified <i>group</i> name to an existing 196 instance or to a newly created or imported 197 instance. 198 199<b>Instance creation/deletion/status change</b> 200 <b>-e</b> <i>action</i> 201 "Edit" managed instances. The following actions are 202 supported: 203 204 <b>init</b> This command is required before <a href="postmulti.1.html"><b>postmulti</b>(1)</a> 205 can be used to manage Postfix instances. 206 The "postmulti -e init" command updates the 207 primary instance's <a href="postconf.5.html">main.cf</a> file by setting: 208 209 <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = 210 ${<a href="postconf.5.html#command_directory">command_directory</a>}/postmulti -p -- 211 <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes 212 213 You can set these by other means if you pre- 214 fer. 215 216 <b>create</b> Create a new Postfix instance and add it to 217 the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter of 218 the primary instance. The "<b>-I</b> <i>name</i>" option 219 is recommended to give the instance a short 220 name that is used to construct default val- 221 ues for the private directories of the new 222 instance. The "<b>-G</b> <i>group</i>" option may be spec- 223 ified to assign the instance to a group, 224 otherwise, the new instance is not a member 225 of any groups. 226 227 The new instance <a href="postconf.5.html">main.cf</a> is the stock 228 <a href="postconf.5.html">main.cf</a> with the parameters that specify the 229 locations of shared files cloned from the 230 primary instance. For "nameless" instances, 231 you should manually adjust "<a href="postconf.5.html#syslog_name">syslog_name</a>" to 232 yield a unique "logtag" starting with "post- 233 fix-" that will uniquely identify the 234 instance in the mail logs. It is simpler to 235 assign the instance a short name with the 236 "<b>-I</b> <i>name</i>" option. 237 238 Optional "name=value" arguments specify the 239 instance <a href="postconf.5.html#config_directory">config_directory</a>, <a href="postconf.5.html#queue_directory">queue_directory</a> 240 and <a href="postconf.5.html#data_directory">data_directory</a>. For example: 241 242 # postmulti -I postfix-mumble \ 243 -G mygroup -e create \ 244 <a href="postconf.5.html#config_directory">config_directory</a>=/my/config/dir \ 245 <a href="postconf.5.html#queue_directory">queue_directory</a>=/my/queue/dir \ 246 <a href="postconf.5.html#data_directory">data_directory</a>=/my/data/dir 247 248 If any of these pathnames is not supplied, 249 the program attempts to generate the path- 250 name by taking the corresponding primary 251 instance pathname, and by replacing the last 252 pathname component by the value of the <b>-I</b> 253 option. 254 255 If the instance configuration directory 256 already exists, and contains both a <a href="postconf.5.html">main.cf</a> 257 and <a href="master.5.html">master.cf</a> file, <b>create</b> will "import" the 258 instance as-is. For existing instances, <b>cre-</b> 259 <b>ate</b> and <b>import</b> are identical. 260 261 <b>import</b> Import an existing instance into the list of 262 instances managed by the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> multi- 263 instance manager. This adds the instance to 264 the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> list of the 265 primary instance. If the "<b>-I</b> <i>name</i>" option 266 is provided it specifies the new name for 267 the instance and is used to define a default 268 location for the instance configuration 269 directory (as with <b>create</b> above). The "<b>-G</b> 270 <i>group</i>" option may be used to assign the 271 instance to a group. Add a "<b><a href="postconf.5.html#config_directory">config_direc</a>-</b> 272 <b><a href="postconf.5.html#config_directory">tory</a>=</b><i>/path</i>" argument to override a default 273 pathname based on "<b>-I</b> <i>name</i>". 274 275 <b>destroy</b> 276 Destroy a secondary Postfix instance. To be 277 a candidate for destruction an instance must 278 be disabled, stopped and its queue must not 279 contain any messages. Attempts to destroy 280 the primary Postfix instance trigger a fatal 281 error, without destroying the instance. 282 283 The instance is removed from the primary 284 instance <a href="postconf.5.html">main.cf</a> file's <a href="postconf.5.html#alternate_config_directories">alternate_con</a>- 285 <a href="postconf.5.html#alternate_config_directories">fig_directories</a> parameter and its data, 286 queue and configuration directories are 287 cleaned of files and directories created by 288 the Postfix system. The <a href="postconf.5.html">main.cf</a> and mas- 289 ter.cf files are removed from the configura- 290 tion directory even if they have been modi- 291 fied since initial creation. Finally, the 292 instance is "deported" from the list of man- 293 aged instances. 294 295 If other files are present in instance pri- 296 vate directories, the directories may not be 297 fully removed, a warning is logged to alert 298 the administrator. It is expected that an 299 instance built using "fresh" directories via 300 the <b>create</b> action will be fully removed by 301 the <b>destroy</b> action (if first disabled). If 302 the instance configuration and queue direc- 303 tories are populated with additional files 304 (access and rewriting tables, chroot jail 305 content, etc.) the instance directories will 306 not be fully removed. 307 308 The <b>destroy</b> action triggers potentially dan- 309 gerous file removal operations. Make sure 310 the instance's data, queue and configuration 311 directories are set correctly and do not 312 contain any valuable files. 313 314 <b>deport</b> Deport a secondary instance from the list of 315 managed instances. This deletes the instance 316 configuration directory from the primary 317 instance's <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> list, 318 but does not remove any files or directo- 319 ries. 320 321 <b>assign</b> Assign a new instance name or a new group 322 name to the selected instance. Use "<b>-G -</b>" 323 to specify "no group" and "<b>-I -</b>" to specify 324 "no name". If you choose to make an 325 instance "nameless", set a suitable sys- 326 log_name in the corresponding <a href="postconf.5.html">main.cf</a> file. 327 328 <b>enable</b> Mark the selected instance as enabled. This 329 just sets the <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> parame- 330 ter to "yes" in the instance's <a href="postconf.5.html">main.cf</a> file. 331 332 <b>disable</b> 333 Mark the selected instance as disabled. This 334 means that the instance will not be started 335 etc. with "postfix start", "postmulti -p 336 start" and so on. The instance can still be 337 started etc. with "postfix -c config-direc- 338 tory start". 339 340<b>Other options</b> 341 <b>-v</b> Enable verbose logging for debugging purposes. Mul- 342 tiple <b>-v</b> options make the software increasingly 343 verbose. 344 345<b>ENVIRONMENT</b> 346 The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command exports the following environment 347 variables before executing the requested <i>command</i> for a 348 given instance: 349 350 <b>MAIL_VERBOSE</b> 351 This is set when the -v command-line option is 352 present. 353 354 <b>MAIL_CONFIG</b> 355 The location of the configuration directory of the 356 instance. 357 358<b>CONFIGURATION PARAMETERS</b> 359 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 360 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and 361 <a href="master.5.html">master.cf</a> configuration files. 362 363 <b><a href="postconf.5.html#daemon_directory">daemon_directory</a> (see 'postconf -d' output)</b> 364 The directory with Postfix support programs and 365 daemon programs. 366 367 <b><a href="postconf.5.html#import_environment">import_environment</a> (see 'postconf -d' output)</b> 368 The list of environment parameters that a Postfix 369 process will import from a non-Postfix parent 370 process. 371 372 <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b> 373 An optional list of non-default Postfix configura- 374 tion directories; these directories belong to addi- 375 tional Postfix instances that share the Postfix 376 executable files and documentation with the default 377 Postfix instance, and that are started, stopped, 378 etc., together with the default Postfix instance. 379 380 <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b> 381 The optional instance group name of this Postfix 382 instance. 383 384 <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b> 385 The optional instance name of this Postfix 386 instance. 387 388 <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b> 389 Allow this Postfix instance to be started, stopped, 390 etc., by a multi-instance manager. 391 392 <b><a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a> (start)</b> 393 The <a href="postfix.1.html"><b>postfix</b>(1)</a> commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> 394 instance manager treats as "start" commands. 395 396 <b><a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a> (see 'postconf -d' output)</b> 397 The <a href="postfix.1.html"><b>postfix</b>(1)</a> commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> 398 instance manager treats as "stop" commands. 399 400 <b><a href="postconf.5.html#postmulti_control_commands">postmulti_control_commands</a> (reload flush)</b> 401 The <a href="postfix.1.html"><b>postfix</b>(1)</a> commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> 402 instance manager treats as "control" commands, that 403 operate on running instances. 404 405 <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> 406 The syslog facility of Postfix logging. 407 408 <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> 409 The mail system name that is prepended to the 410 process name in syslog records, so that "smtpd" 411 becomes, for example, "postfix/smtpd". 412 413<b>FILES</b> 414 $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/<a href="postconf.5.html">main.cf</a>, stock configuration file 415 $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/<a href="master.5.html">master.cf</a>, stock configuration file 416 $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postmulti-script, life-cycle helper program 417 418<b>SEE ALSO</b> 419 <a href="postfix.1.html">postfix(1)</a>, Postfix control program 420 <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a>, Postfix multi-instance API 421 422<b>README FILES</b> 423 <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a>, Postfix multi-instance management 424 425<b>HISTORY</b> 426 The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command was introduced with Postfix ver- 427 sion 2.6. 428 429<b>LICENSE</b> 430 The Secure Mailer license must be distributed with this 431 software. 432 433<b>AUTHOR(S)</b> 434 Victor Duchovni 435 Morgan Stanley 436 437 Wietse Venema 438 IBM T.J. Watson Research 439 P.O. Box 704 440 Yorktown Heights, NY 10598, USA 441 442 POSTMULTI(1) 443</pre> </body> </html> 444