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