diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-06 01:46:30 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-06 01:46:30 +0000 |
| commit | b5896ba9f6047e7031e2bdee0622d543e11a6734 (patch) | |
| tree | fd7b460593a2fee1be579bec5697e6d887ea3421 /html/MULTI_INSTANCE_README.html | |
| parent | Initial commit. (diff) | |
| download | postfix-b5896ba9f6047e7031e2bdee0622d543e11a6734.tar.xz postfix-b5896ba9f6047e7031e2bdee0622d543e11a6734.zip | |
Adding upstream version 3.4.23.upstream/3.4.23upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'html/MULTI_INSTANCE_README.html')
| -rw-r--r-- | html/MULTI_INSTANCE_README.html | 1274 |
1 files changed, 1274 insertions, 0 deletions
diff --git a/html/MULTI_INSTANCE_README.html b/html/MULTI_INSTANCE_README.html new file mode 100644 index 0000000..39fc87d --- /dev/null +++ b/html/MULTI_INSTANCE_README.html @@ -0,0 +1,1274 @@ +<!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. + # + # Postfix 2.10 and later: specify empty <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a>. + <a href="postconf.5.html#smtpd_relay_restrictions">smtpd_relay_restrictions</a> = + <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 postfix-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 $<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> |