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