1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<html> 5 6<head> 7 8<title>Managing multiple Postfix instances on a single host</title> 9 10<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 11<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 12 13</head> 14 15<body> 16 17<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Managing 18multiple Postfix instances on a single host</h1> 19 20<hr> 21 22<h2>Overview </h2> 23 24<p> This document is a guide to managing multiple Postfix instances 25on a single host using the postmulti(1) instance manager. Multi-instance 26support is available with Postfix version 2.6 and later. See the 27postfix-wrapper(5) manual page for background on the instance 28management framework, and on how to deploy a custom instance manager. 29</p> 30 31<p> Topics covered in this document: </p> 32 33<ul> 34 35<li><a href="#why"> Why multiple Postfix instances </a> 36 37<li><a href="#split"> Null-client instances versus service instances </a> 38 39<li><a href="#quick"> Multi-instance walk-through </a> 40 41<li><a href="#parts"> Components of a Postfix system </a> 42 43<li><a href="#default"> The default Postfix instance </a> 44 45<li><a href="#group"> Instance groups </a> 46 47<li><a href="#params"> Multi-instance configuration parameters </a> 48 49<li><a href="#how"> Using the postmulti(1) command </a> 50 51<li><a href="#credits"> Credits </a> 52 53</ul> 54 55<h2><a name="why"> Why multiple Postfix instances </a></h2> 56 57<p> Postfix is a general-purpose mail system that can be configured 58to serve a variety of needs. Examples of Postfix applications are: </p> 59 60<ul> 61 62<li><p> Local mail submission for shell users and system processes. </p> 63 64<li><p> Incoming (MX host) email from the Internet. </p> 65 66<li><p> Outbound mail relay for a corporate network. </p> 67 68<li><p> Authenticated submission for roaming users. </p> 69 70<li><p> Before/after content-filter mail. </p> 71 72</ul> 73 74<p> A single Postfix configuration can provide many or all of these 75services, but a complex interplay of settings may be required, for 76example with master.cf options overriding main.cf settings. In this 77document we take the view that multiple Postfix instances may be a 78simpler way to configure a multi-function Postfix system. With 79multiple Postfix instances, each instance has its own directories 80for configuration, queue and data files, but it shares all Postfix 81program and documentation files with other instances. </p> 82 83<p> Since there is no single right way to configure your system, 84we recommend that you choose what makes you most comfortable. If 85different Postfix services don't involve incompatible main.cf or 86master.cf settings, and if they can be combined together without 87complex tricks, then a single monolithic configuration may be the 88simplest approach. </p> 89 90<p> The purpose of multi-instance support in Postfix is not to force 91you to create multiple Postfix instances, but rather to give you a 92choice. Multiple instances give you the freedom to tune each Postfix 93instance to a single task that it does well and to combine instances 94into complete systems. </p> 95 96<p> With the introduction of the postmulti(1) utility and the reduction 97of the per-instance configuration footprint of a secondary Postfix 98instance to just a main.cf and master.cf file (other files are now in 99shared locations), we hope that multiple instances will be easier to 100use than ever before. </p> 101 102<h2><a name="split"> Null-client instances versus service instances </a></h2> 103 104<p> In the multi-instance approach to configuring Postfix, the first 105simplification is with the default local-submission Postfix instance. 106</p> 107 108<p> Most UNIX systems require support for email submission with the 109sendmail(1) command so that system processes such as cron jobs can 110send status reports, and so that system users can send email with 111command-line utilities. Such email can be handled with a <a 112href="STANDARD_CONFIGURATION_README.html#null_client">null-client</a> 113Postfix configuration that forwards all mail to a central mail hub. 114The null client will typically either not run an SMTP listener at 115all (master_service_disable = inet), or it will listen only on the 116loopback interface (inet_interfaces = loopback-only). </p> 117 118<p> When implementing specialized servers for inbound Internet 119email, outbound MTAs, internal mail hubs, and so on, we recommend 120using a null client for local submission and creating single-function 121secondary Postfix instances to serve the specialized needs. </p> 122 123<blockquote> 124 125<p> Note: usually, you need to use different "myhostname" settings 126when you run multiple instances on the same host. Otherwise, there 127will be false "mail loops back to myself" alarms when one instance 128tries to send mail into another instance. Typically, the null-client 129instance will use the system's hostname, and other instances will 130use their own dedicated "myhostname" settings. Different names are 131not needed when instances send mail to each other with a protocol 132other than SMTP, or with SMTP over a TCP port other than 25 as is 133usual with SMTP-based content filters. </p> 134 135</blockquote> 136 137<h2><a name="quick"> Multi-instance walk-through </a></h2> 138 139<p> Before discussing the fine details of multi-instance operation 140we first show the steps for creating a border mail server. This 141server has with a null-client Postfix instance for local submission, 142an input Postfix instance to receive mail from the Internet, plus 143an <a href="FILTER_README.html#advanced_filter">advanced</a> SMTP 144content-filter and an output Postfix instance to deliver filtered 145email to its internal destination. </p> 146 147<h3>Setting up the null-client Postfix instance </h3> 148 149<p> On a border mail hub, while mail from the Internet requires a 150great deal of scrutiny, locally submitted messages are typically 151limited to mail from cron jobs and other system services. In this 152regard the border MTA is not different from other Unix hosts in 153your environment. For this reason, it will submit locally-generated 154email to the internal mail hub. We start the construction of the 155border mail server with the <a href="#default_instance">default</a> 156instance, which will be a local-submission <a 157href="STANDARD_CONFIGURATION_README.html#null_client">null client</a>: 158</p> 159 160<blockquote> 161<pre> 162/etc/postfix/main.cf: 163 # We are mta1.example.com 164 # 165 myhostname = mta1.example.com 166 mydomain = example.com 167 168 # Flat user-account namespace in example.com: 169 # 170 # user@example.com not user@host.example.com 171 # 172 myorigin = $mydomain 173 174 # Postfix 2.6+, disable inet services, specifically disable smtpd(8) 175 # 176 master_service_disable = inet 177 178 # No local delivery: 179 # 180 mydestination = 181 local_transport = error:5.1.1 Mailbox unavailable 182 alias_database = 183 alias_maps = 184 local_recipient_maps = 185 186 # Send everything to the internal mailhub 187 # 188 relayhost = [mailhub.example.com] 189 190 # Indexed table macro: 191 # (use "hash", ... when <a href="CDB_README.html">cdb</a> is not available) 192 # 193 default_database_type = cdb 194 indexed = ${default_database_type}:${config_directory}/ 195 196 # Expose origin host of mail from "root", ... 197 # 198 smtp_generic_maps = ${indexed}generic 199 200 # Send messages addressed to "root", ... to the MTA support team 201 # 202 virtual_alias_maps = ${indexed}virtual 203 204/etc/postfix/generic: 205 # The smarthost supports "+" addressing (recipient_delimiter = +). 206 # Mail from "root" exposes the origin host, without replies 207 # and bounces going back to the same host. 208 # 209 # On clustered MTAs this file is typically machine-built from 210 # a template file. The build process expands the template into 211 # "mtaadmin+root=mta1" 212 # 213 root mtaadmin+root=mta1 214 215/etc/postfix/virtual: 216 # Caretaker aliases: 217 # 218 root mtaadmin 219 postmaster root 220</pre> 221</blockquote> 222 223<p> You would typically also add a Makefile, to automatically run 224postmap(1) commands when source files change. This Makefile also 225creates a "generic" database when none exists. </p> 226 227<blockquote> 228<pre> 229/etc/postfix/Makefile: 230 MTAADMIN=mtaadmin 231 232 all: virtual.cdb generic.cdb 233 234 generic: Makefile 235 @echo Creating $@ 236 @rm -f $@.tmp 237 @printf '%s\t%s+root=%s\n' root ${MTAADMIN} `uname -n` > $@.tmp 238 @mv $@.tmp generic 239 240 %.cdb: % 241 postmap cdb:$< 242</pre> 243</blockquote> 244 245<p> Construct the "virtual" and "generic" databases (the latter is 246created by running "make"), then start and test the null-client: 247</p> 248 249<blockquote> 250<pre> 251# cd /etc/postfix; make 252# postfix start 253# sendmail -i -f root -t <<EOF 254From: root 255To: root 256Subject: test 257 258testing 259EOF 260</pre> 261</blockquote> 262 263<p> The test message should be delivered to the members of the "mtaadmin" 264address group (or whatever address group you choose) with the 265following headers: </p> 266 267<blockquote> 268<pre> 269From: mtaadmin+root=mta1@example.com 270To: mtadmin+root=mta1@example.com 271Subject: test 272</pre> 273</blockquote> 274 275<h3>Setting up the "output" Postfix instance </h3> 276 277<p> With the null-client instance out of the way, we can create the 278MTA "output" instance that will deliver filtered mail to the inside 279network. We add the "output" instance first, because the output 280instance needs to be up and running before the input instance can 281be fully tested, and when the system boots, the "output" instance 282must start before the input instance. We will put the output and 283input instances into a single instance group named "mta". </p> 284 285<p> Just once, when adding the first secondary instance, enable 286multi-instance support in the default (null-client) instance: </p> 287 288<blockquote> 289<pre> 290# postmulti -e init 291</pre> 292</blockquote> 293 294<p> Then create the output instance: <p> 295 296<blockquote> 297<pre> 298# postmulti -I postfix-out -G mta -e create 299</pre> 300</blockquote> 301 302<p> The instance configuration directory defaults to /etc/postfix-out, 303more precisely, the "postfix-out" subdirectory of the parent directory 304of the default-instance configuration directory. The new instance will 305be created in a "disabled" state: </p> 306 307<blockquote> 308<pre> 309/etc/postfix-out/main.cf 310 # 311 # ... "stock" main.cf settings ... 312 # 313 multi_instance_name = postfix-out 314 queue_directory = /var/spool/postfix-out 315 data_directory = /var/lib/postfix-out 316 # 317 multi_instance_enable = no 318 master_service_disable = inet 319 authorized_submit_users = 320</pre> 321</blockquote> 322 323<p> This instance has a "stock" master.cf file, and its queue and 324data directories, also named "postfix-out", will be located in the 325same parent directories as the corresponding directories of the 326default instance (e.g., /var/spool/postfix-out and /var/lib/postfix-out). 327</p> 328 329<p> While this instance is immediately safe to start, it is not yet 330usefully configured. It needs to be customized to fit the role of a 331post-filter re-injection SMTP service. Typical additions include: </p> 332 333<blockquote> 334<pre> 335/etc/postfix-out/master.cf: 336 # Replace default "smtp inet" entry with one listening on port 10026. 337 127.0.0.1:10026 inet n - n - - smtpd 338 339/etc/postfix-out/main.cf 340 # ... 341 342 # Comment out if you don't use IPv6 internally 343 # inet_protocols = ipv4 344 inet_interfaces = loopback-only 345 mynetworks_style = host 346 smtpd_authorized_xforward_hosts = $mynetworks 347 348 # Don't anvil(8) control the re-injection port. 349 # 350 smtpd_client_connection_count_limit = 0 351 smtpd_client_event_limit_exceptions = $mynetworks 352 353 # Best practice when inet_interfaces is set, as this is not a 354 # "secondary IP personality" configuration. 355 # 356 smtp_bind_address = 0.0.0.0 357 358 # All header rewriting happens upstream 359 # 360 local_header_rewrite_clients = 361 362 # No local delivery on border gateway 363 # 364 mydestination = 365 alias_maps = 366 alias_database = 367 local_recipient_maps = 368 local_transport = error:5.1.1 Mailbox unavailable 369 370 # May need a recipient_delimiter for per-user transport lookups: 371 # 372 recipient_delimiter = + 373 374 # Only one (unrestricted client) 375 # With multiple instances, rarely need "-o param=value" overrides 376 # in master.cf, each instance gets its own main.cf file. 377 # 378 # Postfix 2.10 and later: specify empty smtpd_relay_restrictions. 379 smtpd_relay_restrictions = 380 smtpd_recipient_restrictions = permit_mynetworks, reject 381 382 # Tolerate occasional high latency in the content filter. 383 # 384 smtpd_timeout = 1200s 385 386 # Best when empty, with all parent domain matches explicit. 387 # 388 parent_domain_matches_subdomains = 389 390 # Use the "relay" transport for inbound mail, and the default 391 # "smtp" transport for outbound mail (bounces, ...). The latter 392 # won't starve the former of delivery agent slots. 393 # 394 relay_domains = example.com, .example.com 395 396 # With xforward, match the input instance setting, if you 397 # want "yes", set both to "yes". 398 # 399 smtpd_client_port_logging = no 400 401 # Transport settings ... 402 # Message size limit 403 # Concurrency tuning for "relay" and "smtp" transport 404 # ... 405</pre> 406</blockquote> 407 408<p> With the "output" configuration in place, enable and start the 409instance: </p> 410 411<blockquote> 412<pre> 4131 # postmulti -i postfix-out -x postconf -e \ 4142 "master_service_disable =" "authorized_submit_users = root" 4153 # postmulti -i postfix-out -e enable 4164 # postmulti -i postfix-out -p start 417</pre> 418</blockquote> 419 420<p> This uses the postmulti(1) command to invoke postconf(1) in the 421context (MAIL_CONFIG=/etc/postfix-out) of the output instance. </p> 422 423<ul> 424 425<li> <p> Lines 1-2: With "authorized_submit_users = root", the 426superuser can test the postfix-out instance with "postmulti -i 427postfix-out -x sendmail -bv recipient...", but otherwise local 428submission remains disabled. </p> 429 430<li> <p> Lines 1-2: With "master_service_disable =", the "inet" 431listeners are re-enabled. </p> 432 433<li> <p> Line 3: The output instance is enabled for multi-instance 434start/stop. </p> 435 436<li> <p> Line 4: The output instance is started. </p> 437 438</ul> 439 440<p> Test the output instance by submitting probe messages via "sendmail 441-bv" and "telnet". For production systems, in-depth configuration tests 442should be done on a lab system. The simple tests just suggested will only 443confirm successful deployment of a configuration that should already be 444known good. </p> 445 446<h3> Setting up the content-filter proxy </h3> 447 448<p> With the output instance ready, deploy your content-filter 449proxy. Most proxies will need their own /etc/rc* start/stop script. 450Some proxies, however, are started on demand by the Postfix spawn(8) 451service, in which case you need to add the relevant spawn(8) entry 452to the output instance master.cf file. </p> 453 454<p> Configure the proxy to listen on 127.0.0.1:10025 and to re-inject 455filtered email to 127.0.0.1:10026. Start the proxy service if 456necessary, then test the proxy via "telnet" or automated SMTP 457injectors. The proxy should support the following ESMTP features: 458DSN, 8BITMIME, and XFORWARD. In addition, the proxy should support 459multiple mail deliveries within an SMTP session. </p> 460 461<h3> Setting up the input Postfix instance </h3> 462 463<p> The input Postfix instance receives mail from the network and 464sends it through the content filter. Now we create the input instance, 465also part of the "mta" instance group: </p> 466 467<blockquote> 468<pre> 469# postmulti -I postfix-in -G mta -e create 470</pre> 471</blockquote> 472 473<p> The new instance configuration directory defaults to /etc/postfix-in, 474more precisely, the "postfix-in" subdirectory of the parent directory 475of the default-instance configuration directory. The new instance will 476be created in a "disabled" state: </p> 477 478<blockquote> 479<pre> 480/etc/postfix-in/main.cf 481 # 482 # ... "stock" main.cf settings ... 483 # 484 multi_instance_name = postfix-in 485 queue_directory = /var/spool/postfix-in 486 data_directory = /var/lib/postfix-in 487 # 488 multi_instance_enable = no 489 master_service_disable = inet 490 authorized_submit_users = 491</pre> 492</blockquote> 493 494<p> As before, make appropriate changes to main.cf and master.cf to 495make the instance production ready. Consider setting "soft_bounce = yes" 496during the first few hours of deployment, so you can iron-out any unexpected 497"kinks". </p> 498 499<p> Manual testing can start with: 500 501<blockquote> 502<pre> 503/etc/postfix-in/main.cf 504 # Accept only local traffic, but allow impersonation: 505 inet_interfaces = 127.0.0.1 506 smtpd_authorized_xclient_hosts = 127.0.0.1 507</pre> 508</blockquote> 509 510<p> This allows you to use the Postfix-specific <a 511href="XCLIENT_README.html">XCLIENT</a> SMTP command to safely 512simulate connections from remote systems before any remote systems 513are able to connect. If the test results look good, revert the above 514settings to the required production values. Typical settings in the 515pre-filter input instance include: </p> 516 517<blockquote> 518<pre> 519/etc/postfix-in/main.cf 520 # 521 # ... 522 # 523 524 # No local delivery on border gateway 525 # 526 mydestination = 527 alias_maps = 528 alias_database = 529 local_recipient_maps = 530 local_transport = error:5.1.1 Mailbox unavailable 531 532 # Don't rewrite remote headers 533 # 534 local_header_rewrite_clients = 535 536 # All recipients of not yet filtered email go to the same filter together. 537 # 538 # With multiple instances, the content-filter is specified 539 # via transport settings not the "content_filter" transport 540 # switch override! Here the filter listens on local port 10025. 541 # 542 # If you need to route some users or recipient domains directly to the 543 # output instance bypassing the filter, just define a transport table 544 # with suitable entries. 545 # 546 default_transport = smtp:[127.0.0.1]:10025 547 relay_transport = $default_transport 548 virtual_transport = $default_transport 549 transport_maps = 550 551 # Pass original client log information through the filter. 552 # 553 smtp_send_xforward_command = yes 554 555 # Avoid splitting the envelope and scanning messages multiple times. 556 # Match the re-injection server's recipient limit. 557 # 558 smtp_destination_recipient_limit = 1000 559 560 # Tolerate occasional high latency in the content filter. 561 # 562 smtp_data_done_timeout = 1200s 563 564 # With xforward, match the output instance setting, if you 565 # want "yes", set both to "yes". 566 # 567 smtpd_client_port_logging = no 568 569 # ... Lots of settings for inbound MX host ... 570</pre> 571</blockquote> 572 573<p> With the "input" instance configured, enable and start it: </p> 574 575<blockquote> 576<pre> 577# postmulti -i postfix-in -x postconf -e \ 578 "master_service_disable =" "authorized_submit_users = root" 579# postmulti -i postfix-in -e enable 580# postmulti -i postfix-in -p start 581</pre> 582</blockquote> 583 584<p> That's it. You now have a 3-instance configuration. A null-client 585sending all locally submitted mail to the internal mail hub and a pair of 586"mta" instances that receive mail from the Internet, pass it through a 587content-filter, and then deliver it to the internal destination. </p> 588 589<p> Running "postfix start" or "postfix stop" will now start/stop all 590three Postfix instances. You can use "postfix -c /config/path start" 591to start just one instance, or use the instance name (or instance 592group name) via postmulti(1): </p> 593 594<blockquote> 595<pre> 596# postmulti -i - -p stop 597# postmulti -g mta -p status 598# postmulti -i postfix-out -p flush 599# postmulti -i postfix-in -p reload 600# ... 601</pre> 602</blockquote> 603 604<p> This example ends the multi-instance "walk through". The remainder 605of this document provides background information on Postfix 606multi-instance support features and options. </p> 607 608<h2><a name="parts"> Components of a Postfix system </a></h2> 609 610<p> A Postfix system consists of the following components: </p> 611 612<p> Shared among all instances: </p> 613 614<ul> 615 616<li><p> Command-line utilities for administrators and users installed in 617$command_directory, $sendmail_path, $mailq_path and $newaliases_path. </p> 618 619<li><p> Daemon executables, and run-time support files installed in 620$daemon_directory. </p> 621 622<li><p> Bundled documentation, installed in $html_directory, 623$manpage_directory and $readme_directory. </p> 624 625<li><p> Entries in /etc/passwd and /etc/group for the $mail_owner user and 626$setgid_group group. The $mail_owner user provides the mail system 627with a protected (non-root) execution context. The $setgid_group group 628is used exclusively to support the setgid postdrop(1) and postqueue(1) 629utilities (it <b>must not</b> be the primary group or secondary group 630of any users, including the $mail_owner user). </p> 631 632</ul> 633 634<p> Private to each instance: </p> 635 636<ul> 637 638<li><p> The main.cf, master.cf (and other optional) configuration 639files in $config_directory. </p> 640 641<li> <p> The maildrop, incoming, active, deferred and hold queues 642in $queue_directory (which contains additional directories needed 643by Postfix, and which optionally doubles as a chroot jail for Postfix 644daemon processes). </p> 645 646<li> <p> Various caches (TLS session, address verification, ...) 647in $data_directory. </p> 648 649</ul> 650 651<p> The Postfix configuration parameters mentioned above are 652collectively referred to as "installation parameters". Their default 653values are set when the Postfix software is built from source, and 654all but one may be optionally set to a non-default value via the 655main.cf file. The one parameter that (catch-22) cannot be set in 656main.cf is $config_directory, as this defines the location of the 657main.cf file itself. </p> 658 659<p> Though config_directory cannot be set in main.cf, postfix(1) and 660most of the other command-line Postfix utilities allow you to specify a 661non-default configuration directory via a command line option (typically 662<b>-c</b>) or via the MAIL_CONFIG environment variable. In this way, 663it is possible to have multiple configuration directories on the same 664machine, and to have multiple running master(8) daemons each with its 665own configuration files, queue directory and data directory. </p> 666 667<p> These multiple running copies of master(8) share the base Postfix 668software. They do not (and cannot) share their configuration 669directories, queue directories or data directories. </p> 670 671<p> Each combination of configuration directory, together with the queue 672directory and data directory (specified in the corresponding main.cf file) 673make up a Postfix <b>instance</b>. </p> 674 675<h2><a name="default"> The default Postfix instance </a></h2> 676 677<p> One Postfix instance is special: this is the instance whose 678configuration directory is the default one compiled into the Postfix 679utilities. The location of the default configuration directory is 680typically /etc/postfix, and can be queried via the "postconf -d 681config_directory" command. We call the instance with this configuration 682directory the "default instance". </p> 683 684<p> The default instance is responsible for local mail submission. The 685setgid postdrop(1) utility is used by the sendmail(1) local submission 686program to spool messages into the <b>maildrop</b> sub-directory of the 687queue directory of the default instance. </p> 688 689<p> Even in the rare case when "sendmail -C" is used to submit local mail 690into a non-default Postfix instance, for security reasons, postdrop(1) 691will consult the default main.cf file to check the validity of the 692requested non-default configuration directory. </p> 693 694<p> So, while in most other respects, all instances are equal, the 695default instance is "more equal than others". You may choose to create 696additional instances, but you must have at least the default instance, 697with its configuration directory in the default compiled-in location. </p> 698 699<h2><a name="group"> Instance groups </a></h2> 700 701<p> The postmulti(1) multi-instance manager supports the notion of an 702instance "group". Typically, the member instances of an instance group 703constitute a logical service, and are expected to all be running or all 704be stopped. </p> 705 706<p> In many cases a single Postfix instance will be a complete logical 707"service". You should define such instances as stand-alone instances 708that are not members of any instance "group". The null-client 709instance is an example of a non-group instance. </p> 710 711<p> When a logical service consists of multiple Postfix instances, 712often a pair of pre-filter and post-filter instances with a content 713filter proxy between them, the related instances should be members 714of a single instance group (however, the content filter usually has 715its own start/stop procedure that is separate from any Postfix 716instance). </p> 717 718<p> The default instance main.cf file's $multi_instance_directories 719configuration parameter lists the configuration directories of all 720secondary (non-default) instances. Together with the default instance, 721these secondary instances are managed by the multi-instance manager. 722Instances are started in the order listed, and stopped in the 723opposite order. For instances that are members of a service "group", 724you should arrange to start the service back-to-front, with the 725output stages started and ready to receive mail before the input 726stages are started. </p> 727 728<h2><a name="params"> Multi-instance configuration parameters </a></h2> 729 730<dl> 731 732<dt> multi_instance_wrapper </dt> 733 734<dd> <p> This default-instance configuration parameter must be set 735to a suitable multi-instance manager's "wrapper" program that 736controls the starting, stopping, etc. of a multi-instance Postfix 737system. To use the postmulti(1) manager described in this document, 738this parameter should be set with the "<a href="#init">postmulti 739-e init</a>" command. </p> </dd> 740 741<dt> multi_instance_directories </dt> 742 743<dd> <p> This default-instance configuration parameter specifies 744an optional list of the secondary instances controlled via the 745multi-instance manager. Instances are listed in their "start" order, 746with the default instance always started first (if enabled). If 747$multi_instance_directories is left empty, the postfix(1) command 748runs with multi-instance support turned off, and none of the 749multi_instance_ configuration parameters will have any effect. </p> 750 751<p> Do not assign a non-empty list of secondary instance configuration 752directories to multi_instance_directories until you have configured a 753suitable multi_instance_wrapper setting! This is best accomplished via 754the "<a href="#init">postmulti -e init</a>" command. 755</p> </dd> 756 757<dt> multi_instance_name </dt> 758 759<dd> <p> Each Postfix instance may be assigned a distinct name (with 760"postfix -e create/import/assign -I <i>name</i>..."). This name can 761be used with the postmulti(1) command-line utility to perform tasks 762on the instance by name (rather than the full pathname of its 763configuration directory). Choose a name that concisely captures the 764role of the instance (it must start with "postfix-"). It is an 765error for two instances to have the same $multi_instance_name. You 766can leave an instance "nameless" by leaving this parameter at the 767default empty setting. </p> 768 769<p> To avoid confusion in your logs, if you don't assign each 770secondary instance a non-empty (distinct) $multi_instance_name, you 771should make sure that the $syslog_name setting is different for 772each instance. The $syslog_name parameter defaults to $multi_instance_name 773when the latter is non-empty. If at all possible, the syslog_name 774should start with "postfix-", this helps log parsers to identify 775log entries from secondary Postfix instances. </p> </dd> 776 777<dt> multi_instance_group </dt> 778 779<dd> <p> Each Postfix instance may be assigned an "instance group" 780name (with "postfix -e create/import/assign -G <i>name</i>..."). 781The default (empty) value of multi_instance_group parameter indicates 782a stand-alone instance that is not part of any group. The group 783name can be used with the postmulti(1) command-line utility to 784perform a task on the members of a group by name. Choose a single-word 785group name that concisely captures the role of the group. </p> 786</dd> 787 788<dt> multi_instance_enable </dt> 789 790<dd> <p> This parameter controls whether a Postfix instance will 791be started by a Postfix multi-instance manager. The default value 792is "no". The instance can be started explicitly with "postfix -c 793/path/to/config/directory"; this is useful for testing. </p> 794 795<p> When an instance is disabled, the postfix(1) "start" command 796is replaced by "check". </p> 797 798<p> Some postfix(1) commands (such as "stop", "flush", ...) require 799a running Postfix instance, and skip instances that are disabled. 800</p> 801 802<p> Other postfix(1) commands (such as "status", "set-permissions", 803"upgrade-configuration", ...) do not require a running Postfix 804system, and apply to all instances whether enabled or not. </p> 805</dd> 806 807</dl> 808 809<p> The postmulti(1) utility can be used to create (or destroy) instances. 810It can also be used to "import" or "deport" existing instances into or 811from the list of managed instances. When using postmulti(1) to manage 812instances, the above configuration parameters are managed for you 813automatically. See below. </p> 814 815<h2><a name="how"> Using the postmulti(1) command </a></h2> 816 817<ul> 818 819<li><a href="#init"> Initializing the multi-instance manager </a> 820 821<li><a href="#list"> Listing managed instances </a> 822 823<li><a href="#start"> Starting or stopping a multi-instance system </a> 824 825<li><a href="#adhoc"> Ad-hoc multi-instance operations </a> 826 827<li><a href="#create"> Creating a new Postfix instance </a> 828 829<li><a href="#destroy"> Destroying a Postfix instance </a> 830 831<li><a href="#import"> Importing an existing Postfix instance </a> 832 833<li><a href="#deport"> Deporting a managed Postfix instance </a> 834 835<li><a href="#assign"> Assigning a new name or group name </a> 836 837<li><a href="#enable"> Enabling/disabling managed instances </a> 838 839</ul> 840 841<h3><a name="init"> Initializing the multi-instance manager </a></h3> 842 843<p> Before postmulti(1) is used for the first time, you must install 844it as the multi_instance_wrapper for your Postfix system and enable 845multi-instance operation of the default Postfix instance. You can then 846proceed to add <a href="#create">new</a> or <a href="#import">existing</a> 847instances to the multi-instance configuration. This initial installation 848is accomplished as follows: </p> 849 850<blockquote> 851<pre> 852 # postmulti -e init 853</pre> 854</blockquote> 855 856<p> This updates the default instance main.cf file as follows: </p> 857 858<blockquote> 859<pre> 860 # Use postmulti(1) as a postfix-wrapper(5) 861 # 862 multi_instance_wrapper = ${command_directory}/postmulti -p -- 863 864 # Configure the default instance to start when in multi-instance mode 865 # 866 multi_instance_enable = yes 867</pre> 868</blockquote> 869 870<p> If you prefer, you can make these changes by editing the default 871main.cf directly, or by using "postconf -e". </p> 872 873<h3><a name="list"> Listing managed instances </a></h3> 874 875<p> The list of managed instances consists of the default instance and 876the additional instances whose configuration directories are listed 877(in start order) under the multi_instance_directories parameter of the 878default main.cf configuration file. </p> 879 880<p> You can list selected instances, groups of instances or all 881instances by specifying only the instance matching options with the 882"-l" option. The "-a" option is assumed if no other instance 883selection options are specified (this behavior changes with the 884"-e" option). As a special case, even if it has an explicit name, 885the default instance can always be selected via "-i -". </p> 886 887<blockquote> 888<pre> 889# postmulti -l -a 890# postmulti -l -g a_group 891# postmulti -l -i an_instance 892</pre> 893</blockquote> 894 895<p> The output is one line per instance (in "postfix start" order): 896</p> 897 898<blockquote> 899 900<table border="1"> 901 902<tr> <th align="left">name</th> <th align="left">group</th> <th 903align="left">enabled</th> <th align="left">config_directory</th> 904</tr> 905 906<tr> <td>-</td> <td>-</td> <td>yes</td> <td>/etc/postfix 907 908<tr> <td>mta-out</td> <td>mta</td> <td>yes</td> <td>/etc/postfix/mta-out 909 910<tr> <td>mta-in</td> <td>mta</td> <td>yes</td> <td>/etc/postfix-mta-in 911 912<tr> <td>msa-out</td> <td>msa</td> <td>yes</td> <td>/etc/postfix-msa-out 913 914<tr> <td>msa-in</td> <td>msa</td> <td>yes</td> <td>/etc/postfix-msa-in 915 916<tr> <td>test</td> <td>-</td> <td>no</td> <td>/etc/postfix-test 917 918</table> 919 920</blockquote> 921 922<p> The first line showing the column headings is not part of the 923output. When either the instance name or the instance group is not 924set, it is shown as a "-". </p> 925 926<p> When selecting an existing instance via the "-i" option, you 927can always use the full pathname of its configuration directory 928instead of the instance (short) name. This is the only way to select 929a non-default nameless instance. The default instance can be selected 930via "-i -", whether it has a name or not. </p> 931 932<p> To list instances in reverse start order, include the "-R" 933option together with the instance selection options. </p> 934 935<h3><a name="start"> Starting or stopping a multi-instance system 936</a></h3> 937 938<p> To start, stop, reload, etc. the complete (already configured as 939above) multi-instance system just use postfix(1) as you would with a 940single-instance system. The Postfix multi-instance wrapper framework 941insulates Postfix init.d start and package upgrade scripts from the 942details of multi-instance management! </p> 943 944<p> The <b>-p</b> option of postmulti(1) turns on postfix(1) compatibility 945mode. With this option the remaining arguments are exactly those supported 946by postfix(1), but commands are applied to all instances or all enabled 947instances as appropriate. As described above, this switch is required 948when using postmulti(1) as the multi_instance_wrapper. </p> 949 950<p> If you want to specify a subset of instances by name, or group name, 951or run arbitrary commands (not just "postfix stop/start/etc. in the 952context (MAIL_CONFIG environment variable setting) of a particular 953instance or group of instances, then you can use the instance-aware 954postmulti(1) utility directly. </p> 955 956<h3><a name="adhoc"> Ad-hoc multi-instance operations </a></h3> 957 958<p> The postmulti(1) command can be used by the administrator to run arbitrary 959commands in the context of one or more Postfix instances. The most common 960use-case is stopping or starting a group of Postfix instances: </p> 961 962<blockquote> 963<pre> 964# postmulti -g mygroup -p start 965# postmulti -g mygroup -p flush 966# postmulti -g mygroup -p reload 967# postmulti -g mygroup -p status 968# postmulti -g mygroup -p stop 969# postmulti -g mygroup -p upgrade-configuration 970</pre> 971</blockquote> 972 973<p> The <b>-p</b> option is essentially a short-hand for a leading 974<b>postfix</b> command argument, but with appropriate additional options 975turned on depending on the first argument. In the case of "start", 976disabled instances are "checked" (postfix check) rather than simply 977skipped. </p> 978 979<p> The resulting command is executed for each candidate instance with 980the <b>MAIL_CONFIG</b> environment variable set to the configuration 981directory of the corresponding Postfix instance. </p> 982 983<p> The postmulti(1) utility is able to launch commands other than 984postfix(1), Use the <b>-x</b> option to ask postmulti to execute an 985ad-hoc command for all instances, a group of instances, or just one 986instance. With ad-hoc commands the multi_instance_enable parameter 987is ignored: the command is unconditionally executed for the instances 988selected via -a, -g or -i. In addition to MAIL_CONFIG, the following 989instance parameters are exported into the command environment: </p> 990 991<blockquote> 992<pre> 993command_directory=$command_directory 994daemon_directory=$daemon_directory 995config_directory=$config_directory 996queue_directory=$queue_directory 997data_directory=$data_directory 998multi_instance_name=$multi_instance_name 999multi_instance_group=$multi_instance_group 1000multi_instance_enable=$multi_instance_enable 1001</pre> 1002</blockquote> 1003 1004<p> The config_directory setting is of course the same as MAIL_CONFIG, 1005and is arguably redundant, but leaving it in is less surprising. If 1006you want to skip disabled instances, just check multi_instance_enable 1007environment variable and exit if it is set to "no". </p> 1008 1009<p> The ability to run ad-hoc commands opens up a wealth of additional 1010possibilities: </p> 1011 1012<ul> 1013 1014<li><p> Specify an instance by name rather than configuration directory 1015when using sendmail(1) to send a verification probe: </p> 1016 1017<blockquote> 1018<pre> 1019$ postmulti -i postfix-myinst -x sendmail -bv test@example.net 1020</pre> 1021</blockquote> 1022 1023<li><p> Display non-default main.cf settings of all Postfix instances. 1024This uses an inline shell script to package together multiple shell 1025commands to execute for each instance: </p> 1026 1027<blockquote> 1028<pre> 1029$ postmulti -x sh -c 'echo "-- $MAIL_CONFIG"; postconf -n' 1030</pre> 1031</blockquote> 1032 1033<li><p> Put all mail in enabled member instances of a group on hold: </p> 1034 1035<blockquote> 1036<pre> 1037# postmulti -g group_name -x \ 1038 sh -c 'test $multi_instance_enable = yes && postsuper -h ALL' 1039</pre> 1040</blockquote> 1041 1042<li><p> Show top 10 domains in the deferred queue of all instances: 1043</p> 1044 1045<blockquote> 1046<pre> 1047# postmulti -x sh -c 'echo "-- $MAIL_CONFIG"; qshape deferred | head -12' 1048</pre> 1049</blockquote> 1050 1051</ul> 1052 1053<h3><a name="create"> Creating a new Postfix instance </a></h3> 1054 1055<p> The postmulti(1) command can be used to create additional Postfix 1056instances. New instances are created with local submission and all "inet" 1057services disabled via the following non-default parameter settings in 1058the main.cf file: </p> 1059 1060<blockquote> 1061<pre> 1062authorized_submit_users = 1063master_service_disable = inet 1064</pre> 1065</blockquote> 1066 1067<p> The above settings ensure that new instances are safe to start 1068immediately: they will not conflict with inet listeners in existing 1069Postfix instances. They will also not accept any mail until they are 1070fully configured, at which point you can do away with one or both of 1071the above safety measures. </p> 1072 1073<p> The postmulti(1) command encourages a preferred way of organizing 1074the configuration directories, queue directories and data directories 1075of non-default instances. If the default instance settings are: </p> 1076 1077<blockquote> 1078<pre> 1079config_directory = /conf-path/postfix 1080queue_directory = /queue-path/postfix 1081data_directory = /data-path/postfix 1082</pre> 1083</blockquote> 1084 1085<p> A newly-created instance named <i>postfix-myinst</i> will by default 1086have: </p> 1087 1088<blockquote> 1089<pre> 1090multi_instance_enable = no 1091multi_instance_name = postfix-myinst 1092config_directory = /conf-path/postfix-myinst 1093queue_directory = /queue-path/postfix-myinst 1094data_directory = /data-path/postfix-myinst 1095</pre> 1096</blockquote> 1097 1098<p> You can override any of these defaults when creating the instance, 1099but unless you want to spread instance queue directories over multiple 1100file-systems, use the default naming strategy. It keeps the multiple 1101instances organized in a uniform, predictable fashion. </p> 1102 1103<p> When specifying the instance name later, you can refer to it 1104either as "postfix-myinst", or via the full path of the configuration 1105directory. </p> 1106 1107<p> To create a new instance just use the <b>-e create</b> option: </p> 1108 1109<blockquote> 1110<pre> 1111# postmulti -I postfix-myinst -e create 1112</pre> 1113</blockquote> 1114 1115<p> If the new instance is to belong to a group of related instances that 1116implement a single logical service, assign it to a group: </p> 1117 1118<blockquote> 1119<pre> 1120# postmulti -I postfix-myinst -G mygroup -e create 1121</pre> 1122</blockquote> 1123 1124<p> If you want to override the conventional values of the instance 1125installation parameters, specify their values on the command-line: </p> 1126 1127<blockquote> 1128<pre> 1129# postmulti [-I postfix-myinst] [-G mygroup] -e create \ 1130 "config_directory = /path/to/config_directory" \ 1131 "queue_directory = /path/to/queue_directory" \ 1132 "data_directory = /path/to/data_directory" 1133</pre> 1134</blockquote> 1135 1136<p> A note on the <b>-I</b> and <b>-G</b> options above. These are always 1137used to assign a name or group name to an instance, while the <b>-i</b> 1138and <b>-g</b> options always select existing instances. By default, 1139the configuration directories of newly managed instances are appended 1140to the instance list. You can use the "-i" or "-g" or "-a" options to 1141insert the new instance before the specified instance or group, or at 1142the beginning of the instance list (multi_instance_directories parameter 1143of the default instance). </p> 1144 1145<p> If you do specify a name (use "-I" with a name that is not "-") 1146for the new instance, you may omit any of the 3 instance installation 1147parameters whose instance-name based value is acceptable. Otherwise, all 1148three instance installation parameters are required. You should set the 1149"syslog_name" explicitly in the main.cf file of a "nameless" instance, 1150in order to avoid confusion in the mail logs when multiple instances 1151are in use. </p> 1152 1153<h3><a name="destroy"> Destroying a Postfix instance </a></h3> 1154 1155<p> If you no longer need an instance, you can destroy it via: </p> 1156 1157<blockquote> 1158<pre> 1159# postmulti -i postfix-myinst -p stop 1160# postmulti -i postfix-myinst -e disable 1161# postmulti -i postfix-myinst -e destroy 1162</pre> 1163</blockquote> 1164 1165<p> The instance must be stopped, disabled and have no queued messages. 1166This is expected to fully delete a just created instance that has never 1167been used. If the instance is not freshly created, files added after 1168the instance was created will remain in the configuration, queue or 1169data directories, in which case the corresponding directory may not 1170be fully removed and a warning to that effect will be displayed. You 1171can complete the destruction of the instance manually by removing any 1172unwanted remnants of the instance-specific "private" directories. </p> 1173 1174<h3><a name="import"> Importing an existing Postfix instance </a></h3> 1175 1176<p> If you already have an existing secondary Postfix instance that is 1177not yet managed via postmulti(1), you can "import" it into the list 1178of managed instances. If your instance is already using the default 1179configuration directory naming scheme, just specify the corresponding 1180instance name (the multi_instance_name parameter in its configuration 1181file will be adjusted to match this name if necessary): </p> 1182 1183<blockquote> 1184<pre> 1185# postmulti -I postfix-myinst [-G mygroup] -e import 1186</pre> 1187</blockquote> 1188 1189<p> Otherwise, you must specify the location of its configuration 1190directory: </p> 1191 1192<blockquote> 1193<pre> 1194# postmulti [-I postfix-myinst] [-G mygroup] -e import \ 1195 "config_directory = /path/of/config_directory" 1196</pre> 1197</blockquote> 1198 1199<p> When the instance is imported, you can assign a name or a group. As 1200with <a href="#create">"create"</a>, you can control the placement of the 1201new instance in the start order by using "-i", "-g" or "-a" to prepend 1202before the selected instance or instances. </p> 1203 1204<p> An imported instance is usually not multi-instance "enabled", 1205unless it was part of a multi-instance configuration at an earlier 1206time. If it is fully configured and ready to run, don't forget 1207to <a href="#enable">enable</a> it and if necessary start it. When 1208other enabled instances are already running, new instances need to 1209be started individually when they are first created or imported. 1210</p> 1211 1212<p> To find out what instances are running, use: </p> 1213 1214<blockquote> 1215<pre> 1216# postfix status 1217</pre> 1218</blockquote> 1219 1220<h3><a name="deport"> Deporting a managed Postfix instance </a></h3> 1221 1222<p> You can "deport" an existing instance from the list of managed 1223instances. This does not destroy the instance, rather the instance 1224just becomes a stand-alone Postfix instance not registered with the 1225multi-instance manager. postmulti(1) will refuse to "deport" an 1226instance that is not stopped and disabled. </p> 1227 1228<blockquote> 1229<pre> 1230# postmulti -i postfix-myinst -p stop 1231# postmulti -i postfix-myinst -e disable 1232# postmulti -i postfix-myinst -e deport 1233</pre> 1234</blockquote> 1235 1236<h3><a name="assign"> Assigning a new name or group name </a></h3> 1237 1238<p> You can assign a new name or new group to a managed instance. 1239Use "-" as the new value to assign the instance to no group or make it 1240nameless. To specify a nameless secondary instance use the configuration 1241directory path instead of the old name: </p> 1242 1243<blockquote> 1244<pre> 1245# postmulti -i postfix-old [-I postfix-new] [-G newgroup] -e assign 1246</pre> 1247</blockquote> 1248 1249<h3><a name="enable"> Enabling/disabling managed instances </a></h3> 1250 1251<p> You can enable or disable a managed instance. As documented in 1252postfix-wrapper(5), disabled instances are skipped with actions 1253that <a href="postconf.5.html#postmulti_start_commands">start</a>, 1254<a href="postconf.5.html#postmulti_start_commands">stop</a> or <a 1255href="postconf.5.html#postmulti_control_commands">control</a> running 1256Postfix instances. </p> 1257 1258<blockquote> 1259<pre> 1260# postmulti -i postfix-myinst -e enable 1261# postmulti -i postfix-myinst -e disable 1262</pre> 1263</blockquote> 1264 1265<h2><a name="credits"> Credits </a></h2> 1266 1267<p> Wietse Venema created Postfix, designed and implemented the 1268multi-instance wrapper framework and provided design feedback that made 1269the postmulti(1) utility much more general and useful than originally 1270envisioned. </p> 1271 1272<p> The postmulti(1) utility was developed by Victor Duchovni of Morgan 1273Stanley, who also wrote the initial version of this document. </p> 1274 1275</body> </html> 1276
