1POSTMULTI(1) General Commands Manual POSTMULTI(1)
2
6 postmulti - Postfix multi-instance manager
7
9 postmulti -l [-aRv] [-g group] [-i name]
10 postmulti -p [-av] [-g group] [-i name] command...
12 postmulti -x [-aRv] [-g group] [-i name] command...
14 postmulti -e init [-v]
16 postmulti -e create [-av] [-g group] [-i name] [-G group] [-I name]
18 [param=value ...]
19 postmulti -e import [-av] [-g group] [-i name] [-G group] [-I name]
21 [config_directory=/path]
22 postmulti -e destroy [-v] -i name
24 postmulti -e deport [-v] -i name
26 postmulti -e enable [-v] -i name
28 postmulti -e disable [-v] -i name
30 postmulti -e assign [-v] -i name [-I name] [-G group]
32
34 The postmulti(1) command allows a Postfix administrator to manage mul‐
35 tiple Postfix instances on a single host.
36 postmulti(1) implements two fundamental modes of operation. In itera‐
38 tor mode, it executes the same command for multiple Postfix instances.
39 In life-cycle management mode, it adds or deletes one instance, or
40 changes the multi-instance status of one instance.
41 Each mode of operation has its own command syntax. For this reason,
43 each mode is documented in separate sections below.
44
46 A multi-instance configuration consists of one primary Postfix
47 instance, and one or more secondary instances whose configuration
48 directory pathnames are recorded in the primary instance's main.cf
49 file. Postfix instances share program files and documentation, but have
50 their own configuration, queue and data directories.
51 Currently, only the default Postfix instance can be used as primary
53 instance in a multi-instance configuration. The postmulti(1) command
54 does not currently support a -c option to select an alternative primary
55 instance, and exits with a fatal error if the MAIL_CONFIG environment
56 variable is set to a non-default configuration directory.
57 See the MULTI_INSTANCE_README tutorial for a more detailed discussion
59 of multi-instance management with postmulti(1).
60
62 In iterator mode, postmulti performs the same operation on all Postfix
63 instances in turn.
64 If multi-instance support is not enabled, the requested command is per‐
66 formed just for the primary instance.
67 Iterator mode implements the following command options:
69
71 -a Perform the operation on all instances. This is the default.
72 -g group
74 Perform the operation only for members of the named group.
75 -i name
77 Perform the operation only for the instance with the specified
78 name. You can specify either the instance name or the absolute
79 pathname of the instance's configuration directory. Specify "-"
80 to select the primary Postfix instance.
81 -R Reverse the iteration order. This may be appropriate when updat‐
83 ing a multi-instance system, where "sink" instances are started
84 before "source" instances.
85 This option cannot be used with -p.
87
89 -l List Postfix instances with their instance name, instance group
90 name, enable/disable status and configuration directory.
91
93 -p Invoke postfix(1) to execute the specified command. This option
94 implements the postfix-wrapper(5) interface.
95 · With "start"-like commands, "postfix check" is executed
97 for instances that are not enabled. The full list of com‐
98 mands is specified with the postmulti_start_commands
99 parameter.
100 · With "stop"-like commands, the iteration order is
102 reversed, and disabled instances are skipped. The full
103 list of commands is specified with the post‐
104 multi_stop_commands parameter.
105 · With "reload" and other commands that require a started
107 instance, disabled instances are skipped. The full list
108 of commands is specified with the postmulti_control_com‐
109 mands parameter.
110 · With "status" and other commands that don't require a
112 started instance, the command is executed for all
113 instances.
114 The -p option can also be used interactively to start/stop/etc.
116 a named instance or instance group. For example, to start just
117 the instances in the group "msa", invoke postmulti(1) as fol‐
118 lows:
119 # postmulti -g msa -p start
121
123 -x Execute the specified command for all Postfix instances. The
124 command runs with appropriate environment settings for MAIL_CON‐
125 FIG, command_directory, daemon_directory, config_directory,
126 queue_directory, data_directory, multi_instance_name,
127 multi_instance_group and multi_instance_enable.
128
130 -v Enable verbose logging for debugging purposes. Multiple -v
131 options make the software increasingly verbose.
132
134 With the -e option postmulti(1) can be used to add or delete a Postfix
135 instance, and to manage the multi-instance status of an existing
136 instance.
137 The following options are implemented:
139
141 -a When creating or importing an instance, place the new instance
142 at the front of the secondary instance list.
143 -g group
145 When creating or importing an instance, place the new instance
146 before the first secondary instance that is a member of the
147 specified group.
148 -i name
150 When creating or importing an instance, place the new instance
151 before the matching secondary instance.
152 With other life-cycle operations, apply the operation to the
154 named existing instance. Specify "-" to select the primary
155 Postfix instance.
156
158 -I name
159 Assign the specified instance name to an existing instance,
160 newly-created instance, or imported instance. Instance names
161 other than "-" (which makes the instance "nameless") must start
162 with "postfix-". This restriction reduces the likelihood of
163 name collisions with system files.
164 -G group
166 Assign the specified group name to an existing instance or to a
167 newly created or imported instance.
168
170 -e action
171 "Edit" managed instances. The following actions are supported:
172 init This command is required before postmulti(1) can be used
174 to manage Postfix instances. The "postmulti -e init"
175 command updates the primary instance's main.cf file by
176 setting:
177 multi_instance_wrapper =
179 ${command_directory}/postmulti -p --
180 multi_instance_enable = yes
181 You can set these by other means if you prefer.
183 create Create a new Postfix instance and add it to the
185 multi_instance_directories parameter of the primary
186 instance. The "-I name" option is recommended to give
187 the instance a short name that is used to construct
188 default values for the private directories of the new
189 instance. The "-G group" option may be specified to
190 assign the instance to a group, otherwise, the new
191 instance is not a member of any groups.
192 The new instance main.cf is the stock main.cf with the
194 parameters that specify the locations of shared files
195 cloned from the primary instance. For "nameless"
196 instances, you should manually adjust "syslog_name" to
197 yield a unique "logtag" starting with "postfix-" that
198 will uniquely identify the instance in the mail logs. It
199 is simpler to assign the instance a short name with the
200 "-I name" option.
201 Optional "name=value" arguments specify the instance con‐
203 fig_directory, queue_directory and data_directory. For
204 example:
205 # postmulti -I postfix-mumble \
207 -G mygroup -e create \
208 config_directory=/my/config/dir \
209 queue_directory=/my/queue/dir \
210 data_directory=/my/data/dir
211 If any of these pathnames is not supplied, the program
213 attempts to generate the pathname by taking the corre‐
214 sponding primary instance pathname, and by replacing the
215 last pathname component by the value of the -I option.
216 If the instance configuration directory already exists,
218 and contains both a main.cf and master.cf file, create
219 will "import" the instance as-is. For existing instances,
220 create and import are identical.
221 import Import an existing instance into the list of instances
223 managed by the postmulti(1) multi-instance manager. This
224 adds the instance to the multi_instance_directories list
225 of the primary instance. If the "-I name" option is pro‐
226 vided it specifies the new name for the instance and is
227 used to define a default location for the instance con‐
228 figuration directory (as with create above). The "-G
229 group" option may be used to assign the instance to a
230 group. Add a "config_directory=/path" argument to over‐
231 ride a default pathname based on "-I name".
232 destroy
234 Destroy a secondary Postfix instance. To be a candidate
235 for destruction an instance must be disabled, stopped and
236 its queue must not contain any messages. Attempts to
237 destroy the primary Postfix instance trigger a fatal
238 error, without destroying the instance.
239 The instance is removed from the primary instance main.cf
241 file's alternate_config_directories parameter and its
242 data, queue and configuration directories are cleaned of
243 files and directories created by the Postfix system. The
244 main.cf and master.cf files are removed from the configu‐
245 ration directory even if they have been modified since
246 initial creation. Finally, the instance is "deported"
247 from the list of managed instances.
248 If other files are present in instance private directo‐
250 ries, the directories may not be fully removed, a warning
251 is logged to alert the administrator. It is expected that
252 an instance built using "fresh" directories via the cre‐
253 ate action will be fully removed by the destroy action
254 (if first disabled). If the instance configuration and
255 queue directories are populated with additional files
256 (access and rewriting tables, chroot jail content, etc.)
257 the instance directories will not be fully removed.
258 The destroy action triggers potentially dangerous file
260 removal operations. Make sure the instance's data, queue
261 and configuration directories are set correctly and do
262 not contain any valuable files.
263 deport Deport a secondary instance from the list of managed
265 instances. This deletes the instance configuration direc‐
266 tory from the primary instance's multi_instance_directo‐
267 ries list, but does not remove any files or directories.
268 assign Assign a new instance name or a new group name to the
270 selected instance. Use "-G -" to specify "no group" and
271 "-I -" to specify "no name". If you choose to make an
272 instance "nameless", set a suitable syslog_name in the
273 corresponding main.cf file.
274 enable Mark the selected instance as enabled. This just sets the
276 multi_instance_enable parameter to "yes" in the
277 instance's main.cf file.
278 disable
280 Mark the selected instance as disabled. This means that
281 the instance will not be started etc. with "postfix
282 start", "postmulti -p start" and so on. The instance can
283 still be started etc. with "postfix -c config-directory
284 start".
285
287 -v Enable verbose logging for debugging purposes. Multiple -v
288 options make the software increasingly verbose.
289
291 The postmulti(1) command exports the following environment variables
292 before executing the requested command for a given instance:
293 MAIL_VERBOSE
295 This is set when the -v command-line option is present.
296 MAIL_CONFIG
298 The location of the configuration directory of the instance.
299
301 config_directory (see 'postconf -d' output)
302 The default location of the Postfix main.cf and master.cf con‐
303 figuration files.
304 daemon_directory (see 'postconf -d' output)
306 The directory with Postfix support programs and daemon programs.
307 import_environment (see 'postconf -d' output)
309 The list of environment parameters that a Postfix process will
310 import from a non-Postfix parent process.
311 multi_instance_directories (empty)
313 An optional list of non-default Postfix configuration directo‐
314 ries; these directories belong to additional Postfix instances
315 that share the Postfix executable files and documentation with
316 the default Postfix instance, and that are started, stopped,
317 etc., together with the default Postfix instance.
318 multi_instance_group (empty)
320 The optional instance group name of this Postfix instance.
321 multi_instance_name (empty)
323 The optional instance name of this Postfix instance.
324 multi_instance_enable (no)
326 Allow this Postfix instance to be started, stopped, etc., by a
327 multi-instance manager.
328 postmulti_start_commands (start)
330 The postfix(1) commands that the postmulti(1) instance manager
331 treats as "start" commands.
332 postmulti_stop_commands (see 'postconf -d' output)
334 The postfix(1) commands that the postmulti(1) instance manager
335 treats as "stop" commands.
336 postmulti_control_commands (reload flush)
338 The postfix(1) commands that the postmulti(1) instance manager
339 treats as "control" commands, that operate on running instances.
340 syslog_facility (mail)
342 The syslog facility of Postfix logging.
343 syslog_name (see 'postconf -d' output)
345 The mail system name that is prepended to the process name in
346 syslog records, so that "smtpd" becomes, for example, "post‐
347 fix/smtpd".
348
350 $daemon_directory/main.cf, stock configuration file
351 $daemon_directory/master.cf, stock configuration file
352 $daemon_directory/postmulti-script, life-cycle helper program
353
355 postfix(1), Postfix control program
356 postfix-wrapper(5), Postfix multi-instance API
357
359 Use "postconf readme_directory" or "postconf
360 html_directory" to locate this information.
361 MULTI_INSTANCE_README, Postfix multi-instance management
362
364 The postmulti(1) command was introduced with Postfix version 2.6.
365
367 The Secure Mailer license must be distributed with this software.
368
370 Victor Duchovni
371 Morgan Stanley
372 Wietse Venema
374 IBM T.J. Watson Research
375 P.O. Box 704
376 Yorktown Heights, NY 10598, USA
377 POSTMULTI(1)