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
53 instance, and one or more secondary instances whose configuration
54 directory pathnames are recorded in the primary instance's main.cf
55 file. Postfix instances share program files and documentation, but have
56 their own configuration, queue and data directories.
57 Currently, only the default Postfix instance can be used as primary
59 instance in a multi-instance configuration. The postmulti(1) command
60 does not currently support a -c option to select an alternative primary
61 instance, 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
101 implements 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
106 parameter.
107 · With "stop"-like commands, the iteration order is
109 reversed, and disabled instances are skipped. The full
110 list of commands is specified with the post‐
111 multi_stop_commands 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
120 instances.
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
139 options 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
144 instance.
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
193 multi_instance_directories parameter of the primary
194 instance. The "-I name" option is recommended to give
195 the instance a short name that is used to construct
196 default values for the private directories of the new
197 instance. The "-G group" option may be specified to
198 assign the instance to a group, otherwise, the new
199 instance is not a member of any groups.
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"
204 instances, 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 pathname by taking the corre‐
222 sponding primary instance pathname, and by replacing the
223 last pathname component by the value of the -I option.
224 If the instance configuration directory already exists,
226 and contains both a main.cf and master.cf file, create
227 will "import" the instance as-is. For existing instances,
228 create and import are identical.
229 import Import an existing instance into the list of instances
231 managed by the postmulti(1) multi-instance manager. This
232 adds the instance to the multi_instance_directories list
233 of the primary instance. If the "-I name" option is pro‐
234 vided it specifies the new name for the instance and is
235 used to define a default location for the instance con‐
236 figuration directory (as with create above). The "-G
237 group" option may be used to assign the instance to a
238 group. Add a "config_directory=/path" argument to over‐
239 ride a default pathname based on "-I name".
240 destroy
242 Destroy a secondary Postfix instance. To be a candidate
243 for destruction an instance must be disabled, stopped and
244 its queue must not contain any messages. Attempts to
245 destroy the primary Postfix instance trigger a fatal
246 error, without destroying the instance.
247 The instance is removed from the primary instance main.cf
249 file's alternate_config_directories parameter and its
250 data, queue and configuration directories are cleaned of
251 files and directories created by the Postfix system. The
252 main.cf and master.cf files are removed from the configu‐
253 ration directory even if they have been modified since
254 initial creation. Finally, the instance is "deported"
255 from the list of managed instances.
256 If other files are present in instance private directo‐
258 ries, the directories may not be fully removed, a warning
259 is logged to alert the administrator. It is expected that
260 an instance built using "fresh" directories via the cre‐
261 ate action will be fully removed by the destroy action
262 (if first disabled). If the instance configuration and
263 queue directories are populated with additional files
264 (access and rewriting tables, chroot jail content, etc.)
265 the instance directories will not be fully removed.
266 The destroy action triggers potentially dangerous file
268 removal operations. Make sure the instance's data, queue
269 and configuration directories are set correctly and do
270 not contain any valuable files.
271 deport Deport a secondary instance from the list of managed
273 instances. This deletes the instance configuration direc‐
274 tory from the primary instance's multi_instance_directo‐
275 ries list, but does not remove any files or directories.
276 assign Assign a new instance name or a new group name to the
278 selected instance. Use "-G -" to specify "no group" and
279 "-I -" to specify "no name". If you choose to make an
280 instance "nameless", set a suitable syslog_name in the
281 corresponding main.cf file.
282 enable Mark the selected instance as enabled. This just sets the
284 multi_instance_enable parameter to "yes" in the
285 instance's main.cf file.
286 disable
288 Mark the selected instance as disabled. This means that
289 the instance will not be started etc. with "postfix
290 start", "postmulti -p start" and so on. The instance can
291 still be started etc. with "postfix -c config-directory
292 start".
293
295 -v Enable verbose logging for debugging purposes. Multiple -v
296 options make the software increasingly verbose.
297
299 The postmulti(1) command exports the following environment variables
300 before executing the requested command for a given instance:
301 MAIL_VERBOSE
303 This is set when the -v command-line option is present.
304 MAIL_CONFIG
306 The location of the configuration directory of the instance.
307
309 config_directory (see 'postconf -d' output)
310 The default location of the Postfix main.cf and master.cf con‐
311 figuration files.
312 daemon_directory (see 'postconf -d' output)
314 The directory with Postfix support programs and daemon programs.
315 import_environment (see 'postconf -d' output)
317 The list of environment parameters that a privileged Postfix
318 process will import from a non-Postfix parent process, or
319 name=value environment overrides.
320 multi_instance_directories (empty)
322 An optional list of non-default Postfix configuration directo‐
323 ries; these directories belong to additional Postfix instances
324 that share the Postfix executable files and documentation with
325 the default Postfix instance, and that are started, stopped,
326 etc., together with the default Postfix instance.
327 multi_instance_group (empty)
329 The optional instance group name of this Postfix instance.
330 multi_instance_name (empty)
332 The optional instance name of this Postfix instance.
333 multi_instance_enable (no)
335 Allow this Postfix instance to be started, stopped, etc., by a
336 multi-instance manager.
337 postmulti_start_commands (start)
339 The postfix(1) commands that the postmulti(1) instance manager
340 treats as "start" commands.
341 postmulti_stop_commands (see 'postconf -d' output)
343 The postfix(1) commands that the postmulti(1) instance manager
344 treats as "stop" commands.
345 postmulti_control_commands (reload flush)
347 The postfix(1) commands that the postmulti(1) instance manager
348 treats as "control" commands, that operate on running instances.
349 syslog_facility (mail)
351 The syslog facility of Postfix logging.
352 syslog_name (see 'postconf -d' output)
354 A prefix that is prepended to the process name in syslog
355 records, so that, for example, "smtpd" becomes "prefix/smtpd".
356 Available in Postfix 3.0 and later:
358 meta_directory (see 'postconf -d' output)
360 The location of non-executable files that are shared among mul‐
361 tiple Postfix instances, such as postfix-files, dynamicmaps.cf,
362 and the multi-instance template files main.cf.proto and mas‐
363 ter.cf.proto.
364 shlib_directory (see 'postconf -d' output)
366 The location of Postfix dynamically-linked libraries (libpost‐
367 fix-*.so), and the default location of Postfix database plugins
368 (postfix-*.so) that have a relative pathname in the dynam‐
369 icmaps.cf file.
370
372 $meta_directory/main.cf.proto, stock configuration file
373 $meta_directory/master.cf.proto, stock configuration file
374 $daemon_directory/postmulti-script, life-cycle helper program
375
377 postfix(1), Postfix control program
378 postfix-wrapper(5), Postfix multi-instance API
379
381 Use "postconf readme_directory" or "postconf html_directory" to locate
382 this information.
383 MULTI_INSTANCE_README, Postfix multi-instance management
384
386 The postmulti(1) command was introduced with Postfix version 2.6.
387
389 The Secure Mailer license must be distributed with this software.
390
392 Victor Duchovni
393 Morgan Stanley
394 Wietse Venema
396 IBM T.J. Watson Research
397 P.O. Box 704
398 Yorktown Heights, NY 10598, USA
399 POSTMULTI(1)