This file is indexed.

/usr/share/doc/postfix/html/postfix-wrapper.5.html is in postfix-doc 2.9.6-2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html> <head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<title> Postfix manual - postfix-wrapper(5) </title>
</head> <body> <pre>
POSTFIX-WRAPPER(5)                                          POSTFIX-WRAPPER(5)

<b>NAME</b>
       postfix-wrapper - Postfix multi-instance API

<b>DESCRIPTION</b>
       Support  for managing multiple Postfix instances is avail-
       able as of version 2.6. Instances share  executable  files
       and documentation, but have their own directories for con-
       figuration, queue and data files.

       This document describes how the familiar  "postfix  start"
       etc.  user interface can be used to manage one or multiple
       Postfix instances, and gives details of an API to  coordi-
       nate  activities  between  the  <a href="postfix.1.html">postfix(1)</a>  command  and a
       multi-instance manager program.

       With multi-instance support, the default Postfix  instance
       is  always  required.  This  instance is identified by the
       <a href="postconf.5.html#config_directory">config_directory</a> parameter's default value.

<b>GENERAL OPERATION</b>
       Multi-instance support is backwards compatible:  when  you
       run  only  one Postfix instance, commands such as "postfix
       start" will not change behavior at all.

       Even with multiple Postfix instances, you can  keep  using
       the  same postfix commands in boot scripts, upgrade proce-
       dures, and other places. The commands do  more  work,  but
       humans are not forced to learn new tricks.

       For example, to start all Postfix instances, use:

              # postfix start

       Other <a href="postfix.1.html">postfix(1)</a> commands also work as expected. For exam-
       ple, to find out what Postfix instances exist in a  multi-
       instance configuration, use:

              # postfix status

       This enumerates the status of all Postfix instances within
       a multi-instance configuration.

<b>MANAGING AN INDIVIDUAL POSTFIX INSTANCE</b>
       To manage a specific Postfix instance, specify its config-
       uration directory on the <a href="postfix.1.html">postfix(1)</a> command line:

              # postfix -c <i>/path/to/config</i><b>_</b><i>directory command</i>

       Alternatively,   the   <a href="postfix.1.html">postfix(1)</a>   command   accepts  the
       instance's configuration  directory  via  the  MAIL_CONFIG
       environment  variable  (the  -c  command-line  option  has
       higher precedence).

       Otherwise, the <a href="postfix.1.html">postfix(1)</a>  command  will  operate  on  all
       Postfix instances.

<b>ENABLING POSTFIX(1) MULTI-INSTANCE MODE</b>
       By  default,  the  <a href="postfix.1.html">postfix(1)</a>  command operates in single-
       instance mode. In this mode the command invokes the  post-
       fix-script  file directly (currently installed in the dae-
       mon directory).  This  file  contains  the  commands  that
       start  or stop one Postfix instance, that upgrade the con-
       figuration of one Postfix instance, and so on.

       When the <a href="postfix.1.html">postfix(1)</a>  command  operates  in  multi-instance
       mode  as  discussed  below,  the  command needs to execute
       start, stop, etc.  commands  for  each  Postfix  instance.
       This  multiplication  of  commands  is handled by a multi-
       instance manager program.

       Turning on <a href="postfix.1.html">postfix(1)</a> multi-instance mode goes as follows:
       in the default Postfix instance's <a href="postconf.5.html">main.cf</a> file, 1) specify
       the pathname of a multi-instance manager program with  the
       <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a>    parameter;   2)   populate   the
       <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter with  the  configura-
       tion  directory pathnames of additional Postfix instances.
       For example:

              /etc/postfix/<a href="postconf.5.html">main.cf</a>:
                  <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper
                  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> = /etc/postfix-test

       The $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper  file  implements  a
       simple  manager  and  contains  instructions  for creating
       Postfix instances by hand.  The <a href="postmulti.1.html">postmulti(1)</a> command  pro-
       vides  a  more  extensive implementation including support
       for life-cycle management.

       The <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> and other  <a href="postconf.5.html">main.cf</a>  parame-
       ters are listed below in the CONFIGURATION PARAMETERS sec-
       tion.

       In multi-instance mode, the <a href="postfix.1.html">postfix(1)</a> command invokes the
       $<a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a>  command  instead  of the postfix-
       script file. This multi-instance manager in turn  executes
       the  <a href="postfix.1.html">postfix(1)</a>  command  in single-instance mode for each
       Postfix instance.

       To illustrate the main ideas behind multi-instance  opera-
       tion,  below  is  an example of a simple but useful multi-
       instance manager implementation:

              #!/bin/sh

              : ${<a href="postconf.5.html#command_directory">command_directory</a>?"do not invoke this command directly"}

              POSTCONF=$<a href="postconf.5.html#command_directory">command_directory</a>/postconf
              POSTFIX=$<a href="postconf.5.html#command_directory">command_directory</a>/postfix
              instance_dirs=`$POSTCONF -h <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> |
                              sed 's/,/ /'` || exit 1

              err=0
              for dir in $<a href="postconf.5.html#config_directory">config_directory</a> $instance_dirs
              do
                  case "$1" in
                  stop|abort|flush|reload|drain)
                      test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
                          = yes || continue;;
                  start)
                      test "`$POSTCONF -c $dir -h <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>`" \
                          = yes || {
                          $POSTFIX -c $dir check || err=$?
                          continue
                      };;
                  esac
                  $POSTFIX -c $dir "$@" || err=$?
              done

              exit $err

