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