/[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.54 Revision 1.55
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.54 2007/03/02 07:24:46 nightmorph Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.55 2007/07/16 02:31:38 nightmorph 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
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">
21 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
22</author>
20 23
21<abstract> 24<abstract>
22This document details how to create a virtual mailhosting system based upon 25This document details how to create a virtual mailhosting system based upon
23postfix, mysql, courier-imap, and cyrus-sasl. 26postfix, mysql, courier-imap, and cyrus-sasl.
24</abstract> 27</abstract>
25 28
26<version>1.2</version> 29<version>1.3</version>
27<date>2006-09-04</date> 30<date>2007-07-15</date>
28 31
29<!-- 32<!--
30Contents 33Contents
31 34
32I. Introduction 35I. Introduction
99get the support you need for all the protocols. Further, it's a good idea to 102get the support you need for all the protocols. Further, it's a good idea to
100turn off any other mail and network variables, like ipv6. 103turn off any other mail and network variables, like ipv6.
101</p> 104</p>
102 105
103<impo> 106<impo>
104This howto was written for postfix-2.0.x. If you are using postfix &lt; 2 some
105of the variables in this document will be different. It is recommended that you
106upgrade. Some other packages included in this howto are version sensitive as
107well. You are advised to read the documentation included with packages if you
108run into issues with this.
109</impo>
110
111<impo>
112This document uses apache-1.3.x. Apache-2 has been marked stable in portage.
113However there are still a number of issues with php integration. Until php
114support in apache-2.0.x is marked stable, this guide will continue to use the
1151.3.x version.
116</impo>
117
118<impo>
119You need a domain name to run a public mail server, or at least an MX record 107You need a domain name to run a public mail server, or at least an MX record
120for a domain. Ideally you would have control of at least two domains to take 108for a domain. Ideally you would have control of at least two domains to take
121advantage of your new virtual domain functionality. 109advantage of your new virtual domain functionality.
122</impo> 110</impo>
123 111
246# <i>/etc/init.d/courier-pop3d-ssl start</i> 234# <i>/etc/init.d/courier-pop3d-ssl start</i>
247</pre> 235</pre>
248 236
249<p> 237<p>
250Start up your favorite mail client and verify that all connections you've 238Start up your favorite mail client and verify that all connections you've
251started work for receiving and sending mail. Now that the basics work, we're 239started work for receiving and sending mail. Of course, you won't be able to log
252going to do a whole bunch of stuff at once to get the rest of the system 240on to any of the services because authentication hasn't been configured yet, but
253running. Again, please verify that what we've installed already works before 241it is wise to check if the connections themselves work or not.
254progressing. 242</p>
243
244<p>
245Now that the basics work, we're going to do a whole bunch of stuff at once to
246get the rest of the system running. Again, please verify that what we've
247installed already works before progressing.
255</p> 248</p>
256 249
257</body> 250</body>
258</section> 251</section>
259</chapter> 252</chapter>
316emailAddress_default. 309emailAddress_default.
317 310
318<comment>(If the variables are not already present, just add them in a sensible place.)</comment> 311<comment>(If the variables are not already present, just add them in a sensible place.)</comment>
319 312
320# <i>cd misc</i> 313# <i>cd misc</i>
321# <i>nano -w CA.pl</i> 314# <i>./CA.pl -newreq-nodes</i>
322<comment>(We need to add -nodes to the # create a certificate and
323#create a certificate request code in order to let our new ssl
324certs be loaded without a password. Otherwise when you
325reboot your ssl certs will not be available.)</comment>
326
327# create a certificate
328system ("$REQ -new -nodes -x509 -keyout newreq.pem -out newreq.pem $DAYS");
329
330# create a certificate request
331system ("$REQ -new -nodes -keyout newreq.pem -out newreq.pem $DAYS");
332
333# <i>./CA.pl -newca</i> 315# <i>./CA.pl -newca</i>
334# <i>./CA.pl -newreq</i>
335# <i>./CA.pl -sign</i> 316# <i>./CA.pl -sign</i>
336# <i>cp newcert.pem /etc/postfix</i> 317# <i>cp newcert.pem /etc/postfix</i>
337# <i>cp newreq.pem /etc/postfix</i> 318# <i>cp newreq.pem /etc/postfix</i>
338# <i>cp demoCA/cacert.pem /etc/postfix</i> 319# <i>cp demoCA/cacert.pem /etc/postfix</i>
339<comment>(Now we do the same thing for apache.)</comment> 320<comment>(Now we do the same thing for apache.)</comment>
539Next we'll set up apache and add an interface to interact with the database 520Next we'll set up apache and add an interface to interact with the database
540more easily. 521more easily.
541</p> 522</p>
542 523
543<pre caption="Setting up apache and phpmyadmin"> 524<pre caption="Setting up apache and phpmyadmin">
544# <i>emerge apache mod_php phpmyadmin</i> 525# <i>emerge apache phpmyadmin</i>
545</pre> 526</pre>
546 527
547<p> 528<p>
548There are plenty of guides out there about how to set up apache with php. Like 529There are plenty of guides out there about how to set up apache with php,
549this one: <uri>http://www.linuxguruz.com/z.php?id=31</uri>. There are also 530including guides provided by the <uri link="/proj/en/php/">Gentoo PHP
531Project</uri>. There are also numerous posts on
550numerous posts on <uri>http://forums.gentoo.org</uri> detailing how to solve 532<uri>http://forums.gentoo.org</uri> detailing how to solve problems with the
551problems with the installation (search for 'apache php'). So, that said, I'm 533installation. So, that said, we're not going to cover it here. Set up the
552not going to cover it here. Set up the apache and php installs, then continue 534apache and php installs, then continue with this howto. Now, a word for the
553with this howto. Now, a word for the wise: .htaccess the directory that you put 535wise: .htaccess the directory that you put phpmyadmin in. If you do not do this,
554phpmyadmin in. If you do not do this, search engine spiders will come along and 536search engine spiders will come along and index the page which in turn will mean
555index the page which in turn will mean that anyone will be able to find your 537that anyone will be able to find your phpmyadmin page via google and in turn be
556phpmyadmin page via google and in turn be able to come change your database 538able to come change your database however they want which is <e>BAD!</e> There
557however they want which is <e>BAD!</e> There are many howtos on this 539are many howtos on this including:
558including: <uri>http://www.csoft.net/docs/micro/htaccess.html.en</uri>. 540<uri>http://www.csoft.net/docs/micro/htaccess.html.en</uri>.
559</p> 541</p>
560 542
561<p> 543<p>
562Now we're going to install the Apache certificates we made previously. The 544Now we're going to install the Apache certificates we made previously. The
563Apache-SSL directives that you need to use the resulting cert are: 545Apache-SSL directives that you need to use the resulting cert are:
567 <li>SSLCertificateFile /path/to/certs/new.cert.cert</li> 549 <li>SSLCertificateFile /path/to/certs/new.cert.cert</li>
568 <li>SSLCertificateKeyFile /path/to/certs/new.cert.key</li> 550 <li>SSLCertificateKeyFile /path/to/certs/new.cert.key</li>
569</ul> 551</ul>
570 552
571<pre caption="Install Apache SSL certificates"> 553<pre caption="Install Apache SSL certificates">
572# <i>cp /etc/ssl/misc/new.cert.cert /etc/apache/conf/ssl/</i> 554# <i>cp /etc/ssl/misc/new.cert.cert /etc/apache2/ssl/</i>
573# <i>cp /etc/ssl/misc/new.cert.key /etc/apache/conf/ssl/</i> 555# <i>cp /etc/ssl/misc/new.cert.key /etc/apache2/ssl/</i>
574# <i>nano -w /etc/apache/conf/vhosts/ssl.default-vhost.conf</i> 556# <i>cd /etc/apache2/vhosts.d</i>
557<comment>(Check if you have an ssl-vhost template already.
558 Copy that one instead of the default_vhost if that is the case)</comment>
559# <i>cp 00_default_vhost.conf ssl-vhost.conf</i>
560# <i>nano -w ssl-vhost.conf</i>
575 561
576<comment>(Change the following parameters)</comment> 562<comment>(Change the following parameters)</comment>
563NameVirtualHost host.domain.name:443
577 564
565&lt;VirtualHost host.domain.name:443&gt;
578ServerName host.domain.name 566 ServerName host.domain.name
579ServerAdmin your@email.address 567 ServerAdmin your@email.address
568
569 DocumentRoot "/var/www/localhost/htdocs/phpmyadmin";
570 &lt;Directory "/var/www/localhost/htdocs/phpmyadmin"&gt;
571 ...
572 &lt;/Directory&gt;
573
580SSLCertificateFile /etc/apache/conf/ssl/new.cert.cert 574 SSLCertificateFile /etc/apache2/ssl/new.cert.cert
581SSLCertificateKeyFile /etc/apache/conf/ssl/new.cert.key 575 SSLCertificateKeyFile /etc/apache2/ssl/new.cert.key
576 SSLEngine on
577 ...
578&lt;/VirtualHost&gt;
582 579
580# <i>nano -w /etc/conf.d/apache2</i>
581<comment>(Add -D SSL -D PHP5 to the APACHE2_OPTS)</comment>
582
583# <i>/etc/init.d/apache restart</i> 583# <i>/etc/init.d/apache2 restart</i>
584</pre> 584</pre>
585
586<note>
587If you have an existing apache install, you'll likely have to perform a full
588server reboot to install your new certificates. Check your logs to verify
589apache restarted successfully.
590</note>
591 585
592<p> 586<p>
593Next, configure phpMyAdmin. 587Next, configure phpMyAdmin.
594</p> 588</p>
595 589
596<pre caption="Configuring phpMyAdmin"> 590<pre caption="Configuring phpMyAdmin">
597# <i>nano -w /var/www/localhost/htdocs/phpmyadmin/config.inc.php</i> 591# <i>cd /var/www/localhost/htdocs/phpmyadmin</i>
592# <i>cp config.sample.inc.php config.inc.php</i>
593# <i>nano -w config.inc.php</i>
598<comment>(Change the following parameters.)</comment> 594<comment>(Change the following parameters.)</comment>
595$cfg['blowfish_secret'] = 'someverysecretpassphraze';
599 596
600$cfg['Servers'][$i]['host'] = 'localhost'; // MySQL hostname 597$cfg['Servers'][$i]['host'] = 'localhost'; // MySQL hostname
601$cfg['Servers'][$i]['controluser'] = 'mailsql'; // MySQL control user settings 598$cfg['Servers'][$i]['controluser'] = 'mailsql'; // MySQL control user settings
602 // (this user must have read-only 599 // (this user must have read-only
603$cfg['Servers'][$i]['controlpass'] = '$password'; // access to the "mysql/user" 600$cfg['Servers'][$i]['controlpass'] = '$password'; // access to the "mysql/user"
632At this point you may be wondering what user and directory to use for virtual 629At this point you may be wondering what user and directory to use for virtual
633mail users, and rightly so. Let's set that up. 630mail users, and rightly so. Let's set that up.
634</p> 631</p>
635 632
636<pre caption="Adding the vmail user"> 633<pre caption="Adding the vmail user">
637# <i>adduser -d /home/vmail -s /bin/false vmail</i> 634# <i>adduser -d /home/vmail -s /bin/false -m vmail</i>
638# <i>uid=`cat /etc/passwd | grep vmail | cut -f 3 -d :`</i>
639# <i>groupadd -g $uid vmail</i>
640# <i>mkdir /home/vmail</i>
641# <i>chown vmail: /home/vmail</i>
642</pre> 635</pre>
643 636
644<p> 637<p>
645So now when you're setting up vmail accounts, use the vmail uid, gid, and 638So now you've set up the vmail account. You can create multiple accounts if you
646homedir. When you're setting up local accounts, use that user's uid, gid, and 639want (to keep some structure in your set of virtual mail accounts). The user id,
647homedir. We've been meaning to create a php admin page for this setup but 640group id and home dirs are referenced in the MySQL tables.
648haven't gotten around to it yet, as phpmyadmin generally works fine for us.
649</p> 641</p>
650 642
651</body> 643</body>
652</section> 644</section>
653</chapter> 645</chapter>
733hosts = unix:/var/run/mysqld/mysqld.sock 725hosts = unix:/var/run/mysqld/mysqld.sock
734</pre> 726</pre>
735 727
736<pre caption="/etc/postfix/mysql-virtual-gid.cf (optional)"> 728<pre caption="/etc/postfix/mysql-virtual-gid.cf (optional)">
737# <i>nano -w /etc/postfix/mysql-virtual-gid.cf</i> 729# <i>nano -w /etc/postfix/mysql-virtual-gid.cf</i>
738#myql-virtual-gid.cf 730# mysql-virtual-gid.cf
739 731
740user = mailsql 732user = mailsql
741password = $password 733password = $password
742dbname = mailsql 734dbname = mailsql
743table = users 735table = users
792Lastly, edit <path>/etc/postfix/main.cf</path> one more time. 784Lastly, edit <path>/etc/postfix/main.cf</path> one more time.
793</p> 785</p>
794 786
795<pre caption="/etc/postfix/main.cf"> 787<pre caption="/etc/postfix/main.cf">
796# <i>nano -w /etc/postfix/main.cf</i> 788# <i>nano -w /etc/postfix/main.cf</i>
789<comment>(Ensure that there are no other alias_maps definitions)</comment>
797alias_maps = mysql:/etc/postfix/mysql-aliases.cf 790alias_maps = mysql:/etc/postfix/mysql-aliases.cf
798relocated_maps = mysql:/etc/postfix/mysql-relocated.cf 791relocated_maps = mysql:/etc/postfix/mysql-relocated.cf
799 792
800local_transport = local 793local_transport = local
801local_recipient_maps = $alias_maps $virtual_mailbox_maps unix:passwd.byname 794local_recipient_maps = $alias_maps $virtual_mailbox_maps unix:passwd.byname
802 795
803virtual_transport = virtual 796virtual_transport = virtual
804virtual_mailbox_domains = 797<comment>(The domains listed by the mydestination should not be listed in
805 virt-bar.com, 798 the virtual_mailbox_domains parameter)</comment>
806 $other-virtual-domain.com 799virtual_mailbox_domains = virt-bar.com, $other-virtual-domain.com
807 800
808virtual_minimum_uid = 1000 801virtual_minimum_uid = 1000
802<comment>(Substitute $vmail-gid with the GID of the vmail group)</comment>
809virtual_gid_maps = static:$vmail-gid 803virtual_gid_maps = static:$vmail-gid
810virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-maps.cf 804virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-maps.cf
811virtual_alias_maps = mysql:/etc/postfix/mysql-virtual.cf 805virtual_alias_maps = mysql:/etc/postfix/mysql-virtual.cf
806<comment>(Substitute $vmail-uid with the UID of the vmail user)</comment>
812virtual_uid_maps = static:$vmail-uid 807virtual_uid_maps = static:$vmail-uid
813virtual_mailbox_base = / 808virtual_mailbox_base = /
814#virtual_mailbox_limit = 809#virtual_mailbox_limit =
815</pre> 810</pre>
816 811
886to require a bit of hacking. I really recommend reading all of the mailman 881to require a bit of hacking. I really recommend reading all of the mailman
887documentation, including README.POSTFIX.gz, to understand what's being done 882documentation, including README.POSTFIX.gz, to understand what's being done
888here. 883here.
889</p> 884</p>
890 885
891<p>
892One further note, current versions of mailman install to
893<path>/usr/local/mailman</path>. If you're like me and wish to change the
894default install location, it can be overridden in the ebuild file by changing
895the INSTALLDIR variable.
896</p>
897
898<pre caption="Install mailman"> 886<pre caption="Install mailman">
899# <i>emerge mailman</i> 887# <i>emerge mailman</i>
900</pre> 888</pre>
901 889
902<pre caption="Setting defaults: Mailman/Defaults.py"> 890<pre caption="Setting defaults: Mailman/Defaults.py">
903# <i> nano -w /var/mailman/Mailman/Defaults.py</i> 891# <i> nano -w /usr/local/mailman/Mailman/Defaults.py</i>
904<comment>(Change the values below to reflect your primary domain, virtuals will be set next.)</comment> 892<comment>(Change the values below to reflect your primary domain, virtuals will be set next.)</comment>
905DEFAULT_EMAIL_HOST = 'domain.com' 893DEFAULT_EMAIL_HOST = 'domain.com'
906DEFAULT_URL_HOST = 'www.domain.com' 894DEFAULT_URL_HOST = 'www.domain.com'
907</pre> 895</pre>
908 896
909<pre caption="mailman config: mm_cfg.py"> 897<pre caption="mailman config: mm_cfg.py">
910# <i>nano -w /var/mailman/Mailman/mm_cfg.py</i> 898# <i>nano -w /usr/local/mailman/Mailman/mm_cfg.py</i>
911MTA = "Postfix" 899MTA = "Postfix"
912POSTFIX_STYLE_VIRTUAL_DOMAINS = ['virt-domain.com', 'virt.domain2.com'] 900POSTFIX_STYLE_VIRTUAL_DOMAINS = ['virt-domain.com', 'virt.domain2.com']
913add_virtualhost('www.virt.domain.com', 'virt.domain.com') 901add_virtualhost('www.virt.domain.com', 'virt.domain.com')
914add_virtualhost('www.virt.domain2.com', 'virt.domain2.com') 902add_virtualhost('www.virt.domain2.com', 'virt.domain2.com')
915<comment>(This is required for your virtual domains for mailman to function.)</comment> 903<comment>(This is required for your virtual domains for mailman to function.)</comment>
918<pre caption="And last but not least"> 906<pre caption="And last but not least">
919<comment>(Once that's finished, add your first list.)</comment> 907<comment>(Once that's finished, add your first list.)</comment>
920 908
921# <i>su mailman</i> 909# <i>su mailman</i>
922# <i>cd ~</i> 910# <i>cd ~</i>
923# <i>bin/newlist test</i> 911# <i>./bin/newlist test</i>
924Enter the email of the person running the list: <i>your@email.address</i> 912Enter the email of the person running the list: <i>your@email.address</i>
925Initial test password: 913Initial test password:
926Hit enter to continue with test owner notification... 914Hit enter to continue with test owner notification...
927<comment>(Virtual domain lists may be specified with 915<comment>(Virtual domain lists may be specified with
928list@domain.com style list names.)</comment> 916list@domain.com style list names.)</comment>
929# <i>bin/genaliases</i> 917# <i>./bin/genaliases</i>
930<comment>(Now that your aliases have been generated, 918<comment>(Now that your aliases have been generated,
931verify that they were added successfully.)</comment> 919verify that they were added successfully.)</comment>
932 920
933# <i>nano -w data/aliases</i> 921# <i>nano -w data/aliases</i>
934# STANZA START: test 922# STANZA START: test
943test-request: "|/var/mailman/mail/mailman request test" 931test-request: "|/var/mailman/mail/mailman request test"
944test-subscribe: "|/var/mailman/mail/mailman subscribe test" 932test-subscribe: "|/var/mailman/mail/mailman subscribe test"
945test-unsubscribe: "|/var/mailman/mail/mailman unsubscribe test" 933test-unsubscribe: "|/var/mailman/mail/mailman unsubscribe test"
946# STANZA END: test 934# STANZA END: test
947 935
936<comment>(Create the required mailman list)</comment>
937# <i>./bin/newlist mailman</i>
938# <i>./bin/genaliases</i>
939
940<comment>(Return to the root user)</comment>
941# <i>exit</i>
942
948# <i>/etc/init.d/mailman start</i> 943# <i>/etc/init.d/mailman start</i>
949# <i>rc-update add mailman default</i> 944# <i>rc-update add mailman default</i>
950<comment>(To start mailman at once and on every reboot.)</comment> 945<comment>(To start mailman at once and on every reboot.)</comment>
951</pre> 946</pre>
952 947
955owner_request_special = no 950owner_request_special = no
956recipient_delimiter = + 951recipient_delimiter = +
957<comment>(Read README.POSTFIX.gz for details on this.)</comment> 952<comment>(Read README.POSTFIX.gz for details on this.)</comment>
958 953
959alias_maps = 954alias_maps =
960 hash:/var/mailman/data/aliases, 955 hash:/usr/local/mailman/data/aliases,
961 mysql:/etc/postfix/mysql-aliases.cf 956 mysql:/etc/postfix/mysql-aliases.cf
962 957
963virtual_alias_maps = 958virtual_alias_maps =
964 hash:/var/mailman/data/virtual-mailman, 959 hash:/usr/local/mailman/data/virtual-mailman,
965 mysql:/etc/postfix/mysql-virtual.cf 960 mysql:/etc/postfix/mysql-virtual.cf
966<comment>(This adds mailman alias file support to postfix 961<comment>(This adds mailman alias file support to postfix
967You may of course use the mysql tables for this, 962You may of course use the mysql tables for this,
968but I hate doing that by hand. Also, if you are not 963but I hate doing that by hand. Also, if you are not
969using virtual domains, adding the virtual alias maps 964using virtual domains, adding the virtual alias maps
1090sure it's using the current version. Some of the components will dump their 1085sure it's using the current version. Some of the components will dump their
1091current config's to you, like postfix. 1086current config's to you, like postfix.
1092</p> 1087</p>
1093 1088
1094<pre caption="Some services can dump their current config"> 1089<pre caption="Some services can dump their current config">
1095# <i>apachectl fullstatus</i> (needs lynx installed) 1090# <i>apache2ctl fullstatus</i> (needs lynx installed)
1096# <i>apachectl configtest</i> (checks config sanity) 1091# <i>apache2ctl configtest</i> (checks config sanity)
1097# <i>postconf -n</i> (will tell you exactly what param's postfix is using) 1092# <i>postconf -n</i> (will tell you exactly what param's postfix is using)
1098# <i>/etc/init.d/$service restart</i> 1093# <i>/etc/init.d/$service restart</i>
1099</pre> 1094</pre>
1100 1095
1101</body> 1096</body>
1115 1110
1116<pre caption="Checking the logs"> 1111<pre caption="Checking the logs">
1117# <i>kill -USR1 `ps -C metalog -o pid=`</i>(to turn off metalog buffering) 1112# <i>kill -USR1 `ps -C metalog -o pid=`</i>(to turn off metalog buffering)
1118# <i>nano -w /var/log/mail/current</i> 1113# <i>nano -w /var/log/mail/current</i>
1119# <i>cat /var/log/mysql/mysql.log</i> 1114# <i>cat /var/log/mysql/mysql.log</i>
1120# <i>tail /var/log/apache/error_log</i> 1115# <i>tail /var/log/apache2/error_log</i>
1121</pre> 1116</pre>
1122 1117
1123<p> 1118<p>
1124You may also find the debug_peer parameters in main.cf helpful. Setting these 1119You may also find the debug_peer parameters in main.cf helpful. Setting these
1125will increase log output over just verbose mode. 1120will increase log output over just verbose mode.

Legend:
Removed from v.1.54  
changed lines
  Added in v.1.55

  ViewVC Help
Powered by ViewVC 1.1.20