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] command...
18
19       postmulti -x [-aRv] [-g group] [-i name] 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     Invoke postfix(1) to execute the specified command.  This option
100              implements the postfix-wrapper(5) interface.
101
102              ·      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
107              ·      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
112              ·      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
117              ·      With  "status"  and  other  commands that don't require a
118                     started  instance,  the  command  is  executed  for   all
119                     instances.
120
121              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
126                     # postmulti -g msa -p start
127

Command mode

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

Other options

136       -v     Enable verbose  logging  for  debugging  purposes.  Multiple  -v
137              options make the software increasingly verbose.
138

LIFE-CYCLE MANAGEMENT MODE

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
144       The following options are implemented:
145

Existing instance selection

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

New or existing instance name assignment

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

Instance creation/deletion/status change

176       -e action
177              "Edit" managed instances. The following actions are supported:
178
179              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
184                            multi_instance_wrapper =
185                                    ${command_directory}/postmulti -p --
186                            multi_instance_enable = yes
187
188                     You can set these by other means if you prefer.
189
190              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
199                     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
208                     Optional "name=value" arguments specify the instance con‐
209                     fig_directory, queue_directory and  data_directory.   For
210                     example:
211
212                            # 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
218                     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
223                     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
228              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
239              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
246                     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
255                     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
265                     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
270              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
275              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
281              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
285              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

Other options

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

ENVIRONMENT

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

CONFIGURATION PARAMETERS

307       config_directory (see 'postconf -d' output)
308              The  default  location of the Postfix main.cf and master.cf con‐
309              figuration files.
310
311       daemon_directory (see 'postconf -d' output)
312              The directory with Postfix support programs and daemon programs.
313
314       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
318       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
325       multi_instance_group (empty)
326              The optional instance group name of this Postfix instance.
327
328       multi_instance_name (empty)
329              The optional instance name of this Postfix instance.
330
331       multi_instance_enable (no)
332              Allow  this  Postfix instance to be started, stopped, etc., by a
333              multi-instance manager.
334
335       postmulti_start_commands (start)
336              The postfix(1) commands that the postmulti(1)  instance  manager
337              treats as "start" commands.
338
339       postmulti_stop_commands (see 'postconf -d' output)
340              The  postfix(1)  commands that the postmulti(1) instance manager
341              treats as "stop" commands.
342
343       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
347       syslog_facility (mail)
348              The syslog facility of Postfix logging.
349
350       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

FILES

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

SEE ALSO

361       postfix(1), Postfix control program
362       postfix-wrapper(5), Postfix multi-instance API
363

README FILES

365       Use "postconf readme_directory" or "postconf
366       html_directory" to locate this information.
367       MULTI_INSTANCE_README, Postfix multi-instance management
368

HISTORY

370       The postmulti(1) command was introduced with Postfix version 2.6.
371

LICENSE

373       The Secure Mailer license must be distributed with this software.
374

AUTHOR(S)

376       Victor Duchovni
377       Morgan Stanley
378
379       Wietse Venema
380       IBM T.J. Watson Research
381       P.O. Box 704
382       Yorktown Heights, NY 10598, USA
383
384
385
386                                                                  POSTMULTI(1)
Impressum