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