postfix-master/MULTI_INSTANCE_README.html

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