1POSTMULTI(1)                General Commands Manual               POSTMULTI(1)
2
3
4

NAME

6       postmulti - Postfix multi-instance manager
7

SYNOPSIS

9   Enabling multi-instance management:
10
11       postmulti -e init [-v]
12
13   Iterator mode:
14
15       postmulti -l [-aRv] [-g group] [-i name]
16
17       postmulti -p [-av] [-g group] [-i name] postfix-command...
18
19       postmulti -x [-aRv] [-g group] [-i name] unix-command...
20
21   Life-cycle management:
22
23       postmulti -e create [-av] [-g group] [-i name] [-G group] [-I name]
24       [param=value ...]
25
26       postmulti -e import [-av] [-g group] [-i name] [-G group] [-I name]
27       [config_directory=/path]
28
29       postmulti -e destroy [-v] -i name
30
31       postmulti -e deport [-v] -i name
32
33       postmulti -e enable [-v] -i name
34
35       postmulti -e disable [-v] -i name
36
37       postmulti -e assign [-v] -i name [-I name] [-G group]
38

DESCRIPTION

40       The  postmulti(1) command allows a Postfix administrator to manage mul‐
41       tiple Postfix instances on a single host.
42
43       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
48       Each  mode  of  operation  has its own command syntax. For this reason,
49       each mode is documented in separate sections below.
50

BACKGROUND

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
58       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
64       See the MULTI_INSTANCE_README tutorial for a more  detailed  discussion
65       of multi-instance management with postmulti(1).
66

ITERATOR MODE

68       In  iterator mode, postmulti performs the same operation on all Postfix
69       instances in turn.
70
71       If multi-instance support is not enabled, the requested command is per‐
72       formed just for the primary instance.
73
74       Iterator mode implements the following command options:
75

Instance selection

77       -a     Perform the operation on all instances. This is the default.
78
79       -g group
80              Perform the operation only for members of the named group.
81
82       -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
88       -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
92              This option cannot be used with -p.
93

List mode

95       -l     List Postfix instances with their instance name, instance  group
96              name, enable/disable status and configuration directory.
97

Postfix-wrapper mode

99       -p postfix-command
100              Invoke  postfix(1)  to execute postfix-command.  This option im‐
101              plements the postfix-wrapper(5) interface.
102
103              •      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
108              •      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
113              •      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
118              •      With  "status"  and  other  commands that don't require a
119                     started instance, the command is  executed  for  all  in‐
120                     stances.
121
122              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
127                     # postmulti -g msa -p start
128

Command mode

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

Other options

138       -v     Enable verbose logging for debugging purposes. Multiple  -v  op‐
139              tions make the software increasingly verbose.
140

LIFE-CYCLE MANAGEMENT MODE

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
146       The following options are implemented:
147

Existing instance selection

149       -a     When  creating  or importing an instance, place the new instance
150              at the front of the secondary instance list.
151
152       -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
157       -i name
158              When creating or importing an instance, place the  new  instance
159              before the matching secondary instance.
160
161              With  other  life-cycle  operations,  apply the operation to the
162              named existing instance.  Specify  "-"  to  select  the  primary
163              Postfix instance.
164

New or existing instance name assignment

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
173       -G group
174              Assign  the specified group name to an existing instance or to a
175              newly created or imported instance.
176

Instance creation/deletion/status change

178       -e action
179              "Edit" managed instances. The following actions are supported:
180
181              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
186                            multi_instance_wrapper =
187                                    ${command_directory}/postmulti -p --
188                            multi_instance_enable = yes
189
190                     You can set these by other means if you prefer.
191
192              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
201                     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
210                     Optional "name=value" arguments specify the instance con‐
211                     fig_directory, queue_directory and  data_directory.   For
212                     example:
213
214                            # 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
220                     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
226                     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
231              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
242              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
249                     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
258                     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
268                     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
273              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
278              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
284              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
288              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

Other options

296       -v     Enable verbose logging for debugging purposes. Multiple  -v  op‐
297              tions make the software increasingly verbose.
298

ENVIRONMENT

300       The  postmulti(1)  command  exports the following environment variables
301       before executing the requested command for a given instance:
302
303       MAIL_VERBOSE
304              This is set when the -v command-line option is present.
305
306       MAIL_CONFIG
307              The location of the configuration directory of the instance.
308

CONFIGURATION PARAMETERS

310       config_directory (see 'postconf -d' output)
311              The default location of the Postfix main.cf and  master.cf  con‐
312              figuration files.
313
314       daemon_directory (see 'postconf -d' output)
315              The directory with Postfix support programs and daemon programs.
316
317       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
322       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
329       multi_instance_group (empty)
330              The optional instance group name of this Postfix instance.
331
332       multi_instance_name (empty)
333              The optional instance name of this Postfix instance.
334
335       multi_instance_enable (no)
336              Allow  this  Postfix instance to be started, stopped, etc., by a
337              multi-instance manager.
338
339       postmulti_start_commands (start)
340              The postfix(1) commands that the postmulti(1)  instance  manager
341              treats as "start" commands.
342
343       postmulti_stop_commands (see 'postconf -d' output)
344              The  postfix(1)  commands that the postmulti(1) instance manager
345              treats as "stop" commands.
346
347       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
351       syslog_facility (mail)
352              The syslog facility of Postfix logging.
353
354       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
358       Available in Postfix 3.0 and later:
359
360       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
366       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

FILES

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

SEE ALSO

378       postfix(1), Postfix control program
379       postfix-wrapper(5), Postfix multi-instance API
380

README FILES

382       Use "postconf readme_directory" or "postconf html_directory" to  locate
383       this information.
384       MULTI_INSTANCE_README, Postfix multi-instance management
385

HISTORY

387       The postmulti(1) command was introduced with Postfix version 2.6.
388

LICENSE

390       The Secure Mailer license must be distributed with this software.
391

AUTHOR(S)

393       Victor Duchovni
394       Morgan Stanley
395
396       Wietse Venema
397       IBM T.J. Watson Research
398       P.O. Box 704
399       Yorktown Heights, NY 10598, USA
400
401       Wietse Venema
402       Google, Inc.
403       111 8th Avenue
404       New York, NY 10011, USA
405
406
407
408                                                                  POSTMULTI(1)
Impressum