From 5e61585d76ae77fd5e9e96ebabb57afa4d74880d Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Sat, 27 Apr 2024 14:06:34 +0200
Subject: Adding upstream version 3.5.24.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 README_FILES/MULTI_INSTANCE_README | 981 +++++++++++++++++++++++++++++++++++++
 1 file changed, 981 insertions(+)
 create mode 100644 README_FILES/MULTI_INSTANCE_README

(limited to 'README_FILES/MULTI_INSTANCE_README')

diff --git a/README_FILES/MULTI_INSTANCE_README b/README_FILES/MULTI_INSTANCE_README
new file mode 100644
index 0000000..7e930f2
--- /dev/null
+++ b/README_FILES/MULTI_INSTANCE_README
@@ -0,0 +1,981 @@
+MMaannaaggiinngg mmuullttiippllee PPoossttffiixx iinnssttaanncceess oonn aa ssiinnggllee hhoosstt
+
+-------------------------------------------------------------------------------
+
+OOvveerrvviieeww
+
+This document is a guide to managing multiple Postfix instances on a single
+host using the postmulti(1) instance manager. Multi-instance support is
+available with Postfix version 2.6 and later. See the postfix-wrapper(5) manual
+page for background on the instance management framework, and on how to deploy
+a custom instance manager.
+
+Topics covered in this document:
+
+  * Why multiple Postfix instances
+  * Null-client instances versus service instances
+  * Multi-instance walk-through
+  * Components of a Postfix system
+  * The default Postfix instance
+  * Instance groups
+  * Multi-instance configuration parameters
+  * Using the postmulti(1) command
+  * Credits
+
+WWhhyy mmuullttiippllee PPoossttffiixx iinnssttaanncceess
+
+Postfix is a general-purpose mail system that can be configured to serve a
+variety of needs. Examples of Postfix applications are:
+
+  * Local mail submission for shell users and system processes.
+
+  * Incoming (MX host) email from the Internet.
+
+  * Outbound mail relay for a corporate network.
+
+  * Authenticated submission for roaming users.
+
+  * Before/after content-filter mail.
+
+A single Postfix configuration can provide many or all of these services, but a
+complex interplay of settings may be required, for example with master.cf
+options overriding main.cf settings. In this document we take the view that
+multiple Postfix instances may be a simpler way to configure a multi-function
+Postfix system. With multiple Postfix instances, each instance has its own
+directories for configuration, queue and data files, but it shares all Postfix
+program and documentation files with other instances.
+
+Since there is no single right way to configure your system, we recommend that
+you choose what makes you most comfortable. If different Postfix services don't
+involve incompatible main.cf or master.cf settings, and if they can be combined
+together without complex tricks, then a single monolithic configuration may be
+the simplest approach.
+
+The purpose of multi-instance support in Postfix is not to force you to create
+multiple Postfix instances, but rather to give you a choice. Multiple instances
+give you the freedom to tune each Postfix instance to a single task that it
+does well and to combine instances into complete systems.
+
+With the introduction of the postmulti(1) utility and the reduction of the per-
+instance configuration footprint of a secondary Postfix instance to just a
+main.cf and master.cf file (other files are now in shared locations), we hope
+that multiple instances will be easier to use than ever before.
+
+NNuullll--cclliieenntt iinnssttaanncceess vveerrssuuss sseerrvviiccee iinnssttaanncceess
+
+In the multi-instance approach to configuring Postfix, the first simplification
+is with the default local-submission Postfix instance.
+
+Most UNIX systems require support for email submission with the sendmail(1)
+command so that system processes such as cron jobs can send status reports, and
+so that system users can send email with command-line utilities. Such email can
+be handled with a null-client Postfix configuration that forwards all mail to a
+central mail hub. The null client will typically either not run an SMTP
+listener at all (master_service_disable = inet), or it will listen only on the
+loopback interface (inet_interfaces = loopback-only).
+
+When implementing specialized servers for inbound Internet email, outbound
+MTAs, internal mail hubs, and so on, we recommend using a null client for local
+submission and creating single-function secondary Postfix instances to serve
+the specialized needs.
+
+    Note: usually, you need to use different "myhostname" settings when you run
+    multiple instances on the same host. Otherwise, there will be false "mail
+    loops back to myself" alarms when one instance tries to send mail into
+    another instance. Typically, the null-client instance will use the system's
+    hostname, and other instances will use their own dedicated "myhostname"
+    settings. Different names are not needed when instances send mail to each
+    other with a protocol other than SMTP, or with SMTP over a TCP port other
+    than 25 as is usual with SMTP-based content filters.
+
+MMuullttii--iinnssttaannccee wwaallkk--tthhrroouugghh
+
+Before discussing the fine details of multi-instance operation we first show
+the steps for creating a border mail server. This server has with a null-client
+Postfix instance for local submission, an input Postfix instance to receive
+mail from the Internet, plus an advanced SMTP content-filter and an output
+Postfix instance to deliver filtered email to its internal destination.
+
+SSeettttiinngg uupp tthhee nnuullll--cclliieenntt PPoossttffiixx iinnssttaannccee
+
+On a border mail hub, while mail from the Internet requires a great deal of
+scrutiny, locally submitted messages are typically limited to mail from cron
+jobs and other system services. In this regard the border MTA is not different
+from other Unix hosts in your environment. For this reason, it will submit
+locally-generated email to the internal mail hub. We start the construction of
+the border mail server with the default instance, which will be a local-
+submission null client:
+
+    /etc/postfix/main.cf:
+        # We are mta1.example.com
+        #
+        myhostname = mta1.example.com
+        mydomain = example.com
+
+        # Flat user-account namespace in example.com:
+        #
+        #   user@example.com not user@host.example.com
+        #
+        myorigin = $mydomain
+
+        # Postfix 2.6+, disable inet services, specifically disable smtpd(8)
+        #
+        master_service_disable = inet
+
+        # No local delivery:
+        #
+        mydestination =
+        local_transport = error:5.1.1 Mailbox unavailable
+        alias_database =
+        alias_maps =
+        local_recipient_maps =
+
+        # Send everything to the internal mailhub
+        #
+        relayhost = [mailhub.example.com]
+
+        # Indexed table macro:
+        # (use "hash", ... when cdb is not available)
+        #
+        default_database_type = cdb
+        indexed = ${default_database_type}:${config_directory}/
+
+        # Expose origin host of mail from "root", ...
+        #
+        smtp_generic_maps = ${indexed}generic
+
+        # Send messages addressed to "root", ... to the MTA support team
+        #
+        virtual_alias_maps = ${indexed}virtual
+
+    /etc/postfix/generic:
+        # The smarthost supports "+" addressing (recipient_delimiter = +).
+        # Mail from "root" exposes the origin host, without replies
+        # and bounces going back to the same host.
+        #
+        # On clustered MTAs this file is typically machine-built from
+        # a template file. The build process expands the template into
+        # "mtaadmin+root=mta1"
+        #
+        root        mtaadmin+root=mta1
+
+    /etc/postfix/virtual:
+        # Caretaker aliases:
+        #
+        root        mtaadmin
+        postmaster  root
+
+You would typically also add a Makefile, to automatically run postmap(1)
+commands when source files change. This Makefile also creates a "generic"
+database when none exists.
+
+    /etc/postfix/Makefile:
+        MTAADMIN=mtaadmin
+
+        all: virtual.cdb generic.cdb
+
+        generic: Makefile
+                @echo Creating $@
+                @rm -f $@.tmp
+                @printf '%s\t%s+root=%s\n' root ${MTAADMIN} `uname -n` > $@.tmp
+                @mv $@.tmp generic
+
+        %.cdb: %
+                postmap cdb:$<
+
+Construct the "virtual" and "generic" databases (the latter is created by
+running "make"), then start and test the null-client:
+
+    # cd /etc/postfix; make
+    # postfix start
+    # sendmail -i -f root -t <<EOF
+    From: root
+    To: root
+    Subject: test
+
+    testing
+    EOF
+
+The test message should be delivered the members of the "mtaadmin" address
+group (or whatever address group you choose) with the following headers:
+
+    From: mtaadmin+root=mta1@example.com
+    To: mtadmin+root=mta1@example.com
+    Subject: test
+
+SSeettttiinngg uupp tthhee ""oouuttppuutt"" PPoossttffiixx iinnssttaannccee
+
+With the null-client instance out of the way, we can create the MTA "output"
+instance that will deliver filtered mail to the inside network. We add the
+"output" instance first, because the output instance needs to be up and running
+before the input instance can be fully tested, and when the system boots, the
+"output" instance must start before the input instance. We will put the output
+and input instances into a single instance group named "mta".
+
+Just once, when adding the first secondary instance, enable multi-instance
+support in the default (null-client) instance:
+
+    # postmulti -e init
+
+Then create the output instance:
+
+    # postmulti -I postfix-out -G mta -e create
+
+The instance configuration directory defaults to /etc/postfix-out, more
+precisely, the "postfix-out" subdirectory of the parent directory of the
+default-instance configuration directory. The new instance will be created in a
+"disabled" state:
+
+    /etc/postfix-out/main.cf
+        #
+        # ... "stock" main.cf settings ...
+        #
+        multi_instance_name = postfix-out
+        queue_directory = /var/spool/postfix-out
+        data_directory = /var/lib/postfix-out
+        #
+        multi_instance_enable = no
+        master_service_disable = inet
+        authorized_submit_users =
+
+This instance has a "stock" master.cf file, and its queue and data directories,
+also named "postfix-out", will be located in the same parent directories as the
+corresponding directories of the default instance (e.g., /var/spool/postfix-out
+and /var/lib/postfix-out).
+
+While this instance is immediately safe to start, it is not yet usefully
+configured. It needs to be customized to fit the role of a post-filter re-
+injection SMTP service. Typical additions include:
+
+    /etc/postfix-out/master.cf:
+        # Replace default "smtp inet" entry with one listening on port 10026.
+        127.0.0.1:10026     inet  n       -       n       -       -       smtpd
+
+    /etc/postfix-out/main.cf
+        # ...
+
+        # Comment out if you don't use IPv6 internally
+        # inet_protocols = ipv4
+        inet_interfaces = loopback-only
+        mynetworks_style = host
+        smtpd_authorized_xforward_hosts = $mynetworks
+
+        # Don't anvil(8) control the re-injection port.
+        #
+        smtpd_client_connection_count_limit = 0
+        smtpd_client_event_limit_exceptions = $mynetworks
+
+        # Best practice when inet_interfaces is set, as this is not a
+        # "secondary IP personality" configuration.
+        #
+        smtp_bind_address = 0.0.0.0
+
+        # All header rewriting happens upstream
+        #
+        local_header_rewrite_clients =
+
+        # No local delivery on border gateway
+        #
+        mydestination =
+        alias_maps =
+        alias_database =
+        local_recipient_maps =
+        local_transport = error:5.1.1 Mailbox unavailable
+
+        # May need a recipient_delimiter for per-user transport lookups:
+        #
+        recipient_delimiter = +
+
+        # Only one (unrestricted client)
+        # With multiple instances, rarely need "-o param=value" overrides
+        # in master.cf, each instance gets its own main.cf file.
+        #
+        # Postfix 2.10 and later: specify empty smtpd_relay_restrictions.
+        smtpd_relay_restrictions =
+        smtpd_recipient_restrictions = permit_mynetworks, reject
+
+        # Tolerate occasional high latency in the  content filter.
+        #
+        smtpd_timeout = 1200s
+
+        # Best when empty, with all parent domain matches explicit.
+        #
+        parent_domain_matches_subdomains =
+
+        # Use the "relay" transport for inbound mail, and the default
+        # "smtp" transport for outbound mail (bounces, ...). The latter
+        # won't starve the former of delivery agent slots.
+        #
+        relay_domains = example.com, .example.com
+
+        # With xforward, match the input instance setting, if you
+        # want "yes", set both to "yes".
+        #
+        smtpd_client_port_logging = no
+
+        # Transport settings ...
+        # Message size limit
+        # Concurrency tuning for "relay" and "smtp" transport
+        # ...
+
+With the "output" configuration in place, enable and start the instance:
+
+    1 # postmulti -i postfix-out -x postconf -e \
+    2     "master_service_disable =" "authorized_submit_users = root"
+    3 # postmulti -i postfix-out -e enable
+    4 # postmulti -i postfix-out -p start
+
+This uses the postmulti(1) command to invoke postconf(1) in the context
+(MAIL_CONFIG=/etc/postfix-out) of the output instance.
+
+  * Lines 1-2: With "authorized_submit_users = root", the superuser can test
+    the postfix-out instance with "postmulti -i postfix-out -x sendmail -bv
+    recipient...", but otherwise local submission remains disabled.
+
+  * Lines 1-2: With "master_service_disable =", the "inet" listeners are re-
+    enabled.
+
+  * Line 3: The output instance is enabled for multi-instance start/stop.
+
+  * Line 4: The output instance is started.
+
+Test the output instance by submitting probe messages via "sendmail -bv" and
+"telnet". For production systems, in-depth configuration tests should be done
+on a lab system. The simple tests just suggested will only confirm successful
+deployment of a configuration that should already be known good.
+
+SSeettttiinngg uupp tthhee ccoonntteenntt--ffiilltteerr pprrooxxyy
+
+With the output instance ready, deploy your content-filter proxy. Most proxies
+will need their own /etc/rc* start/stop script. Some proxies, however, are
+started on demand by the Postfix spawn(8) service, in which case you need to
+add the relevant spawn(8) entry to the output instance master.cf file.
+
+Configure the proxy to listen on 127.0.0.1:10025 and to re-inject filtered
+email to 127.0.0.1:10026. Start the proxy service if necessary, then test the
+proxy via "telnet" or automated SMTP injectors. The proxy should support the
+following ESMTP features: DSN, 8BITMIME, and XFORWARD. In addition, the proxy
+should support multiple mail deliveries within an SMTP session.
+
+SSeettttiinngg uupp tthhee iinnppuutt PPoossttffiixx iinnssttaannccee
+
+The input Postfix instance receives mail from the network and sends it through
+the content filter. Now we create the input instance, also part of the "mta"
+instance group:
+
+    # postmulti -I postfix-in -G mta -e create
+
+The new instance configuration directory defaults to /etc/postfix-in, more
+precisely, the "postfix-in" subdirectory of the parent directory of the
+default-instance configuration directory. The new instance will be created in a
+"disabled" state:
+
+    /etc/postfix-in/main.cf
+        #
+        # ... "stock" main.cf settings ...
+        #
+        multi_instance_name = postfix-in
+        queue_directory = /var/spool/postfix-in
+        data_directory = /var/lib/postfix-in
+        #
+        multi_instance_enable = no
+        master_service_disable = inet
+        authorized_submit_users =
+
+As before, make appropriate changes to main.cf and master.cf to make the
+instance production ready. Consider setting "soft_bounce = yes" during the
+first few hours of deployment, so you can iron-out any unexpected "kinks".
+
+Manual testing can start with:
+
+    /etc/postfix-in/main.cf
+        # Accept only local traffic, but allow impersonation:
+        inet_interfaces = 127.0.0.1
+        smtpd_authorized_xclient_hosts = 127.0.0.1
+
+This allows you to use the Postfix-specific XCLIENT SMTP command to safely
+simulate connections from remote systems before any remote systems are able to
+connect. If the test results look good, revert the above settings to the
+required production values. Typical settings in the pre-filter input instance
+include:
+
+    /etc/postfix-in/main.cf
+        #
+        # ...
+        #
+
+        # No local delivery on border gateway
+        #
+        mydestination =
+        alias_maps =
+        alias_database =
+        local_recipient_maps =
+        local_transport = error:5.1.1 Mailbox unavailable
+
+        # Don't rewrite remote headers
+        #
+        local_header_rewrite_clients =
+
+        # All recipients of not yet filtered email go to the same filter
+    together.
+        #
+        # With multiple instances, the content-filter is specified
+        # via transport settings not the "content_filter" transport
+        # switch override! Here the filter listens on local port 10025.
+        #
+        # If you need to route some users or recipient domains directly to the
+        # output instance bypassing the filter, just define a transport table
+        # with suitable entries.
+        #
+        default_transport = smtp:[127.0.0.1]:10025
+        relay_transport = $default_transport
+        virtual_transport = $default_transport
+        transport_maps =
+
+        # Pass original client log information through the filter.
+        #
+        smtp_send_xforward_command = yes
+
+        # Avoid splitting the envelope and scanning messages multiple times.
+        # Match the re-injection server's recipient limit.
+        #
+        smtp_destination_recipient_limit = 1000
+
+        # Tolerate occasional high latency in the content filter.
+        #
+        smtp_data_done_timeout = 1200s
+
+        # With xforward, match the output instance setting, if you
+        # want "yes", set both to "yes".
+        #
+        smtpd_client_port_logging = no
+
+        # ... Lots of settings for inbound MX host ...
+
+With the "input" instance configured, enable and start it:
+
+    # postmulti -i postfix-in -x postconf -e \
+        "master_service_disable =" "authorized_submit_users = root"
+    # postmulti -i postfix-in -e enable
+    # postmulti -i postfix-in -p start
+
+That's it. You now have a 3-instance configuration. A null-client sending all
+locally submitted mail to the internal mail hub and a pair of "mta" instances
+that receive mail from the Internet, pass it through a content-filter, and then
+deliver it to the internal destination.
+
+Running "postfix start" or "postfix stop" will now start/stop all three Postfix
+instances. You can use "postfix -c /config/path start" to start just one
+instance, or use the instance name (or instance group name) via postmulti(1):
+
+    # postmulti -i - -p stop
+    # postmulti -g mta -p status
+    # postmulti -i postfix-out -p flush
+    # postmulti -i postfix-in -p reload
+    # ...
+
+This example ends the multi-instance "walk through". The remainder of this
+document provides background information on Postfix multi-instance support
+features and options.
+
+CCoommppoonneennttss ooff aa PPoossttffiixx ssyysstteemm
+
+A Postfix system consists of the following components:
+
+Shared among all instances:
+
+  * Command-line utilities for administrators and users installed in
+    $command_directory, $sendmail_path, $mailq_path and $newaliases_path.
+
+  * Daemon executables, and run-time support files installed in
+    $daemon_directory.
+
+  * Bundled documentation, installed in $html_directory, $manpage_directory and
+    $readme_directory.
+
+  * Entries in /etc/passwd and /etc/group for the $mail_owner user and
+    $setgid_group group. The $mail_owner user provides the mail system with a
+    protected (non-root) execution context. The $setgid_group group is used
+    exclusively to support the setgid postdrop(1) and postqueue(1) utilities
+    (it mmuusstt nnoott be the primary group or secondary group of any users,
+    including the $mail_owner user).
+
+Private to each instance:
+
+  * The main.cf, master.cf (and other optional) configuration files in
+    $config_directory.
+
+  * The maildrop, incoming, active, deferred and hold queues in
+    $queue_directory (which contains additional directories needed by Postfix,
+    and which optionally doubles as a chroot jail for Postfix daemon
+    processes).
+
+  * Various caches (TLS session, address verification, ...) in $data_directory.
+
+The Postfix configuration parameters mentioned above are collectively referred
+to as "installation parameters". Their default values are set when the Postfix
+software is built from source, and all but one may be optionally set to a non-
+default value via the main.cf file. The one parameter that (catch-22) cannot be
+set in main.cf is $config_directory, as this defines the location of the
+main.cf file itself.
+
+Though config_directory cannot be set in main.cf, postfix(1) and most of the
+other command-line Postfix utilities allow you to specify a non-default
+configuration directory via a command line option (typically --cc) or via the
+MAIL_CONFIG environment variable. In this way, it is possible to have multiple
+configuration directories on the same machine, and to have multiple running
+master(8) daemons each with its own configuration files, queue directory and
+data directory.
+
+These multiple running copies of master(8) share the base Postfix software.
+They do not (and cannot) share their configuration directories, queue
+directories or data directories.
+
+Each combination of configuration directory, together with the queue directory
+and data directory (specified in the corresponding main.cf file) make up a
+Postfix iinnssttaannccee.
+
+TThhee ddeeffaauulltt PPoossttffiixx iinnssttaannccee
+
+One Postfix instance is special: this is the instance whose configuration
+directory is the default one compiled into the Postfix utilities. The location
+of the default configuration directory is typically /etc/postfix, and can be
+queried via the "postconf -d config_directory" command. We call the instance
+with this configuration directory the "default instance".
+
+The default instance is responsible for local mail submission. The setgid
+postdrop(1) utility is used by the sendmail(1) local submission program to
+spool messages into the mmaaiillddrroopp sub-directory of the queue directory of the
+default instance.
+
+Even in the rare case when "sendmail -C" is used to submit local mail into a
+non-default Postfix instance, for security reasons, postdrop(1) will consult
+the default main.cf file to check the validity of the requested non-default
+configuration directory.
+
+So, while in most other respects, all instances are equal, the default instance
+is "more equal than others". You may choose to create additional instances, but
+you must have at least the default instance, with its configuration directory
+in the default compiled-in location.
+
+IInnssttaannccee ggrroouuppss
+
+The postmulti(1) multi-instance manager supports the notion of an instance
+"group". Typically, the member instances of an instance group constitute a
+logical service, and are expected to all be running or all be stopped.
+
+In many cases a single Postfix instance will be a complete logical "service".
+You should define such instances as stand-alone instances that are not members
+of any instance "group". The null-client instance is an example of a non-group
+instance.
+
+When a logical service consists of multiple Postfix instances, often a pair of
+pre-filter and post-filter instances with a content filter proxy between them,
+the related instances should be members of a single instance group (however,
+the content filter usually has its own start/stop procedure that is separate
+from any Postfix instance).
+
+The default instance main.cf file's $multi_instance_directories configuration
+parameter lists the configuration directories of all secondary (non-default)
+instances. Together with the default instance, these secondary instances are
+managed by the multi-instance manager. Instances are started in the order
+listed, and stopped in the opposite order. For instances that are members of a
+service "group", you should arrange to start the service back-to-front, with
+the output stages started and ready to receive mail before the input stages are
+started.
+
+MMuullttii--iinnssttaannccee ccoonnffiigguurraattiioonn ppaarraammeetteerrss
+
+multi_instance_wrapper
+    This default-instance configuration parameter must be set to a suitable
+    multi-instance manager's "wrapper" program that controls the starting,
+    stopping, etc. of a multi-instance Postfix system. To use the postmulti(1)
+    manager described in this document, this parameter should be set with the
+    "postmulti -e init" command.
+
+multi_instance_directories
+    This default-instance configuration parameter specifies an optional list of
+    the secondary instances controlled via the multi-instance manager.
+    Instances are listed in their "start" order, with the default instance
+    always started first (if enabled). If $multi_instance_directories is left
+    empty, the postfix(1) command runs with multi-instance support turned off,
+    and none of the multi_instance_ configuration parameters will have any
+    effect.
+
+    Do not assign a non-empty list of secondary instance configuration
+    directories to multi_instance_directories until you have configured a
+    suitable multi_instance_wrapper setting! This is best accomplished via the
+    "postmulti -e init" command.
+
+multi_instance_name
+    Each Postfix instance may be assigned a distinct name (with "postfix -
+    e create/import/assign -I name..."). This name can be used with the
+    postmulti(1) command-line utility to perform tasks on the instance by name
+    (rather than the full pathname of its configuration directory). Choose a
+    name that concisely captures the role of the instance (it must start with
+    "postfix-"). It is an error for two instances to have the same
+    $multi_instance_name. You can leave an instance "nameless" by leaving this
+    parameter at the default empty setting.
+
+    To avoid confusion in your logs, if you don't assign each secondary
+    instance a non-empty (distinct) $multi_instance_name, you should make sure
+    that the $syslog_name setting is different for each instance. The
+    $syslog_name parameter defaults to $multi_instance_name when the latter is
+    non-empty. If at all possible, the syslog_name should start with "postfix-
+    ", this helps log parsers to identify log entries from secondary Postfix
+    instances.
+
+multi_instance_group
+    Each Postfix instance may be assigned an "instance group" name (with
+    "postfix -e create/import/assign -G name..."). The default (empty) value of
+    multi_instance_group parameter indicates a stand-alone instance that is not
+    part of any group. The group name can be used with the postmulti(1)
+    command-line utility to perform a task on the members of a group by name.
+    Choose a single-word group name that concisely captures the role of the
+    group.
+
+multi_instance_enable
+    This parameter controls whether a Postfix instance will be started by a
+    Postfix multi-instance manager. The default value is "no". The instance can
+    be started explicitly with "postfix -c /path/to/config/directory"; this is
+    useful for testing.
+
+    When an instance is disabled, the postfix(1) "start" command is replaced by
+    "check".
+
+    Some postfix(1) commands (such as "stop", "flush", ...) require a running
+    Postfix instance, and skip instances that are disabled.
+
+    Other postfix(1) commands (such as "status", "set-permissions", "upgrade-
+    configuration", ...) do not require a running Postfix system, and apply to
+    all instances whether enabled or not.
+
+The postmulti(1) utility can be used to create (or destroy) instances. It can
+also be used to "import" or "deport" existing instances into or from the list
+of managed instances. When using postmulti(1) to manage instances, the above
+configuration parameters are managed for you automatically. See below.
+
+UUssiinngg tthhee ppoossttmmuullttii((11)) ccoommmmaanndd
+
+  * Initializing the multi-instance manager
+  * Listing managed instances
+  * Starting or stopping a multi-instance system
+  * Ad-hoc multi-instance operations
+  * Creating a new Postfix instance
+  * Destroying a Postfix instance
+  * Importing an existing Postfix instance
+  * Deporting a managed Postfix instance
+  * Assigning a new name or group name
+  * Enabling/disabling managed instances
+
+IInniittiiaalliizziinngg tthhee mmuullttii--iinnssttaannccee mmaannaaggeerr
+
+Before postmulti(1) is used for the first time, you must install it as the
+multi_instance_wrapper for your Postfix system and enable multi-instance
+operation of the default Postfix instance. You can then proceed to add new or
+existing instances to the multi-instance configuration. This initial
+installation is accomplished as follows:
+
+        # postmulti -e init
+
+This updates the default instance main.cf file as follows:
+
+        # Use postmulti(1) as a postfix-wrapper(5)
+        #
+        multi_instance_wrapper = ${command_directory}/postmulti -p --
+
+        # Configure the default instance to start when in multi-instance mode
+        #
+        multi_instance_enable = yes
+
+If you prefer, you can make these changes by editing the default main.cf
+directly, or by using "postconf -e".
+
+LLiissttiinngg mmaannaaggeedd iinnssttaanncceess
+
+The list of managed instances consists of the default instance and the
+additional instances whose configuration directories are listed (in start
+order) under the multi_instance_directories parameter of the default main.cf
+configuration file.
+
+You can list selected instances, groups of instances or all instances by
+specifying only the instance matching options with the "-l" option. The "-a"
+option is assumed if no other instance selection options are specified (this
+behavior changes with the "-e" option). As a special case, even if it has an
+explicit name, the default instance can always be selected via "-i -".
+
+    # postmulti -l -a
+    # postmulti -l -g a_group
+    # postmulti -l -i an_instance
+
+The output is one line per instance (in "postfix start" order):
+
+     _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
+    |nnaammee   |ggrroouupp|eennaabblleedd|ccoonnffiigg__ddiirreeccttoorryy    |
+    |_ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+    |-      |-    |yes    |/etc/postfix        |
+    |_ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+    |mta-out|mta  |yes    |/etc/postfix/mta-out|
+    |_ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+    |mta-in |mta  |yes    |/etc/postfix-mta-in |
+    |_ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+    |msa-out|msa  |yes    |/etc/postfix-msa-out|
+    |_ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+    |msa-in |msa  |yes    |/etc/postfix-msa-in |
+    |_ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+    |test   |-    |no     |/etc/postfix-test   |
+    |_ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
+
+The first line showing the column headings is not part of the output. When
+either the instance name or the instance group is not set, it is shown as a "-
+".
+
+When selecting an existing instance via the "-i" option, you can always use the
+full pathname of its configuration directory instead of the instance (short)
+name. This is the only way to select a non-default nameless instance. The
+default instance can be selected via "-i -", whether it has a name or not.
+
+To list instances in reverse start order, include the "-R" option together with
+the instance selection options.
+
+SSttaarrttiinngg oorr ssttooppppiinngg aa mmuullttii--iinnssttaannccee ssyysstteemm
+
+To start, stop, reload, etc. the complete (already configured as above) multi-
+instance system just use postfix(1) as you would with a single-instance system.
+The Postfix multi-instance wrapper framework insulates Postfix init.d start and
+package upgrade scripts from the details of multi-instance management!
+
+The --pp option of postmulti(1) turns on postfix(1) compatibility mode. With this
+option the remaining arguments are exactly those supported by postfix(1), but
+commands are applied to all instances or all enabled instances as appropriate.
+As described above, this switch is required when using postmulti(1) as the
+multi_instance_wrapper.
+
+If you want to specify a subset of instances by name, or group name, or run
+arbitrary commands (not just "postfix stop/start/etc. in the context
+(MAIL_CONFIG environment variable setting) of a particular instance or group of
+instances, then you can use the instance-aware postmulti(1) utility directly.
+
+AAdd--hhoocc mmuullttii--iinnssttaannccee ooppeerraattiioonnss
+
+The postmulti(1) command can be used by the administrator to run arbitrary
+commands in the context of one or more Postfix instances. The most common use-
+case is stopping or starting a group of Postfix instances:
+
+    # postmulti -g mygroup -p start
+    # postmulti -g mygroup -p flush
+    # postmulti -g mygroup -p reload
+    # postmulti -g mygroup -p status
+    # postmulti -g mygroup -p stop
+    # postmulti -g mygroup -p upgrade-configuration
+
+The --pp option is essentially a short-hand for a leading ppoossttffiixx command
+argument, but with appropriate additional options turned on depending on the
+first argument. In the case of "start", disabled instances are "checked"
+(postfix check) rather than simply skipped.
+
+The resulting command is executed for each candidate instance with the
+MMAAIILL__CCOONNFFIIGG environment variable set to the configuration directory of the
+corresponding Postfix instance.
+
+The postmulti(1) utility is able to launch commands other than postfix(1), Use
+the --xx option to ask postmulti to execute an ad-hoc command for all instances,
+a group of instances, or just one instance. With ad-hoc commands the
+multi_instance_enable parameter is ignored: the command is unconditionally
+executed for the instances selected via -a, -g or -i. In addition to
+MAIL_CONFIG, the following instance parameters are exported into the command
+environment:
+
+    command_directory=$command_directory
+    daemon_directory=$daemon_directory
+    config_directory=$config_directory
+    queue_directory=$queue_directory
+    data_directory=$data_directory
+    multi_instance_name=$multi_instance_name
+    multi_instance_group=$multi_instance_group
+    multi_instance_enable=$multi_instance_enable
+
+The config_directory setting is of course the same as MAIL_CONFIG, and is
+arguably redundant, but leaving it in is less surprising. If you want to skip
+disabled instances, just check multi_instance_enable environment variable and
+exit if it is set to "no".
+
+The ability to run ad-hoc commands opens up a wealth of additional
+possibilities:
+
+  * Specify an instance by name rather than configuration directory when using
+    sendmail(1) to send a verification probe:
+
+        $ postmulti -i postfix-myinst -x sendmail -bv test@example.net
+
+  * Display non-default main.cf settings of all Postfix instances. This uses an
+    inline shell script to package together multiple shell commands to execute
+    for each instance:
+
+        $ postmulti -x sh -c 'echo "-- $MAIL_CONFIG"; postconf -n'
+
+  * Put all mail in enabled member instances of a group on hold:
+
+        # postmulti -g group_name -x \
+            sh -c 'test $multi_instance_enable = yes && postsuper -h ALL'
+
+  * Show top 10 domains in the deferred queue of all instances:
+
+        # postmulti -x sh -c 'echo "-- $MAIL_CONFIG"; qshape deferred | head -
+        12'
+
+CCrreeaattiinngg aa nneeww PPoossttffiixx iinnssttaannccee
+
+The postmulti(1) command can be used to create additional Postfix instances.
+New instances are created with local submission and all "inet" services
+disabled via the following non-default parameter settings in the main.cf file:
+
+    authorized_submit_users =
+    master_service_disable = inet
+
+The above settings ensure that new instances are safe to start immediately:
+they will not conflict with inet listeners in existing Postfix instances. They
+will also not accept any mail until they are fully configured, at which point
+you can do away with one or both of the above safety measures.
+
+The postmulti(1) command encourages a preferred way of organizing the
+configuration directories, queue directories and data directories of non-
+default instances. If the default instance settings are:
+
+    config_directory = /conf-path/postfix
+    queue_directory = /queue-path/postfix
+    data_directory = /data-path/postfix
+
+A newly-created instance named postfix-myinst will by default have:
+
+    multi_instance_enable = no
+    multi_instance_name = postfix-myinst
+    config_directory = /conf-path/postfix-myinst
+    queue_directory = /queue-path/postfix-myinst
+    data_directory = /data-path/postfix-myinst
+
+You can override any of these defaults when creating the instance, but unless
+you want to spread instance queue directories over multiple file-systems, use
+the default naming strategy. It keeps the multiple instances organized in a
+uniform, predictable fashion.
+
+When specifying the instance name later, you can refer to it either as
+"postfix-myinst", or via the full path of the configuration directory.
+
+To create a new instance just use the --ee ccrreeaattee option:
+
+    # postmulti -I postfix-myinst -e create
+
+If the new instance is to belong to a group of related instances that implement
+a single logical service, assign it to a group:
+
+    # postmulti -I postfix-myinst -G mygroup -e create
+
+If you want to override the conventional values of the instance installation
+parameters, specify their values on the command-line:
+
+    # postmulti [-I postfix-myinst] [-G mygroup] -e create \
+            "config_directory = /path/to/config_directory" \
+            "queue_directory = /path/to/queue_directory" \
+            "data_directory = /path/to/data_directory"
+
+A note on the --II and --GG options above. These are always used to assign a name
+or group name to an instance, while the --ii and --gg options always select
+existing instances. By default, the configuration directories of newly managed
+instances are appended to the instance list. You can use the "-i" or "-g" or "-
+a" options to insert the new instance before the specified instance or group,
+or at the beginning of the instance list (multi_instance_directories parameter
+of the default instance).
+
+If you do specify a name (use "-I" with a name that is not "-") for the new
+instance, you may omit any of the 3 instance installation parameters whose
+instance-name based value is acceptable. Otherwise, all three instance
+installation parameters are required. You should set the "syslog_name"
+explicitly in the main.cf file of a "nameless" instance, in order to avoid
+confusion in the mail logs when multiple instances are in use.
+
+DDeessttrrooyyiinngg aa PPoossttffiixx iinnssttaannccee
+
+If you no longer need an instance, you can destroy it via:
+
+    # postmulti -i postfix-myinst -p stop
+    # postmulti -i postfix-myinst -e disable
+    # postmulti -i postfix-myinst -e destroy
+
+The instance must be stopped, disabled and have no queued messages. This is
+expected to fully delete a just created instance that has never been used. If
+the instance is not freshly created, files added after the instance was created
+will remain in the configuration, queue or data directories, in which case the
+corresponding directory may not be fully removed and a warning to that effect
+will be displayed. You can complete the destruction of the instance manually by
+removing any unwanted remnants of the instance-specific "private" directories.
+
+IImmppoorrttiinngg aann eexxiissttiinngg PPoossttffiixx iinnssttaannccee
+
+If you already have an existing secondary Postfix instance that is not yet
+managed via postmulti(1), you can "import" it into the list of managed
+instances. If your instance is already using the default configuration
+directory naming scheme, just specify the corresponding instance name (the
+multi_instance_name parameter in its configuration file will be adjusted to
+match this name if necessary):
+
+    # postmulti -I postfix-myinst [-G mygroup] -e import
+
+Otherwise, you must specify the location of its configuration directory:
+
+    # postmulti [-I postfix-myinst] [-G mygroup] -e import \
+            "config_directory = /path/of/config_directory"
+
+When the instance is imported, you can assign a name or a group. As with
+"create", you can control the placement of the new instance in the start order
+by using "-i", "-g" or "-a" to prepend before the selected instance or
+instances.
+
+An imported instance is usually not multi-instance "enabled", unless it was
+part of a multi-instance configuration at an earlier time. If it is fully
+configured and ready to run, don't forget to enable it and if necessary start
+it. When other enabled instances are already running, new instances need to be
+started individually when they are first created or imported.
+
+To find out what instances are running, use:
+
+    # postfix status
+
+DDeeppoorrttiinngg aa mmaannaaggeedd PPoossttffiixx iinnssttaannccee
+
+You can "deport" an existing instance from the list of managed instances. This
+does not destroy the instance, rather the instance just becomes a stand-alone
+Postfix instance not registered with the multi-instance manager. postmulti(1)
+will refuse to "deport" an instance that is not stopped and disabled.
+
+    # postmulti -i postfix-myinst -p stop
+    # postmulti -i postfix-myinst -e disable
+    # postmulti -i postfix-myinst -e deport
+
+AAssssiiggnniinngg aa nneeww nnaammee oorr ggrroouupp nnaammee
+
+You can assign a new name or new group to a managed instance. Use "-" as the
+new value to assign the instance to no group or make it nameless. To specify a
+nameless secondary instance use the configuration directory path instead of the
+old name:
+
+    # postmulti -i postfix-old [-I postfix-new] [-G newgroup] -e assign
+
+EEnnaabblliinngg//ddiissaabblliinngg mmaannaaggeedd iinnssttaanncceess
+
+You can enable or disable a managed instance. As documented in postfix-wrapper
+(5), disabled instances are skipped with actions that start, stop or control
+running Postfix instances.
+
+    # postmulti -i postfix-myinst -e enable
+    # postmulti -i postfix-myinst -e disable
+
+CCrreeddiittss
+
+Wietse Venema created Postfix, designed and implemented the multi-instance
+wrapper framework and provided design feedback that made the postmulti(1)
+utility much more general and useful than originally envisioned.
+
+The postmulti(1) utility was developed by Victor Duchovni of Morgan Stanley,
+who also wrote the initial version of this document.
+
-- 
cgit v1.2.3