/[gentoo]/xml/htdocs/doc/en/virt-mail-howto.xml
Gentoo

Diff of /xml/htdocs/doc/en/virt-mail-howto.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.56 Revision 1.57
1<?xml version='1.0' encoding='UTF-8'?> 1<?xml version='1.0' encoding='UTF-8'?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.56 2007/07/20 09:09:04 nightmorph Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.57 2007/07/23 15:44:42 swift Exp $ -->
3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 3<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4 4
5<guide link="/doc/en/virt-mail-howto.xml"> 5<guide link="/doc/en/virt-mail-howto.xml">
6<title>Virtual Mailhosting System with Postfix Guide</title> 6<title>Virtual Mailhosting System with Postfix Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="antifa@gentoo.org">Ken Nowack</mail> 9 <mail link="antifa@gentoo.org">Ken Nowack</mail>
10</author> 10</author>
11<author title="Author"> 11<author title="Author">
12 <mail link="ezra@revoltltd.org">Ezra Gorman</mail> 12 <mail link="ezra@revoltltd.org">Ezra Gorman</mail>
13</author> 13</author>
14<author title="Editor"> 14<author title="Editor">
15 <mail link="klasikahl@gentoo.org">Zack Gilburd</mail> 15 <mail link="klasikahl@gentoo.org">Zack Gilburd</mail>
16</author> 16</author>
17<author title="Editor"> 17<author title="Editor">
18 <mail link="seather@scygro.za.net">Scygro</mail> 18 <mail link="seather@scygro.za.net">Scygro</mail>
19</author> 19</author>
20<author title="Editor"> 20<author title="Editor">
21 <mail link="swift@gentoo.org">Sven Vermeulen</mail> 21 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
22</author> 22</author>
23 23
24<abstract> 24<abstract>
25This document details how to create a virtual mailhosting system based upon 25This document details how to create a virtual mailhosting system based upon
26postfix, mysql, courier-imap, and cyrus-sasl. 26postfix, mysql, courier-imap, and cyrus-sasl.
27</abstract> 27</abstract>
28 28
29<version>1.4</version> 29<version>1.5</version>
30<date>2007-07-20</date> 30<date>2007-07-23</date>
31
32<!--
33Contents
34
35I. Introduction
36II. Postfix Basics
37III. Courier-imap
38IV. Cyrus-sasl
39V. SSL Certificates for Postfix and Apache
40VI. Adding SSL and SASL support to Postfix
41VII. MySQL
42VIII. Apache and phpMyAdmin
43IX. The vmail user
44X. Configuring MySQL Authentication and vhosts
45XI. Squirrelmail
46XII. Mailman
47XIII. Content Filtering and Anti-Virus
48XIV. Wrap Up
49XV. Troubleshooting
50-->
51 31
52<chapter> 32<chapter>
53<title>Introduction</title> 33<title>Introduction</title>
54<section> 34<section>
55<body> 35<body>
56 36
57<p> 37<p>
58For most Gentoo users, a simple mail client and fetchmail will do. However, if 38For most Gentoo users, a simple mail client and fetchmail will do. However, if
59you're hosting a domain with your system, you'll need a full blown MTA (Mail 39you're hosting a domain with your system, you'll need a full blown MTA (Mail
60Transfer Agent). And if you're hosting multiple domains, then you'll definitely 40Transfer Agent). And if you're hosting multiple domains, then you'll definitely
61need something more robust to handle all of the email for your users. This 41need something more robust to handle all of the email for your users. This
62system was designed to be an elegant solution to that problem. 42system was designed to be an elegant solution to that problem.
63</p> 43</p>
64 44
65<p> 45<p>
372smtpd_tls_cert_file = /etc/postfix/newcert.pem 352smtpd_tls_cert_file = /etc/postfix/newcert.pem
373smtpd_tls_CAfile = /etc/postfix/cacert.pem 353smtpd_tls_CAfile = /etc/postfix/cacert.pem
374smtpd_tls_loglevel = 3 354smtpd_tls_loglevel = 3
375smtpd_tls_received_header = yes 355smtpd_tls_received_header = yes
376smtpd_tls_session_cache_timeout = 3600s 356smtpd_tls_session_cache_timeout = 3600s
377tls_random_source = dev:/dev/urandom 357tls_random_source = dev:/dev/urandom
378 358
379<comment>(smtpd_tls_auth_only is commented out to ease testing the system. 359<comment>(smtpd_tls_auth_only is commented out to ease testing the system.
380You can turn this on later if you desire.)</comment> 360You can turn this on later if you desire.)</comment>
381 361
382# <i>postfix reload</i> 362# <i>postfix reload</i>
383</pre> 363</pre>
384 364
385<p> 365<p>
386Now we're going to verify that the config's we added were picked up by postfix. 366Now we're going to verify that the config's we added were picked up by postfix.
367For this we are going to use <c>telnet</c> (provided by for instance
368<c>net-misc/netkit-telnetd</c>) although you can also use <c>nc</c> (provided by
369<c>net-analyzer/netcat</c>):
387</p> 370</p>
388 371
389<pre caption="Verifying sasl and tls support"> 372<pre caption="Verifying sasl and tls support">
390# <i>telnet localhost 25</i> 373# <i>telnet localhost 25</i>
391 374
392Trying 127.0.0.1... 375Trying 127.0.0.1...
393Connected to localhost. 376Connected to localhost.
394Escape character is '^]'. 377Escape character is '^]'.
395220 mail.domain.com ESMTP Postfix 378220 mail.domain.com ESMTP Postfix
396<i>EHLO domain.com</i> 379<i>EHLO domain.com</i>
397250-mail.domain.com 380250-mail.domain.com
398250-PIPELINING 381250-PIPELINING
399250-SIZE 10240000 382250-SIZE 10240000
400250-VRFY 383250-VRFY
401250-ETRN 384250-ETRN
409</pre> 392</pre>
410 393
411<p> 394<p>
412Verify that the above AUTH and STARTTLS lines now appear in your postfix 395Verify that the above AUTH and STARTTLS lines now appear in your postfix
413install. As I said before, as it stands now AUTH will not work. that's because 396install. As I said before, as it stands now AUTH will not work. that's because
414sasl will try to auth against it's sasldb, instead of the shadow file for some 397sasl will try to auth against it's sasldb, instead of the shadow file for some
415unknown reason, which we have not set up. So we're going to just plow through 398unknown reason, which we have not set up. So we're going to just plow through
416and set up mysql to hold all of our auth and virtual domain information. 399and set up mysql to hold all of our auth and virtual domain information.
417</p> 400</p>
418 401
419</body> 402</body>
420</section> 403</section>
421</chapter> 404</chapter>
422 405
423<chapter> 406<chapter>
407<title>The vmail user</title>
408<section>
409<body>
410
411<p>
412Before we set up our virtual mailhosting environment, we create a functional
413user under which the virtual mailboxes will be hosted. For clarity's sake we
414will call this <e>vmail</e>:
415</p>
416
417<pre caption="Adding the vmail user">
418# <i>adduser -d /home/vmail -s /bin/false -m vmail</i>
419</pre>
420
421<p>
422So now you've set up the vmail account. You can create multiple accounts if you
423want (to keep some structure in your set of virtual mail accounts). The user id,
424group id and home dirs are referenced in the MySQL tables.
425</p>
426
427<p>
428Next to the user account we also need to create the location where the mailboxes
429will reside:
430</p>
431
432<pre caption="Creating mailboxes">
433# <i>mkdir /home/vmail/virt-domain.com/foo</i>
434# <i>chown -R vmail:vmail /home/vmail/virt-domain.com</i>
435# <i>maildirmake /home/vmail/virt-domain.com/foo/.maildir</i>
436</pre>
437
438</body>
439</section>
440</chapter>
441
442<chapter>
424<title>MySQL</title> 443<title>MySQL</title>
425<section> 444<section>
426<body> 445<body>
427 446
428<p> 447<p>
429Next we're going to install and configure MySQL. You'll need the <uri 448Next we're going to install and configure MySQL. You'll need the <uri
430link="http://www.gentoo.org/doc/en/files/genericmailsql.sql">genericmailsql.sql</uri> 449link="http://www.gentoo.org/doc/en/files/genericmailsql.sql">genericmailsql.sql</uri>
431dumpfile for this step. 450dumpfile for this step.
432</p> 451</p>
433 452
434<pre caption="Installing and configuring MySQL"> 453<pre caption="Installing and configuring MySQL">
435# <i>emerge mysql</i> 454# <i>emerge mysql</i>
436 455
437# <i>/usr/bin/mysql_install_db</i> 456# <i>/usr/bin/mysql_install_db</i>
438<comment>(After this command runs follow the onscreen directions 457<comment>(After this command runs follow the onscreen directions
473 </li> 492 </li>
474 <li>users - all user account information</li> 493 <li>users - all user account information</li>
475 <li>virtual - virtual domain email alias maps</li> 494 <li>virtual - virtual domain email alias maps</li>
476</ul> 495</ul>
477 496
478<pre caption="alias table sample"> 497<pre caption="alias table sample">
479id alias destination 498id alias destination
4801 root foo@bar.com 4991 root foo@bar.com
4812 postmaster foo@bar.com 5002 postmaster foo@bar.com
482</pre> 501</pre>
483 502
484<pre caption="user table sample"> 503<pre caption="user table sample">
485<comment>(Line wrapped for clarity.)</comment> 504<comment>(Line wrapped for clarity.)</comment>
486id email clear name uid gid homedir \ 505id email clear name uid gid homedir \
487 maildir quota postfix 506 maildir quota postfix
48810 foo@virt-bar.org $password realname virtid virtid /home/vmail \ 50710 foo@virt-domain.com $password realname virtid virtid /home/vmail \
489 /home/vmail/virt-bar.org/foo/.maildir/ y 508 /home/vmail/virt-domain.com/foo/.maildir/ y
49013 foo@bar.com $password realname localid localid /home/foo \ 50913 foo@bar.com $password realname localid localid /home/foo \
491 /home/foo/.maildir/ y 510 /home/foo/.maildir/ y
492</pre> 511</pre>
493 512
494<p> 513<p>
495The values of the <c>virtid</c> uid and gid should be those of the <c>vmail</c> 514The values of the <c>virtid</c> uid and gid should be those of the <c>vmail</c>
496user and group. 515user and group.
497</p> 516</p>
498 517
499<pre caption="transport table sample"> 518<pre caption="transport table sample">
500id domain destination 519id domain destination
5011 bar.com local: 5201 bar.com local:
5022 virt-bar.org virtual: 5212 virt-domain.com virtual:
503</pre> 522</pre>
504 523
505<pre caption="virtual table sample"> 524<pre caption="virtual table sample">
506id email destination 525id email destination
5073 root@virt-bar.org other@email.address 5263 root@virt-domain.com other@email.address
508</pre> 527</pre>
509 528
510</body> 529</body>
511</section> 530</section>
512</chapter> 531</chapter>
513 532
514<chapter> 533<chapter>
515<title>Apache and phpMyAdmin</title> 534<title>Apache and phpMyAdmin</title>
516<section> 535<section>
517<body> 536<body>
518 537
519<p> 538<p>
520Next we'll set up apache and add an interface to interact with the database 539Next we'll set up apache and add an interface to interact with the database
521more easily. 540more easily.
522</p> 541</p>
602$cfg['Servers'][$i]['user'] = 'mailsql'; // MySQL user 621$cfg['Servers'][$i]['user'] = 'mailsql'; // MySQL user
603$cfg['Servers'][$i]['password'] = '$password'; // MySQL password 622$cfg['Servers'][$i]['password'] = '$password'; // MySQL password
604</pre> 623</pre>
605 624
606<p> 625<p>
607Now enter the phpmyadmin page and browse the tables. You'll want to add in your 626Now enter the phpmyadmin page and browse the tables. You'll want to add in your
608local aliases, edit your user table to add a test user, and change your 627local aliases, edit your user table to add a test user, and change your
609transport table to add information about your domains. The default values 628transport table to add information about your domains. The default values
610supplied with the dumpfile should be a sufficient guide to what values need to 629supplied with the dumpfile should be a sufficient guide to what values need to
611go where. Make sure that if you put information in the database that it is 630go where. Make sure that if you put information in the database that it is
612accurate. For instance, make sure the local user's home dir exists and that the 631accurate. For instance, make sure the local user's home dir exists and that the
613correct uid/gid values are in place. The maildirs should be created 632correct uid/gid values are in place. The maildirs should be created
614automatically by postfix when the user receives their first email. So, in 633automatically by postfix when the user receives their first email. So, in
615general, it's a good idea to send a "Welcome" mail to a new user after you 634general, it's a good idea to send a "Welcome" mail to a new user after you
616setup their account to make sure the .maildir gets created. 635setup their account to make sure the .maildir gets created.
617</p>
618
619</body>
620</section>
621</chapter>
622
623<chapter>
624<title>The vmail user</title>
625<section>
626<body>
627
628<p>
629At this point you may be wondering what user and directory to use for virtual
630mail users, and rightly so. Let's set that up.
631</p>
632
633<pre caption="Adding the vmail user">
634# <i>adduser -d /home/vmail -s /bin/false -m vmail</i>
635</pre>
636
637<p>
638So now you've set up the vmail account. You can create multiple accounts if you
639want (to keep some structure in your set of virtual mail accounts). The user id,
640group id and home dirs are referenced in the MySQL tables.
641</p> 636</p>
642 637
643</body> 638</body>
644</section> 639</section>
645</chapter> 640</chapter>
646 641
647<chapter> 642<chapter>
648<title>Configuring MySQL Authentication and vhosts</title> 643<title>Configuring MySQL Authentication and vhosts</title>
649<section> 644<section>
650<body> 645<body>
651 646
652<p> 647<p>
653Next we'll reconfigure our authentication to use the mailsql database in 648Next we'll reconfigure our authentication to use the mailsql database in
654courier-imap and postfix. In all of the following examples, replace 649courier-imap and postfix. In all of the following examples, replace
655<c>$password</c> with the password you set for the mailsql mysql user. 650<c>$password</c> with the password you set for the mailsql mysql user.
729# <i>nano -w /etc/postfix/mysql-virtual-gid.cf</i> 724# <i>nano -w /etc/postfix/mysql-virtual-gid.cf</i>
730# mysql-virtual-gid.cf 725# mysql-virtual-gid.cf
731 726
732user = mailsql 727user = mailsql
733password = $password 728password = $password
734dbname = mailsql 729dbname = mailsql
735table = users 730table = users
736select_field = gid 731select_field = gid
737where_field = email 732where_field = email
738additional_conditions = and postfix = 'y' 733additional_conditions = and postfix = 'y'
739hosts = unix:/var/run/mysqld/mysqld.sock 734hosts = unix:/var/run/mysqld/mysqld.sock
740</pre> 735</pre>
741 736
742<pre caption="/etc/postfix/mysql-virtual-maps.cf"> 737<pre caption="/etc/postfix/mysql-virtual-maps.cf">
743# <i>nano -w /etc/postfix/mysql-virtual-maps.cf</i> 738# <i>nano -w /etc/postfix/mysql-virtual-maps.cf</i>
744#myql-virtual-maps.cf 739# mysql-virtual-maps.cf
745 740
746user = mailsql 741user = mailsql
747password = $password 742password = $password
748dbname = mailsql 743dbname = mailsql
749table = users 744table = users
750select_field = maildir 745select_field = maildir
751where_field = email 746where_field = email
752additional_conditions = and postfix = 'y' 747additional_conditions = and postfix = 'y'
753hosts = unix:/var/run/mysqld/mysqld.sock 748hosts = unix:/var/run/mysqld/mysqld.sock
754</pre> 749</pre>
755 750
756<pre caption="/etc/postfix/mysql-virtual-uid.cf (optional)"> 751<pre caption="/etc/postfix/mysql-virtual-uid.cf (optional)">
757# <i>nano -w /etc/postfix/mysql-virtual-uid.cf</i> 752# <i>nano -w /etc/postfix/mysql-virtual-uid.cf</i>
758# mysql-virtual-uid.cf 753# mysql-virtual-uid.cf
759 754
784Lastly, edit <path>/etc/postfix/main.cf</path> one more time. 779Lastly, edit <path>/etc/postfix/main.cf</path> one more time.
785</p> 780</p>
786 781
787<pre caption="/etc/postfix/main.cf"> 782<pre caption="/etc/postfix/main.cf">
788# <i>nano -w /etc/postfix/main.cf</i> 783# <i>nano -w /etc/postfix/main.cf</i>
789<comment>(Ensure that there are no other alias_maps definitions)</comment> 784<comment>(Ensure that there are no other alias_maps definitions)</comment>
790alias_maps = mysql:/etc/postfix/mysql-aliases.cf 785alias_maps = mysql:/etc/postfix/mysql-aliases.cf
791relocated_maps = mysql:/etc/postfix/mysql-relocated.cf 786relocated_maps = mysql:/etc/postfix/mysql-relocated.cf
792 787
793local_transport = local 788local_transport = local
794local_recipient_maps = $alias_maps $virtual_mailbox_maps unix:passwd.byname 789local_recipient_maps = $alias_maps $virtual_mailbox_maps unix:passwd.byname
795 790
796virtual_transport = virtual 791virtual_transport = virtual
797<comment>(The domains listed by the mydestination should not be listed in 792<comment>(The domains listed by the mydestination should not be listed in
798 the virtual_mailbox_domains parameter)</comment> 793 the virtual_mailbox_domains parameter)</comment>
799virtual_mailbox_domains = virt-bar.com, $other-virtual-domain.com 794virtual_mailbox_domains = virt-domain.com, $other-virtual-domain.com
800 795
801virtual_minimum_uid = 1000 796virtual_minimum_uid = 1000
802<comment>(Substitute $vmail-gid with the GID of the vmail group)</comment> 797<comment>(Substitute $vmail-gid with the GID of the vmail group)</comment>
803virtual_gid_maps = static:$vmail-gid 798virtual_gid_maps = static:$vmail-gid
804virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-maps.cf 799virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-maps.cf
805virtual_alias_maps = mysql:/etc/postfix/mysql-virtual.cf 800virtual_alias_maps = mysql:/etc/postfix/mysql-virtual.cf
806<comment>(Substitute $vmail-uid with the UID of the vmail user)</comment> 801<comment>(Substitute $vmail-uid with the UID of the vmail user)</comment>
807virtual_uid_maps = static:$vmail-uid 802virtual_uid_maps = static:$vmail-uid
808virtual_mailbox_base = / 803virtual_mailbox_base = /
809#virtual_mailbox_limit = 804#virtual_mailbox_limit =
810</pre> 805</pre>
811 806
812<p> 807<p>
813For security reasons you should change the permissions of the various 808For security reasons you should change the permissions of the various
814<path>/etc/mail/mysql-*.cf</path>: 809<path>/etc/mail/mysql-*.cf</path>:
896 891
897<pre caption="mailman config: mm_cfg.py"> 892<pre caption="mailman config: mm_cfg.py">
898# <i>nano -w /usr/local/mailman/Mailman/mm_cfg.py</i> 893# <i>nano -w /usr/local/mailman/Mailman/mm_cfg.py</i>
899MTA = "Postfix" 894MTA = "Postfix"
900POSTFIX_STYLE_VIRTUAL_DOMAINS = ['virt-domain.com', 'virt.domain2.com'] 895POSTFIX_STYLE_VIRTUAL_DOMAINS = ['virt-domain.com', 'virt.domain2.com']
901add_virtualhost('www.virt.domain.com', 'virt.domain.com') 896add_virtualhost('www.virt.domain.com', 'virt.domain.com')
902add_virtualhost('www.virt.domain2.com', 'virt.domain2.com') 897add_virtualhost('www.virt.domain2.com', 'virt.domain2.com')
903<comment>(This is required for your virtual domains for mailman to function.)</comment> 898<comment>(This is required for your virtual domains for mailman to function.)</comment>
904</pre> 899</pre>
905 900
906<pre caption="And last but not least"> 901<pre caption="And last but not least">
907<comment>(Once that's finished, add your first list.)</comment> 902<comment>(Once that's finished, add your first list.)</comment>
908 903
909# <i>su mailman</i> 904# <i>su mailman</i>
910# <i>cd ~</i> 905# <i>cd ~</i>
911# <i>./bin/newlist test</i> 906# <i>./bin/newlist --urlhost='www.virt-domain.com' --emailhost='virt-domain.com' test</i>
912Enter the email of the person running the list: <i>your@email.address</i> 907Enter the email of the person running the list: <i>your@email.address</i>
913Initial test password: 908Initial test password:
914Hit enter to continue with test owner notification... 909Hit enter to continue with test owner notification...
915<comment>(Virtual domain lists may be specified with 910<comment>(Virtual domain lists may also be specified with
916list@domain.com style list names.)</comment> 911list@domain.com style list names.)</comment>
917# <i>./bin/genaliases</i> 912# <i>./bin/genaliases</i>
918<comment>(Now that your aliases have been generated, 913<comment>(Now that your aliases have been generated,
919verify that they were added successfully.)</comment> 914verify that they were added successfully.)</comment>
920 915
921# <i>nano -w data/aliases</i> 916# <i>nano -w data/aliases</i>
922# STANZA START: test 917# STANZA START: test
923# CREATED: 918# CREATED:
924test: "|/var/mailman/mail/mailman post test" 919test: "|/usr/local/mailman/mail/mailman post test"
925test-admin: "|/var/mailman/mail/mailman admin test" 920test-admin: "|/usr/local/mailman/mail/mailman admin test"
926test-bounces: "|/var/mailman/mail/mailman bounces test" 921test-bounces: "|/usr/local/mailman/mail/mailman bounces test"
927test-confirm: "|/var/mailman/mail/mailman confirm test" 922test-confirm: "|/usr/local/mailman/mail/mailman confirm test"
928test-join: "|/var/mailman/mail/mailman join test" 923test-join: "|/usr/local/mailman/mail/mailman join test"
929test-leave: "|/var/mailman/mail/mailman leave test" 924test-leave: "|/usr/local/mailman/mail/mailman leave test"
930test-owner: "|/var/mailman/mail/mailman owner test" 925test-owner: "|/usr/local/mailman/mail/mailman owner test"
931test-request: "|/var/mailman/mail/mailman request test" 926test-request: "|/usr/local/mailman/mail/mailman request test"
932test-subscribe: "|/var/mailman/mail/mailman subscribe test" 927test-subscribe: "|/usr/local/mailman/mail/mailman subscribe test"
933test-unsubscribe: "|/var/mailman/mail/mailman unsubscribe test" 928test-unsubscribe: "|/usr/local/mailman/mail/mailman unsubscribe test"
934# STANZA END: test 929# STANZA END: test
935 930
936<comment>(Create the required mailman list)</comment> 931<comment>(Create the required mailman list)</comment>
937# <i>./bin/newlist mailman</i> 932# <i>./bin/newlist mailman</i>
938# <i>./bin/genaliases</i> 933# <i>./bin/genaliases</i>
939 934
940<comment>(Return to the root user)</comment> 935<comment>(Return to the root user)</comment>
941# <i>exit</i> 936# <i>exit</i>
942 937
943# <i>/etc/init.d/mailman start</i> 938# <i>/etc/init.d/mailman start</i>
944# <i>rc-update add mailman default</i> 939# <i>rc-update add mailman default</i>
945<comment>(To start mailman at once and on every reboot.)</comment> 940<comment>(To start mailman at once and on every reboot.)</comment>
946</pre> 941</pre>
947 942
948<pre caption="Adding mailman alias support to postfix"> 943<pre caption="Adding mailman alias support to postfix">

Legend:
Removed from v.1.56  
changed lines
  Added in v.1.57

  ViewVC Help
Powered by ViewVC 1.1.20