<b>PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS</b>
       Each Postfix instance has its own <a href="postconf.5.html">main.cf</a> file with param-
       eters that control how the multi-instance manager operates
       on that instance.  This section discusses the most  impor-
       tant settings.

       The  setting  "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  =  yes"  allows  the
       multi-instance manager to start (stop,  etc.)  the  corre-
       sponding  Postfix  instance. For safety reasons, this set-
       ting is not the default.

       The default setting "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no" is useful
       for manual testing with "postfix -c <i>/path/name</i> start" etc.
       The  multi-instance  manager  will  not  start   such   an
       instance,  and  it  will  skip  commands such as "stop" or
       "flush" that require  a  running  Postfix  instance.   The
       multi-instance  manager  will  execute  commands  such  as
       "check", "set-permissions" or "upgrade-configuration", and
       it  will  replace "start" by "check" so that problems will
       be reported even when the instance is disabled.

<b>MAINTAINING SHARED AND NON-SHARED FILES</b>
       Some files are shared between Postfix instances,  such  as
       executables and manpages, and some files are per-instance,
       such as configuration files, mail queue  files,  and  data
       files.   See the NON-SHARED FILES section below for a list
       of per-instance files.

       Before Postfix multi-instance support was implemented, the
       executables,  manpages,  etc., have always been maintained
       as part of the default Postfix instance.

       With multi-instance support,  we  simply  continue  to  do
       this.   Specifically, a Postfix instance will not check or
       update shared files when that instance's  <a href="postconf.5.html#config_directory">config_directory</a>
       value   is   listed   with   the  default  <a href="postconf.5.html">main.cf</a>  file's
       <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter.

       The consequence of this approach is that the default Post-
       fix  instance  should  be  checked  and updated before any
       other instances.

