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