<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>Managing multiple Postfix instances on a single host</title> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> </head> <body> <h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Managing multiple Postfix instances on a single host</h1> <hr> <h2>Overview </h2> <p> This document is a guide to managing multiple Postfix instances on a single host using the <a href="postmulti.1.html">postmulti(1)</a> instance manager. Multi-instance support is available with Postfix version 2.6 and later. See the <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a> manual page for background on the instance management framework, and on how to deploy a custom instance manager. </p> <p> Topics covered in this document: </p> <ul> <li><a href="#why"> Why multiple Postfix instances </a> <li><a href="#split"> Null-client instances versus service instances </a> <li><a href="#quick"> Multi-instance walk-through </a> <li><a href="#parts"> Components of a Postfix system </a> <li><a href="#default"> The default Postfix instance </a> <li><a href="#group"> Instance groups </a> <li><a href="#params"> Multi-instance configuration parameters </a> <li><a href="#how"> Using the postmulti(1) command </a> <li><a href="#credits"> Credits </a> </ul> <h2><a name="why"> Why multiple Postfix instances </a></h2> <p> Postfix is a general-purpose mail system that can be configured to serve a variety of needs. Examples of Postfix applications are: </p> <ul> <li><p> Local mail submission for shell users and system processes. </p> <li><p> Incoming (MX host) email from the Internet. </p> <li><p> Outbound mail relay for a corporate network. </p> <li><p> Authenticated submission for roaming users. </p> <li><p> Before/after content-filter mail. </p> </ul> <p> A single Postfix configuration can provide many or all of these services, but a complex interplay of settings may be required, for example with <a href="master.5.html">master.cf</a> options overriding <a href="postconf.5.html">main.cf</a> 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. </p> <p> 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 <a href="postconf.5.html">main.cf</a> or <a href="master.5.html">master.cf</a> settings, and if they can be combined together without complex tricks, then a single monolithic configuration may be the simplest approach. </p> <p> 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. </p> <p> With the introduction of the <a href="postmulti.1.html">postmulti(1)</a> utility and the reduction of the per-instance configuration footprint of a secondary Postfix instance to just a <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> file (other files are now in shared locations), we hope that multiple instances will be easier to use than ever before. </p> <h2><a name="split"> Null-client instances versus service instances </a></h2> <p> In the multi-instance approach to configuring Postfix, the first simplification is with the default local-submission Postfix instance. </p> <p> Most UNIX systems require support for email submission with the <a href="sendmail.1.html">sendmail(1)</a> 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 <a href="STANDARD_CONFIGURATION_README.html#null_client">null-client</a> Postfix configuration that forwards all mail to a central mail hub. The null client will typically either not run an SMTP listener at all (<a href="postconf.5.html#master_service_disable">master_service_disable</a> = inet), or it will listen only on the loopback interface (<a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = loopback-only). </p> <p> 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. </p> <blockquote> <p> Note: usually, you need to use different "<a href="postconf.5.html#myhostname">myhostname</a>" 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 "<a href="postconf.5.html#myhostname">myhostname</a>" 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. </p> </blockquote> <h2><a name="quick"> Multi-instance walk-through </a></h2> <p> 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 <a href="FILTER_README.html#advanced_filter">advanced</a> SMTP content-filter and an output Postfix instance to deliver filtered email to its internal destination. </p> <h3>Setting up the null-client Postfix instance </h3> <p> 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 <a href="#default_instance">default</a> instance, which will be a local-submission <a href="STANDARD_CONFIGURATION_README.html#null_client">null client</a>: </p> <blockquote> <pre> /etc/postfix/<a href="postconf.5.html">main.cf</a>: # We are mta1.example.com # <a href="postconf.5.html#myhostname">myhostname</a> = mta1.example.com <a href="postconf.5.html#mydomain">mydomain</a> = example.com # Flat user-account namespace in example.com: # # user@example.com not user@host.example.com # <a href="postconf.5.html#myorigin">myorigin</a> = $<a href="postconf.5.html#mydomain">mydomain</a> # Postfix 2.6+, disable inet services, specifically disable <a href="smtpd.8.html">smtpd(8)</a> # <a href="postconf.5.html#master_service_disable">master_service_disable</a> = inet # No local delivery: # <a href="postconf.5.html#mydestination">mydestination</a> = <a href="postconf.5.html#local_transport">local_transport</a> = <a href="error.8.html">error</a>:5.1.1 Mailbox unavailable <a href="postconf.5.html#alias_database">alias_database</a> = <a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> = # Send everything to the internal mailhub # <a href="postconf.5.html#relayhost">relayhost</a> = [mailhub.example.com] # Indexed table macro: # (use "hash", ... when <a href="CDB_README.html">cdb</a> is not available) # <a href="postconf.5.html#default_database_type">default_database_type</a> = cdb indexed = ${<a href="postconf.5.html#default_database_type">default_database_type</a>}:${<a href="postconf.5.html#config_directory">config_directory</a>}/ # Expose origin host of mail from "root", ... # <a href="postconf.5.html#smtp_generic_maps">smtp_generic_maps</a> = ${indexed}generic # Send messages addressed to "root", ... to the MTA support team # <a href="postconf.5.html#virtual_alias_maps">virtual_alias_maps</a> = ${indexed}virtual /etc/postfix/generic: # The smarthost supports "+" addressing (<a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> = +). # 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 </pre> </blockquote> <p> You would typically also add a Makefile, to automatically run <a href="postmap.1.html">postmap(1)</a> commands when source files change. This Makefile also creates a "generic" database when none exists. </p> <blockquote> <pre> /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 %.<a href="CDB_README.html">cdb</a>: % postmap <a href="CDB_README.html">cdb</a>:$< </pre> </blockquote> <p> Construct the "virtual" and "generic" databases (the latter is created by running "make"), then start and test the null-client: </p> <blockquote> <pre> # cd /etc/postfix; make # postfix start # sendmail -i -f root -t <<EOF From: root To: root Subject: test testing EOF </pre> </blockquote> <p> The test message should be delivered the members of the "mtaadmin" address group (or whatever address group you choose) with the following headers: </p> <blockquote> <pre> From: mtaadmin+root=mta1@example.com To: mtadmin+root=mta1@example.com Subject: test </pre> </blockquote> <h3>Setting up the "output" Postfix instance </h3> <p> 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". </p> <p> Just once, when adding the first secondary instance, enable multi-instance support in the default (null-client) instance: </p> <blockquote> <pre> # postmulti -e init </pre> </blockquote> <p> Then create the output instance: <p> <blockquote> <pre> # postmulti -I postfix-out -G mta -e create </pre> </blockquote> <p> 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: </p> <blockquote> <pre> /etc/postfix-out/<a href="postconf.5.html">main.cf</a> # # ... "stock" <a href="postconf.5.html">main.cf</a> settings ... # <a href="postconf.5.html#multi_instance_name">multi_instance_name</a> = postfix-out <a href="postconf.5.html#queue_directory">queue_directory</a> = /var/spool/postfix-out <a href="postconf.5.html#data_directory">data_directory</a> = /var/lib/postfix-out # <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no <a href="postconf.5.html#master_service_disable">master_service_disable</a> = inet <a href="postconf.5.html#authorized_submit_users">authorized_submit_users</a> = </pre> </blockquote> <p> This instance has a "stock" <a href="master.5.html">master.cf</a> 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). </p> <p> 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: </p> <blockquote> <pre> /etc/postfix-out/<a href="master.5.html">master.cf</a>: # Replace default "smtp inet" entry with one listening on port 10026. 127.0.0.1:10026 inet n - n - - smtpd /etc/postfix-out/<a href="postconf.5.html">main.cf</a> # ... # Comment out if you don't use IPv6 internally # <a href="postconf.5.html#inet_protocols">inet_protocols</a> = ipv4 <a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = loopback-only <a href="postconf.5.html#mynetworks_style">mynetworks_style</a> = host <a href="postconf.5.html#smtpd_authorized_xforward_hosts">smtpd_authorized_xforward_hosts</a> = $<a href="postconf.5.html#mynetworks">mynetworks</a> # Don't <a href="anvil.8.html">anvil(8)</a> control the re-injection port. # <a href="postconf.5.html#smtpd_client_connection_count_limit">smtpd_client_connection_count_limit</a> = 0 <a href="postconf.5.html#smtpd_client_event_limit_exceptions">smtpd_client_event_limit_exceptions</a> = $<a href="postconf.5.html#mynetworks">mynetworks</a> # Best practice when <a href="postconf.5.html#inet_interfaces">inet_interfaces</a> is set, as this is not a # "secondary IP personality" configuration. # <a href="postconf.5.html#smtp_bind_address">smtp_bind_address</a> = 0.0.0.0 # All header rewriting happens upstream # <a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> = # No local delivery on border gateway # <a href="postconf.5.html#mydestination">mydestination</a> = <a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="postconf.5.html#alias_database">alias_database</a> = <a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> = <a href="postconf.5.html#local_transport">local_transport</a> = <a href="error.8.html">error</a>:5.1.1 Mailbox unavailable # May need a <a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> for per-user transport lookups: # <a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> = + # Only one (unrestricted client) # With multiple instances, rarely need "-o param=value" overrides # in <a href="master.5.html">master.cf</a>, each instance gets its own <a href="postconf.5.html">main.cf</a> file. # <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> = <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>, reject # Tolerate occasional high latency in the content filter. # <a href="postconf.5.html#smtpd_timeout">smtpd_timeout</a> = 1200s # Best when empty, with all parent domain matches explicit. # <a href="postconf.5.html#parent_domain_matches_subdomains">parent_domain_matches_subdomains</a> = # 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. # <a href="postconf.5.html#relay_domains">relay_domains</a> = example.com, .example.com # With xforward, match the input instance setting, if you # want "yes", set both to "yes". # <a href="postconf.5.html#smtpd_client_port_logging">smtpd_client_port_logging</a> = no # Transport settings ... # Message size limit # Concurrency tuning for "relay" and "smtp" transport # ... </pre> </blockquote> <p> With the "output" configuration in place, enable and start the instance: </p> <blockquote> <pre> 1 # postmulti -i postfix-out -x postconf -e \ 2 "<a href="postconf.5.html#master_service_disable">master_service_disable</a> =" "<a href="postconf.5.html#authorized_submit_users">authorized_submit_users</a> = root" 3 # postmulti -i postfix-out -e enable 4 # postmulti -i postfix-out -p start </pre> </blockquote> <p> This uses the <a href="postmulti.1.html">postmulti(1)</a> command to invoke <a href="postconf.1.html">postconf(1)</a> in the context (MAIL_CONFIG=/etc/postfix-out) of the output instance. </p> <ul> <li> <p> Lines 1-2: With "<a href="postconf.5.html#authorized_submit_users">authorized_submit_users</a> = root", the superuser can test the postix-out instance with "postmulti -i postfix-out -x sendmail -bv recipient...", but otherwise local submission remains disabled. </p> <li> <p> Lines 1-2: With "<a href="postconf.5.html#master_service_disable">master_service_disable</a> =", the "inet" listeners are re-enabled. </p> <li> <p> Line 3: The output instance is enabled for multi-instance start/stop. </p> <li> <p> Line 4: The output instance is started. </p> </ul> <p> 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. </p> <h3> Setting up the content-filter proxy </h3> <p> 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 <a href="spawn.8.html">spawn(8)</a> service, in which case you need to add the relevant <a href="spawn.8.html">spawn(8)</a> entry to the output instance <a href="master.5.html">master.cf</a> file. </p> <p> 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. </p> <h3> Setting up the input Postfix instance </h3> <p> 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: </p> <blockquote> <pre> # postmulti -I postfix-in -G mta -e create </pre> </blockquote> <p> 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: </p> <blockquote> <pre> /etc/postfix-in/<a href="postconf.5.html">main.cf</a> # # ... "stock" <a href="postconf.5.html">main.cf</a> settings ... # <a href="postconf.5.html#multi_instance_name">multi_instance_name</a> = postfix-in <a href="postconf.5.html#queue_directory">queue_directory</a> = /var/spool/postfix-in <a href="postconf.5.html#data_directory">data_directory</a> = /var/lib/postfix-in # <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no <a href="postconf.5.html#master_service_disable">master_service_disable</a> = inet <a href="postconf.5.html#authorized_submit_users">authorized_submit_users</a> = </pre> </blockquote> <p> As before, make appropriate changes to <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> to make the instance production ready. Consider setting "<a href="postconf.5.html#soft_bounce">soft_bounce</a> = yes" during the first few hours of deployment, so you can iron-out any unexpected "kinks". </p> <p> Manual testing can start with: <blockquote> <pre> /etc/postfix-in/<a href="postconf.5.html">main.cf</a> # Accept only local traffic, but allow impersonation: <a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = 127.0.0.1 <a href="postconf.5.html#smtpd_authorized_xclient_hosts">smtpd_authorized_xclient_hosts</a> = 127.0.0.1 </pre> </blockquote> <p> This allows you to use the Postfix-specific <a href="XCLIENT_README.html">XCLIENT</a> 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: </p> <blockquote> <pre> /etc/postfix-in/<a href="postconf.5.html">main.cf</a> # # ... # # No local delivery on border gateway # <a href="postconf.5.html#mydestination">mydestination</a> = <a href="postconf.5.html#alias_maps">alias_maps</a> = <a href="postconf.5.html#alias_database">alias_database</a> = <a href="postconf.5.html#local_recipient_maps">local_recipient_maps</a> = <a href="postconf.5.html#local_transport">local_transport</a> = <a href="error.8.html">error</a>:5.1.1 Mailbox unavailable # Don't rewrite remote headers # <a href="postconf.5.html#local_header_rewrite_clients">local_header_rewrite_clients</a> = # 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 "<a href="postconf.5.html#content_filter">content_filter</a>" 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. # <a href="postconf.5.html#default_transport">default_transport</a> = <a href="smtp.8.html">smtp</a>:[127.0.0.1]:10025 <a href="postconf.5.html#relay_transport">relay_transport</a> = $<a href="postconf.5.html#default_transport">default_transport</a> <a href="postconf.5.html#virtual_transport">virtual_transport</a> = $<a href="postconf.5.html#default_transport">default_transport</a> <a href="postconf.5.html#transport_maps">transport_maps</a> = # Pass original client log information through the filter. # <a href="postconf.5.html#smtp_send_xforward_command">smtp_send_xforward_command</a> = yes # Avoid splitting the envelope and scanning messages multiple times. # Match the re-injection server's recipient limit. # <a href="postconf.5.html#smtp_destination_recipient_limit">smtp_destination_recipient_limit</a> = 1000 # Tolerate occasional high latency in the content filter. # <a href="postconf.5.html#smtp_data_done_timeout">smtp_data_done_timeout</a> = 1200s # With xforward, match the output instance setting, if you # want "yes", set both to "yes". # <a href="postconf.5.html#smtpd_client_port_logging">smtpd_client_port_logging</a> = no # ... Lots of settings for inbound MX host ... </pre> </blockquote> <p> With the "input" instance configured, enable and start it: </p> <blockquote> <pre> # postmulti -i postfix-in -x postconf -e \ "<a href="postconf.5.html#master_service_disable">master_service_disable</a> =" "<a href="postconf.5.html#authorized_submit_users">authorized_submit_users</a> = root" # postmulti -i postfix-in -e enable # postmulti -i postfix-in -p start </pre> </blockquote> <p> 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. </p> <p> 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 <a href="postmulti.1.html">postmulti(1)</a>: </p> <blockquote> <pre> # postmulti -i - -p stop # postmulti -g mta -p status # postmulti -i postfix-out -p flush # postmulti -i postfix-in -p reload # ... </pre> </blockquote> <p> This example ends the multi-instance "walk through". The remainder of this document provides background information on Postfix multi-instance support features and options. </p> <h2><a name="parts"> Components of a Postfix system </a></h2> <p> A Postfix system consists of the following components: </p> <p> Shared among all instances: </p> <ul> <li><p> Command-line utilities for administrators and users installed in $<a href="postconf.5.html#command_directory">command_directory</a>, $<a href="postconf.5.html#sendmail_path">sendmail_path</a>, $<a href="postconf.5.html#mailq_path">mailq_path</a> and $<a href="postconf.5.html#newaliases_path">newaliases_path</a>. </p> <li><p> Daemon executables, and run-time support files installed in $<a href="postconf.5.html#daemon_directory">daemon_directory</a>. </p> <li><p> Bundled documentation, installed in $<a href="postconf.5.html#html_directory">html_directory</a>, $<a href="postconf.5.html#manpage_directory">manpage_directory</a> and $<a href="postconf.5.html#readme_directory">readme_directory</a>. </p> <li><p> Entries in /etc/passwd and /etc/group for the $<a href="postconf.5.html#mail_owner">mail_owner</a> user and $<a href="postconf.5.html#setgid_group">setgid_group</a> group. The the $<a href="postconf.5.html#mail_owner">mail_owner</a> user provides the mail system with a protected (non-root) execution context. The $<a href="postconf.5.html#setgid_group">setgid_group</a> group is used exclusively to support the setgid <a href="postdrop.1.html">postdrop(1)</a> and <a href="postqueue.1.html">postqueue(1)</a> utilities (it <b>must not</b> be the primary group or secondary group of any users, including the $<a href="postconf.5.html#mail_owner">mail_owner</a> user). </p> </ul> <p> Private to each instance: </p> <ul> <li><p> The <a href="postconf.5.html">main.cf</a>, <a href="master.5.html">master.cf</a> (and other optional) configuration files in $<a href="postconf.5.html#config_directory">config_directory</a>. </p> <li> <p> The <a href="QSHAPE_README.html#maildrop_queue">maildrop</a>, incoming, active, deferred and <a href="QSHAPE_README.html#hold_queue">hold queues</a> in $<a href="postconf.5.html#queue_directory">queue_directory</a> (which contains additional directories needed by Postfix, and which optionally doubles as a chroot jail for Postfix daemon processes). </p> <li> <p> Various caches (TLS session, address verification, ...) in $<a href="postconf.5.html#data_directory">data_directory</a>. </p> </ul> <p> 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 <a href="postconf.5.html">main.cf</a> file. The one parameter that (catch-22) cannot be set in <a href="postconf.5.html">main.cf</a> is $<a href="postconf.5.html#config_directory">config_directory</a>, as this defines the location of the <a href="postconf.5.html">main.cf</a> file itself. </p> <p> Though <a href="postconf.5.html#config_directory">config_directory</a> cannot be set in <a href="postconf.5.html">main.cf</a>, <a href="postfix.1.html">postfix(1)</a> and most of the other command-line Postfix utilities allow you to specify a non-default configuration directory via a command line option (typically <b>-c</b>) 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 <a href="master.8.html">master(8)</a> daemons each with its own configuration files, queue directory and data directory. </p> <p> These multiple running copies of <a href="master.8.html">master(8)</a> share the base Postfix software. They do not (and cannot) share their configuration directories, queue directories or data directories. </p> <p> Each combination of configuration directory, together with the queue directory and data directory (specified in the corresponding <a href="postconf.5.html">main.cf</a> file) make up a Postfix <b>instance</b>. </p> <h2><a name="default"> The default Postfix instance </a></h2> <p> 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 <a href="postconf.5.html#config_directory">config_directory</a>" command. We call the instance with this configuration directory the "default instance". </p> <p> The default instance is responsible for local mail submission. The setgid <a href="postdrop.1.html">postdrop(1)</a> utility is used by the <a href="sendmail.1.html">sendmail(1)</a> local submission program to spool messages into the <b>maildrop</b> sub-directory of the queue directory of the default instance. </p> <p> Even in the rare case when "sendmail -C" is used to submit local mail into a non-default Postfix instance, for security reasons, <a href="postdrop.1.html">postdrop(1)</a> will consult the default <a href="postconf.5.html">main.cf</a> file to check the validity of the requested non-default configuration directory. </p> <p> 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. </p> <h2><a name="group"> Instance groups </a></h2> <p> The <a href="postmulti.1.html">postmulti(1)</a> 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. </p> <p> 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. </p> <p> 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). </p> <p> The default instance <a href="postconf.5.html">main.cf</a> file's $<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> 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. </p> <h2><a name="params"> Multi-instance configuration parameters </a></h2> <dl> <dt> <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> </dt> <dd> <p> 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 <a href="postmulti.1.html">postmulti(1)</a> manager described in this document, this parameter should be set with the "<a href="#init">postmulti -e init</a>" command. </p> </dd> <dt> <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> </dt> <dd> <p> 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 $<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> is left empty, the <a href="postfix.1.html">postfix(1)</a> command runs with multi-instance support turned off, and none of the multi_instance_ configuration parameters will have any effect. </p> <p> Do not assign a non-empty list of secondary instance configuration directories to <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> until you have configured a suitable <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> setting! This is best accomplished via the "<a href="#init">postmulti -e init</a>" command. </p> </dd> <dt> <a href="postconf.5.html#multi_instance_name">multi_instance_name</a> </dt> <dd> <p> Each Postfix instance may be assigned a distinct name (with "postfix -e create/import/assign -I <i>name</i>..."). This name can be used with the <a href="postmulti.1.html">postmulti(1)</a> 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 $<a href="postconf.5.html#multi_instance_name">multi_instance_name</a>. You can leave an instance "nameless" by leaving this parameter at the default empty setting. </p> <p> To avoid confusion in your logs, if you don't assign each secondary instance a non-empty (distinct) $<a href="postconf.5.html#multi_instance_name">multi_instance_name</a>, you should make sure that the $<a href="postconf.5.html#syslog_name">syslog_name</a> setting is different for each instance. The $<a href="postconf.5.html#syslog_name">syslog_name</a> parameter defaults to $<a href="postconf.5.html#multi_instance_name">multi_instance_name</a> when the latter is non-empty. If at all possible, the <a href="postconf.5.html#syslog_name">syslog_name</a> should start with "postfix-", this helps log parsers to identify log entries from secondary Postfix instances. </p> </dd> <dt> <a href="postconf.5.html#multi_instance_group">multi_instance_group</a> </dt> <dd> <p> Each Postfix instance may be assigned an "instance group" name (with "postfix -e create/import/assign -G <i>name</i>..."). The default (empty) value of <a href="postconf.5.html#multi_instance_group">multi_instance_group</a> parameter indicates a stand-alone instance that is not part of any group. The group name can be used with the <a href="postmulti.1.html">postmulti(1)</a> 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. </p> </dd> <dt> <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> </dt> <dd> <p> 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. </p> <p> When an instance is disabled, the <a href="postfix.1.html">postfix(1)</a> "start" command is replaced by "check". </p> <p> Some <a href="postfix.1.html">postfix(1)</a> commands (such as "stop", "flush", ...) require a running Postfix instance, and skip instances that are disabled. </p> <p> Other <a href="postfix.1.html">postfix(1)</a> commands (such as "status", "set-permissions", "upgrade-configuration", ...) do not require a running Postfix system, and apply to all instances whether enabled or not. </p> </dd> </dl> <p> The <a href="postmulti.1.html">postmulti(1)</a> 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 <a href="postmulti.1.html">postmulti(1)</a> to manage instances, the above configuration parameters are managed for you automatically. See below. </p> <h2><a name="how"> Using the postmulti(1) command </a></h2> <ul> <li><a href="#init"> Initializing the multi-instance manager </a> <li><a href="#list"> Listing managed instances </a> <li><a href="#start"> Starting or stopping a multi-instance system </a> <li><a href="#adhoc"> Ad-hoc multi-instance operations </a> <li><a href="#create"> Creating a new Postfix instance </a> <li><a href="#destroy"> Destroying a Postfix instance </a> <li><a href="#import"> Importing an existing Postfix instance </a> <li><a href="#deport"> Deporting a managed Postfix instance </a> <li><a href="#assign"> Assigning a new name or group name </a> <li><a href="#enable"> Enabling/disabling managed instances </a> </ul> <h3><a name="init"> Initializing the multi-instance manager </a></h3> <p> Before <a href="postmulti.1.html">postmulti(1)</a> is used for the first time, you must install it as the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> for your Postfix system and enable multi-instance operation of the default Postfix instance. You can then proceed to add <a href="#create">new</a> or <a href="#import">existing</a> instances to the multi-instance configuration. This initial installation is accomplished as follows: </p> <blockquote> <pre> # postmulti -e init </pre> </blockquote> <p> This updates the default instance <a href="postconf.5.html">main.cf</a> file as follows: </p> <blockquote> <pre> # Use <a href="postmulti.1.html">postmulti(1)</a> as a <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a> # <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> = ${<a href="postconf.5.html#command_directory">command_directory</a>}/postmulti -p -- # Configure the default instance to start when in multi-instance mode # <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes </pre> </blockquote> <p> If you prefer, you can make these changes by editing the default <a href="postconf.5.html">main.cf</a> directly, or by using "postconf -e". </p> <h3><a name="list"> Listing managed instances </a></h3> <p> The list of managed instances consists of the default instance and the additional instances whose configuration directories are listed (in start order) under the <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter of the default <a href="postconf.5.html">main.cf</a> configuration file. </p> <p> 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 -". </p> <blockquote> <pre> # postmulti -l -a # postmulti -l -g a_group # postmulti -l -i an_instance </pre> </blockquote> <p> The output is one line per instance (in "postfix start" order): </p> <blockquote> <table border="1"> <tr> <th align="left">name</th> <th align="left">group</th> <th align="left">enabled</th> <th align="left"><a href="postconf.5.html#config_directory">config_directory</a></th> </tr> <tr> <td>-</td> <td>-</td> <td>yes</td> <td>/etc/postfix <tr> <td>mta-out</td> <td>mta</td> <td>yes</td> <td>/etc/postfix/mta-out <tr> <td>mta-in</td> <td>mta</td> <td>yes</td> <td>/etc/postfix-mta-in <tr> <td>msa-out</td> <td>msa</td> <td>yes</td> <td>/etc/postfix-msa-out <tr> <td>msa-in</td> <td>msa</td> <td>yes</td> <td>/etc/postfix-msa-in <tr> <td>test</td> <td>-</td> <td>no</td> <td>/etc/postfix-test </table> </blockquote> <p> 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 "-". </p> <p> 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. </p> <p> To list instances in reverse start order, include the "-R" option together with the instance selection options. </p> <h3><a name="start"> Starting or stopping a multi-instance system </a></h3> <p> To start, stop, reload, etc. the complete (already configured as above) multi-instance system just use <a href="postfix.1.html">postfix(1)</a> 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! </p> <p> The <b>-p</b> option of <a href="postmulti.1.html">postmulti(1)</a> turns on <a href="postfix.1.html">postfix(1)</a> compatibility mode. With this option the remaining arguments are exactly those supported by <a href="postfix.1.html">postfix(1)</a>, but commands are applied to all instances or all enabled instances as appropriate. As described above, this switch is required when using <a href="postmulti.1.html">postmulti(1)</a> as the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a>. </p> <p> 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 <a href="postmulti.1.html">postmulti(1)</a> utility directly. </p> <h3><a name="adhoc"> Ad-hoc multi-instance operations </a></h3> <p> The <a href="postmulti.1.html">postmulti(1)</a> 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: </p> <blockquote> <pre> # 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 </pre> </blockquote> <p> The <b>-p</b> option is essentially a short-hand for a leading <b>postfix</b> 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. </p> <p> The resulting command is executed for each candidate instance with the <b>MAIL_CONFIG</b> environment variable set to the configuration directory of the corresponding Postfix instance. </p> <p> The <a href="postmulti.1.html">postmulti(1)</a> utility is able to launch commands other than <a href="postfix.1.html">postfix(1)</a>, Use the <b>-x</b> 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 <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> 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: </p> <blockquote> <pre> <a href="postconf.5.html#command_directory">command_directory</a>=$<a href="postconf.5.html#command_directory">command_directory</a> <a href="postconf.5.html#daemon_directory">daemon_directory</a>=$<a href="postconf.5.html#daemon_directory">daemon_directory</a> <a href="postconf.5.html#config_directory">config_directory</a>=$<a href="postconf.5.html#config_directory">config_directory</a> <a href="postconf.5.html#queue_directory">queue_directory</a>=$<a href="postconf.5.html#queue_directory">queue_directory</a> <a href="postconf.5.html#data_directory">data_directory</a>=$<a href="postconf.5.html#data_directory">data_directory</a> <a href="postconf.5.html#multi_instance_name">multi_instance_name</a>=$<a href="postconf.5.html#multi_instance_name">multi_instance_name</a> <a href="postconf.5.html#multi_instance_group">multi_instance_group</a>=$<a href="postconf.5.html#multi_instance_group">multi_instance_group</a> <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a>=$<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> </pre> </blockquote> <p> The <a href="postconf.5.html#config_directory">config_directory</a> 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 <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> environment variable and exit if it is set to "no". </p> <p> The ability to run ad-hoc commands opens up a wealth of additional possibilities: </p> <ul> <li><p> Specify an instance by name rather than configuration directory when using <a href="sendmail.1.html">sendmail(1)</a> to send a verification probe: </p> <blockquote> <pre> $ postmulti -i postfix-myinst -x sendmail -bv test@example.net </pre> </blockquote> <li><p> Display non-default <a href="postconf.5.html">main.cf</a> settings of all Postfix instances. This uses an inline shell script to package together multiple shell commands to execute for each instance: </p> <blockquote> <pre> $ postmulti -x sh -c 'echo "-- $MAIL_CONFIG"; postconf -n' </pre> </blockquote> <li><p> Put all mail in enabled member instances of a group on hold: </p> <blockquote> <pre> # postmulti -g group_name -x \ sh -c 'test $<a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = yes && postsuper -h ALL' </pre> </blockquote> <li><p> Show top 10 domains in the <a href="QSHAPE_README.html#deferred_queue">deferred queue</a> of all instances: </p> <blockquote> <pre> # postmulti -x sh -c 'echo "-- $MAIL_CONFIG"; qshape deferred | head -12' </pre> </blockquote> </ul> <h3><a name="create"> Creating a new Postfix instance </a></h3> <p> The <a href="postmulti.1.html">postmulti(1)</a> 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 <a href="postconf.5.html">main.cf</a> file: </p> <blockquote> <pre> <a href="postconf.5.html#authorized_submit_users">authorized_submit_users</a> = <a href="postconf.5.html#master_service_disable">master_service_disable</a> = inet </pre> </blockquote> <p> 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. </p> <p> The <a href="postmulti.1.html">postmulti(1)</a> 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: </p> <blockquote> <pre> <a href="postconf.5.html#config_directory">config_directory</a> = /conf-path/postfix <a href="postconf.5.html#queue_directory">queue_directory</a> = /queue-path/postfix <a href="postconf.5.html#data_directory">data_directory</a> = /data-path/postfix </pre> </blockquote> <p> A newly-created instance named <i>postfix-myinst</i> will by default have: </p> <blockquote> <pre> <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> = no <a href="postconf.5.html#multi_instance_name">multi_instance_name</a> = postfix-myinst <a href="postconf.5.html#config_directory">config_directory</a> = /conf-path/postfix-myinst <a href="postconf.5.html#queue_directory">queue_directory</a> = /queue-path/postfix-myinst <a href="postconf.5.html#data_directory">data_directory</a> = /data-path/postfix-myinst </pre> </blockquote> <p> 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. </p> <p> When specifying the instance name later, you can refer to it either as "postfix-myinst", or via the full path of the configuration directory. </p> <p> To create a new instance just use the <b>-e create</b> option: </p> <blockquote> <pre> # postmulti -I postfix-myinst -e create </pre> </blockquote> <p> If the new instance is to belong to a group of related instances that implement a single logical service, assign it to a group: </p> <blockquote> <pre> # postmulti -I postfix-myinst -G mygroup -e create </pre> </blockquote> <p> If you want to override the conventional values of the instance installation parameters, specify their values on the command-line: </p> <blockquote> <pre> # postmulti [-I postfix-myinst] [-G mygroup] -e create \ "<a href="postconf.5.html#config_directory">config_directory</a> = /path/to/config_directory" \ "<a href="postconf.5.html#queue_directory">queue_directory</a> = /path/to/queue_directory" \ "<a href="postconf.5.html#data_directory">data_directory</a> = /path/to/data_directory" </pre> </blockquote> <p> A note on the <b>-I</b> and <b>-G</b> options above. These are always used to assign a name or group name to an instance, while the <b>-i</b> and <b>-g</b> 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 (<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter of the default instance). </p> <p> 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 "<a href="postconf.5.html#syslog_name">syslog_name</a>" explicitly in the <a href="postconf.5.html">main.cf</a> file of a "nameless" instance, in order to avoid confusion in the mail logs when multiple instances are in use. </p> <h3><a name="destroy"> Destroying a Postfix instance </a></h3> <p> If you no longer need an instance, you can destroy it via: </p> <blockquote> <pre> # postmulti -i postfix-myinst -p stop # postmulti -i postfix-myinst -e disable # postmulti -i postfix-myinst -e destroy </pre> </blockquote> <p> 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. </p> <h3><a name="import"> Importing an existing Postfix instance </a></h3> <p> If you already have an existing secondary Postfix instance that is not yet managed via <a href="postmulti.1.html">postmulti(1)</a>, 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 <a href="postconf.5.html#multi_instance_name">multi_instance_name</a> parameter in its configuration file will be adjusted to match this name if necessary): </p> <blockquote> <pre> # postmulti -I postfix-myinst [-G mygroup] -e import </pre> </blockquote> <p> Otherwise, you must specify the location of its configuration directory: </p> <blockquote> <pre> # postmulti [-I postfix-myinst] [-G mygroup] -e import \ "<a href="postconf.5.html#config_directory">config_directory</a> = /path/of/config_directory" </pre> </blockquote> <p> When the instance is imported, you can assign a name or a group. As with <a href="#create">"create"</a>, 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. </p> <p> 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 <a href="#enable">enable</a> 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. </p> <p> To find out what instances are running, use: </p> <blockquote> <pre> # postfix status </pre> </blockquote> <h3><a name="deport"> Deporting a managed Postfix instance </a></h3> <p> 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. <a href="postmulti.1.html">postmulti(1)</a> will refuse to "deport" an instance that is not stopped and disabled. </p> <blockquote> <pre> # postmulti -i postfix-myinst -p stop # postmulti -i postfix-myinst -e disable # postmulti -i postfix-myinst -e deport </pre> </blockquote> <h3><a name="assign"> Assigning a new name or group name </a></h3> <p> 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: </p> <blockquote> <pre> # postmulti -i postfix-old [-I postfix-new] [-G newgroup] -e assign </pre> </blockquote> <h3><a name="enable"> Enabling/disabling managed instances </a></h3> <p> You can enable or disable a managed instance. As documented in <a href="postfix-wrapper.5.html">postfix-wrapper(5)</a>, disabled instances are skipped with actions that <a href="postconf.5.html#postmulti_start_commands">start</a>, <a href="postconf.5.html#postmulti_start_commands">stop</a> or <a href="postconf.5.html#postmulti_control_commands">control</a> running Postfix instances. </p> <blockquote> <pre> # postmulti -i postfix-myinst -e enable # postmulti -i postfix-myinst -e disable </pre> </blockquote> <h2><a name="credits"> Credits </a></h2> <p> Wietse Venema created Postfix, designed and implemented the multi-instance wrapper framework and provided design feedback that made the <a href="postmulti.1.html">postmulti(1)</a> utility much more general and useful than originally envisioned. </p> <p> The <a href="postmulti.1.html">postmulti(1)</a> utility was developed by Victor Duchovni of Morgan Stanley, who also wrote the initial version of this document. </p> </body> </html>