<b>MULTI-INSTANCE API SUMMARY</b>
       Only the multi-instance manager implements support for the
       <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  configuration parameter. The multi-
       instance manager will start only Postfix  instances  whose
       <a href="postconf.5.html">main.cf</a>  file has "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes". A setting
       of "no" allows a Postfix instance to be tested by hand.

       The  <a href="postfix.1.html">postfix(1)</a>  command  operates  on  only  one  Postfix
       instance   when  the  -c  option  is  specified,  or  when
       MAIL_CONFIG is present in the process environment. This is
       necessary to terminate recursion.

       Otherwise,  when  the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter
       value is non-empty, the <a href="postfix.1.html">postfix(1)</a>  command  executes  the
       command  specified with the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> parame-
       ter, instead of executing the commands in  postfix-script.

       The  multi-instance  manager skips commands such as "stop"
       or "reload" that require a running Postfix instance,  when
       an  instance  does not have "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes".
       This avoids false error messages.

       The multi-instance manager replaces a "start"  command  by
       "check"  when  a  Postfix instance's <a href="postconf.5.html">main.cf</a> file does not
       have  "<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>  =  yes".  This  substitution
       ensures  that  problems  will  be  reported  even when the
       instance is disabled.

       No Postfix command or script will update or  check  shared
       files  when  its  <a href="postconf.5.html#config_directory">config_directory</a>  value is listed in the
       default  <a href="postconf.5.html">main.cf</a>'s  <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>   parameter
       value.   Therefore, the default instance should be checked
       and updated before any Postfix instances  that  depend  on
       it.

       Set-gid  commands  such  as  <a href="postdrop.1.html">postdrop(1)</a>  and <a href="postqueue.1.html">postqueue(1)</a>
       effectively append the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  parame-
       ter   value  to  the  legacy  <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a>
       parameter value. The  commands  use  this  information  to
       determine  whether  a -c option or MAIL_CONFIG environment
       setting specifies a legitimate value.

       The legacy <a href="postconf.5.html#alternate_config_directories">alternate_config_directories</a> parameter  remains
       necessary  for non-default Postfix instances that are run-
       ning different versions of Postfix, or that are  not  man-
       aged together with the default Postfix instance.

<b>ENVIRONMENT VARIABLES</b>
       MAIL_CONFIG
              When present, this forces the <a href="postfix.1.html">postfix(1)</a> command to
              operate only on  the  specified  Postfix  instance.
              This  environment variable is exported by the <a href="postfix.1.html">post-</a>
              <a href="postfix.1.html">fix(1)</a> -c option, so that  <a href="postfix.1.html">postfix(1)</a>  commands  in
              descendant processes will work correctly.

<b>CONFIGURATION PARAMETERS</b>
       The  text  below  provides  only  a parameter summary. See
       <a href="postconf.5.html">postconf(5)</a> for more details.

       <b><a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> (empty)</b>
              An optional list of non-default Postfix  configura-
              tion directories; these directories belong to addi-
              tional Postfix instances  that  share  the  Postfix
              executable files and documentation with the default
              Postfix instance, and that  are  started,  stopped,
              etc., together with the default Postfix instance.

       <b><a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> (empty)</b>
              The  pathname  of  a multi-instance manager command
              that  the  <a href="postfix.1.html"><b>postfix</b>(1)</a>  command  invokes  when   the
              <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a>  parameter value is non-
              empty.

       <b><a href="postconf.5.html#multi_instance_name">multi_instance_name</a> (empty)</b>
              The  optional  instance  name   of   this   Postfix
              instance.

       <b><a href="postconf.5.html#multi_instance_group">multi_instance_group</a> (empty)</b>
              The  optional  instance  group name of this Postfix
              instance.

       <b><a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> (no)</b>
              Allow this Postfix instance to be started, stopped,
              etc., by a multi-instance manager.

<b>NON-SHARED FILES</b>
       <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
              The  default  location  of  the Postfix <a href="postconf.5.html">main.cf</a> and
              <a href="master.5.html">master.cf</a> configuration files.

       <b><a href="postconf.5.html#data_directory">data_directory</a> (see 'postconf -d' output)</b>
              The directory with Postfix-writable data files (for
              example: caches, pseudo-random numbers).

       <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
              The  location of the Postfix top-level queue direc-
              tory.

<b>SEE ALSO</b>
       <a href="postfix.1.html">postfix(1)</a> Postfix control program
       <a href="postmulti.1.html">postmulti(1)</a> full-blown multi-instance manager
       $<a href="postconf.5.html#daemon_directory">daemon_directory</a>/postfix-wrapper simple multi-instance manager

<b>LICENSE</b>
       The Secure Mailer license must be  distributed  with  this
       software.

<b>AUTHOR(S)</b>
       Wietse Venema
       IBM T.J. Watson Research
       P.O. Box 704
       Yorktown Heights, NY 10598, USA

                                                            POSTFIX-WRAPPER(5)
</pre> </body> </html>