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