1275 lines
54 KiB
HTML
1275 lines
54 KiB
HTML
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"https://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=utf-8">
|
|
<link rel='stylesheet' type='text/css' href='postfix-doc.css'>
|
|
|
|
</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 to 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>, <a href="QSHAPE_README.html#incoming_queue">incoming</a>, 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>
|