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 17multiple 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 24on a single host using the <a href="postmulti.1.html">postmulti(1)</a> instance manager. Multi-instance 25support 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 27management 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 57to 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 74services, but a complex interplay of settings may be required, for 75example with <a href="master.5.html">master.cf</a> options overriding <a href="postconf.5.html">main.cf</a> settings. In this 76document we take the view that multiple Postfix instances may be a 77simpler way to configure a multi-function Postfix system. With 78multiple Postfix instances, each instance has its own directories 79for configuration, queue and data files, but it shares all Postfix 80program and documentation files with other instances. </p> 81 82<p> Since there is no single right way to configure your system, 83we recommend that you choose what makes you most comfortable. If 84different 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 86complex tricks, then a single monolithic configuration may be the 87simplest approach. </p> 88 89<p> The purpose of multi-instance support in Postfix is not to force 90you to create multiple Postfix instances, but rather to give you a 91choice. Multiple instances give you the freedom to tune each Postfix 92instance to a single task that it does well and to combine instances 93into complete systems. </p> 94 95<p> With the introduction of the <a href="postmulti.1.html">postmulti(1)</a> utility and the reduction 96of the per-instance configuration footprint of a secondary Postfix 97instance 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 98shared locations), we hope that multiple instances will be easier to 99use 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 104simplification 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 109send status reports, and so that system users can send email with 110command-line utilities. Such email can be handled with a <a 111href="STANDARD_CONFIGURATION_README.html#null_client">null-client</a> 112Postfix configuration that forwards all mail to a central mail hub. 113The null client will typically either not run an SMTP listener at 114all (<a href="postconf.5.html#master_service_disable">master_service_disable</a> = inet), or it will listen only on the 115loopback interface (<a href="postconf.5.html#inet_interfaces">inet_interfaces</a> = loopback-only). </p> 116 117<p> When implementing specialized servers for inbound Internet 118email, outbound MTAs, internal mail hubs, and so on, we recommend 119using a null client for local submission and creating single-function 120secondary 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 125when you run multiple instances on the same host. Otherwise, there 126will be false "mail loops back to myself" alarms when one instance 127tries to send mail into another instance. Typically, the null-client 128instance will use the system's hostname, and other instances will 129use their own dedicated "<a href="postconf.5.html#myhostname">myhostname</a>" settings. Different names are 130not needed when instances send mail to each other with a protocol 131other than SMTP, or with SMTP over a TCP port other than 25 as is 132usual 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 139we first show the steps for creating a border mail server. This 140server has with a null-client Postfix instance for local submission, 141an input Postfix instance to receive mail from the Internet, plus 142an <a href="FILTER_README.html#advanced_filter">advanced</a> SMTP 143content-filter and an output Postfix instance to deliver filtered 144email 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 149great deal of scrutiny, locally submitted messages are typically 150limited to mail from cron jobs and other system services. In this 151regard the border MTA is not different from other Unix hosts in 152your environment. For this reason, it will submit locally-generated 153email to the internal mail hub. We start the construction of the 154border mail server with the <a href="#default_instance">default</a> 155instance, which will be a local-submission <a 156href="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 224creates 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` > $@.tmp 237 @mv $@.tmp generic 238 239 %.<a href="CDB_README.html">cdb</a>: % 240 postmap <a href="CDB_README.html">cdb</a>:$< 241</pre> 242</blockquote> 243 244<p> Construct the "virtual" and "generic" databases (the latter is 245created 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 <<EOF 253From: root 254To: root 255Subject: test 256 257testing 258EOF 259</pre> 260</blockquote> 261 262<p> The test message should be delivered the members of the "mtaadmin" 263address group (or whatever address group you choose) with the 264following headers: </p> 265 266<blockquote> 267<pre> 268From: mtaadmin+root=mta1@example.com 269To: mtadmin+root=mta1@example.com 270Subject: 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 277MTA "output" instance that will deliver filtered mail to the inside 278network. We add the "output" instance first, because the output 279instance needs to be up and running before the input instance can 280be fully tested, and when the system boots, the "output" instance 281must start before the input instance. We will put the output and 282input instances into a single instance group named "mta". </p> 283 284<p> Just once, when adding the first secondary instance, enable 285multi-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, 302more precisely, the "postfix-out" subdirectory of the parent directory 303of the default-instance configuration directory. The new instance will 304be 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 323data directories, also named "postfix-out", will be located in the 324same parent directories as the corresponding directories of the 325default 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 329usefully configured. It needs to be customized to fit the role of a 330post-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 406instance: </p> 407 408<blockquote> 409<pre> 4101 # postmulti -i postfix-out -x postconf -e \ 4112 "<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" 4123 # postmulti -i postfix-out -e enable 4134 # 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 418context (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 423superuser can test the postix-out instance with "postmulti -i 424postfix-out -x sendmail -bv recipient...", but otherwise local 425submission 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" 428listeners are re-enabled. </p> 429 430<li> <p> Line 3: The output instance is enabled for multi-instance 431start/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 439should be done on a lab system. The simple tests just suggested will only 440confirm successful deployment of a configuration that should already be 441known good. </p> 442 443<h3> Setting up the content-filter proxy </h3> 444 445<p> With the output instance ready, deploy your content-filter 446proxy. Most proxies will need their own /etc/rc* start/stop script. 447Some proxies, however, are started on demand by the Postfix <a href="spawn.8.html">spawn(8)</a> 448service, in which case you need to add the relevant <a href="spawn.8.html">spawn(8)</a> entry 449to 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 452filtered email to 127.0.0.1:10026. Start the proxy service if 453necessary, then test the proxy via "telnet" or automated SMTP 454injectors. The proxy should support the following ESMTP features: 455DSN, 8BITMIME, and XFORWARD. In addition, the proxy should support 456multiple 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 461sends it through the content filter. Now we create the input instance, 462also 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, 471more precisely, the "postfix-in" subdirectory of the parent directory 472of the default-instance configuration directory. The new instance will 473be 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 492make the instance production ready. Consider setting "<a href="postconf.5.html#soft_bounce">soft_bounce</a> = yes" 493during 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 508href="XCLIENT_README.html">XCLIENT</a> SMTP command to safely 509simulate connections from remote systems before any remote systems 510are able to connect. If the test results look good, revert the above 511settings to the required production values. Typical settings in the 512pre-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 582sending 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 584content-filter, and then deliver it to the internal destination. </p> 585 586<p> Running "postfix start" or "postfix stop" will now start/stop all 587three Postfix instances. You can use "postfix -c /config/path start" 588to start just one instance, or use the instance name (or instance 589group 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 602of this document provides background information on Postfix 603multi-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 624with a protected (non-root) execution context. The $<a href="postconf.5.html#setgid_group">setgid_group</a> group 625is used exclusively to support the setgid <a href="postdrop.1.html">postdrop(1)</a> and <a href="postqueue.1.html">postqueue(1)</a> 626utilities (it <b>must not</b> be the primary group or secondary group 627of 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 636files 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> 639in $<a href="postconf.5.html#queue_directory">queue_directory</a> (which contains additional directories needed 640by Postfix, and which optionally doubles as a chroot jail for Postfix 641daemon processes). </p> 642 643<li> <p> Various caches (TLS session, address verification, ...) 644in $<a href="postconf.5.html#data_directory">data_directory</a>. </p> 645 646</ul> 647 648<p> The Postfix configuration parameters mentioned above are 649collectively referred to as "installation parameters". Their default 650values are set when the Postfix software is built from source, and 651all 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 657most of the other command-line Postfix utilities allow you to specify a 658non-default configuration directory via a command line option (typically 659<b>-c</b>) or via the MAIL_CONFIG environment variable. In this way, 660it is possible to have multiple configuration directories on the same 661machine, and to have multiple running <a href="master.8.html">master(8)</a> daemons each with its 662own 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 665software. They do not (and cannot) share their configuration 666directories, queue directories or data directories. </p> 667 668<p> Each combination of configuration directory, together with the queue 669directory and data directory (specified in the corresponding <a href="postconf.5.html">main.cf</a> file) 670make 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 675configuration directory is the default one compiled into the Postfix 676utilities. The location of the default configuration directory is 677typically /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 679directory the "default instance". </p> 680 681<p> The default instance is responsible for local mail submission. The 682setgid <a href="postdrop.1.html">postdrop(1)</a> utility is used by the <a href="sendmail.1.html">sendmail(1)</a> local submission 683program to spool messages into the <b>maildrop</b> sub-directory of the 684queue directory of the default instance. </p> 685 686<p> Even in the rare case when "sendmail -C" is used to submit local mail 687into a non-default Postfix instance, for security reasons, <a href="postdrop.1.html">postdrop(1)</a> 688will consult the default <a href="postconf.5.html">main.cf</a> file to check the validity of the 689requested non-default configuration directory. </p> 690 691<p> So, while in most other respects, all instances are equal, the 692default instance is "more equal than others". You may choose to create 693additional instances, but you must have at least the default instance, 694with 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 699instance "group". Typically, the member instances of an instance group 700constitute a logical service, and are expected to all be running or all 701be 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 705that are not members of any instance "group". The null-client 706instance is an example of a non-group instance. </p> 707 708<p> When a logical service consists of multiple Postfix instances, 709often a pair of pre-filter and post-filter instances with a content 710filter proxy between them, the related instances should be members 711of a single instance group (however, the content filter usually has 712its own start/stop procedure that is separate from any Postfix 713instance). </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> 716configuration parameter lists the configuration directories of all 717secondary (non-default) instances. Together with the default instance, 718these secondary instances are managed by the multi-instance manager. 719Instances are started in the order listed, and stopped in the 720opposite order. For instances that are members of a service "group", 721you should arrange to start the service back-to-front, with the 722output stages started and ready to receive mail before the input 723stages 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 732to a suitable multi-instance manager's "wrapper" program that 733controls the starting, stopping, etc. of a multi-instance Postfix 734system. To use the <a href="postmulti.1.html">postmulti(1)</a> manager described in this document, 735this 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 741an optional list of the secondary instances controlled via the 742multi-instance manager. Instances are listed in their "start" order, 743with 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 745runs with multi-instance support turned off, and none of the 746multi_instance_ configuration parameters will have any effect. </p> 747 748<p> Do not assign a non-empty list of secondary instance configuration 749directories to <a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> until you have configured a 750suitable <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> setting! This is best accomplished via 751the "<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 758be used with the <a href="postmulti.1.html">postmulti(1)</a> command-line utility to perform tasks 759on the instance by name (rather than the full pathname of its 760configuration directory). Choose a name that concisely captures the 761role of the instance (it must start with "postfix-"). It is an 762error for two instances to have the same $<a href="postconf.5.html#multi_instance_name">multi_instance_name</a>. You 763can leave an instance "nameless" by leaving this parameter at the 764default empty setting. </p> 765 766<p> To avoid confusion in your logs, if you don't assign each 767secondary instance a non-empty (distinct) $<a href="postconf.5.html#multi_instance_name">multi_instance_name</a>, you 768should make sure that the $<a href="postconf.5.html#syslog_name">syslog_name</a> setting is different for 769each 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> 770when the latter is non-empty. If at all possible, the <a href="postconf.5.html#syslog_name">syslog_name</a> 771should start with "postfix-", this helps log parsers to identify 772log 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" 777name (with "postfix -e create/import/assign -G <i>name</i>..."). 778The default (empty) value of <a href="postconf.5.html#multi_instance_group">multi_instance_group</a> parameter indicates 779a stand-alone instance that is not part of any group. The group 780name can be used with the <a href="postmulti.1.html">postmulti(1)</a> command-line utility to 781perform a task on the members of a group by name. Choose a single-word 782group 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 788be started by a Postfix multi-instance manager. The default value 789is "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 793is replaced by "check". </p> 794 795<p> Some <a href="postfix.1.html">postfix(1)</a> commands (such as "stop", "flush", ...) require 796a 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 801system, 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. 807It can also be used to "import" or "deport" existing instances into or 808from the list of managed instances. When using <a href="postmulti.1.html">postmulti(1)</a> to manage 809instances, the above configuration parameters are managed for you 810automatically. 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 841it as the <a href="postconf.5.html#multi_instance_wrapper">multi_instance_wrapper</a> for your Postfix system and enable 842multi-instance operation of the default Postfix instance. You can then 843proceed to add <a href="#create">new</a> or <a href="#import">existing</a> 844instances to the multi-instance configuration. This initial installation 845is 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 873the 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 875default <a href="postconf.5.html">main.cf</a> configuration file. </p> 876 877<p> You can list selected instances, groups of instances or all 878instances by specifying only the instance matching options with the 879"-l" option. The "-a" option is assumed if no other instance 880selection options are specified (this behavior changes with the 881"-e" option). As a special case, even if it has an explicit name, 882the 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 900align="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 920output. When either the instance name or the instance group is not 921set, it is shown as a "-". </p> 922 923<p> When selecting an existing instance via the "-i" option, you 924can always use the full pathname of its configuration directory 925instead of the instance (short) name. This is the only way to select 926a non-default nameless instance. The default instance can be selected 927via "-i -", whether it has a name or not. </p> 928 929<p> To list instances in reverse start order, include the "-R" 930option 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 936above) multi-instance system just use <a href="postfix.1.html">postfix(1)</a> as you would with a 937single-instance system. The Postfix multi-instance wrapper framework 938insulates Postfix init.d start and package upgrade scripts from the 939details 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 942mode. With this option the remaining arguments are exactly those supported 943by <a href="postfix.1.html">postfix(1)</a>, but commands are applied to all instances or all enabled 944instances as appropriate. As described above, this switch is required 945when 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, 948or run arbitrary commands (not just "postfix stop/start/etc. in the 949context (MAIL_CONFIG environment variable setting) of a particular 950instance 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 956commands in the context of one or more Postfix instances. The most common 957use-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 972turned on depending on the first argument. In the case of "start", 973disabled instances are "checked" (postfix check) rather than simply 974skipped. </p> 975 976<p> The resulting command is executed for each candidate instance with 977the <b>MAIL_CONFIG</b> environment variable set to the configuration 978directory 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 982ad-hoc command for all instances, a group of instances, or just one 983instance. With ad-hoc commands the <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> parameter 984is ignored: the command is unconditionally executed for the instances 985selected via -a, -g or -i. In addition to MAIL_CONFIG, the following 986instance 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, 1002and is arguably redundant, but leaving it in is less surprising. If 1003you want to skip disabled instances, just check <a href="postconf.5.html#multi_instance_enable">multi_instance_enable</a> 1004environment 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 1007possibilities: </p> 1008 1009<ul> 1010 1011<li><p> Specify an instance by name rather than configuration directory 1012when 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. 1021This uses an inline shell script to package together multiple shell 1022commands 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 && 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 1053instances. New instances are created with local submission and all "inet" 1054services disabled via the following non-default parameter settings in 1055the <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 1065immediately: they will not conflict with inet listeners in existing 1066Postfix instances. They will also not accept any mail until they are 1067fully configured, at which point you can do away with one or both of 1068the above safety measures. </p> 1069 1070<p> The <a href="postmulti.1.html">postmulti(1)</a> command encourages a preferred way of organizing 1071the configuration directories, queue directories and data directories 1072of 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 1083have: </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, 1096but unless you want to spread instance queue directories over multiple 1097file-systems, use the default naming strategy. It keeps the multiple 1098instances organized in a uniform, predictable fashion. </p> 1099 1100<p> When specifying the instance name later, you can refer to it 1101either as "postfix-myinst", or via the full path of the configuration 1102directory. </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 1113implement 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 1122installation 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 1134used to assign a name or group name to an instance, while the <b>-i</b> 1135and <b>-g</b> options always select existing instances. By default, 1136the configuration directories of newly managed instances are appended 1137to the instance list. You can use the "-i" or "-g" or "-a" options to 1138insert the new instance before the specified instance or group, or at 1139the beginning of the instance list (<a href="postconf.5.html#multi_instance_directories">multi_instance_directories</a> parameter 1140of the default instance). </p> 1141 1142<p> If you do specify a name (use "-I" with a name that is not "-") 1143for the new instance, you may omit any of the 3 instance installation 1144parameters whose instance-name based value is acceptable. Otherwise, all 1145three 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, 1147in order to avoid confusion in the mail logs when multiple instances 1148are 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. 1163This is expected to fully delete a just created instance that has never 1164been used. If the instance is not freshly created, files added after 1165the instance was created will remain in the configuration, queue or 1166data directories, in which case the corresponding directory may not 1167be fully removed and a warning to that effect will be displayed. You 1168can complete the destruction of the instance manually by removing any 1169unwanted 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 1174not yet managed via <a href="postmulti.1.html">postmulti(1)</a>, you can "import" it into the list 1175of managed instances. If your instance is already using the default 1176configuration directory naming scheme, just specify the corresponding 1177instance name (the <a href="postconf.5.html#multi_instance_name">multi_instance_name</a> parameter in its configuration 1178file 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 1187directory: </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 1197with <a href="#create">"create"</a>, you can control the placement of the 1198new instance in the start order by using "-i", "-g" or "-a" to prepend 1199before the selected instance or instances. </p> 1200 1201<p> An imported instance is usually not multi-instance "enabled", 1202unless it was part of a multi-instance configuration at an earlier 1203time. If it is fully configured and ready to run, don't forget 1204to <a href="#enable">enable</a> it and if necessary start it. When 1205other enabled instances are already running, new instances need to 1206be 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 1220instances. This does not destroy the instance, rather the instance 1221just becomes a stand-alone Postfix instance not registered with the 1222multi-instance manager. <a href="postmulti.1.html">postmulti(1)</a> will refuse to "deport" an 1223instance 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. 1236Use "-" as the new value to assign the instance to no group or make it 1237nameless. To specify a nameless secondary instance use the configuration 1238directory 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 1250that <a href="postconf.5.html#postmulti_start_commands">start</a>, 1251<a href="postconf.5.html#postmulti_start_commands">stop</a> or <a 1252href="postconf.5.html#postmulti_control_commands">control</a> running 1253Postfix 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 1265multi-instance wrapper framework and provided design feedback that made 1266the <a href="postmulti.1.html">postmulti(1)</a> utility much more general and useful than originally 1267envisioned. </p> 1268 1269<p> The <a href="postmulti.1.html">postmulti(1)</a> utility was developed by Victor Duchovni of Morgan 1270Stanley, who also wrote the initial version of this document. </p> 1271 1272</body> </html> 1273