xref: /netbsd-src/external/ibm-public/postfix/dist/html/postmulti.1.html (revision b0d1725196a7921d003d2c66a14f186abda4176b)
1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
2        "http://www.w3.org/TR/html4/loose.dtd">
3<html> <head>
4<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
5<title> Postfix manual - postmulti(1) </title>
6</head> <body> <pre>
7POSTMULTI(1)                                                      POSTMULTI(1)
8
9<b>NAME</b>
10       postmulti - Postfix multi-instance manager
11
12<b>SYNOPSIS</b>
13   <b>Enabling multi-instance management:</b>
14
15       <b>postmulti -e init</b> [<b>-v</b>]
16
17   <b>Iterator mode:</b>
18
19       <b>postmulti -l</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>]
20
21       <b>postmulti -p</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>postfix-command...</i>
22
23       <b>postmulti -x</b> [<b>-aRv</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] <i>unix-command...</i>
24
25   <b>Life-cycle management:</b>
26
27       <b>postmulti -e create</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] [<b>-G</b> <i>group</i>] [<b>-I</b> <i>name</i>]
28       [<i>param=value</i> ...]
29
30       <b>postmulti -e import</b> [<b>-av</b>] [<b>-g</b> <i>group</i>] [<b>-i</b> <i>name</i>] [<b>-G</b> <i>group</i>] [<b>-I</b> <i>name</i>]
31       [<b><a href="postconf.5.html#config_directory">config_directory</a>=</b><i>/path</i>]
32
33       <b>postmulti -e destroy</b> [<b>-v</b>] <b>-i</b> <i>name</i>
34
35       <b>postmulti -e deport</b> [<b>-v</b>] <b>-i</b> <i>name</i>
36
37       <b>postmulti -e enable</b> [<b>-v</b>] <b>-i</b> <i>name</i>
38
39       <b>postmulti -e disable</b> [<b>-v</b>] <b>-i</b> <i>name</i>
40
41       <b>postmulti -e assign</b> [<b>-v</b>] <b>-i</b> <i>name</i> [<b>-I</b> <i>name</i>] [-G <i>group</i>]
42
43<b>DESCRIPTION</b>
44       The  <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command allows a Postfix administrator to manage mul-
45       tiple Postfix instances on a single host.
46
47       <a href="postmulti.1.html"><b>postmulti</b>(1)</a> implements two fundamental modes of operation.  In  <b>itera-</b>
48       <b>tor</b>  mode, it executes the same command for multiple Postfix instances.
49       In <b>life-cycle management</b> mode, it adds  or  deletes  one  instance,  or
50       changes the multi-instance status of one instance.
51
52       Each  mode  of  operation  has its own command syntax. For this reason,
53       each mode is documented in separate sections below.
54
55<b>BACKGROUND</b>
56       A  multi-instance  configuration  consists  of  one   primary   Postfix
57       instance,  and  one  or  more  secondary  instances whose configuration
58       directory pathnames are recorded  in  the  primary  instance's  <a href="postconf.5.html">main.cf</a>
59       file. Postfix instances share program files and documentation, but have
60       their own configuration, queue and data directories.
61
62       Currently, only the default Postfix instance can  be  used  as  primary
63       instance  in  a  multi-instance configuration. The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command
64       does not currently support a <b>-c</b> option to select an alternative primary
65       instance,  and  exits with a fatal error if the <b>MAIL_CONFIG</b> environment
66       variable is set to a non-default configuration directory.
67
68       See the <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a> tutorial for a more  detailed  discussion
69       of multi-instance management with <a href="postmulti.1.html"><b>postmulti</b>(1)</a>.
70
71<b>ITERATOR MODE</b>
72       In  iterator mode, <b>postmulti</b> performs the same operation on all Postfix
73       instances in turn.
74
75       If multi-instance support is not enabled, the requested command is per-
76       formed just for the primary instance.
77
78       Iterator mode implements the following command options:
79
80<b>Instance selection</b>
81       <b>-a</b>     Perform the operation on all instances. This is the default.
82
83       <b>-g</b> <i>group</i>
84              Perform the operation only for members of the named <i>group</i>.
85
86       <b>-i</b> <i>name</i>
87              Perform  the  operation only for the instance with the specified
88              <i>name</i>.  You can specify either the instance name or the  absolute
89              pathname of the instance's configuration directory.  Specify "-"
90              to select the primary Postfix instance.
91
92       <b>-R</b>     Reverse the iteration order. This may be appropriate when updat-
93              ing  a multi-instance system, where "sink" instances are started
94              before "source" instances.
95
96              This option cannot be used with <b>-p</b>.
97
98<b>List mode</b>
99       <b>-l</b>     List Postfix instances with their instance name, instance  group
100              name, enable/disable status and configuration directory.
101
102<b>Postfix-wrapper mode</b>
103       <b>-p</b> <i>postfix-command</i>
104              Invoke  <a href="postfix.1.html"><b>postfix(1)</a></b>  to  execute  <i>postfix-command</i>.   This  option
105              implements the <a href="postfix-wrapper.5.html"><b>postfix-wrapper</b>(5)</a> interface.
106
107              <b>o</b>      With "start"-like commands, "postfix check"  is  executed
108                     for instances that are not enabled. The full list of com-
109                     mands  is  specified  with  the  <a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a>
110                     parameter.
111
112              <b>o</b>      With   "stop"-like   commands,  the  iteration  order  is
113                     reversed, and disabled instances are  skipped.  The  full
114                     list   of   commands   is   specified   with   the  <a href="postconf.5.html#postmulti_stop_commands">post</a>-
115                     <a href="postconf.5.html#postmulti_stop_commands">multi_stop_commands</a> parameter.
116
117              <b>o</b>      With "reload" and other commands that require  a  started
118                     instance,  disabled  instances are skipped. The full list
119                     of commands is specified with the  <a href="postconf.5.html#postmulti_control_commands">postmulti_control_com</a>-
120                     <a href="postconf.5.html#postmulti_control_commands">mands</a> parameter.
121
122              <b>o</b>      With  "status"  and  other  commands that don't require a
123                     started  instance,  the  command  is  executed  for   all
124                     instances.
125
126              The  <b>-p</b> option can also be used interactively to start/stop/etc.
127              a named instance or instance group. For example, to  start  just
128              the  instances  in  the group "msa", invoke <a href="postmulti.1.html"><b>postmulti</b>(1)</a> as fol-
129              lows:
130
131                     # postmulti -g msa -p start
132
133<b>Command mode</b>
134       <b>-x</b> <i>unix-command</i>
135              Execute the specified <i>unix-command</i> for  all  Postfix  instances.
136              The  command  runs  with  appropriate  environment  settings for
137              MAIL_CONFIG, <a href="postconf.5.html#command_directory">command_directory</a>, <a href="postconf.5.html#daemon_directory">daemon_directory</a>,  <a href="postconf.5.html#config_directory">config_direc</a>-
138              <a href="postconf.5.html#config_directory">tory</a>,   <a href="postconf.5.html#queue_directory">queue_directory</a>,   <a href="postconf.5.html#data_directory">data_directory</a>,  <a href="postconf.5.html#multi_instance_name">multi_instance_name</a>,
139              <a href="postconf.5.html#multi_instance_group">multi_instance_group</a> and <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>.
140
141<b>Other options</b>
142       <b>-v</b>     Enable verbose  logging  for  debugging  purposes.  Multiple  <b>-v</b>
143              options make the software increasingly verbose.
144
145<b>LIFE-CYCLE MANAGEMENT MODE</b>
146       With  the <b>-e</b> option <a href="postmulti.1.html"><b>postmulti</b>(1)</a> can be used to add or delete a Postfix
147       instance, and to  manage  the  multi-instance  status  of  an  existing
148       instance.
149
150       The following options are implemented:
151
152<b>Existing instance selection</b>
153       <b>-a</b>     When  creating  or importing an instance, place the new instance
154              at the front of the secondary instance list.
155
156       <b>-g</b> <i>group</i>
157              When creating or importing an instance, place the  new  instance
158              before  the  first  secondary  instance  that is a member of the
159              specified group.
160
161       <b>-i</b> <i>name</i>
162              When creating or importing an instance, place the  new  instance
163              before the matching secondary instance.
164
165              With  other  life-cycle  operations,  apply the operation to the
166              named existing instance.  Specify  "-"  to  select  the  primary
167              Postfix instance.
168
169<b>New or existing instance name assignment</b>
170       <b>-I</b> <i>name</i>
171              Assign  the  specified  instance  <i>name</i>  to an existing instance,
172              newly-created instance, or imported  instance.   Instance  names
173              other  than "-" (which makes the instance "nameless") must start
174              with "postfix-".  This restriction  reduces  the  likelihood  of
175              name collisions with system files.
176
177       <b>-G</b> <i>group</i>
178              Assign  the specified <i>group</i> name to an existing instance or to a
179              newly created or imported instance.
180
181<b>Instance creation/deletion/status change</b>
182       <b>-e</b> <i>action</i>
183              "Edit" managed instances. The following actions are supported:
184
185              <b>init</b>   This command is required before <a href="postmulti.1.html"><b>postmulti</b>(1)</a> can be  used
186                     to  manage  Postfix  instances.   The "postmulti -e init"
187                     command updates the primary instance's  <a href="postconf.5.html">main.cf</a>  file  by
188                     setting:
189
190                            <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> =
191                                    ${<a href="postconf.5.html#command_directory">command_directory</a>}/postmulti -p --
192                            <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes
193
194                     You can set these by other means if you prefer.
195
196              <b>create</b> Create   a  new  Postfix  instance  and  add  it  to  the
197                     <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  parameter  of   the   primary
198                     instance.   The  "<b>-I</b>  <i>name</i>" option is recommended to give
199                     the instance a short  name  that  is  used  to  construct
200                     default  values  for  the  private directories of the new
201                     instance. The "<b>-G</b>  <i>group</i>"  option  may  be  specified  to
202                     assign  the  instance  to  a  group,  otherwise,  the new
203                     instance is not a member of any group.
204
205                     The new instance <a href="postconf.5.html">main.cf</a> is the stock  <a href="postconf.5.html">main.cf</a>  with  the
206                     parameters  that  specify  the  locations of shared files
207                     cloned  from  the  primary  instance.    For   "nameless"
208                     instances,  you  should  manually adjust "<a href="postconf.5.html#syslog_name">syslog_name</a>" to
209                     yield a unique "logtag"  starting  with  "postfix-"  that
210                     will  uniquely identify the instance in the mail logs. It
211                     is simpler to assign the instance a short name  with  the
212                     "<b>-I</b> <i>name</i>" option.
213
214                     Optional "name=value" arguments specify the instance <a href="postconf.5.html#config_directory">con</a>-
215                     <a href="postconf.5.html#config_directory">fig_directory</a>, <a href="postconf.5.html#queue_directory">queue_directory</a> and  <a href="postconf.5.html#data_directory">data_directory</a>.   For
216                     example:
217
218                            # postmulti -I postfix-mumble \
219                                    -G mygroup -e create \
220                                    <a href="postconf.5.html#config_directory">config_directory</a>=/my/config/dir \
221                                    <a href="postconf.5.html#queue_directory">queue_directory</a>=/my/queue/dir \
222                                    <a href="postconf.5.html#data_directory">data_directory</a>=/my/data/dir
223
224                     If  any  of  these pathnames is not supplied, the program
225                     attempts to generate the missing  pathname(s)  by  taking
226                     the  corresponding primary instance pathname, and replac-
227                     ing the last pathname component by the value  of  the  <b>-I</b>
228                     option.
229
230                     If  the  instance configuration directory already exists,
231                     and contains both a <a href="postconf.5.html">main.cf</a> and  <a href="master.5.html">master.cf</a>  file,  <b>create</b>
232                     will "import" the instance as-is. For existing instances,
233                     <b>create</b> and <b>import</b> are identical.
234
235              <b>import</b> Import an existing instance into the  list  of  instances
236                     managed by the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> multi-instance manager.  This
237                     adds the instance to the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  list
238                     of the primary instance.  If the "<b>-I</b> <i>name</i>" option is pro-
239                     vided it specifies the new name for the instance  and  is
240                     used  to  define a default location for the instance con-
241                     figuration directory (as with  <b>create</b>  above).   The  "<b>-G</b>
242                     <i>group</i>"  option  may  be  used to assign the instance to a
243                     group. Add a "<b><a href="postconf.5.html#config_directory">config_directory</a>=</b><i>/path</i>" argument  to  over-
244                     ride a default pathname based on "<b>-I</b> <i>name</i>".
245
246              <b>destroy</b>
247                     Destroy  a  secondary Postfix instance. To be a candidate
248                     for destruction an instance must be disabled, stopped and
249                     its  queue  must  not  contain  any messages. Attempts to
250                     destroy the primary  Postfix  instance  trigger  a  fatal
251                     error, without destroying the instance.
252
253                     The instance is removed from the primary instance <a href="postconf.5.html">main.cf</a>
254                     file's  <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a>  parameter  and  its
255                     data,  queue and configuration directories are cleaned of
256                     files and directories created by the Postfix system.  The
257                     <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> files are removed from the configu-
258                     ration directory even if they have  been  modified  since
259                     initial  creation.  Finally,  the  instance is "deported"
260                     from the list of managed instances.
261
262                     If other files are present in instance  private  directo-
263                     ries, the directories may not be fully removed, a warning
264                     is logged to alert the administrator. It is expected that
265                     an  instance built using "fresh" directories via the <b>cre-</b>
266                     <b>ate</b> action will be fully removed by  the  <b>destroy</b>  action
267                     (if  first  disabled).  If the instance configuration and
268                     queue directories are  populated  with  additional  files
269                     (access  and rewriting tables, chroot jail content, etc.)
270                     the instance directories will not be fully removed.
271
272                     The <b>destroy</b> action triggers  potentially  dangerous  file
273                     removal  operations. Make sure the instance's data, queue
274                     and configuration directories are set  correctly  and  do
275                     not contain any valuable files.
276
277              <b>deport</b> Deport  a  secondary  instance  from  the list of managed
278                     instances. This deletes the instance configuration direc-
279                     tory  from the primary instance's <a href="postconf.5.html#multi_instance_directories">multi_instance_directo</a>-
280                     <a href="postconf.5.html#multi_instance_directories">ries</a> list, but does not remove any files or  directories.
281
282              <b>assign</b> Assign  a  new  instance  name or a new group name to the
283                     selected instance.  Use "<b>-G -</b>" to specify "no group"  and
284                     "<b>-I  -</b>"  to  specify "no name".  If you choose to make an
285                     instance "nameless", set a suitable  <a href="postconf.5.html#syslog_name">syslog_name</a>  in  the
286                     corresponding <a href="postconf.5.html">main.cf</a> file.
287
288              <b>enable</b> Mark the selected instance as enabled. This just sets the
289                     <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>   parameter   to   "yes"   in   the
290                     instance's <a href="postconf.5.html">main.cf</a> file.
291
292              <b>disable</b>
293                     Mark  the  selected instance as disabled. This means that
294                     the instance will  not  be  started  etc.  with  "postfix
295                     start",  "postmulti -p start" and so on. The instance can
296                     still be started etc. with "postfix  -c  config-directory
297                     start".
298
299<b>Other options</b>
300       <b>-v</b>     Enable  verbose  logging  for  debugging  purposes.  Multiple <b>-v</b>
301              options make the software increasingly verbose.
302
303<b>ENVIRONMENT</b>
304       The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command exports the  following  environment  variables
305       before executing the requested <i>command</i> for a given instance:
306
307       <b>MAIL_VERBOSE</b>
308              This is set when the -v command-line option is present.
309
310       <b>MAIL_CONFIG</b>
311              The location of the configuration directory of the instance.
312
313<b>CONFIGURATION PARAMETERS</b>
314       <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
315              The  default  location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con-
316              figuration files.
317
318       <b><a href="postconf.5.html#daemon_directory">daemon_directory</a> (see 'postconf -d' output)</b>
319              The directory with Postfix support programs and daemon programs.
320
321       <b><a href="postconf.5.html#import_environment">import_environment</a> (see 'postconf -d' output)</b>
322              The  list  of  environment  variables  that a privileged Postfix
323              process will  import  from  a  non-Postfix  parent  process,  or
324              name=value environment overrides.
325
326       <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b>
327              An  optional  list of non-default Postfix configuration directo-
328              ries; these directories belong to additional  Postfix  instances
329              that  share  the Postfix executable files and documentation with
330              the default Postfix instance, and  that  are  started,  stopped,
331              etc., together with the default Postfix instance.
332
333       <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b>
334              The optional instance group name of this Postfix instance.
335
336       <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b>
337              The optional instance name of this Postfix instance.
338
339       <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b>
340              Allow  this  Postfix instance to be started, stopped, etc., by a
341              multi-instance manager.
342
343       <b><a href="postconf.5.html#postmulti_start_commands">postmulti_start_commands</a> (start)</b>
344              The <a href="postfix.1.html"><b>postfix</b>(1)</a> commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a>  instance  manager
345              treats as "start" commands.
346
347       <b><a href="postconf.5.html#postmulti_stop_commands">postmulti_stop_commands</a> (see 'postconf -d' output)</b>
348              The  <a href="postfix.1.html"><b>postfix</b>(1)</a>  commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a> instance manager
349              treats as "stop" commands.
350
351       <b><a href="postconf.5.html#postmulti_control_commands">postmulti_control_commands</a> (reload flush)</b>
352              The <a href="postfix.1.html"><b>postfix</b>(1)</a> commands that the <a href="postmulti.1.html"><b>postmulti</b>(1)</a>  instance  manager
353              treats as "control" commands, that operate on running instances.
354
355       <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
356              The syslog facility of Postfix logging.
357
358       <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
359              A prefix that  is  prepended  to  the  process  name  in  syslog
360              records, so that, for example, "smtpd" becomes "prefix/smtpd".
361
362       Available in Postfix 3.0 and later:
363
364       <b><a href="postconf.5.html#meta_directory">meta_directory</a> (see 'postconf -d' output)</b>
365              The  location of non-executable files that are shared among mul-
366              tiple Postfix instances, such as postfix-files,  dynamicmaps.cf,
367              and  the  multi-instance  template  files <a href="postconf.5.html">main.cf</a>.proto and <a href="master.5.html">mas-
368              ter.cf</a>.proto.
369
370       <b><a href="postconf.5.html#shlib_directory">shlib_directory</a> (see 'postconf -d' output)</b>
371              The location of Postfix dynamically-linked  libraries  (libpost-
372              fix-*.so),  and the default location of Postfix database plugins
373              (postfix-*.so) that have  a  relative  pathname  in  the  dynam-
374              icmaps.cf file.
375
376<b>FILES</b>
377       $<a href="postconf.5.html#meta_directory">meta_directory</a>/<a href="postconf.5.html">main.cf</a>.proto, stock configuration file
378       $<a href="postconf.5.html#meta_directory">meta_directory</a>/<a href="master.5.html">master.cf</a>.proto, stock configuration file
379       $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postmulti-script, life-cycle helper program
380
381<b>SEE ALSO</b>
382       <a href="postfix.1.html">postfix(1)</a>, Postfix control program
383       <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a>, Postfix multi-instance API
384
385<b>README FILES</b>
386       <a href="MULTI_INSTANCE_README.html">MULTI_INSTANCE_README</a>, Postfix multi-instance management
387
388<b>HISTORY</b>
389       The <a href="postmulti.1.html"><b>postmulti</b>(1)</a> command was introduced with Postfix version 2.6.
390
391<b>LICENSE</b>
392       The Secure Mailer license must be distributed with this software.
393
394<b>AUTHOR(S)</b>
395       Victor Duchovni
396       Morgan Stanley
397
398       Wietse Venema
399       IBM T.J. Watson Research
400       P.O. Box 704
401       Yorktown Heights, NY 10598, USA
402
403       Wietse Venema
404       Google, Inc.
405       111 8th Avenue
406       New York, NY 10011, USA
407
408                                                                  POSTMULTI(1)
409</pre> </body> </html>
410