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