1POSTFIX-WRAPPER(5) File Formats Manual POSTFIX-WRAPPER(5)
2
6 postfix-wrapper - Postfix multi-instance API
7
9 Support for managing multiple Postfix instances is available as of ver‐
10 sion 2.6. Instances share executable files and documentation, but have
11 their own directories for configuration, queue and data files.
12 This document describes how the familiar "postfix start" etc. user
14 interface can be used to manage one or multiple Postfix instances, and
15 gives details of an API to coordinate activities between the postfix(1)
16 command and a multi-instance manager program.
17 With multi-instance support, the default Postfix instance is always
19 required. This instance is identified by the config_directory parame‐
20 ter's default value.
21
23 Multi-instance support is backwards compatible: when you run only one
24 Postfix instance, commands such as "postfix start" will not change
25 behavior at all.
26 Even with multiple Postfix instances, you can keep using the same post‐
28 fix commands in boot scripts, upgrade procedures, and other places. The
29 commands do more work, but humans are not forced to learn new tricks.
30 For example, to start all Postfix instances, use:
32 # postfix start
34 Other postfix(1) commands also work as expected. For example, to find
36 out what Postfix instances exist in a multi-instance configuration,
37 use:
38 # postfix status
40 This enumerates the status of all Postfix instances within a multi-
42 instance configuration.
43
45 To manage a specific Postfix instance, specify its configuration direc‐
46 tory on the postfix(1) command line:
47 # postfix -c /path/to/config_directory command
49 Alternatively, the postfix(1) command accepts the instance's configura‐
51 tion directory via the MAIL_CONFIG environment variable (the -c com‐
52 mand-line option has higher precedence).
53 Otherwise, the postfix(1) command will operate on all Postfix
55 instances.
56
58 By default, the postfix(1) command operates in single-instance mode. In
59 this mode the command invokes the postfix-script file directly (cur‐
60 rently installed in the daemon directory). This file contains the com‐
61 mands that start or stop one Postfix instance, that upgrade the config‐
62 uration of one Postfix instance, and so on.
63 When the postfix(1) command operates in multi-instance mode as dis‐
65 cussed below, the command needs to execute start, stop, etc. commands
66 for each Postfix instance. This multiplication of commands is handled
67 by a multi-instance manager program.
68 Turning on postfix(1) multi-instance mode goes as follows: in the
70 default Postfix instance's main.cf file, 1) specify the pathname of a
71 multi-instance manager program with the multi_instance_wrapper parame‐
72 ter; 2) populate the multi_instance_directories parameter with the con‐
73 figuration directory pathnames of additional Postfix instances. For
74 example:
75 /etc/postfix/main.cf:
77 multi_instance_wrapper = $daemon_directory/postfix-wrapper
78 multi_instance_directories = /etc/postfix-test
79 The $daemon_directory/postfix-wrapper file implements a simple manager
81 and contains instructions for creating Postfix instances by hand. The
82 postmulti(1) command provides a more extensive implementation including
83 support for life-cycle management.
84 The multi_instance_directories and other main.cf parameters are listed
86 below in the CONFIGURATION PARAMETERS section.
87 In multi-instance mode, the postfix(1) command invokes the
89 $multi_instance_wrapper command instead of the postfix-script file.
90 This multi-instance manager in turn executes the postfix(1) command in
91 single-instance mode for each Postfix instance.
92 To illustrate the main ideas behind multi-instance operation, below is
94 an example of a simple but useful multi-instance manager implementa‐
95 tion:
96 #!/bin/sh
98 : ${command_directory?"do not invoke this command directly"}
100 POSTCONF=$command_directory/postconf
102 POSTFIX=$command_directory/postfix
103 instance_dirs=`$POSTCONF -h multi_instance_directories |
104 sed 's/,/ /'` || exit 1
105 err=0
107 for dir in $config_directory $instance_dirs
108 do
109 case "$1" in
110 stop|abort|flush|reload|drain)
111 test "`$POSTCONF -c $dir -h multi_instance_enable`" \
112 = yes || continue;;
113 start)
114 test "`$POSTCONF -c $dir -h multi_instance_enable`" \
115 = yes || {
116 $POSTFIX -c $dir check || err=$?
117 continue
118 };;
119 esac
120 $POSTFIX -c $dir "$@" || err=$?
121 done
122 exit $err
124
126 Each Postfix instance has its own main.cf file with parameters that
127 control how the multi-instance manager operates on that instance. This
128 section discusses the most important settings.
129 The setting "multi_instance_enable = yes" allows the multi-instance
131 manager to start (stop, etc.) the corresponding Postfix instance. For
132 safety reasons, this setting is not the default.
133 The default setting "multi_instance_enable = no" is useful for manual
135 testing with "postfix -c /path/name start" etc. The multi-instance
136 manager will not start such an instance, and it will skip commands such
137 as "stop" or "flush" that require a running Postfix instance. The
138 multi-instance manager will execute commands such as "check", "set-per‐
139 missions" or "upgrade-configuration", and it will replace "start" by
140 "check" so that problems will be reported even when the instance is
141 disabled.
142
144 Some files are shared between Postfix instances, such as executables
145 and manpages, and some files are per-instance, such as configuration
146 files, mail queue files, and data files. See the NON-SHARED FILES sec‐
147 tion below for a list of per-instance files.
148 Before Postfix multi-instance support was implemented, the executables,
150 manpages, etc., have always been maintained as part of the default
151 Postfix instance.
152 With multi-instance support, we simply continue to do this. Specifi‐
154 cally, a Postfix instance will not check or update shared files when
155 that instance's config_directory value is listed with the default
156 main.cf file's multi_instance_directories parameter.
157 The consequence of this approach is that the default Postfix instance
159 should be checked and updated before any other instances.
160
162 Only the multi-instance manager implements support for the
163 multi_instance_enable configuration parameter. The multi-instance man‐
164 ager will start only Postfix instances whose main.cf file has
165 "multi_instance_enable = yes". A setting of "no" allows a Postfix
166 instance to be tested by hand.
167 The postfix(1) command operates on only one Postfix instance when the
169 -c option is specified, or when MAIL_CONFIG is present in the process
170 environment. This is necessary to terminate recursion.
171 Otherwise, when the multi_instance_directories parameter value is non-
173 empty, the postfix(1) command executes the command specified with the
174 multi_instance_wrapper parameter, instead of executing the commands in
175 postfix-script.
176 The multi-instance manager skips commands such as "stop" or "reload"
178 that require a running Postfix instance, when an instance does not have
179 "multi_instance_enable = yes". This avoids false error messages.
180 The multi-instance manager replaces a "start" command by "check" when a
182 Postfix instance's main.cf file does not have "multi_instance_enable =
183 yes". This substitution ensures that problems will be reported even
184 when the instance is disabled.
185 No Postfix command or script will update or check shared files when its
187 config_directory value is listed in the default main.cf's
188 multi_instance_directories parameter value. Therefore, the default
189 instance should be checked and updated before any Postfix instances
190 that depend on it.
191 Set-gid commands such as postdrop(1) and postqueue(1) effectively
193 append the multi_instance_directories parameter value to the legacy
194 alternate_config_directories parameter value. The commands use this
195 information to determine whether a -c option or MAIL_CONFIG environment
196 setting specifies a legitimate value.
197 The legacy alternate_config_directories parameter remains necessary for
199 non-default Postfix instances that are running different versions of
200 Postfix, or that are not managed together with the default Postfix
201 instance.
202
204 MAIL_CONFIG
205 When present, this forces the postfix(1) command to operate only
206 on the specified Postfix instance. This environment variable is
207 exported by the postfix(1) -c option, so that postfix(1) com‐
208 mands in descendant processes will work correctly.
209
211 The text below provides only a parameter summary. See postconf(5) for
212 more details.
213 multi_instance_directories (empty)
215 An optional list of non-default Postfix configuration directo‐
216 ries; these directories belong to additional Postfix instances
217 that share the Postfix executable files and documentation with
218 the default Postfix instance, and that are started, stopped,
219 etc., together with the default Postfix instance.
220 multi_instance_wrapper (empty)
222 The pathname of a multi-instance manager command that the post‐
223 fix(1) command invokes when the multi_instance_directories
224 parameter value is non-empty.
225 multi_instance_name (empty)
227 The optional instance name of this Postfix instance.
228 multi_instance_group (empty)
230 The optional instance group name of this Postfix instance.
231 multi_instance_enable (no)
233 Allow this Postfix instance to be started, stopped, etc., by a
234 multi-instance manager.
235
237 config_directory (see 'postconf -d' output)
238 The default location of the Postfix main.cf and master.cf con‐
239 figuration files.
240 data_directory (see 'postconf -d' output)
242 The directory with Postfix-writable data files (for example:
243 caches, pseudo-random numbers).
244 queue_directory (see 'postconf -d' output)
246 The location of the Postfix top-level queue directory.
247
249 postfix(1) Postfix control program
250 postmulti(1) full-blown multi-instance manager
251 $daemon_directory/postfix-wrapper simple multi-instance manager
252
254 The Secure Mailer license must be distributed with this software.
255
257 Wietse Venema
258 IBM T.J. Watson Research
259 P.O. Box 704
260 Yorktown Heights, NY 10598, USA
261 POSTFIX-WRAPPER(5)