From 5e61585d76ae77fd5e9e96ebabb57afa4d74880d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 14:06:34 +0200 Subject: Adding upstream version 3.5.24. Signed-off-by: Daniel Baumann --- proto/MULTI_INSTANCE_README.html | 1274 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 1274 insertions(+) create mode 100644 proto/MULTI_INSTANCE_README.html (limited to 'proto/MULTI_INSTANCE_README.html') diff --git a/proto/MULTI_INSTANCE_README.html b/proto/MULTI_INSTANCE_README.html new file mode 100644 index 0000000..a2574df --- /dev/null +++ b/proto/MULTI_INSTANCE_README.html @@ -0,0 +1,1274 @@ + + + + + + +Managing multiple Postfix instances on a single host + + + + + + + +

Managing +multiple Postfix instances on a single host

+ +
+ +

Overview

+ +

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

+ +

Postfix is a general-purpose mail system that can be configured +to serve a variety of needs. Examples of Postfix applications are:

+ + + +

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.

+ +

Null-client instances versus service instances

+ +

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.

+ +
+ +

Multi-instance walk-through

+ +

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.

+ +

Setting up the null-client Postfix instance

+ +

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
+
+
+ +

Setting up the "output" Postfix instance

+ +

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.

+ + + +

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.

+ +

Setting up the content-filter proxy

+ +

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.

+ +

Setting up the input Postfix instance

+ +

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.

+ +

Components of a Postfix system

+ +

A Postfix system consists of the following components:

+ +

Shared among all instances:

+ + + +

Private to each instance:

+ + + +

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 +-c) 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 instance.

+ +

The default Postfix instance

+ +

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 maildrop 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.

+ +

Instance groups

+ +

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.

+ +

Multi-instance configuration parameters

+ +
+ +
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.

+ +

Using the postmulti(1) command

+ + + +

Initializing the multi-instance manager

+ +

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".

+ +

Listing managed instances

+ +

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): +

+ +
+ + + + + + +
name group enabled config_directory
- - 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.

+ +

Starting or stopping a multi-instance system +

+ +

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 -p 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.

+ +

Ad-hoc multi-instance operations

+ +

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 -p option is essentially a short-hand for a leading +postfix 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 MAIL_CONFIG 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 -x 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:

+ + + +

Creating a new Postfix instance

+ +

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 -e create 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 -I and -G options above. These are always +used to assign a name or group name to an instance, while the -i +and -g 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.

+ +

Destroying a Postfix instance

+ +

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.

+ +

Importing an existing Postfix instance

+ +

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
+
+
+ +

Deporting a managed Postfix instance

+ +

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
+
+
+ +

Assigning a new name or group name

+ +

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
+
+
+ +

Enabling/disabling managed instances

+ +

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
+
+
+ +

Credits

+ +

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