external/ibm-public/postfix/dist/man/man5/postfix-wrapper.5

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