diff options
Diffstat (limited to 'proto/postfix-wrapper')
| -rw-r--r-- | proto/postfix-wrapper | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/proto/postfix-wrapper b/proto/postfix-wrapper new file mode 100644 index 0000000..177282e --- /dev/null +++ b/proto/postfix-wrapper @@ -0,0 +1,290 @@ +#++ +# NAME +# postfix-wrapper 5 +# SUMMARY +# Postfix multi-instance API +# DESCRIPTION +# Support for managing multiple Postfix instances is available +# as of version 2.6. Instances share executable files and +# documentation, but have their own directories for configuration, +# 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 coordinate +# activities between the postfix(1) command and a multi-instance +# manager program. +# +# With multi-instance support, the default Postfix instance +# is always required. This instance is identified by the +# config_directory parameter's default value. +# GENERAL OPERATION +# .ad +# .fi +# 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 procedures, +# 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: +# .IP +# # postfix start +# .PP +# Other postfix(1) commands also work as expected. For example, +# to find out what Postfix instances exist in a multi-instance +# configuration, use: +# .IP +# # postfix status +# .PP +# This enumerates the status of all Postfix instances within +# a multi-instance configuration. +# MANAGING AN INDIVIDUAL POSTFIX INSTANCE +# .ad +# .fi +# To manage a specific Postfix instance, specify its configuration +# directory on the postfix(1) command line: +# .IP +# # postfix -c \fI/path/to/config_directory command\fR +# .PP +# Alternatively, the postfix(1) command accepts the instance's +# configuration directory via the MAIL_CONFIG environment +# variable (the -c command-line option has higher precedence). +# +# Otherwise, the postfix(1) command will operate on all Postfix +# instances. +# ENABLING POSTFIX(1) MULTI-INSTANCE MODE +# .ad +# .fi +# By default, the postfix(1) command operates in single-instance +# mode. In this mode the command invokes the postfix-script +# file directly (currently installed in the daemon directory). +# This file contains the commands that start or stop one +# Postfix instance, that upgrade the configuration of one +# Postfix instance, and so on. +# +# When the postfix(1) 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 postfix(1) multi-instance mode goes as follows: +# in the default Postfix instance's main.cf file, 1) specify +# the pathname of a multi-instance manager program with the +# multi_instance_wrapper parameter; 2) populate the +# multi_instance_directories parameter with the configuration +# directory pathnames of additional Postfix instances. For +# example: +# .IP +# .nf +# /etc/postfix/main.cf: +# multi_instance_wrapper = $daemon_directory/postfix-wrapper +# multi_instance_directories = /etc/postfix-test +# .fi +# .PP +# The $daemon_directory/postfix-wrapper file implements a +# simple manager and contains instructions for creating Postfix +# instances by hand. The postmulti(1) command provides a +# more extensive implementation including support for life-cycle +# management. +# +# The multi_instance_directories and other main.cf parameters +# are listed below in the CONFIGURATION PARAMETERS section. +# +# In multi-instance mode, the postfix(1) command invokes the +# $multi_instance_wrapper command instead of the postfix-script +# file. This multi-instance manager in turn executes the +# postfix(1) command in single-instance mode for each Postfix +# instance. +# +# To illustrate the main ideas behind multi-instance operation, +# below is an example of a simple but useful multi-instance +# manager implementation: +# .IP +# .nf +# #!/bin/sh +# +# : ${command_directory?"do not invoke this command directly"} +# +# POSTCONF=$command_directory/postconf +# POSTFIX=$command_directory/postfix +# instance_dirs=\`$POSTCONF -h multi_instance_directories | +# sed 's/,/ /'\` || exit 1 +# +# err=0 +# for dir in $config_directory $instance_dirs +# do +# case "$1" in +# stop|abort|flush|reload|drain) +# test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e +# = yes || continue;; +# start) +# test "\`$POSTCONF -c $dir -h multi_instance_enable\`" \e +# = yes || { +# $POSTFIX -c $dir check || err=$? +# continue +# };; +# esac +# $POSTFIX -c $dir "$@" || err=$? +# done +# +# exit $err +# .fi +# PER-INSTANCE MULTI-INSTANCE MANAGER CONTROLS +# .ad +# .fi +# Each Postfix instance has its own main.cf file with parameters +# that control how the multi-instance manager operates on +# that instance. This section discusses the most important +# settings. +# +# The setting "multi_instance_enable = yes" allows the +# multi-instance manager to start (stop, etc.) the corresponding +# Postfix instance. For safety reasons, this setting is not +# the default. +# +# The default setting "multi_instance_enable = no" is useful +# for manual testing with "postfix -c \fI/path/name\fR 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. +# MAINTAINING SHARED AND NON-SHARED FILES +# .ad +# .fi +# 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 config_directory value is +# listed with the default main.cf file's multi_instance_directories +# parameter. +# +# The consequence of this approach is that the default Postfix +# instance should be checked and updated before any other +# instances. +# MULTI-INSTANCE API SUMMARY +# .ad +# .fi +# Only the multi-instance manager implements support for the +# multi_instance_enable configuration parameter. The +# multi-instance manager will start only Postfix instances +# whose main.cf file has "multi_instance_enable = yes". A +# setting of "no" allows a Postfix instance to be tested by +# hand. +# +# The postfix(1) 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 multi_instance_directories parameter +# value is non-empty, the postfix(1) command executes the +# command specified with the multi_instance_wrapper parameter, +# 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 "multi_instance_enable = yes". +# This avoids false error messages. +# +# The multi-instance manager replaces a "start" command by +# "check" when a Postfix instance's main.cf file does not +# have "multi_instance_enable = 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 config_directory value is listed in the +# default main.cf's multi_instance_directories parameter +# value. Therefore, the default instance should be checked +# and updated before any Postfix instances that depend on it. +# +# Set-gid commands such as postdrop(1) and postqueue(1) +# effectively append the multi_instance_directories parameter +# value to the legacy alternate_config_directories parameter +# value. The commands use this information to determine whether +# a -c option or MAIL_CONFIG environment setting specifies a +# legitimate value. +# +# The legacy alternate_config_directories parameter remains +# necessary for non-default Postfix instances that are running +# different versions of Postfix, or that are not managed +# together with the default Postfix instance. +# ENVIRONMENT VARIABLES +# .ad +# .fi +# .IP MAIL_CONFIG +# When present, this forces the postfix(1) command to operate +# only on the specified Postfix instance. This environment +# variable is exported by the postfix(1) -c option, so that +# postfix(1) commands in descendant processes will work +# correctly. +# CONFIGURATION PARAMETERS +# .ad +# .fi +# The text below provides only a parameter summary. See +# postconf(5) for more details. +# .IP "\fBmulti_instance_directories (empty)\fR" +# An optional list of non-default Postfix configuration directories; +# these directories belong to additional 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. +# .IP "\fBmulti_instance_wrapper (empty)\fR" +# The pathname of a multi-instance manager command that the +# \fBpostfix\fR(1) command invokes when the multi_instance_directories +# parameter value is non-empty. +# .IP "\fBmulti_instance_name (empty)\fR" +# The optional instance name of this Postfix instance. +# .IP "\fBmulti_instance_group (empty)\fR" +# The optional instance group name of this Postfix instance. +# .IP "\fBmulti_instance_enable (no)\fR" +# Allow this Postfix instance to be started, stopped, etc., by a +# multi-instance manager. +# NON-SHARED FILES +# .ad +# .fi +# .IP "\fBconfig_directory (see 'postconf -d' output)\fR" +# The default location of the Postfix main.cf and master.cf +# configuration files. +# .IP "\fBdata_directory (see 'postconf -d' output)\fR" +# The directory with Postfix-writable data files (for example: +# caches, pseudo-random numbers). +# .IP "\fBqueue_directory (see 'postconf -d' output)\fR" +# The location of the Postfix top-level queue directory. +# SEE ALSO +# postfix(1) Postfix control program +# postmulti(1) full-blown multi-instance manager +# $daemon_directory/postfix-wrapper simple multi-instance manager +# LICENSE +# .ad +# .fi +# The Secure Mailer license must be distributed with this +# software. +# AUTHOR(S) +# Wietse Venema +# IBM T.J. Watson Research +# P.O. Box 704 +# Yorktown Heights, NY 10598, USA +# +# Wietse Venema +# Google, Inc. +# 111 8th Avenue +# New York, NY 10011, USA +#-- |