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>
|