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
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
58       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
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
101              implements 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
106                     parameter.
107
108              ·      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
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
120                     instances.
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
139              options 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
144       instance.
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
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
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"
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
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 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
225                     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
230              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
241              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
248                     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
257                     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
267                     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
272              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
277              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
283              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
287              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

Other options

295       -v     Enable  verbose  logging  for  debugging  purposes.  Multiple -v
296              options make the software increasingly verbose.
297

ENVIRONMENT

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

CONFIGURATION PARAMETERS

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

FILES

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

SEE ALSO

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

README FILES

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

HISTORY

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

LICENSE

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

AUTHOR(S)

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