/[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.14 Revision 1.15
1<?xml version = '1.0' encoding = 'UTF-8'?> 1<?xml version = '1.0' encoding = 'UTF-8'?>
2<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> 2<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
3<guide link=" /doc/en/virt-mail-howto.xml" > 3<guide link=" /doc/en/virt-mail-howto.xml" >
4<title>Virtual Mailhosting System Guide</title> 4<title>Virtual Mailhosting System Guide</title>
5<author title="Author" > 5<author title="Author" >
6<mail link="antifa@gentoo.org" >Ken Nowack</mail> 6<mail link="antifa@gentoo.org" >Ken Nowack</mail>
7</author> 7</author>
8<author title="Author" > 8<author title="Author" >
9<mail link="ezra@revoltltd.org" >Ezra Gorman</mail> 9<mail link="ezra@revoltltd.org" >Ezra Gorman</mail>
10</author> 10</author>
11<abstract>This document details how to create a virtual mailhosting system based upon postfix, mysql, courier-imap, and cyrus-sasl. </abstract> 11<abstract>This document details how to create a virtual mailhosting system based upon postfix, mysql, courier-imap, and cyrus-sasl. </abstract>
12<version>1.0.1</version> 12<version>1.0.2</version>
13<date>7 Aug 2003</date> 13<date>7 Aug 2003</date>
14<!-- 14<!--
15 15
16Contents 16Contents
17 17
18I. Introduction 18I. Introduction
19II. Postfix Basics 19II. Postfix Basics
20III. Courier-imap 20III. Courier-imap
21IV. Cyrus-sasl 21IV. Cyrus-sasl
22V. SSL Certificates for Postfix and Apache 22V. SSL Certificates for Postfix and Apache
23VI. Adding SSL and SASL support to Postfix 23VI. Adding SSL and SASL support to Postfix
24VII. MySQL 24VII. MySQL
25VIII. Apache and phpMyAdmin 25VIII. Apache and phpMyAdmin
26IX. The vmail user 26IX. The vmail user
27X. Configuring MySQL Authentication and vhosts 27X. Configuring MySQL Authentication and vhosts
275 -> <i>quit</i> 275 -> <i>quit</i>
276<codenote>Verify that the new mailsql user can connect to the mysql server.</codenote> 276<codenote>Verify that the new mailsql user can connect to the mysql server.</codenote>
277 277
278# <i>mysql -u mailsql -p mailsql</i> 278# <i>mysql -u mailsql -p mailsql</i>
279</pre> 279</pre>
280<p>Your new database has default values and tables set up for two domains. The following tables are included: 280<p>Your new database has default values and tables set up for two domains. The following tables are included:
281 <ul> 281 <ul>
282<li>alias - local email alias and mailman alias information.</li> 282<li>alias - local email alias and mailman alias information.</li>
283<li>relocated - relocated user email address maps</li> 283<li>relocated - relocated user email address maps</li>
284<li>transport - default mail transport information for all domains you are hosting</li> 284<li>transport - default mail transport information for all domains you are hosting</li>
285<li>users - all user account information</li> 285<li>users - all user account information</li>
286<li>virtual - virtual domain email alias maps</li> 286<li>virtual - virtual domain email alias maps</li>
287</ul> 287</ul>
288</p> 288</p>
289<pre caption="alias table sample" > 289<pre caption="alias table sample" >
290 id alias destination 290id alias destination
291 1 root foo@bar.com 2911 root foo@bar.com
292 2 postmaster foo@bar.com 2922 postmaster foo@bar.com
293</pre> 293</pre>
294<pre caption="user table sample" > 294<pre caption="user table sample" >
295 id email clear name uid gid homedir maildir quota postfix 295<codenote>Line wrapped for clarity</codenote>
296 10 foo@virt-bar.org $password realname virtid virtid /home/vmail /home/vmail/virt-bar.org/foo/.maildir/ y 296id email clear name uid gid homedir \
297 13 foo@bar.com $password realname localid localid /home/foo /home/foo/.maildir/ y 297 maildir quota postfix
29810 foo@virt-bar.org $password realname virtid virtid /home/vmail \
299 /home/vmail/virt-bar.org/foo/.maildir/ y
30013 foo@bar.com $password realname localid localid /home/foo \
301 /home/foo/.maildir/ y
298</pre> 302</pre>
299<pre caption="transport table sample" > 303<pre caption="transport table sample" >
300 id domain destination 304id domain destination
301 1 bar.com local: 3051 bar.com local:
302 2 virt-bar.org virtual: 3062 virt-bar.org virtual:
303</pre> 307</pre>
304<pre caption="virtual table sample" > 308<pre caption="virtual table sample" >
305 id email destination 309id email destination
306 3 root@virt-bar.org other@email.address 3103 root@virt-bar.org other@email.address
307</pre> 311</pre>
308</body> 312</body>
309</chapter> 313</chapter>
310<chapter> 314<chapter>
311<title>Apache and phpMyAdmin</title> 315<title>Apache and phpMyAdmin</title>
312<body> 316<body>
313<p>Next we'll set up apache and add an interface to interact with the database more easily. </p> 317<p>Next we'll set up apache and add an interface to interact with the database more easily. </p>
314<pre caption="Setting up apache and phpmyadmin" > 318<pre caption="Setting up apache and phpmyadmin" >
315# <i>emerge apache mod_php mod_ssl phpmyadmin</i> 319# <i>emerge apache mod_php mod_ssl phpmyadmin</i>
316</pre> 320</pre>
317<p>There are plenty of guides out there about how to set up apache with php. Like this one: <uri>http://www.linuxguruz.org/z.php?id=31</uri>. There are also numerous posts on <uri>http://forums.gentoo.org</uri> detailing how to solve problems with the installation (search for 'apache php'). So, that said, I'm not going to cover it here. Set up the apache and php installs, then continue with this howto. Now, a word for the wise: .htaccess the directory that you put phpmyadmin in. If you do not do this, search engine spiders will come along and index the page which in turn will mean that anyone will be able to find your phpmyadmin page via google and in turn be able to come change your database however they want which is <e>BAD!</e> There are many howtos on this including: <uri>http://docs.csoft.net/micro/black-htaccess.html</uri>.</p> 321<p>There are plenty of guides out there about how to set up apache with php. Like this one: <uri>http://www.linuxguruz.org/z.php?id=31</uri>. There are also numerous posts on <uri>http://forums.gentoo.org</uri> detailing how to solve problems with the installation (search for 'apache php'). So, that said, I'm not going to cover it here. Set up the apache and php installs, then continue with this howto. Now, a word for the wise: .htaccess the directory that you put phpmyadmin in. If you do not do this, search engine spiders will come along and index the page which in turn will mean that anyone will be able to find your phpmyadmin page via google and in turn be able to come change your database however they want which is <e>BAD!</e> There are many howtos on this including: <uri>http://docs.csoft.net/micro/black-htaccess.html</uri>.</p>
318<p>Now we're going to install the Apache certificates we made previously. The Apache-SSL directives that you need to use the resulting cert are: 322<p>Now we're going to install the Apache certificates we made previously. The Apache-SSL directives that you need to use the resulting cert are:
319 <ul> 323 <ul>
320<li>SSLCertificateFile /path/to/certs/new.cert.cert</li> 324<li>SSLCertificateFile /path/to/certs/new.cert.cert</li>
321<li>SSLCertificateKeyFile /path/to/certs/new.cert.key</li> 325<li>SSLCertificateKeyFile /path/to/certs/new.cert.key</li>
328<codenote>Change the following parameters</codenote> 332<codenote>Change the following parameters</codenote>
329 333
330ServerName host.domain.name 334ServerName host.domain.name
331ServerAdmin your@email.address 335ServerAdmin your@email.address
332SSLCertificateFile /etc/apache/conf/ssl/new.cert.cert 336SSLCertificateFile /etc/apache/conf/ssl/new.cert.cert
333SSLCertificateKeyFile /etc/apache/conf/ssl/new.cert.key 337SSLCertificateKeyFile /etc/apache/conf/ssl/new.cert.key
334 338
335# <i>/etc/init.d/apache restart</i> 339# <i>/etc/init.d/apache restart</i>
336</pre> 340</pre>
337<note>If you have an existing apache install, you'll likely have to perform a full server reboot to install your new certificates. Check your logs to verify apache restarted successfully.</note> 341<note>If you have an existing apache install, you'll likely have to perform a full server reboot to install your new certificates. Check your logs to verify apache restarted successfully.</note>
338<p>Next, configure phpMyAdmin.</p> 342<p>Next, configure phpMyAdmin.</p>
339<pre caption="Configuring phpMyAdmin" > 343<pre caption="Configuring phpMyAdmin" >
340# <i>nano -w /home/httpd/htdocs/phpmyadmin/config.inc.php</i> 344# <i>nano -w /home/httpd/htdocs/phpmyadmin/config.inc.php</i>
341<codenote>Change the following parameters</codenote> 345<codenote>Change the following parameters</codenote>
342 346
343$cfg['Servers'][$i]['host'] = 'localhost'; // MySQL hostname 347$cfg['Servers'][$i]['host'] = 'localhost'; // MySQL hostname
344$cfg['Servers'][$i]['controluser'] = 'mailsql'; // MySQL control user settings 348$cfg['Servers'][$i]['controluser'] = 'mailsql'; // MySQL control user settings
345 // (this user must have read-only 349 // (this user must have read-only
346$cfg['Servers'][$i]['controlpass'] = '$password'; // access to the &quot;mysql/user&quot; 350$cfg['Servers'][$i]['controlpass'] = '$password'; // access to the &quot;mysql/user&quot;
347 // and &quot;mysql/db&quot; tables) 351 // and &quot;mysql/db&quot; tables)
348$cfg['Servers'][$i]['user'] = 'mailsql'; // MySQL user 352$cfg['Servers'][$i]['user'] = 'mailsql'; // MySQL user
349$cfg['Servers'][$i]['password'] = '$password'; // MySQL password 353$cfg['Servers'][$i]['password'] = '$password'; // MySQL password
350</pre> 354</pre>
351<p>Now enter the phpmyadmin page and browse the tables. You'll want to add in your local aliases, edit your user table to add a test user, and change your transport table to add information about your domains. The default values supplied with the dumpfile should be a sufficient guide to what values need to go where. Make sure that if you put information in the database that it is accurate. For instance, make sure the local users home dir exists and that the correct uid/gid values are in place. The maildirs should be created automatically by postfix when the user receives their first email. So, in general, it's a good idea to send a &quot;Welcome&quot; mail to a new user after you setup their account to make sure the .maildir gets created. </p> 355<p>Now enter the phpmyadmin page and browse the tables. You'll want to add in your local aliases, edit your user table to add a test user, and change your transport table to add information about your domains. The default values supplied with the dumpfile should be a sufficient guide to what values need to go where. Make sure that if you put information in the database that it is accurate. For instance, make sure the local users home dir exists and that the correct uid/gid values are in place. The maildirs should be created automatically by postfix when the user receives their first email. So, in general, it's a good idea to send a &quot;Welcome&quot; mail to a new user after you setup their account to make sure the .maildir gets created. </p>
352</body> 356</body>
353</chapter> 357</chapter>
354<chapter> 358<chapter>
355<title>The vmail user</title> 359<title>The vmail user</title>
356<body> 360<body>
357<p>At this point you may be wondering what user and directory to use for virtual mail users, and rightly so. Let's set that up.</p> 361<p>At this point you may be wondering what user and directory to use for virtual mail users, and rightly so. Let's set that up.</p>
358<pre caption="Adding the vmail user" > 362<pre caption="Adding the vmail user" >
359# <i>adduser -d /home/vmail -s /bin/false vmail</i> 363# <i>adduser -d /home/vmail -s /bin/false vmail</i>
360# <i>uid=`cat /etc/passwd | grep vmail | cut -f 3 -d :`</i> 364# <i>uid=`cat /etc/passwd | grep vmail | cut -f 3 -d :`</i>
361# <i>groupadd -g $uid vmail</i> 365# <i>groupadd -g $uid vmail</i>
362# <i>mkdir /home/vmail</i> 366# <i>mkdir /home/vmail</i>
363# <i>chown vmail. /home/vmail</i> 367# <i>chown vmail. /home/vmail</i>
364</pre> 368</pre>
718</pre> 722</pre>
719</body> 723</body>
720</section> 724</section>
721<section> 725<section>
722<title>Step 5: Talk to the service itself.</title> 726<title>Step 5: Talk to the service itself.</title>
723<body> 727<body>
724<p>SMTP, IMAP, and POP3 all respond to telnet sessions. As we've seen earlier when we verified postfix's config. Sometimes it's helpful to open a telnet session to the service itself and see what's happening.</p> 728<p>SMTP, IMAP, and POP3 all respond to telnet sessions. As we've seen earlier when we verified postfix's config. Sometimes it's helpful to open a telnet session to the service itself and see what's happening.</p>
725<pre> 729<pre>
726# <i>telnet localhost $port</i> 730# <i>telnet localhost $port</i>
727<codenote>SMTP is 25, IMAP is 143, POP3 is 110. You should receive at least an OK string,</codenote> 731<codenote>SMTP is 25, IMAP is 143, POP3 is 110. You should receive at least an OK string,</codenote>
728<codenote>letting you know that the service is running and ready to respond to requests.</codenote> 732<codenote>letting you know that the service is running and ready to respond to requests.</codenote>
729 733
730Trying 127.0.0.1... 734Trying 127.0.0.1...
731Connected to localhost. 735Connected to localhost.
732Escape character is '^]'. 736Escape character is '^]'.
733* OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc. See COPYING for distribution information. 737* OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc.
734</pre> 738</pre>
735</body> 739</body>
736</section> 740</section>
737<section> 741<section>
738<title>Step 6: Sometimes only the big guns will give you the information you need: strace.</title> 742<title>Step 6: Sometimes only the big guns will give you the information you need: strace.</title>
739<body> 743<body>
740<p>You should have this installed anyway. This is an invaluable tool for debugging software. You can start commands from the command line with strace and watch all the system calls as they happen. It often dumps a huge amount of information, so you'll either need to watch it realtime as you retry a failed transaction with the mail system, or dump the output to a file for review.</p> 744<p>You should have this installed anyway. This is an invaluable tool for debugging software. You can start commands from the command line with strace and watch all the system calls as they happen. It often dumps a huge amount of information, so you'll either need to watch it realtime as you retry a failed transaction with the mail system, or dump the output to a file for review.</p>
741<pre> 745<pre>
742# <i>emerge strace</i> 746# <i>emerge strace</i>
743# <i>strace $command</i> 747# <i>strace $command</i>
744# <i>strace -p `ps -C $service -o pid=`</i> 748# <i>strace -p `ps -C $service -o pid=`</i>
745</pre> 749</pre>
746</body> 750</body>
747</section> 751</section>
748<section> 752<section>

Legend:
Removed from v.1.14  
changed lines
  Added in v.1.15

  ViewVC Help
Powered by ViewVC 1.1.20