| blob | 8856448fca13697ae235263b4e884494f73d8f50 |
1 #++
2 # NAME
3 # postfix-wrapper 5
4 # SUMMARY
5 # Postfix multi-instance API
6 # DESCRIPTION
7 # Postfix versions 2.6 and later provide support for multiple
8 # Postfix instances. Instances share executable files and
9 # documentation, but have their own directories for configuration,
10 # queue and data files.
11 #
12 # This document describes how the familiar "postfix start"
13 # etc. user interface can be used to manage one or multiple
14 # Postfix instances, and gives details of an API to coordinate
15 # activities between the postfix(1) command and a multi-instance
16 # manager program.
17 #
18 # With multi-instance support, the default Postfix instance
19 # is always required. The config_directory parameter's default
20 # value specifies that instance's configuration file location.
21 # GENERAL OPERATION
22 # .ad
23 # .fi
24 # Multi-instance support is backwards compatible: when you
25 # run only one Postfix instance, commands such as "postfix
26 # start" will not change behavior at all.
27 #
28 # Even with multiple Postfix instances, you can keep using
29 # the same postfix commands in boot scripts, upgrade procedures,
30 # and other places. The commands do more work, but humans are
31 # not forced to learn new tricks.
32 #
33 # For example, to start all Postfix instances, use:
34 # .IP
35 # # postfix start
36 # .PP
37 # Other postfix(1) commands also work as expected. For example,
38 # to find out what Postfix instances exist in a multi-instance
39 # configuration, use:
40 # .IP
41 # # postfix status
42 # .PP
43 # This enumerates the status of all Postfix instances within
44 # a multi-instance configuration.
45 # MANAGING AN INDIVIDUAL POSTFIX INSTANCE
46 # .ad
47 # .fi
48 # To manage a specific Postfix instance, specify its configuration
49 # directory on the postfix(1) command line:
50 # .IP
51 # # postfix -c \fI/path/to/config_directory command\fR
52 # .PP
53 # Alternatively, the postfix(1) command accepts the instance's
54 # configuration directory via the MAIL_CONFIG environment
55 # variable (the -c command-line option has higher precedence).
56 #
57 # When no Postfix instance information is specified, the
58 # postfix(1) command will operate on all Postfix instances.
59 # ENABLING POSTFIX(1) MULTI-INSTANCE MODE
60 # .ad
61 # .fi
62 # By default, the postfix(1) command operates in single-instance
63 # mode. In this mode the command invokes the postfix-script
64 # file directly (currently installed in the daemon directory).
65 # This file contains the commands that start or stop one
66 # Postfix instance, that upgrade the configuration of one
67 # Postfix instance, and so on.
68 #
69 # When the postfix(1) command operates in multi-instance mode
70 # as discussed below, the command needs to execute start,
71 # stop, etc. commands for each Postfix instance. This
72 # multiplication of commands is handled by a multi-instance
73 # manager program.
74 #
75 # Turning on postfix(1) multi-instance mode goes as follows:
76 # in the default Postfix instance's main.cf file, 1) specify
77 # the pathname of a multi-instance manager program with the
78 # multi_instance_wrapper parameter; 2) populate the
79 # multi_instance_directories parameter with the configuration
80 # directory pathnames of additional Postfix instances. For
81 # example:
82 # .IP
83 # .nf
84 # /etc/postfix/main.cf:
85 # multi_instance_wrapper = $daemon_directory/postfix-wrapper
86 # multi_instance_directories = /etc/postfix-test
87 # .fi
88 # .PP
89 # The $daemon_directory/postfix-wrapper file implements a
90 # simple manager and contains instructions for creating Postfix
91 # instances by hand. The postmulti(1) command provides a
92 # more extensive implementation including support for life-cycle
93 # management.
94 #
95 # The multi_instance_directories and other main.cf parameters
96 # are listed below in the CONFIGURATION PARAMETERS section.
97 #
98 # In multi-instance mode, the postfix(1) command invokes the
99 # $multi_instance_wrapper command instead of the postfix-script
100 # file. This multi-instance manager in turn executes the
101 # postfix(1) command in single-instance mode for each Postfix
102 # instance.
103 #
104 # To illustrate the main ideas behind multi-instance operation,
105 # below is an example of a simple but useful multi-instance
106 # manager implementation:
107 # .IP
108 # .nf
109 # #!/bin/sh
110 #
111 # : ${command_directory?"do not invoke this command directly"}
112 #
113 # POSTCONF=$command_directory/postconf
114 # POSTFIX=$command_directory/postfix
115 # instance_dirs=\`$POSTCONF -h multi_instance_directories |
116 # sed 's/,/ /'\` || exit 1
117 #
118 # err=0
119 # for dir in $config_directory $instance_dirs
120 # do
121 # case "$1" in
122 # stop|abort|flush|reload|drain)
123 # test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e
124 # = yes || continue;;
125 # start)
126 # test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e
127 # = yes || {
128 # $POSTFIX -c $dir check || err=$?
129 # continue
130 # };;
131 # esac
132 # $POSTFIX -c $dir "$@" || err=$?
133 # done
134 #
135 # exit $err
136 # .fi
137 # PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS
138 # .ad
139 # .fi
140 # Each Postfix instance has its own main.cf file with parameters
141 # that control how the multi-instance manager operates on
142 # that instance. This section discusses the most important
143 # settings.
144 #
145 # The setting "multi_instance_enable = yes" allows the
146 # multi-instance manager to start (stop, etc.) the corresponding
147 # Postfix instance. For safety reasons, this setting is not
148 # the default.
149 #
150 # The default setting "multi_instance_enable = no" is useful
151 # for manual testing with "postfix -c \fI/path/name\fR start"
152 # etc. The multi-instance manager will not start such an
153 # instance, and it will skip commands such as "stop" or "flush"
154 # that require a running Postfix instance. The multi-instance
155 # manager will execute commands such as "check", "set-permissions"
156 # or "upgrade-configuration", and it will replace "start" by
157 # "check" so that problems will be reported even when the
158 # instance is disabled.
159 # MAINTAINING SHARED AND NON-SHARED FILES
160 # .ad
161 # .fi
162 # Some files are shared between Postfix instances, such as
163 # executables and manpages, and some files are per-instance,
164 # such as configuration files, mail queue files, and data
165 # files. See the NON-SHARED FILES section below for a list
166 # of per-instance files.
167 #
168 # Before Postfix multi-instance support was implemented, the
169 # executables, manpages, etc., have always been maintained
170 # as part of the default Postfix instance.
171 #
172 # With multi-instance support, we simply continue to do this.
173 # Specifically, a Postfix instance will not check or update
174 # shared files when that instance's config_directory value is
175 # listed with the default main.cf file's multi_instance_directories
176 # parameter.
177 #
178 # The consequence of this approach is that the default Postfix
179 # instance should be checked and updated before any other
180 # instances.
181 # MULTI-INSTANCE API SUMMARY
182 # .ad
183 # .fi
184 # Only the multi-instance manager implements support for the
185 # multi_instance_enable configuration parameter. The
186 # multi-instance manager will start only Postfix instances
187 # whose main.cf file has "multi_instance_enable = yes". A
188 # setting of "no" allows a Postfix instance to be tested by
189 # hand.
190 #
191 # The postfix(1) command operates on only one Postfix instance
192 # when the -c option is specified, or when MAIL_CONFIG is
193 # present in the process environment. This is necessary to
194 # terminate recursion.
195 #
196 # Otherwise, when the multi_instance_directories parameter
197 # value is non-empty, the postfix(1) command executes the
198 # command specified with the multi_instance_wrapper parameter,
199 # instead of executing the commands in postfix-script.
200 #
201 # The multi-instance manager skips commands such as "stop"
202 # or "reload" that require a running Postfix instance, when
203 # an instance does not have "multi_instance_enable = yes".
204 # This avoids false error messages.
205 #
206 # The multi-instance manager replaces a "start" command by
207 # "check" when a Postfix instance's main.cf file does not
208 # have "multi_instance_enable = yes". This substitution ensures
209 # that problems will be reported even when the instance is
210 # disabled.
211 #
212 # No Postfix command or script will update or check shared
213 # files when its config_directory value is listed in the
214 # default main.cf's multi_instance_directories parameter
215 # value. Therefore, the default instance should be checked
216 # and updated before any Postfix instances that depend on it.
217 #
218 # Set-gid commands such as postdrop(1) and postqueue(1)
219 # effectively append the multi_instance_directories parameter
220 # value to the legacy alternate_config_directories parameter
221 # value. The commands use this information to determine whether
222 # a -c option or MAIL_CONFIG environment setting specifies a
223 # legitimate value.
224 #
225 # The legacy alternate_config_directories parameter remains
226 # necessary for non-default Postfix instances that are running
227 # different versions of Postfix, or that are not managed
228 # together with the default Postfix instance.
229 # ENVIRONMENT VARIABLES
230 # .ad
231 # .fi
232 # .IP MAIL_CONFIG
233 # When present, this forces the postfix(1) command to operate
234 # only on the specified Postfix instance. This environment
235 # variable is exported by the postfix(1) -c option, so that
236 # postfix(1) commands in descendant processes will work
237 # correctly.
238 # CONFIGURATION PARAMETERS
239 # .ad
240 # .fi
241 # The text below provides only a parameter summary. See
242 # postconf(5) for more details.
243 # .IP "\fBmulti_instance_directories (empty)\fR"
244 # An optional list of non-default Postfix configuration directories;
245 # these directories belong to additional Postfix instances that share
246 # the Postfix executable files and documentation with the default
247 # Postfix instance, and that are started, stopped, etc., together
248 # with the default Postfix instance.
249 # .IP "\fBmulti_instance_wrapper (empty)\fR"
250 # The pathname of a multi-instance manager command that the
251 # \fBpostfix\fR(1) command invokes when the multi_instance_directories
252 # parameter value is non-empty.
253 # .IP "\fBmulti_instance_name (empty)\fR"
254 # The optional instance name of this Postfix instance.
255 # .IP "\fBmulti_instance_group (empty)\fR"
256 # The optional instance group name of this Postfix instance.
257 # .IP "\fBmulti_instance_enable (no)\fR"
258 # Allow this Postfix instance to be started, stopped, etc., by a
259 # multi-instance manager.
260 # NON-SHARED FILES
261 # .ad
262 # .fi
263 # .IP "\fBconfig_directory (see 'postconf -d' output)\fR"
264 # The default location of the Postfix main.cf and master.cf
265 # configuration files.
266 # .IP "\fBdata_directory (see 'postconf -d' output)\fR"
267 # The directory with Postfix-writable data files (for example:
268 # caches, pseudo-random numbers).
269 # .IP "\fBqueue_directory (see 'postconf -d' output)\fR"
270 # The location of the Postfix top-level queue directory.
271 # SEE ALSO
272 # postfix(1) Postfix control program
273 # postmulti(1) full-blown multi-instance manager
274 # $daemon_directory/postfix-wrapper simple multi-instance manager
275 # LICENSE
276 # .ad
277 # .fi
278 # The Secure Mailer license must be distributed with this
279 # software.
280 # AUTHOR(S)
281 # Wietse Venema
282 # IBM T.J. Watson Research
283 # P.O. Box 704
284 # Yorktown Heights, NY 10598, USA
285 #--