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