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>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 groups. 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 pathname by taking the corre- 226 sponding primary instance pathname, and by replacing the 227 last pathname component by the value of the <b>-I</b> option. 228 229 If the instance configuration directory already exists, 230 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> 231 will "import" the instance as-is. For existing instances, 232 <b>create</b> and <b>import</b> are identical. 233 234 <b>import</b> Import an existing instance into the list of instances 235 managed by the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> multi-instance manager. This 236 adds the instance to the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> list 237 of the primary instance. If the "<b>-I</b> <i>name</i>" option is pro- 238 vided it specifies the new name for the instance and is 239 used to define a default location for the instance con- 240 figuration directory (as with <b>create</b> above). The "<b>-G</b> 241 <i>group</i>" option may be used to assign the instance to a 242 group. Add a "<b><a href="postconf.5.html#config_directory">config_directory</a>=</b><i>/path</i>" argument to over- 243 ride a default pathname based on "<b>-I</b> <i>name</i>". 244 245 <b>destroy</b> 246 Destroy a secondary Postfix instance. To be a candidate 247 for destruction an instance must be disabled, stopped and 248 its queue must not contain any messages. Attempts to 249 destroy the primary Postfix instance trigger a fatal 250 error, without destroying the instance. 251 252 The instance is removed from the primary instance <a href="postconf.5.html">main.cf</a> 253 file's <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter and its 254 data, queue and configuration directories are cleaned of 255 files and directories created by the Postfix system. The 256 <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> files are removed from the configu- 257 ration directory even if they have been modified since 258 initial creation. Finally, the instance is "deported" 259 from the list of managed instances. 260 261 If other files are present in instance private directo- 262 ries, the directories may not be fully removed, a warning 263 is logged to alert the administrator. It is expected that 264 an instance built using "fresh" directories via the <b>cre-</b> 265 <b>ate</b> action will be fully removed by the <b>destroy</b> action 266 (if first disabled). If the instance configuration and 267 queue directories are populated with additional files 268 (access and rewriting tables, chroot jail content, etc.) 269 the instance directories will not be fully removed. 270 271 The <b>destroy</b> action triggers potentially dangerous file 272 removal operations. Make sure the instance's data, queue 273 and configuration directories are set correctly and do 274 not contain any valuable files. 275 276 <b>deport</b> Deport a secondary instance from the list of managed 277 instances. This deletes the instance configuration direc- 278 tory from the primary instance's <a href="postconf.5.html#multi_instance_directories">multi_instance_directo</a>- 279 <a href="postconf.5.html#multi_instance_directories">ries</a> list, but does not remove any files or directories. 280 281 <b>assign</b> Assign a new instance name or a new group name to the 282 selected instance. Use "<b>-G -</b>" to specify "no group" and 283 "<b>-I -</b>" to specify "no name". If you choose to make an 284 instance "nameless", set a suitable <a href="postconf.5.html#syslog_name">syslog_name</a> in the 285 corresponding <a href="postconf.5.html">main.cf</a> file. 286 287 <b>enable</b> Mark the selected instance as enabled. This just sets the 288 <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> parameter to "yes" in the 289 instance's <a href="postconf.5.html">main.cf</a> file. 290 291 <b>disable</b> 292 Mark the selected instance as disabled. This means that 293 the instance will not be started etc. with "postfix 294 start", "postmulti -p start" and so on. The instance can 295 still be started etc. with "postfix -c config-directory 296 start". 297 298<b>Other options</b> 299 <b>-v</b> Enable verbose logging for debugging purposes. Multiple <b>-v</b> 300 options make the software increasingly verbose. 301 302<b>ENVIRONMENT</b> 303 The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command exports the following environment variables 304 before executing the requested <i>command</i> for a given instance: 305 306 <b>MAIL_VERBOSE</b> 307 This is set when the -v command-line option is present. 308 309 <b>MAIL_CONFIG</b> 310 The location of the configuration directory of the instance. 311 312<b>CONFIGURATION PARAMETERS</b> 313 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 314 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- 315 figuration files. 316 317 <b><a href="postconf.5.html#daemon_directory">daemon_directory</a> (see 'postconf -d' output)</b> 318 The directory with Postfix support programs and daemon programs. 319 320 <b><a href="postconf.5.html#import_environment">import_environment</a> (see 'postconf -d' output)</b> 321 The list of environment parameters that a privileged Postfix 322 process will import from a non-Postfix parent process, or 323 name=value environment overrides. 324 325 <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b> 326 An optional list of non-default Postfix configuration directo- 327 ries; these directories belong to additional Postfix instances 328 that share the Postfix executable files and documentation with 329 the default Postfix instance, and that are started, stopped, 330 etc., together with the default Postfix instance. 331 332 <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b> 333 The optional instance group name of this Postfix instance. 334 335 <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b> 336 The optional instance name of this Postfix instance. 337 338 <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b> 339 Allow this Postfix instance to be started, stopped, etc., by a 340 multi-instance manager. 341 342 <b><a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a> (start)</b> 343 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 344 treats as "start" commands. 345 346 <b><a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a> (see 'postconf -d' output)</b> 347 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 348 treats as "stop" commands. 349 350 <b><a href="postconf.5.html#postmulti_control_commands">postmulti_control_commands</a> (reload flush)</b> 351 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 352 treats as "control" commands, that operate on running instances. 353 354 <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> 355 The syslog facility of Postfix logging. 356 357 <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> 358 A prefix that is prepended to the process name in syslog 359 records, so that, for example, "smtpd" becomes "prefix/smtpd". 360 361 Available in Postfix 3.0 and later: 362 363 <b><a href="postconf.5.html#meta_directory">meta_directory</a> (see 'postconf -d' output)</b> 364 The location of non-executable files that are shared among mul- 365 tiple Postfix instances, such as postfix-files, dynamicmaps.cf, 366 and the multi-instance template files <a href="postconf.5.html">main.cf</a>.proto and <a href="master.5.html">mas- 367 ter.cf</a>.proto. 368 369 <b><a href="postconf.5.html#shlib_directory">shlib_directory</a> (see 'postconf -d' output)</b> 370 The location of Postfix dynamically-linked libraries (libpost- 371 fix-*.so), and the default location of Postfix database plugins 372 (postfix-*.so) that have a relative pathname in the dynam- 373 icmaps.cf file. 374 375<b>FILES</b> 376 $<a href="postconf.5.html#meta_directory">meta_directory</a>/<a href="postconf.5.html">main.cf</a>.proto, stock configuration file 377 $<a href="postconf.5.html#meta_directory">meta_directory</a>/<a href="master.5.html">master.cf</a>.proto, stock configuration file 378 $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postmulti-script, life-cycle helper program 379 380<b>SEE ALSO</b> 381 <a href="postfix.1.html">postfix(1)</a>, Postfix control program 382 <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a>, Postfix multi-instance API 383 384<b>README FILES</b> 385 <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a>, Postfix multi-instance management 386 387<b>HISTORY</b> 388 The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command was introduced with Postfix version 2.6. 389 390<b>LICENSE</b> 391 The Secure Mailer license must be distributed with this software. 392 393<b>AUTHOR(S)</b> 394 Victor Duchovni 395 Morgan Stanley 396 397 Wietse Venema 398 IBM T.J. Watson Research 399 P.O. Box 704 400 Yorktown Heights, NY 10598, USA 401 402 Wietse Venema 403 Google, Inc. 404 111 8th Avenue 405 New York, NY 10011, USA 406 407 POSTMULTI(1) 408</pre> </body> </html> 409