1 files changed, 434 insertions, 0 deletions
diff --git a/man/man1/postmulti.1 b/man/man1/postmulti.1
new file mode 100644
index 0000000..6db035e
--- /dev/null
+++ b/man/man1/postmulti.1
@@ -0,0 +1,434 @@
+.TH POSTMULTI 1 
+.ad
+.fi
+.SH NAME
+postmulti
+\-
+Postfix multi\-instance manager
+.SH "SYNOPSIS"
+.na
+.nf
+.fi
+.ti -4
+\fBEnabling multi\-instance management:\fR
+
+\fBpostmulti\fR \fB\-e init\fR [\fB\-v\fR]
+
+.ti -4
+\fBIterator mode:\fR
+
+\fBpostmulti\fR \fB\-l\fR [\fB\-aRv\fR] [\fB\-g \fIgroup\fR]
+[\fB\-i \fIname\fR]
+
+\fBpostmulti\fR \fB\-p\fR [\fB\-av\fR] [\fB\-g \fIgroup\fR]
+[\fB\-i \fIname\fR] \fIpostfix\-command...\fR
+
+\fBpostmulti\fR \fB\-x\fR [\fB\-aRv\fR] [\fB\-g \fIgroup\fR]
+[\fB\-i \fIname\fR] \fIunix\-command...\fR
+
+.ti -4
+\fBLife\-cycle management:\fR
+
+\fBpostmulti\fR \fB\-e create\fR [\fB\-av\fR]
+[\fB\-g \fIgroup\fR] [\fB\-i \fIname\fR] [\fB\-G \fIgroup\fR]
+[\fB\-I \fIname\fR] [\fIparam=value\fR ...]
+
+\fBpostmulti\fR \fB\-e import\fR [\fB\-av\fR]
+[\fB\-g \fIgroup\fR] [\fB\-i \fIname\fR] [\fB\-G \fIgroup\fR]
+[\fB\-I \fIname\fR] [\fBconfig_directory=\fI/path\fR]
+
+\fBpostmulti\fR \fB\-e destroy\fR [\fB\-v\fR] \fB\-i \fIname\fR
+
+\fBpostmulti\fR \fB\-e deport\fR [\fB\-v\fR] \fB\-i \fIname\fR
+
+\fBpostmulti\fR \fB\-e enable\fR [\fB\-v\fR] \fB\-i \fIname\fR
+
+\fBpostmulti\fR \fB\-e disable\fR [\fB\-v\fR] \fB\-i \fIname\fR
+
+\fBpostmulti\fR \fB\-e assign\fR [\fB\-v\fR] \fB\-i \fIname\fR
+[\fB\-I \fIname\fR] [\-G \fIgroup\fR]
+.SH DESCRIPTION
+.ad
+.fi
+The \fBpostmulti\fR(1) command allows a Postfix administrator
+to manage multiple Postfix instances on a single host.
+
+\fBpostmulti\fR(1) implements two fundamental modes of
+operation.  In \fBiterator\fR mode, it executes the same
+command for multiple Postfix instances.  In \fBlife\-cycle
+management\fR mode, it adds or deletes one instance, or
+changes the multi\-instance status of one instance.
+
+Each mode of operation has its own command syntax. For this
+reason, each mode is documented in separate sections below.
+.SH "BACKGROUND"
+.na
+.nf
+.ad
+.fi
+A multi\-instance configuration consists of one primary
+Postfix instance, and one or more secondary instances whose
+configuration directory pathnames are recorded in the primary
+instance's main.cf file. Postfix instances share program
+files and documentation, but have their own configuration,
+queue and data directories.
+
+Currently, only the default Postfix instance can be used
+as primary instance in a multi\-instance configuration. The
+\fBpostmulti\fR(1) command does not currently support a \fB\-c\fR
+option to select an alternative primary instance, and exits
+with a fatal error if the \fBMAIL_CONFIG\fR environment
+variable is set to a non\-default configuration directory.
+
+See the MULTI_INSTANCE_README tutorial for a more detailed
+discussion of multi\-instance management with \fBpostmulti\fR(1).
+.SH "ITERATOR MODE"
+.na
+.nf
+.ad
+.fi
+In iterator mode, \fBpostmulti\fR performs the same operation
+on all Postfix instances in turn.
+
+If multi\-instance support is not enabled, the requested
+command is performed just for the primary instance.
+.PP
+Iterator mode implements the following command options:
+.SH "Instance selection"
+.IP \fB\-a\fR
+Perform the operation on all instances. This is the default.
+.IP "\fB\-g \fIgroup\fR"
+Perform the operation only for members of the named \fIgroup\fR.
+.IP "\fB\-i \fIname\fR"
+Perform the operation only for the instance with the specified
+\fIname\fR.  You can specify either the instance name
+or the absolute pathname of the instance's configuration
+directory.  Specify "\-" to select the primary Postfix instance.
+.IP \fB\-R\fR
+Reverse the iteration order. This may be appropriate when
+updating a multi\-instance system, where "sink" instances
+are started before "source" instances.
+.sp
+This option cannot be used with \fB\-p\fR.
+.SH "List mode"
+.IP \fB\-l\fR
+List Postfix instances with their instance name, instance
+group name, enable/disable status and configuration directory.
+.SH "Postfix\-wrapper mode"
+.IP "\fB\-p \fIpostfix\-command\fR"
+Invoke \fBpostfix(1)\fR to execute \fIpostfix\-command\fR.
+This option implements the \fBpostfix\-wrapper\fR(5) interface.
+.RS
+.IP \(bu
+With "start"\-like commands, "postfix check" is executed for
+instances that are not enabled. The full list of commands
+is specified with the postmulti_start_commands parameter.
+.IP \(bu
+With "stop"\-like commands, the iteration order is reversed,
+and disabled instances are skipped. The full list of commands
+is specified with the postmulti_stop_commands parameter.
+.IP \(bu
+With "reload" and other commands that require a started
+instance, disabled instances are skipped. The full list of
+commands is specified with the postmulti_control_commands
+parameter.
+.IP \(bu
+With "status" and other commands that don't require a started
+instance, the command is executed for all instances.
+.RE
+.IP
+The \fB\-p\fR option can also be used interactively to
+start/stop/etc.  a named instance or instance group. For
+example, to start just the instances in the group "msa",
+invoke \fBpostmulti\fR(1) as follows:
+.RS
+.IP
+# postmulti \-g msa \-p start
+.RE
+.SH "Command mode"
+.IP "\fB\-x \fIunix\-command\fR"
+Execute the specified \fIunix\-command\fR for all Postfix instances.
+The command runs with appropriate environment settings for
+MAIL_CONFIG, command_directory, daemon_directory,
+config_directory, queue_directory, data_directory,
+multi_instance_name, multi_instance_group and
+multi_instance_enable.
+.SH "Other options"
+.IP \fB\-v\fR
+Enable verbose logging for debugging purposes. Multiple
+\fB\-v\fR options make the software increasingly verbose.
+.SH "LIFE-CYCLE MANAGEMENT MODE"
+.na
+.nf
+.ad
+.fi
+With the \fB\-e\fR option \fBpostmulti\fR(1) can be used to
+add or delete a Postfix instance, and to manage the
+multi\-instance status of an existing instance.
+.PP
+The following options are implemented:
+.SH "Existing instance selection"
+.IP \fB\-a\fR
+When creating or importing an instance, place the new
+instance at the front of the secondary instance list.
+.IP "\fB\-g \fIgroup\fR"
+When creating or importing an instance, place the new
+instance before the first secondary instance that is a
+member of the specified group.
+.IP "\fB\-i \fIname\fR"
+When creating or importing an instance, place the new
+instance before the matching secondary instance.
+.sp
+With other life\-cycle operations, apply the operation to
+the named existing instance.  Specify "\-" to select the
+primary Postfix instance.
+.SH "New or existing instance name assignment"
+.IP "\fB\-I \fIname\fR"
+Assign the specified instance \fIname\fR to an existing
+instance, newly\-created instance, or imported instance.
+Instance
+names other than "\-" (which makes the instance "nameless")
+must start with "postfix\-".  This restriction reduces the
+likelihood of name collisions with system files.
+.IP "\fB\-G \fIgroup\fR"
+Assign the specified \fIgroup\fR name to an existing instance
+or to a newly created or imported instance.
+.SH "Instance creation/deletion/status change"
+.IP "\fB\-e \fIaction\fR"
+"Edit" managed instances. The following actions are supported:
+.RS
+.IP \fBinit\fR
+This command is required before \fBpostmulti\fR(1) can be
+used to manage Postfix instances.  The "postmulti \-e init"
+command updates the primary instance's main.cf file by
+setting:
+.RS
+.IP
+.nf
+multi_instance_wrapper =
+        ${command_directory}/postmulti \-p \-\-
+multi_instance_enable = yes
+.fi
+.RE
+.IP
+You can set these by other means if you prefer.
+.IP \fBcreate\fR
+Create a new Postfix instance and add it to the
+multi_instance_directories parameter of the primary instance.
+The "\fB\-I \fIname\fR" option is recommended to give the
+instance a short name that is used to construct default
+values for the private directories of the new instance. The
+"\fB\-G \fIgroup\fR" option may be specified to assign the
+instance to a group, otherwise, the new instance is not a
+member of any group.
+.sp
+The new instance main.cf is the stock main.cf with the
+parameters that specify the locations of shared files cloned
+from the primary instance.  For "nameless" instances, you
+should manually adjust "syslog_name" to yield a unique
+"logtag" starting with "postfix\-" that will uniquely identify
+the instance in the mail logs. It is simpler to assign the
+instance a short name with the "\fB\-I \fIname\fR" option.
+.sp
+Optional "name=value" arguments specify the instance
+config_directory, queue_directory and data_directory.
+For example:
+.RS
+.IP
+.nf
+# postmulti \-I postfix\-mumble \e
+        \-G mygroup \-e create \e
+        config_directory=/my/config/dir \e
+        queue_directory=/my/queue/dir \e
+        data_directory=/my/data/dir
+.fi
+.RE
+.IP
+If any of these pathnames is not supplied, the program
+attempts to generate the missing pathname(s) by taking the
+corresponding primary instance pathname, and replacing the
+last pathname component by the value of the \fB\-I\fR option.
+.sp
+If the instance configuration directory already exists, and
+contains both a main.cf and master.cf file, \fBcreate\fR
+will "import" the instance as\-is. For existing instances,
+\fBcreate\fR and \fBimport\fR are identical.
+.IP \fBimport\fR
+Import an existing instance into the list of instances
+managed by the \fBpostmulti\fR(1) multi\-instance manager.
+This adds the instance to the multi_instance_directories
+list of the primary instance.  If the "\fB\-I \fIname\fR"
+option is provided it specifies the new name for the instance
+and is used to define a default location for the instance
+configuration directory (as with \fBcreate\fR above).  The
+"\fB\-G \fIgroup\fR" option may be used to assign the instance
+to a group. Add a "\fBconfig_directory=\fI/path\fR" argument
+to override a default pathname based on "\fB\-I \fIname\fR".
+.IP \fBdestroy\fR
+Destroy a secondary Postfix instance. To be a candidate for
+destruction an instance must be disabled, stopped and its
+queue must not contain any messages. Attempts to destroy
+the primary Postfix instance trigger a fatal error, without
+destroying the instance.
+.sp
+The instance is removed from the primary instance main.cf
+file's alternate_config_directories parameter and its data,
+queue and configuration directories are cleaned of files
+and directories created by the Postfix system. The main.cf
+and master.cf files are removed from the configuration
+directory even if they have been modified since initial
+creation. Finally, the instance is "deported" from the list
+of managed instances.
+.sp
+If other files are present in instance private directories,
+the directories may not be fully removed, a warning is
+logged to alert the administrator. It is expected that an
+instance built using "fresh" directories via the \fBcreate\fR
+action will be fully removed by the \fBdestroy\fR action
+(if first disabled). If the instance configuration and queue
+directories are populated with additional files (access and
+rewriting tables, chroot jail content, etc.) the instance
+directories will not be fully removed.
+.sp
+The \fBdestroy\fR action triggers potentially dangerous
+file removal operations. Make sure the instance's data,
+queue and configuration directories are set correctly and
+do not contain any valuable files.
+.IP \fBdeport\fR
+Deport a secondary instance from the list of managed
+instances. This deletes the instance configuration directory
+from the primary instance's multi_instance_directories list,
+but does not remove any files or directories.
+.IP \fBassign\fR
+Assign a new instance name or a new group name to the
+selected instance.  Use "\fB\-G \-\fR" to specify "no group"
+and "\fB\-I \-\fR" to specify "no name".  If you choose to
+make an instance "nameless", set a suitable syslog_name in
+the corresponding main.cf file.
+.IP \fBenable\fR
+Mark the selected instance as enabled. This just sets the
+multi_instance_enable parameter to "yes" in the instance's
+main.cf file.
+.IP \fBdisable\fR
+Mark the selected instance as disabled. This means that
+the instance will not be started etc. with "postfix start",
+"postmulti \-p start" and so on. The instance can still be
+started etc. with "postfix \-c config\-directory start".
+.SH "Other options"
+.IP \fB\-v\fR
+Enable verbose logging for debugging purposes. Multiple
+\fB\-v\fR options make the software increasingly verbose.
+.RE
+.SH "ENVIRONMENT"
+.na
+.nf
+.ad
+.fi
+The \fBpostmulti\fR(1) command exports the following environment
+variables before executing the requested \fIcommand\fR for a given
+instance:
+.IP \fBMAIL_VERBOSE\fR
+This is set when the \-v command\-line option is present.
+.IP \fBMAIL_CONFIG\fR
+The location of the configuration directory of the instance.
+.SH "CONFIGURATION PARAMETERS"
+.na
+.nf
+.ad
+.fi
+.IP "\fBconfig_directory (see 'postconf -d' output)\fR"
+The default location of the Postfix main.cf and master.cf
+configuration files.
+.IP "\fBdaemon_directory (see 'postconf -d' output)\fR"
+The directory with Postfix support programs and daemon programs.
+.IP "\fBimport_environment (see 'postconf -d' output)\fR"
+The list of environment variables that a privileged Postfix
+process will import from a non\-Postfix parent process, or name=value
+environment overrides.
+.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_group (empty)\fR"
+The optional instance group name of this Postfix instance.
+.IP "\fBmulti_instance_name (empty)\fR"
+The optional instance 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.
+.IP "\fBpostmulti_start_commands (start)\fR"
+The \fBpostfix\fR(1) commands that the \fBpostmulti\fR(1) instance manager treats
+as "start" commands.
+.IP "\fBpostmulti_stop_commands (see 'postconf -d' output)\fR"
+The \fBpostfix\fR(1) commands that the \fBpostmulti\fR(1) instance manager treats
+as "stop" commands.
+.IP "\fBpostmulti_control_commands (reload flush)\fR"
+The \fBpostfix\fR(1) commands that the \fBpostmulti\fR(1) instance manager
+treats as "control" commands, that operate on running instances.
+.IP "\fBsyslog_facility (mail)\fR"
+The syslog facility of Postfix logging.
+.IP "\fBsyslog_name (see 'postconf -d' output)\fR"
+A prefix that is prepended to the process name in syslog
+records, so that, for example, "smtpd" becomes "prefix/smtpd".
+.PP
+Available in Postfix 3.0 and later:
+.IP "\fBmeta_directory (see 'postconf -d' output)\fR"
+The location of non\-executable files that are shared among
+multiple Postfix instances, such as postfix\-files, dynamicmaps.cf,
+and the multi\-instance template files main.cf.proto and master.cf.proto.
+.IP "\fBshlib_directory (see 'postconf -d' output)\fR"
+The location of Postfix dynamically\-linked libraries
+(libpostfix\-*.so), and the default location of Postfix database
+plugins (postfix\-*.so) that have a relative pathname in the
+dynamicmaps.cf file.
+.SH "FILES"
+.na
+.nf
+$meta_directory/main.cf.proto, stock configuration file
+$meta_directory/master.cf.proto, stock configuration file
+$daemon_directory/postmulti\-script, life\-cycle helper program
+.SH "SEE ALSO"
+.na
+.nf
+postfix(1), Postfix control program
+postfix\-wrapper(5), Postfix multi\-instance API
+.SH "README FILES"
+.na
+.nf
+.ad
+.fi
+Use "\fBpostconf readme_directory\fR" or "\fBpostconf
+html_directory\fR" to locate this information.
+.nf
+.na
+MULTI_INSTANCE_README, Postfix multi\-instance management
+.SH HISTORY
+.ad
+.fi
+.ad
+.fi
+The \fBpostmulti\fR(1) command was introduced with Postfix
+version 2.6.
+.SH "LICENSE"
+.na
+.nf
+.ad
+.fi
+The Secure Mailer license must be distributed with this software.
+.SH "AUTHOR(S)"
+.na
+.nf
+Victor Duchovni
+Morgan Stanley
+
+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