diff options
Diffstat (limited to 'README_FILES/MULTI_INSTANCE_README')
| -rw-r--r-- | README_FILES/MULTI_INSTANCE_README | 981 |
1 files changed, 981 insertions, 0 deletions
diff --git a/README_FILES/MULTI_INSTANCE_README b/README_FILES/MULTI_INSTANCE_README new file mode 100644 index 0000000..1f261f6 --- /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 to 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. + |