summaryrefslogtreecommitdiffstats
path: root/proto/postfix-wrapper
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--proto/postfix-wrapper290
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
+#--