1POSTMULTI(1) General Commands Manual POSTMULTI(1)
2
6 postmulti - Postfix multi-instance manager
7
9 Enabling multi-instance management:
10 postmulti -e init [-v]
12 Iterator mode:
14 postmulti -l [-aRv] [-g group] [-i name]
16 postmulti -p [-av] [-g group] [-i name] postfix-command...
18 postmulti -x [-aRv] [-g group] [-i name] unix-command...
20 Life-cycle management:
22 postmulti -e create [-av] [-g group] [-i name] [-G group] [-I name]
24 [param=value ...]
25 postmulti -e import [-av] [-g group] [-i name] [-G group] [-I name]
27 [config_directory=/path]
28 postmulti -e destroy [-v] -i name
30 postmulti -e deport [-v] -i name
32 postmulti -e enable [-v] -i name
34 postmulti -e disable [-v] -i name
36 postmulti -e assign [-v] -i name [-I name] [-G group]
38
40 The postmulti(1) command allows a Postfix administrator to manage mul‐
41 tiple Postfix instances on a single host.
42 postmulti(1) implements two fundamental modes of operation. In itera‐
44 tor mode, it executes the same command for multiple Postfix instances.
45 In life-cycle management mode, it adds or deletes one instance, or
46 changes the multi-instance status of one instance.
47 Each mode of operation has its own command syntax. For this reason,
49 each mode is documented in separate sections below.
50
52 A multi-instance configuration consists of one primary Postfix in‐
53 stance, and one or more secondary instances whose configuration direc‐
54 tory pathnames are recorded in the primary instance's main.cf file.
55 Postfix instances share program files and documentation, but have their
56 own configuration, queue and data directories.
57 Currently, only the default Postfix instance can be used as primary in‐
59 stance in a multi-instance configuration. The postmulti(1) command does
60 not currently support a -c option to select an alternative primary in‐
61 stance, and exits with a fatal error if the MAIL_CONFIG environment
62 variable is set to a non-default configuration directory.
63 See the MULTI_INSTANCE_README tutorial for a more detailed discussion
65 of multi-instance management with postmulti(1).
66
68 In iterator mode, postmulti performs the same operation on all Postfix
69 instances in turn.
70 If multi-instance support is not enabled, the requested command is per‐
72 formed just for the primary instance.
73 Iterator mode implements the following command options:
75
77 -a Perform the operation on all instances. This is the default.
78 -g group
80 Perform the operation only for members of the named group.
81 -i name
83 Perform the operation only for the instance with the specified
84 name. You can specify either the instance name or the absolute
85 pathname of the instance's configuration directory. Specify "-"
86 to select the primary Postfix instance.
87 -R Reverse the iteration order. This may be appropriate when updat‐
89 ing a multi-instance system, where "sink" instances are started
90 before "source" instances.
91 This option cannot be used with -p.
93
95 -l List Postfix instances with their instance name, instance group
96 name, enable/disable status and configuration directory.
97
99 -p postfix-command
100 Invoke postfix(1) to execute postfix-command. This option im‐
101 plements the postfix-wrapper(5) interface.
102 • With "start"-like commands, "postfix check" is executed
104 for instances that are not enabled. The full list of com‐
105 mands is specified with the postmulti_start_commands pa‐
106 rameter.
107 • With "stop"-like commands, the iteration order is re‐
109 versed, and disabled instances are skipped. The full list
110 of commands is specified with the postmulti_stop_commands
111 parameter.
112 • With "reload" and other commands that require a started
114 instance, disabled instances are skipped. The full list
115 of commands is specified with the postmulti_control_com‐
116 mands parameter.
117 • With "status" and other commands that don't require a
119 started instance, the command is executed for all in‐
120 stances.
121 The -p option can also be used interactively to start/stop/etc.
123 a named instance or instance group. For example, to start just
124 the instances in the group "msa", invoke postmulti(1) as fol‐
125 lows:
126 # postmulti -g msa -p start
128
130 -x unix-command
131 Execute the specified unix-command for all Postfix instances.
132 The command runs with appropriate environment settings for
133 MAIL_CONFIG, command_directory, daemon_directory, config_direc‐
134 tory, queue_directory, data_directory, multi_instance_name,
135 multi_instance_group and multi_instance_enable.
136
138 -v Enable verbose logging for debugging purposes. Multiple -v op‐
139 tions make the software increasingly verbose.
140
142 With the -e option postmulti(1) can be used to add or delete a Postfix
143 instance, and to manage the multi-instance status of an existing in‐
144 stance.
145 The following options are implemented:
147
149 -a When creating or importing an instance, place the new instance
150 at the front of the secondary instance list.
151 -g group
153 When creating or importing an instance, place the new instance
154 before the first secondary instance that is a member of the
155 specified group.
156 -i name
158 When creating or importing an instance, place the new instance
159 before the matching secondary instance.
160 With other life-cycle operations, apply the operation to the
162 named existing instance. Specify "-" to select the primary
163 Postfix instance.
164
166 -I name
167 Assign the specified instance name to an existing instance,
168 newly-created instance, or imported instance. Instance names
169 other than "-" (which makes the instance "nameless") must start
170 with "postfix-". This restriction reduces the likelihood of
171 name collisions with system files.
172 -G group
174 Assign the specified group name to an existing instance or to a
175 newly created or imported instance.
176
178 -e action
179 "Edit" managed instances. The following actions are supported:
180 init This command is required before postmulti(1) can be used
182 to manage Postfix instances. The "postmulti -e init"
183 command updates the primary instance's main.cf file by
184 setting:
185 multi_instance_wrapper =
187 ${command_directory}/postmulti -p --
188 multi_instance_enable = yes
189 You can set these by other means if you prefer.
191 create Create a new Postfix instance and add it to the multi_in‐
193 stance_directories parameter of the primary instance.
194 The "-I name" option is recommended to give the instance
195 a short name that is used to construct default values for
196 the private directories of the new instance. The "-G
197 group" option may be specified to assign the instance to
198 a group, otherwise, the new instance is not a member of
199 any group.
200 The new instance main.cf is the stock main.cf with the
202 parameters that specify the locations of shared files
203 cloned from the primary instance. For "nameless" in‐
204 stances, you should manually adjust "syslog_name" to
205 yield a unique "logtag" starting with "postfix-" that
206 will uniquely identify the instance in the mail logs. It
207 is simpler to assign the instance a short name with the
208 "-I name" option.
209 Optional "name=value" arguments specify the instance con‐
211 fig_directory, queue_directory and data_directory. For
212 example:
213 # postmulti -I postfix-mumble \
215 -G mygroup -e create \
216 config_directory=/my/config/dir \
217 queue_directory=/my/queue/dir \
218 data_directory=/my/data/dir
219 If any of these pathnames is not supplied, the program
221 attempts to generate the missing pathname(s) by taking
222 the corresponding primary instance pathname, and replac‐
223 ing the last pathname component by the value of the -I
224 option.
225 If the instance configuration directory already exists,
227 and contains both a main.cf and master.cf file, create
228 will "import" the instance as-is. For existing instances,
229 create and import are identical.
230 import Import an existing instance into the list of instances
232 managed by the postmulti(1) multi-instance manager. This
233 adds the instance to the multi_instance_directories list
234 of the primary instance. If the "-I name" option is pro‐
235 vided it specifies the new name for the instance and is
236 used to define a default location for the instance con‐
237 figuration directory (as with create above). The "-G
238 group" option may be used to assign the instance to a
239 group. Add a "config_directory=/path" argument to over‐
240 ride a default pathname based on "-I name".
241 destroy
243 Destroy a secondary Postfix instance. To be a candidate
244 for destruction an instance must be disabled, stopped and
245 its queue must not contain any messages. Attempts to de‐
246 stroy the primary Postfix instance trigger a fatal error,
247 without destroying the instance.
248 The instance is removed from the primary instance main.cf
250 file's alternate_config_directories parameter and its
251 data, queue and configuration directories are cleaned of
252 files and directories created by the Postfix system. The
253 main.cf and master.cf files are removed from the configu‐
254 ration directory even if they have been modified since
255 initial creation. Finally, the instance is "deported"
256 from the list of managed instances.
257 If other files are present in instance private directo‐
259 ries, the directories may not be fully removed, a warning
260 is logged to alert the administrator. It is expected that
261 an instance built using "fresh" directories via the cre‐
262 ate action will be fully removed by the destroy action
263 (if first disabled). If the instance configuration and
264 queue directories are populated with additional files
265 (access and rewriting tables, chroot jail content, etc.)
266 the instance directories will not be fully removed.
267 The destroy action triggers potentially dangerous file
269 removal operations. Make sure the instance's data, queue
270 and configuration directories are set correctly and do
271 not contain any valuable files.
272 deport Deport a secondary instance from the list of managed in‐
274 stances. This deletes the instance configuration direc‐
275 tory from the primary instance's multi_instance_directo‐
276 ries list, but does not remove any files or directories.
277 assign Assign a new instance name or a new group name to the se‐
279 lected instance. Use "-G -" to specify "no group" and
280 "-I -" to specify "no name". If you choose to make an
281 instance "nameless", set a suitable syslog_name in the
282 corresponding main.cf file.
283 enable Mark the selected instance as enabled. This just sets the
285 multi_instance_enable parameter to "yes" in the in‐
286 stance's main.cf file.
287 disable
289 Mark the selected instance as disabled. This means that
290 the instance will not be started etc. with "postfix
291 start", "postmulti -p start" and so on. The instance can
292 still be started etc. with "postfix -c config-directory
293 start".
294
296 -v Enable verbose logging for debugging purposes. Multiple -v op‐
297 tions make the software increasingly verbose.
298
300 The postmulti(1) command exports the following environment variables
301 before executing the requested command for a given instance:
302 MAIL_VERBOSE
304 This is set when the -v command-line option is present.
305 MAIL_CONFIG
307 The location of the configuration directory of the instance.
308
310 config_directory (see 'postconf -d' output)
311 The default location of the Postfix main.cf and master.cf con‐
312 figuration files.
313 daemon_directory (see 'postconf -d' output)
315 The directory with Postfix support programs and daemon programs.
316 import_environment (see 'postconf -d' output)
318 The list of environment variables that a privileged Postfix
319 process will import from a non-Postfix parent process, or
320 name=value environment overrides.
321 multi_instance_directories (empty)
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 multi_instance_group (empty)
330 The optional instance group name of this Postfix instance.
331 multi_instance_name (empty)
333 The optional instance name of this Postfix instance.
334 multi_instance_enable (no)
336 Allow this Postfix instance to be started, stopped, etc., by a
337 multi-instance manager.
338 postmulti_start_commands (start)
340 The postfix(1) commands that the postmulti(1) instance manager
341 treats as "start" commands.
342 postmulti_stop_commands (see 'postconf -d' output)
344 The postfix(1) commands that the postmulti(1) instance manager
345 treats as "stop" commands.
346 postmulti_control_commands (reload flush)
348 The postfix(1) commands that the postmulti(1) instance manager
349 treats as "control" commands, that operate on running instances.
350 syslog_facility (mail)
352 The syslog facility of Postfix logging.
353 syslog_name (see 'postconf -d' output)
355 A prefix that is prepended to the process name in syslog
356 records, so that, for example, "smtpd" becomes "prefix/smtpd".
357 Available in Postfix 3.0 and later:
359 meta_directory (see 'postconf -d' output)
361 The location of non-executable files that are shared among mul‐
362 tiple Postfix instances, such as postfix-files, dynamicmaps.cf,
363 and the multi-instance template files main.cf.proto and mas‐
364 ter.cf.proto.
365 shlib_directory (see 'postconf -d' output)
367 The location of Postfix dynamically-linked libraries (libpost‐
368 fix-*.so), and the default location of Postfix database plugins
369 (postfix-*.so) that have a relative pathname in the dynam‐
370 icmaps.cf file.
371
373 $meta_directory/main.cf.proto, stock configuration file
374 $meta_directory/master.cf.proto, stock configuration file
375 $daemon_directory/postmulti-script, life-cycle helper program
376
378 postfix(1), Postfix control program
379 postfix-wrapper(5), Postfix multi-instance API
380
382 Use "postconf readme_directory" or "postconf html_directory" to locate
383 this information.
384 MULTI_INSTANCE_README, Postfix multi-instance management
385
387 The postmulti(1) command was introduced with Postfix version 2.6.
388
390 The Secure Mailer license must be distributed with this software.
391
393 Victor Duchovni
394 Morgan Stanley
395 Wietse Venema
397 IBM T.J. Watson Research
398 P.O. Box 704
399 Yorktown Heights, NY 10598, USA
400 Wietse Venema
402 Google, Inc.
403 111 8th Avenue
404 New York, NY 10011, USA
405 POSTMULTI(1)