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>Postfix Virtual Domain Hosting Howto</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="">Postfix 17Virtual Domain Hosting Howto</h1> 18 19<hr> 20 21<h2>Purpose of this document</h2> 22 23<p> This document requires Postfix version 2.0 or later. </p> 24 25<p> This document gives an overview of how Postfix can be used for 26hosting multiple Internet domains, both for final delivery on the 27machine itself and for the purpose of forwarding to destinations 28elsewhere. </p> 29 30<p> The text not only describes delivery mechanisms that are built 31into Postfix, but also gives pointers for using non-Postfix mail 32delivery software. </p> 33 34<p> The following topics are covered: </p> 35 36<ul> 37 38<li> <a href="#canonical">Canonical versus hosted versus other domains</a> 39 40<li> <a href="#local_vs_database">Local files versus network databases</a> 41 42<li> <a href="#local">As simple as can be: shared domains, 43UNIX system accounts</a> 44 45<li> <a href="#virtual_alias">Postfix virtual ALIAS example: 46separate domains, UNIX system accounts</a> 47 48<li> <a href="#virtual_mailbox">Postfix virtual MAILBOX example: 49separate domains, non-UNIX accounts</a> 50 51<li> <a href="#in_virtual_other">Non-Postfix mailbox store: separate 52domains, non-UNIX accounts</a> 53 54<li> <a href="#forwarding">Mail forwarding domains</a> 55 56<li> <a href="#mailing_lists">Mailing lists</a> 57 58<li> <a href="#autoreplies">Autoreplies</a> 59 60</ul> 61 62<h2><a name="canonical">Canonical versus hosted versus 63other domains</a></h2> 64 65<p>Most Postfix systems are <b>final destination</b> for only a 66few domain names. These include the hostnames and [the IP addresses] 67of the machine that Postfix runs on, and sometimes also include 68the parent domain of the hostname. The remainder of this document 69will refer to these domains as the canonical domains. They are 70usually implemented with the Postfix local domain address class, 71as defined in the ADDRESS_CLASS_README file.</p> 72 73<p> Besides the canonical domains, Postfix can be configured to be 74<b>final destination</b> for any number of additional domains. 75These domains are called hosted, because they are not directly 76associated with the name of the machine itself. Hosted domains are 77usually implemented with the virtual alias domain address class 78and/or with the virtual mailbox domain address class, as defined 79in the ADDRESS_CLASS_README file. </p> 80 81<p> But wait! There is more. Postfix can be configured as a backup 82MX host for other domains. In this case Postfix is <b>not the final 83destination</b> for those domains. It merely queues the mail when 84the primary MX host is down, and forwards the mail when the primary 85MX host becomes available. This function is implemented with the 86relay domain address class, as defined in the ADDRESS_CLASS_README 87file. </p> 88 89<p> Finally, Postfix can be configured as a transit host for sending 90mail across the internet. Obviously, Postfix is not final destination 91for such mail. This function is available only for authorized 92clients and/or users, and is implemented by the default domain 93address class, as defined in the ADDRESS_CLASS_README file. </p> 94 95<h2><a name="local_vs_database">Local files versus network databases</a></h2> 96 97<p> The examples in this text use table lookups from local files 98such as DBM or Berkeley DB. These are easy to debug with the 99<b>postmap</b> command: </p> 100 101<blockquote> 102Example: <tt>postmap -q info@example.com hash:/etc/postfix/virtual</tt> 103</blockquote> 104 105<p> See the documentation in LDAP_README, MYSQL_README and PGSQL_README 106for how to replace local files by databases. The reader is strongly 107advised to make the system work with local files before migrating 108to network databases, and to use the <b>postmap</b> command to verify 109that network database lookups produce the exact same results as 110local file lookup. </p> 111 112<blockquote> 113Example: <tt>postmap -q info@example.com ldap:/etc/postfix/virtual.cf</tt> 114</blockquote> 115 116<h2><a name="local">As simple as can be: shared domains, UNIX system 117accounts</a></h2> 118 119<p> The simplest method to host an additional domain is to add the 120domain name to the domains listed in the Postfix mydestination 121configuration parameter, and to add the user names to the UNIX 122password file. </p> 123 124<p> This approach makes no distinction between canonical and hosted 125domains. Each username can receive mail in every domain. </p> 126 127<p> In the examples we will use "example.com" as the domain that is 128being hosted on the local Postfix machine. </p> 129 130<blockquote> 131<pre> 132/etc/postfix/main.cf: 133 mydestination = $myhostname localhost.$mydomain ... example.com 134</pre> 135</blockquote> 136 137<p> The limitations of this approach are: </p> 138 139<ul> 140 141<li>A total lack of separation: mail for info@my.host.name is 142delivered to the same UNIX system account as mail for info@example.com. 143 144<li> With users in the UNIX password file, administration of large 145numbers of users becomes inconvenient. 146 147</ul> 148 149<p> The examples that follow provide solutions for both limitations. 150</p> 151 152<h2><a name="virtual_alias">Postfix virtual ALIAS example: 153separate domains, UNIX system accounts</a></h2> 154 155<p> With the approach described in this section, every hosted domain 156can have its own info etc. email address. However, it still uses 157UNIX system accounts for local mailbox deliveries. </p> 158 159<p> With virtual alias domains, each hosted address is aliased to 160a local UNIX system account or to a remote address. The example 161below shows how to use this mechanism for the example.com domain. 162</p> 163 164<blockquote> 165<pre> 166 1 /etc/postfix/main.cf: 167 2 virtual_alias_domains = example.com ...other hosted domains... 168 3 virtual_alias_maps = hash:/etc/postfix/virtual 169 4 170 5 /etc/postfix/virtual: 171 6 postmaster@example.com postmaster 172 7 info@example.com joe 173 8 sales@example.com jane 174 9 # Uncomment entry below to implement a catch-all address 17510 # @example.com jim 17611 ...virtual aliases for more domains... 177</pre> 178</blockquote> 179 180<p> Notes: </p> 181 182<ul> 183 184<li> <p> Line 2: the virtual_alias_domains setting tells Postfix 185that example.com is a so-called virtual alias domain. If you omit 186this setting then Postfix will reject mail (relay access denied) 187or will not be able to deliver it (mail for example.com loops back 188to myself). </p> 189 190<p> NEVER list a virtual alias domain name as a mydestination 191domain! </p> 192 193<li> <p> Lines 3-8: the /etc/postfix/virtual file contains the virtual 194aliases. With the example above, mail for postmaster@example.com 195goes to the local postmaster, while mail for info@example.com goes 196to the UNIX account joe, and mail for sales@example.com goes to 197the UNIX account jane. Mail for all other addresses in example.com 198is rejected with the error message "User unknown". </p> 199 200<li> <p> Line 10: the commented out entry (text after #) shows how 201one would implement a catch-all virtual alias that receives mail 202for every example.com address not listed in the virtual alias file. 203This is not without risk. Spammers nowadays try to send mail from 204(or mail to) every possible name that they can think of. A catch-all 205mailbox is likely to receive many spam messages, and many bounces 206for spam messages that were sent in the name of anything@example.com. 207</p> 208 209</ul> 210 211<p>Execute the command "<b>postmap /etc/postfix/virtual</b>" after 212changing the virtual file, and execute the command "<b>postfix 213reload</b>" after changing the main.cf file. </p> 214 215<p> Note: virtual aliases can resolve to a local address or to a 216remote address, or both. They don't have to resolve to UNIX system 217accounts on your machine. </p> 218 219<p> More details about the virtual alias file are given in the 220virtual(5) manual page, including multiple addresses on the right-hand 221side. </p> 222 223<p> Virtual aliasing solves one problem: it allows each domain to 224have its own info mail address. But there still is one drawback: 225each virtual address is aliased to a UNIX system account. As you 226add more virtual addresses you also add more UNIX system accounts. 227The next section eliminates this problem. </p> 228 229<h2><a name="virtual_mailbox">Postfix virtual MAILBOX example: 230separate domains, non-UNIX accounts</a></h2> 231 232<p> As a system hosts more and more domains and users, it becomes less 233desirable to give every user their own UNIX system account.</p> 234 235<p> With the Postfix virtual(8) mailbox delivery agent, every 236recipient address can have its own virtual mailbox. Unlike virtual 237alias domains, virtual mailbox domains do not need the clumsy 238translation from each recipient addresses into a different address, 239and owners of a virtual mailbox address do not need to have a UNIX 240system account.</p> 241 242<p> The Postfix virtual(8) mailbox delivery agent looks up the user 243mailbox pathname, uid and gid via separate tables that are searched 244with the recipient's mail address. Maildir style delivery is turned 245on by terminating the mailbox pathname with "/".</p> 246 247<p> If you find the idea of multiple tables bothersome, remember 248that you can migrate the information (once it works), to an SQL 249database. If you take that route, be sure to review the <a 250href="#local_vs_database"> "local files versus databases"</a> 251section at the top of this document.</p> 252 253<p> Here is an example of a virtual mailbox domain "example.com": 254</p> 255 256<blockquote> 257<pre> 258 1 /etc/postfix/main.cf: 259 2 virtual_mailbox_domains = example.com ...more domains... 260 3 virtual_mailbox_base = /var/mail/vhosts 261 4 virtual_mailbox_maps = hash:/etc/postfix/vmailbox 262 5 virtual_minimum_uid = 100 263 6 virtual_uid_maps = static:5000 264 7 virtual_gid_maps = static:5000 265 8 virtual_alias_maps = hash:/etc/postfix/virtual 266 9 26710 /etc/postfix/vmailbox: 26811 info@example.com example.com/info 26912 sales@example.com example.com/sales/ 27013 # Comment out the entry below to implement a catch-all. 27114 # @example.com example.com/catchall 27215 ...virtual mailboxes for more domains... 27316 27417 /etc/postfix/virtual: 27518 postmaster@example.com postmaster 276</pre> 277</blockquote> 278 279<p> Notes: </p> 280 281<ul> 282 283<li> <p> Line 2: The virtual_mailbox_domains setting tells Postfix 284that example.com is a so-called virtual mailbox domain. If you omit 285this setting then Postfix will reject mail (relay access denied) 286or will not be able to deliver it (mail for example.com loops back 287to myself). </p> 288 289<p> NEVER list a virtual MAILBOX domain name as a mydestination 290domain! </p> 291 292<p> NEVER list a virtual MAILBOX domain name as a virtual ALIAS 293domain! </p> 294 295<li> <p> Line 3: The virtual_mailbox_base parameter specifies a 296prefix for all virtual mailbox pathnames. This is a safety mechanism 297in case someone makes a mistake. It prevents mail from being 298delivered all over the file system. </p> 299 300<li> <p> Lines 4, 10-15: The virtual_mailbox_maps parameter specifies 301the lookup table with mailbox (or maildir) pathnames, indexed by 302the virtual mail address. In this example, mail for info@example.com 303goes to the mailbox at /var/mail/vhosts/example.com/info while mail 304for sales@example.com goes to the maildir located at 305/var/mail/vhosts/example.com/sales/. </p> 306 307<li> <p> Line 5: The virtual_minimum_uid specifies a lower bound 308on the mailbox or maildir owner's UID. This is a safety mechanism 309in case someone makes a mistake. It prevents mail from being written 310to sensitive files. </p> 311 312<li> <p> Lines 6, 7: The virtual_uid_maps and virtual_gid_maps 313parameters specify that all the virtual mailboxes are owned by a 314fixed uid and gid 5000. If this is not what you want, specify 315lookup tables that are searched by the recipient's mail address. 316</p> 317 318<li> <p> Line 14: The commented out entry (text after #) shows how 319one would implement a catch-all virtual mailbox address. Be prepared 320to receive a lot of spam, as well as bounced spam that was sent in 321the name of anything@example.com. </p> 322 323<p> NEVER put a virtual MAILBOX wild-card in the virtual ALIAS 324file!! </p> 325 326<li> <p> Lines 8, 17, 18: As you see, it is possible to mix virtual 327aliases with virtual mailboxes. We use this feature to redirect 328mail for example.com's postmaster address to the local postmaster. 329You can use the same mechanism to redirect an address to a remote 330address. </p> 331 332<li> <p> Line 18: This example assumes that in main.cf, $myorigin 333is listed under the mydestination parameter setting. If that is 334not the case, specify an explicit domain name on the right-hand 335side of the virtual alias table entries or else mail will go to 336the wrong domain. </p> 337 338</ul> 339 340<p> Execute the command "<b>postmap /etc/postfix/virtual</b>" after 341changing the virtual file, execute "<b>postmap /etc/postfix/vmailbox</b>" 342after changing the vmailbox file, and execute the command "<b>postfix 343reload</b>" after changing the main.cf file. </p> 344 345<p> Note: mail delivery happens with the recipient's UID/GID 346privileges specified with virtual_uid_maps and virtual_gid_maps. 347Postfix 2.0 and earlier will not create mailDIRs in world-writable 348parent directories; you must create them in advance before you can 349use them. Postfix may be able to create mailBOX files by itself, 350depending on parent directory write permissions, but it is safer 351to create mailBOX files ahead of time. </p> 352 353<p> More details about the virtual mailbox delivery agent are given 354in the virtual(8) manual page. </p> 355 356<h2><a name="in_virtual_other">Non-Postfix mailbox store: separate 357domains, non-UNIX accounts</a></h2> 358 359<p> This is a variation on the Postfix virtual mailbox example. 360Again, every hosted address can have its own mailbox. </p> 361 362<p> While non-Postfix software is being used for final delivery, 363some Postfix concepts are still needed in order to glue everything 364together. For additional background on this glue you may want to 365take a look at the virtual mailbox domain class as defined in the 366ADDRESS_CLASS_README file. </p> 367 368<p> The text in this section describes what things should look like 369from Postfix's point of view. See CYRUS_README or MAILDROP_README 370for specific information about Cyrus or about Courier maildrop. 371</p> 372 373<p> Here is an example for a hosted domain example.com that delivers 374to a non-Postfix delivery agent: </p> 375 376<blockquote> 377<pre> 378 1 /etc/postfix/main.cf: 379 2 virtual_transport = ...see below... 380 3 virtual_mailbox_domains = example.com ...more domains... 381 4 virtual_mailbox_maps = hash:/etc/postfix/vmailbox 382 5 virtual_alias_maps = hash:/etc/postfix/virtual 383 6 384 7 /etc/postfix/vmailbox: 385 8 info@example.com whatever 386 9 sales@example.com whatever 38710 # Comment out the entry below to implement a catch-all. 38811 # Configure the mailbox store to accept all addresses. 38912 # @example.com whatever 39013 ...virtual mailboxes for more domains... 39114 39215 /etc/postfix/virtual: 39316 postmaster@example.com postmaster 394</pre> 395</blockquote> 396 397<p> Notes: </p> 398 399<ul> 400 401<li> <p> Line 2: With delivery to a non-Postfix mailbox store for 402hosted domains, the virtual_transport parameter usually specifies 403the Postfix LMTP client, or the name of a master.cf entry that 404executes non-Postfix software via the pipe delivery agent. Typical 405examples (use only one): </p> 406 407<blockquote> 408<pre> 409virtual_transport = lmtp:unix:/path/name (uses UNIX-domain socket) 410virtual_transport = lmtp:hostname:port (uses TCP socket) 411virtual_transport = maildrop: (uses pipe(8) to command) 412</pre> 413</blockquote> 414 415<p> Postfix comes ready with support for LMTP. And an example 416maildrop delivery method is already defined in the default Postfix 417master.cf file. See the MAILDROP_README document for more details. 418</p> 419 420<li> <p> Line 3: The virtual_mailbox_domains setting tells Postfix 421that example.com is delivered via the virtual_transport that was 422discussed in the previous paragraph. If you omit this 423virtual_mailbox_domains setting then Postfix will either reject 424mail (relay access denied) or will not be able to deliver it (mail 425for example.com loops back to myself). </p> 426 427<p> NEVER list a virtual MAILBOX domain name as a mydestination 428domain! </p> 429 430<p> NEVER list a virtual MAILBOX domain name as a virtual ALIAS 431domain! </p> 432 433<li> <p> Lines 4, 7-13: The virtual_mailbox_maps parameter specifies 434the lookup table with all valid recipient addresses. The lookup 435result value is ignored by Postfix. In the above example, 436info@example.com 437and sales@example.com are listed as valid addresses; other mail for 438example.com is rejected with "User unknown" by the Postfix SMTP 439server. It's left up to the non-Postfix delivery agent to reject 440non-existent recipients from local submission or from local alias 441expansion. If you intend to 442use LDAP, MySQL or PgSQL instead of local files, be sure to review 443the <a href="#local_vs_database"> "local files versus databases"</a> 444section at the top of this document! </p> 445 446<li> <p> Line 12: The commented out entry (text after #) shows how 447one would inform Postfix of the existence of a catch-all address. 448Again, the lookup result is ignored by Postfix. </p> 449 450<p> NEVER put a virtual MAILBOX wild-card in the virtual ALIAS 451file!! </p> 452 453<p> Note: if you specify a wildcard in virtual_mailbox_maps, then 454you still need to configure the non-Postfix mailbox store to receive 455mail for any address in that domain. </p> 456 457<li> <p> Lines 5, 15, 16: As you see above, it is possible to mix 458virtual aliases with virtual mailboxes. We use this feature to 459redirect mail for example.com's postmaster address to the local 460postmaster. You can use the same mechanism to redirect any addresses 461to a local or remote address. </p> 462 463<li> <p> Line 16: This example assumes that in main.cf, $myorigin 464is listed under the mydestination parameter setting. If that is 465not the case, specify an explicit domain name on the right-hand 466side of the virtual alias table entries or else mail will go to 467the wrong domain. </p> 468 469</ul> 470 471<p> Execute the command "<b>postmap /etc/postfix/virtual</b>" after 472changing the virtual file, execute "<b>postmap /etc/postfix/vmailbox</b>" 473after changing the vmailbox file, and execute the command "<b>postfix 474reload</b>" after changing the main.cf file. </p> 475 476<h2><a name="forwarding">Mail forwarding domains</a></h2> 477 478<p> Some providers host domains that have no (or only a few) local 479mailboxes. The main purpose of these domains is to forward mail 480elsewhere. The following example shows how to set up example.com 481as a mail forwarding domain: </p> 482 483<blockquote> 484<pre> 485 1 /etc/postfix/main.cf: 486 2 virtual_alias_domains = example.com ...other hosted domains... 487 3 virtual_alias_maps = hash:/etc/postfix/virtual 488 4 489 5 /etc/postfix/virtual: 490 6 postmaster@example.com postmaster 491 7 joe@example.com joe@somewhere 492 8 jane@example.com jane@somewhere-else 493 9 # Uncomment entry below to implement a catch-all address 49410 # @example.com jim@yet-another-site 49511 ...virtual aliases for more domains... 496</pre> 497</blockquote> 498 499<p> Notes: </p> 500 501<ul> 502 503<li> <p> Line 2: The virtual_alias_domains setting tells Postfix 504that example.com is a so-called virtual alias domain. If you omit 505this setting then Postfix will reject mail (relay access denied) 506or will not be able to deliver it (mail for example.com loops back 507to myself). </p> 508 509<p> NEVER list a virtual alias domain name as a mydestination 510domain! </p> 511 512<li> <p> Lines 3-11: The /etc/postfix/virtual file contains the 513virtual aliases. With the example above, mail for postmaster@example.com 514goes to the local postmaster, while mail for joe@example.com goes 515to the remote address joe@somewhere, and mail for jane@example.com 516goes to the remote address jane@somewhere-else. Mail for all other 517addresses in example.com is rejected with the error message "User 518unknown". </p> 519 520<li> <p> Line 10: The commented out entry (text after #) shows how 521one would implement a catch-all virtual alias that receives mail 522for every example.com address not listed in the virtual alias file. 523This is not without risk. Spammers nowadays try to send mail from 524(or mail to) every possible name that they can think of. A catch-all 525mailbox is likely to receive many spam messages, and many bounces 526for spam messages that were sent in the name of anything@example.com. 527</p> 528 529</ul> 530 531<p> Execute the command "<b>postmap /etc/postfix/virtual</b>" after 532changing the virtual file, and execute the command "<b>postfix 533reload</b>" after changing the main.cf file. </p> 534 535<p> More details about the virtual alias file are given in the 536virtual(5) manual page, including multiple addresses on the right-hand 537side. </p> 538 539<h2><a name="mailing_lists">Mailing lists</a></h2> 540 541<p> The examples that were given above already show how to direct 542mail for virtual postmaster addresses to a local postmaster. You 543can use the same method to direct mail for any address to a local 544or remote address. </p> 545 546<p> There is one major limitation: virtual aliases and virtual 547mailboxes can't directly deliver to mailing list managers such as 548majordomo. The solution is to set up virtual aliases that direct 549virtual addresses to the local delivery agent: </p> 550 551<blockquote> 552<pre> 553/etc/postfix/main.cf: 554 virtual_alias_maps = hash:/etc/postfix/virtual 555 556/etc/postfix/virtual: 557 listname-request@example.com listname-request 558 listname@example.com listname 559 owner-listname@example.com owner-listname 560 561/etc/aliases: 562 listname: "|/some/where/majordomo/wrapper ..." 563 owner-listname: ... 564 listname-request: ... 565</pre> 566</blockquote> 567 568<p> This example assumes that in main.cf, $myorigin is listed under 569the mydestination parameter setting. If that is not the case, 570specify an explicit domain name on the right-hand side of the 571virtual alias table entries or else mail will go to the wrong 572domain. </p> 573 574<p> More information about the Postfix local delivery agent can be 575found in the local(8) manual page. </p> 576 577<p> Why does this example use a clumsy virtual alias instead of a 578more elegant transport mapping? The reason is that mail for the 579virtual mailing list would be rejected with "User unknown". In 580order to make the transport mapping work one would still need a 581bunch of virtual alias or virtual mailbox table entries. </p> 582 583<ul> 584 585<li> In case of a virtual alias domain, there would need to be one 586identity mapping from each mailing list address to itself. 587 588<li> In case of a virtual mailbox domain, there would need to be 589a dummy mailbox for each mailing list address. 590 591</ul> 592 593<h2><a name="autoreplies">Autoreplies</a></h2> 594 595<p> In order to set up an autoreply for virtual recipients while 596still delivering mail as normal, set up a rule in a virtual alias 597table: </p> 598 599<blockquote> 600<pre> 601/etc/postfix/main.cf: 602 virtual_alias_maps = hash:/etc/postfix/virtual 603 604/etc/postfix/virtual: 605 user@domain.tld user@domain.tld, user@domain.tld@autoreply.mydomain.tld 606</pre> 607</blockquote> 608 609<p> This delivers mail to the recipient, and sends a copy of the 610mail to the address that produces automatic replies. The address 611can be serviced on a different machine, or it can be serviced 612locally by setting up a transport map entry that pipes all mail 613for autoreply.mydomain.tld into some script that sends an automatic 614reply back to the sender. </p> 615 616<p> DO NOT list autoreply.mydomain.tld in mydestination! </p> 617 618<blockquote> 619<pre> 620/etc/postfix/main.cf: 621 transport_maps = hash:/etc/postfix/transport 622 623/etc/postfix/transport: 624 autoreply.mydomain.tld autoreply: 625 626/etc/postfix/master.cf: 627 # ============================================================= 628 # service type private unpriv chroot wakeup maxproc command 629 # (yes) (yes) (yes) (never) (100) 630 # ============================================================= 631 autoreply unix - n n - - pipe 632 flags= user=nobody argv=/path/to/autoreply $sender $mailbox 633</pre> 634</blockquote> 635 636<p> This invokes /path/to/autoreply with the sender address and 637the user@domain.tld recipient address on the command line. </p> 638 639<p> For more information, see the pipe(8) manual page, and the 640comments in the Postfix master.cf file. </p> 641 642</body> 643 644</html> 645
