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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.44 - (hide annotations) (download) (as text)
Mon May 23 16:09:09 2005 UTC (9 years, 3 months ago) by swift
Branch: MAIN
Changes since 1.43: +4 -4 lines
File MIME type: application/xml
courier-imap now has courier-authlib, not authdaemond anymore

1 vapier 1.32 <?xml version='1.0' encoding='UTF-8'?>
2 swift 1.44 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.43 2005/03/25 15:00:25 swift Exp $ -->
3 swift 1.16 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 neysx 1.39 <guide link="/doc/en/virt-mail-howto.xml">
6 vapier 1.25 <title>Virtual Mailhosting System with Postfix Guide</title>
7 neysx 1.39
8     <author title="Author">
9     <mail link="antifa@gentoo.org">Ken Nowack</mail>
10 zhen 1.3 </author>
11 neysx 1.39 <author title="Author">
12     <mail link="ezra@revoltltd.org">Ezra Gorman</mail>
13 zhen 1.3 </author>
14 klasikahl 1.22 <author title="Editor">
15 neysx 1.39 <mail link="klasikahl@gentoo.org">Zack Gilburd</mail>
16 klasikahl 1.22 </author>
17 neysx 1.39
18     <abstract>
19     This document details how to create a virtual mailhosting system based upon
20     postfix, mysql, courier-imap, and cyrus-sasl.
21     </abstract>
22    
23 swift 1.44 <version>1.0.21</version>
24     <date>2005-05-23</date>
25 neysx 1.39
26 zhen 1.3 <!--
27     Contents
28    
29     I. Introduction
30     II. Postfix Basics
31     III. Courier-imap
32     IV. Cyrus-sasl
33     V. SSL Certificates for Postfix and Apache
34     VI. Adding SSL and SASL support to Postfix
35     VII. MySQL
36     VIII. Apache and phpMyAdmin
37     IX. The vmail user
38     X. Configuring MySQL Authentication and vhosts
39     XI. Squirrelmail
40     XII. Mailman
41     XIII. Content Filtering and Anti-Virus
42     XIV. Wrap Up
43     XV. Troubleshooting
44 neysx 1.39 -->
45 zhen 1.1
46 neysx 1.39 <chapter>
47 zhen 1.1 <title>Introduction</title>
48 swift 1.26 <section>
49 zhen 1.3 <body>
50 neysx 1.39
51     <p>
52     For most gentoo users, a simple mail client and fetchmail will do. However, if
53     you're hosting a domain with your system, you'll need a full blown MTA (Mail
54     Transfer Agent). And if you're hosting multiple domains, then you'll definitely
55     need something more robust to handle all of the email for your users. This
56     system was designed to be an elegant solution to that problem.
57     </p>
58    
59     <p>
60     A virtual mail system needs to be able to handle email for numerous domains
61     with multiple users over a variety of interfaces. This presents some issues
62     that must be dealt with. For instance, what if you have two users on different
63     domains that want the same user name? If you are providing imap access and
64     smtp-auth, how do combine the various authentication daemons into a single
65     system? How do you provide security for the numerous components that comprise
66     the system? How do you manage it all?
67     </p>
68    
69     <p>
70     This howto will show you how to set up with a mail system capable of handling
71     mail for as many domains as your hardware can handle, supports virtual mail
72     users that don't require shell accounts, has domain specific user names, can
73     authenticate web, imap, smtp, and pop3 clients against a single database,
74     utilizes ssl for transport layer security, has a web interface, can handle
75     mailing lists for any domain on the machine, and is controlled by a nice,
76     central and easy mysql database.
77     </p>
78    
79     <p>
80     There are quite a variety of ways to go about setting up a virtual mailhosting
81     system. With so may options, another may be the best choice for your specific
82     needs. Consider investigating <uri>http://www.qmail.org/</uri> and
83     <uri>http://www.exim.org/</uri> to explore your options.
84     </p>
85    
86     <p>
87     The following packages are used in this setup: apache, courier-imap, pam_mysql,
88     postfix, mod_php, phpmyadmin, squirrelmail, cyrus-sasl, mysql, php, and
89     mailman.
90     </p>
91    
92     <p>
93     Make sure to turn on the following USE variables in <path>/etc/make.conf</path>
94     before compiling the packages: <c>USE="mysql pam-mysql imap libwww maildir
95     sasl ssl"</c>. Otherwise you will most likely have to recompile things to
96     get the support you need for all the protocols. Further, it's a good idea to
97     turn off any other mail and network variables, like ipv6.
98     </p>
99    
100     <impo>
101     This howto was written for postfix-2.0.x. If you are using postfix &lt; 2 some
102     of the variables in this document will be different. It is recommended that you
103     upgrade. Some other packages included in this howto are version sensitive as
104     well. You are advised to read the documentation included with packages if you
105     run into issues with this.
106     </impo>
107    
108     <impo>
109     This document uses apache-1.3.x. Apache-2 has been marked stable in portage.
110     However there are still a number of issues with php integration. Until php
111     support in apache-2.0.x is marked stable, this guide will continue to use the
112     1.3.x version.
113     </impo>
114    
115     <impo>
116     You need a domain name to run a public mail server, or at least an MX record
117     for a domain. Ideally you would have control of at least two domains to take
118     advantage of your new virtual domain functionality.
119     </impo>
120    
121     <impo>
122     Make sure <path>/etc/hostname</path> is set to the right hostname for your mail
123     server. Verify your hostname is set correctly with <c>hostname</c>. Also
124     verify that there are no conflicting entries in <path>/etc/hosts</path>.
125     </impo>
126    
127     <note>
128     It is recommended that you read this entire document and familiarize yourself
129     with all the steps before attempting the install. If you run into problems with
130     any of the steps, check the troubleshooting guide at the end of this document.
131     Also, not all the referenced packages are necessary, this set up is very
132     flexible. For instance, if you do not desire a web interface, feel free to skip
133     the squirrelmail section.
134     </note>
135    
136 zhen 1.3 </body>
137 swift 1.26 </section>
138 zhen 1.1 </chapter>
139 swift 1.26
140 zhen 1.1 <chapter>
141     <title>Postfix Basics</title>
142 swift 1.26 <section>
143 zhen 1.3 <body>
144 neysx 1.39
145     <pre caption="Install postfix">
146     # <i>emerge postfix</i>
147 zhen 1.3 </pre>
148 neysx 1.39
149     <warn>
150     Verify that you have not installed any other MTA, such as ssmtp, exim, or
151     qmail, or you will surely have BIG problems.
152     </warn>
153    
154     <p>
155     After postfix is installed, it's time to configure it. Change the following
156     options in <path>/etc/postfix/main.cf</path>:
157     </p>
158    
159     <pre caption="/etc/postfix/main.cf">
160 rajiv 1.14 myhostname = $host.domain.name
161     mydomain = $domain.name
162     inet_interfaces = all
163     mydestination = $myhostname, localhost.$mydomain $mydomain
164     mynetworks = my.ip.net.work/24, 127.0.0.0/8
165     home_mailbox = .maildir/
166     local_destination_concurrency_limit = 2
167 neysx 1.39 default_destination_concurrency_limit = 10
168     </pre>
169    
170     <p>
171     Next change the following in <path>/etc/postfix/master.cf</path>. This will
172     turn on verbose output for debugging:
173     </p>
174    
175     <pre caption="/etc/postfix/master.cf">
176 rajiv 1.14 # service type private unpriv chroot wakeup maxproc command + args
177     # (yes) (yes) (yes) (never) (50)
178     #
179     ==========================================================================
180 neysx 1.39 <comment>(Just add the "-v" after the smtpd in the following line)</comment>
181 rajiv 1.14 smtp inet n - n - - smtpd -v
182 neysx 1.39 </pre>
183 rajiv 1.14
184 neysx 1.39 <p>
185     Next, edit <path>/etc/mail/aliases</path> to add your local aliases. There
186     should at least be an alias for root like: <c>root: your@email.address</c>.
187     </p>
188    
189     <pre caption="Starting postfix for the first time">
190 rajiv 1.14 # <i>/usr/bin/newaliases</i>
191 neysx 1.39 <comment>(This will install the new aliases. You only need to do this
192     when you update or install aliases.)</comment>
193 zhen 1.3
194 rajiv 1.14 # <i>/etc/init.d/postfix start</i>
195 zhen 1.3 </pre>
196 neysx 1.39
197     <p>
198     Now that postfix is running, fire up your favorite console mail client and send
199     yourself an email. I use <c>mutt</c> for all my console mail. Verify that
200     postfix is delivering mail to local users, once that's done, we're on to the
201     next step.
202     </p>
203    
204     <note>
205     I strongly recommend that you verify this basic postfix setup is functioning
206     before you progress to the next step of the howto.
207     </note>
208    
209 zhen 1.3 </body>
210 swift 1.26 </section>
211 zhen 1.1 </chapter>
212 neysx 1.39
213 zhen 1.1 <chapter>
214     <title>Courier-imap</title>
215 swift 1.26 <section>
216 zhen 1.3 <body>
217 neysx 1.39
218     <pre caption="Install courier-imap">
219     # <i>emerge courier-imap</i>
220 zhen 1.3 </pre>
221 neysx 1.39
222     <pre caption="Courier-imap configuration">
223 rajiv 1.14 # <i>cd /etc/courier-imap</i>
224 neysx 1.39 <comment>(If you want to use the ssl capabilities of courier-imap or pop3,
225     you'll need to create certs for this purpose.
226     This step is recommended. If you do not want to use ssl, skip this step.)</comment>
227 rajiv 1.14
228     # <i>nano -w pop3d.cnf</i>
229     # <i>nano -w imapd.cnf</i>
230 neysx 1.39 <comment>(Change the C, ST, L, CN, and email parameters to match your server.)</comment>
231 rajiv 1.14
232     # <i>mkpop3dcert</i>
233     # <i>mkimapdcert</i>
234 zhen 1.3 </pre>
235 neysx 1.39
236     <pre caption="Start the courier services you need.">
237 rajiv 1.14 # <i>/etc/init.d/courier-imapd start</i>
238     # <i>/etc/init.d/courier-imapd-ssl start</i>
239     # <i>/etc/init.d/courier-pop3d start</i>
240     # <i>/etc/init.d/courier-pop3d-ssl start</i>
241 zhen 1.3 </pre>
242 neysx 1.39
243     <p>
244     Start up your favorite mail client and verify that all connections you've
245     started work for receiving and sending mail. Now that the basics work, we're
246     going to do a whole bunch of stuff at once to get the rest of the system
247     running. Again, please verify that what we've installed already works before
248     progressing.
249     </p>
250    
251 zhen 1.3 </body>
252 swift 1.26 </section>
253 zhen 1.1 </chapter>
254 neysx 1.39
255 zhen 1.1 <chapter>
256     <title>Cyrus-sasl</title>
257 swift 1.26 <section>
258 zhen 1.3 <body>
259 neysx 1.39
260     <p>
261     Next we're going to install cyrus-sasl. Sasl is going to play the role of
262     actually passing your auth variables to pam, which will in turn pass that
263     information to mysql for authentication of smtp users. For this howto, we'll
264     not even try to verify that sasl is working until mysql is set up and contains
265     a test user. Which is fine since we'll be authenticating against mysql in the
266     end anyway.
267     </p>
268    
269     <pre caption="Configuring and installing the cyrus-sasl ebuild">
270 swift 1.36 # <i>emerge cyrus-sasl</i>
271 zhen 1.3 </pre>
272 neysx 1.39
273     <p>
274     Next, edit <path>/etc/sasl2/smtpd.conf</path>.
275     </p>
276    
277     <pre caption="Starting sasl">
278 swift 1.27 # <i>nano -w /etc/sasl2/smtpd.conf</i>
279 swift 1.41 mech_list: PLAIN LOGIN
280 rajiv 1.14 pwcheck_method: saslauthd
281 swift 1.41 # <i>nano -w /etc/conf.d/saslauthd</i>
282     SASLAUTHD_OPTS="${SASLAUTH_MECH} -a pam -r"
283 rajiv 1.14 # <i>/etc/init.d/saslauthd start</i>
284 zhen 1.3 </pre>
285 neysx 1.39
286 zhen 1.3 </body>
287 swift 1.26 </section>
288 zhen 1.1 </chapter>
289 neysx 1.39
290 zhen 1.1 <chapter>
291     <title>SSL Certs for Postfix and Apache</title>
292 swift 1.26 <section>
293 zhen 1.3 <body>
294 neysx 1.39
295     <p>
296     Next we're going to make a set of ssl certificates for postfix and apache.
297     </p>
298    
299     <pre caption="Making ssl certicates">
300 rajiv 1.14 # <i>cd /etc/ssl/</i>
301     # <i>nano -w openssl.cnf</i>
302    
303 neysx 1.39 <comment>Change the following default values for your domain:</comment>
304 rajiv 1.14 countryName_default
305     stateOrProvinceName_default
306     localityName_default
307     0.organizationName_default
308     commonName_default
309     emailAddress_default.
310    
311 neysx 1.39 <comment>(If the variables are not already present, just add them in a sensible place.)</comment>
312 zhen 1.1
313 rajiv 1.14 # <i>cd misc</i>
314     # <i>nano -w CA.pl</i>
315 neysx 1.39 <comment>(We need to add -nodes to the # create a certificate and
316     #create a certificate request code in order to let our new ssl
317     certs be loaded without a password. Otherwise when you
318     reboot your ssl certs will not be available.)</comment>
319 rajiv 1.14
320     # create a certificate
321 neysx 1.39 system ("$REQ -new -nodes -x509 -keyout newreq.pem -out newreq.pem $DAYS");
322 rajiv 1.14
323     # create a certificate request
324 neysx 1.39 system ("$REQ -new -nodes -keyout newreq.pem -out newreq.pem $DAYS");
325 zhen 1.1
326 rajiv 1.14 # <i>./CA.pl -newca</i>
327     # <i>./CA.pl -newreq</i>
328     # <i>./CA.pl -sign</i>
329     # <i>cp newcert.pem /etc/postfix</i>
330     # <i>cp newreq.pem /etc/postfix</i>
331     # <i>cp demoCA/cacert.pem /etc/postfix</i>
332 neysx 1.39 <comment>(Now we do the same thing for apache.)</comment>
333 zhen 1.3
334 rajiv 1.14 # <i>openssl req -new > new.cert.csr</i>
335     # <i>openssl rsa -in privkey.pem -out new.cert.key</i>
336     # <i>openssl x509 -in new.cert.csr -out new.cert.cert -req -signkey new.cert.key -days 365</i>
337 neysx 1.39 <comment>(Just leave the resulting certificates here for now.
338     We'll install them after Apache is installed.)</comment>
339 zhen 1.3 </pre>
340 neysx 1.39
341 zhen 1.3 </body>
342 swift 1.26 </section>
343 neysx 1.39
344 zhen 1.1 </chapter>
345     <chapter>
346     <title>Adding SSL and SASL support to Postfix</title>
347 swift 1.26 <section>
348 zhen 1.3 <body>
349 neysx 1.39
350     <p>
351     Now edit the postfix config's to make it aware of your new sasl and ssl
352     capabilities. Add the following parameters to the end of the file where they
353     will be easy to find.
354     </p>
355    
356     <pre caption="/etc/postfix/main.cf">
357 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
358    
359     smtpd_sasl_auth_enable = yes
360     smtpd_sasl2_auth_enable = yes
361     smtpd_sasl_security_options = noanonymous
362     broken_sasl_auth_clients = yes
363     smtpd_sasl_local_domain =
364    
365 neysx 1.39 <comment>(The broken_sasl_auth_clients option and the login auth method
366     are for outlook and outlook express only and are undocumented.
367     Isn't having to hack software for stupid, broken, M$ BS great?
368     smtpd_sasl_local_domain appends a domain name to clients using
369     smtp-auth. Make sure it's blank or your user names will get
370     mangled by postfix and be unable to auth.)</comment>
371 zhen 1.1
372 rajiv 1.14 smtpd_recipient_restrictions =
373     permit_sasl_authenticated,
374     permit_mynetworks,
375     reject_unauth_destination
376    
377    
378     smtpd_use_tls = yes
379     #smtpd_tls_auth_only = yes
380     smtpd_tls_key_file = /etc/postfix/newreq.pem
381     smtpd_tls_cert_file = /etc/postfix/newcert.pem
382     smtpd_tls_CAfile = /etc/postfix/cacert.pem
383     smtpd_tls_loglevel = 3
384     smtpd_tls_received_header = yes
385     smtpd_tls_session_cache_timeout = 3600s
386     tls_random_source = dev:/dev/urandom
387    
388 neysx 1.39 <comment>(smtpd_tls_auth_only is commented out to ease testing the system.
389     You can turn this on later if you desire.)</comment>
390 rajiv 1.14
391     # <i>postfix reload</i>
392 zhen 1.3 </pre>
393 neysx 1.39
394     <p>
395     Now we're going to verify that the config's we added were picked up by postfix.
396     </p>
397    
398     <pre caption="Verifying sasl and tls support">
399 rajiv 1.14 # <i>telnet localhost 25</i>
400 zhen 1.1
401 rajiv 1.14 Trying 127.0.0.1...
402     Connected to localhost.
403     Escape character is '^]'.
404     220 mail.domain.com ESMTP Postfix
405     <i>EHLO domain.com</i>
406     250-mail.domain.com
407     250-PIPELINING
408     250-SIZE 10240000
409     250-VRFY
410     250-ETRN
411     250-STARTTLS
412     250-AUTH LOGIN PLAIN
413     250-AUTH=LOGIN PLAIN
414     250-XVERP
415     250 8BITMIME
416     <i>^]</i>
417     telnet> <i>quit</i>
418 zhen 1.3 </pre>
419 neysx 1.39
420     <p>
421     Verify that the above AUTH and STARTTLS lines now appear in your postfix
422     install. As I said before, as it stands now AUTH will not work. that's because
423     sasl will try to auth against it's sasldb, instead of the shadow file for some
424     unknown reason, which we have not set up. So we're going to just plow through
425     and set up mysql to hold all of our auth and virtual domain information.
426     </p>
427    
428 zhen 1.3 </body>
429 swift 1.26 </section>
430 zhen 1.1 </chapter>
431 neysx 1.39
432 zhen 1.1 <chapter>
433     <title>MySQL</title>
434 swift 1.26 <section>
435 zhen 1.3 <body>
436 neysx 1.39
437     <p>
438     Next we're going to install and configure MySQL. You'll need the <uri
439     link="http://www.gentoo.org/doc/en/files/genericmailsql.sql">genericmailsql.sql</uri>
440     dumpfile for this step.
441     </p>
442    
443     <pre caption="Installing and configuring MySQL">
444 rajiv 1.14 # <i>emerge mysql</i>
445 zhen 1.3
446 rajiv 1.14 # <i>/usr/bin/mysql_install_db</i>
447 neysx 1.39 <comment>(After this command runs follow the onscreen directions
448     for adding a root password with mysql,
449     not mysqladmin, otherwise your db will be wide open.)</comment>
450 zhen 1.1
451 rajiv 1.14 # <i>/etc/init.d/mysql start</i>
452     # <i>mysqladmin -u root -p create mailsql</i>
453     # <i>mysql -u root -p mailsql &lt; genericmailsql.sql</i>
454    
455     # <i>mysql -u root -p mysql</i>
456     mysql> <i>GRANT SELECT,INSERT,UPDATE,DELETE</i>
457     -> <i>ON mailsql.*</i>
458     -> <i>TO mailsql@localhost</i>
459     -> <i>IDENTIFIED BY '$password';</i>
460    
461     -> <i>quit</i>
462 neysx 1.39 <comment>(Verify that the new mailsql user can connect to the mysql server.)</comment>
463 rajiv 1.14
464     # <i>mysql -u mailsql -p mailsql</i>
465 zhen 1.3 </pre>
466 cam 1.30
467     <p>
468 neysx 1.39 Your new database has default values and tables set up for two domains. The
469     following tables are included:
470 cam 1.30 </p>
471    
472     <ul>
473 neysx 1.39 <li>alias - local email alias and mailman alias information.</li>
474     <li>relocated - relocated user email address maps</li>
475     <li>
476     transport - default mail transport information for all domains you are
477     hosting
478     </li>
479     <li>users - all user account information</li>
480     <li>virtual - virtual domain email alias maps</li>
481 zhen 1.3 </ul>
482 cam 1.30
483 neysx 1.39 <pre caption="alias table sample">
484 rajiv 1.15 id alias destination
485     1 root foo@bar.com
486     2 postmaster foo@bar.com
487 rajiv 1.14 </pre>
488 neysx 1.39
489     <pre caption="user table sample">
490     <comment>(Line wrapped for clarity.)</comment>
491 rajiv 1.15 id email clear name uid gid homedir \
492     maildir quota postfix
493     10 foo@virt-bar.org $password realname virtid virtid /home/vmail \
494     /home/vmail/virt-bar.org/foo/.maildir/ y
495     13 foo@bar.com $password realname localid localid /home/foo \
496     /home/foo/.maildir/ y
497 rajiv 1.14 </pre>
498 swift 1.37
499     <p>
500     The values of the <c>virtid</c> uid and gid should be those of the <c>vmail</c>
501     user and group.
502     </p>
503    
504 neysx 1.39 <pre caption="transport table sample">
505 rajiv 1.15 id domain destination
506     1 bar.com local:
507     2 virt-bar.org virtual:
508 rajiv 1.14 </pre>
509 neysx 1.39
510     <pre caption="virtual table sample">
511 rajiv 1.15 id email destination
512     3 root@virt-bar.org other@email.address
513 rajiv 1.14 </pre>
514 neysx 1.39
515 zhen 1.3 </body>
516 swift 1.26 </section>
517 zhen 1.1 </chapter>
518 neysx 1.39
519 zhen 1.1 <chapter>
520     <title>Apache and phpMyAdmin</title>
521 swift 1.26 <section>
522 zhen 1.3 <body>
523 neysx 1.39
524     <p>
525     Next we'll set up apache and add an interface to interact with the database
526     more easily.
527     </p>
528    
529     <pre caption="Setting up apache and phpmyadmin">
530 swift 1.17 # <i>emerge apache mod_php phpmyadmin</i>
531 zhen 1.3 </pre>
532 cam 1.30
533     <p>
534 neysx 1.39 There are plenty of guides out there about how to set up apache with php. Like
535     this one: <uri>http://www.linuxguruz.org/z.php?id=31</uri>. There are also
536     numerous posts on <uri>http://forums.gentoo.org</uri> detailing how to solve
537     problems with the installation (search for 'apache php'). So, that said, I'm
538     not going to cover it here. Set up the apache and php installs, then continue
539     with this howto. Now, a word for the wise: .htaccess the directory that you put
540     phpmyadmin in. If you do not do this, search engine spiders will come along and
541     index the page which in turn will mean that anyone will be able to find your
542     phpmyadmin page via google and in turn be able to come change your database
543     however they want which is <e>BAD!</e> There are many howtos on this
544     including: <uri>http://www.csoft.net/docs/micro/htaccess.html.en</uri>.
545     </p>
546    
547     <p>
548     Now we're going to install the Apache certificates we made previously. The
549     Apache-SSL directives that you need to use the resulting cert are:
550 cam 1.30 </p>
551    
552     <ul>
553 neysx 1.39 <li>SSLCertificateFile /path/to/certs/new.cert.cert</li>
554     <li>SSLCertificateKeyFile /path/to/certs/new.cert.key</li>
555 zhen 1.3 </ul>
556 cam 1.30
557 neysx 1.39 <pre caption="Install Apache SSL certificates">
558 rajiv 1.14 # <i>cp /etc/ssl/misc/new.cert.cert /etc/apache/conf/ssl/</i>
559     # <i>cp /etc/ssl/misc/new.cert.key /etc/apache/conf/ssl/</i>
560     # <i>nano -w /etc/apache/conf/vhosts/ssl.default-vhost.conf</i>
561 neysx 1.39
562     <comment>(Change the following parameters)</comment>
563 rajiv 1.14
564     ServerName host.domain.name
565     ServerAdmin your@email.address
566     SSLCertificateFile /etc/apache/conf/ssl/new.cert.cert
567     SSLCertificateKeyFile /etc/apache/conf/ssl/new.cert.key
568    
569     # <i>/etc/init.d/apache restart</i>
570 zhen 1.3 </pre>
571 neysx 1.39
572     <note>
573     If you have an existing apache install, you'll likely have to perform a full
574     server reboot to install your new certificates. Check your logs to verify
575     apache restarted successfully.
576     </note>
577    
578     <p>
579     Next, configure phpMyAdmin.
580     </p>
581    
582     <pre caption="Configuring phpMyAdmin">
583 pylon 1.21 # <i>nano -w /var/www/localhost/htdocs/phpmyadmin/config.inc.php</i>
584 neysx 1.39 <comment>(Change the following parameters.)</comment>
585 rajiv 1.14
586 rajiv 1.15 $cfg['Servers'][$i]['host'] = 'localhost'; // MySQL hostname
587     $cfg['Servers'][$i]['controluser'] = 'mailsql'; // MySQL control user settings
588     // (this user must have read-only
589 neysx 1.39 $cfg['Servers'][$i]['controlpass'] = '$password'; // access to the "mysql/user"
590     // and "mysql/db" tables)
591 rajiv 1.15 $cfg['Servers'][$i]['user'] = 'mailsql'; // MySQL user
592     $cfg['Servers'][$i]['password'] = '$password'; // MySQL password
593 rajiv 1.14 </pre>
594 neysx 1.39
595     <p>
596     Now enter the phpmyadmin page and browse the tables. You'll want to add in your
597     local aliases, edit your user table to add a test user, and change your
598     transport table to add information about your domains. The default values
599     supplied with the dumpfile should be a sufficient guide to what values need to
600     go where. Make sure that if you put information in the database that it is
601     accurate. For instance, make sure the local users home dir exists and that the
602     correct uid/gid values are in place. The maildirs should be created
603     automatically by postfix when the user receives their first email. So, in
604     general, it's a good idea to send a "Welcome" mail to a new user
605     after you setup their account to make sure the .maildir gets created.
606     </p>
607    
608 zhen 1.3 </body>
609 swift 1.26 </section>
610 zhen 1.1 </chapter>
611 neysx 1.39
612 zhen 1.1 <chapter>
613     <title>The vmail user</title>
614 swift 1.26 <section>
615 zhen 1.3 <body>
616 neysx 1.39
617     <p>
618     At this point you may be wondering what user and directory to use for virtual
619     mail users, and rightly so. Let's set that up.
620     </p>
621    
622     <pre caption="Adding the vmail user">
623 rajiv 1.14 # <i>adduser -d /home/vmail -s /bin/false vmail</i>
624     # <i>uid=`cat /etc/passwd | grep vmail | cut -f 3 -d :`</i>
625     # <i>groupadd -g $uid vmail</i>
626     # <i>mkdir /home/vmail</i>
627 cam 1.29 # <i>chown vmail: /home/vmail</i>
628 zhen 1.3 </pre>
629 neysx 1.39
630     <p>
631     So now when you're setting up vmail accounts, use the vmail uid, gid, and
632     homedir. When you're setting up local accounts, use that users uid, gid, and
633     homedir. We've been meaning to create a php admin page for this setup but
634     haven't gotten around to it yet, as phpmyadmin generally works fine for us.
635     </p>
636    
637 zhen 1.3 </body>
638 swift 1.26 </section>
639 zhen 1.1 </chapter>
640 neysx 1.39
641 zhen 1.1 <chapter>
642     <title>Configuring MySQL Authentication and vhosts</title>
643 swift 1.26 <section>
644 zhen 1.3 <body>
645 neysx 1.39
646     <p>
647     Next we'll reconfigure our authentication to use the mailsql database in
648     courier-imap and postfix. In all of the following examples, replace
649     <c>$password</c> with the password you set for the mailsql mysql user.
650     </p>
651    
652     <pre caption="Configuring authentication">
653 swift 1.20 # <i>emerge pam_mysql</i>
654 swift 1.43 # <i>nano -w /etc/pam.d/smtp</i>
655 neysx 1.39 <comment>(Comment out the existing auth lines and add the following as shown.)</comment>
656 zhen 1.1
657 swift 1.43 #auth required /lib/security/pam_stack.so service=system-auth
658     #account required /lib/security/pam_stack.so service=system-auth
659 rajiv 1.14
660 swift 1.18 auth optional pam_mysql.so host=localhost db=mailsql user=mailsql \
661 rajiv 1.14 passwd=$password table=users usercolumn=email passwdcolumn=clear crypt=0
662 swift 1.18 account required pam_mysql.so host=localhost db=mailsql user=mailsql \
663 rajiv 1.14 passwd=$password table=users usercolumn=email passwdcolumn=clear crypt=0
664 zhen 1.1
665 zhen 1.3 </pre>
666 neysx 1.39
667     <p>
668     Next, we need to edit courier's authentication config's.
669     </p>
670    
671     <pre caption="Configuring authentication">
672 rajiv 1.14 # <i>nano -w /etc/courier-imap/authdaemonrc</i>
673 neysx 1.39 authmodulelist="authmysql authpam"
674 zhen 1.1
675 rajiv 1.14 # <i>nano -w /etc/courier-imap/authdaemond.conf</i>
676 neysx 1.39 AUTHDAEMOND="authdaemond.mysql"
677 zhen 1.1
678 rajiv 1.14 # <i>nano -w /etc/courier-imap/authmysqlrc</i>
679     MYSQL_SERVER localhost
680     MYSQL_USERNAME mailsql
681     MYSQL_PASSWORD $password
682     MYSQL_DATABASE mailsql
683     MYSQL_USER_TABLE users
684 neysx 1.39 <comment>(Make sure the following line is commented out since we're storing plaintext.)</comment>
685     #MYSQL_CRYPT_PWFIELD crypt
686 rajiv 1.14 MYSQL_CLEAR_PWFIELD clear
687     MYSQL_UID_FIELD uid
688     MYSQL_GID_FIELD gid
689     MYSQL_LOGIN_FIELD email
690     MYSQL_HOME_FIELD homedir
691     MYSQL_NAME_FIELD name
692     MYSQL_MAILDIR_FIELD maildir
693 zhen 1.1
694 swift 1.44 # <i>/etc/init.d/courier-authlib restart</i>
695 rajiv 1.14 # <i>/etc/init.d/saslauthd restart</i>
696 zhen 1.3 </pre>
697 neysx 1.39
698     <p>
699     We're almost there I promise! Next, set up the rest of the necessary config's
700     for postfix to interract with the database for all it's other transport needs.
701     </p>
702    
703     <pre caption="/etc/postfix/mysql-aliases.cf">
704 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-aliases.cf</i>
705     # mysql-aliases.cf
706 zhen 1.1
707 rajiv 1.14 user = mailsql
708     password = $password
709     dbname = mailsql
710     table = alias
711     select_field = destination
712     where_field = alias
713     hosts = unix:/var/run/mysqld/mysqld.sock
714     </pre>
715 neysx 1.39
716     <pre caption="/etc/postfix/mysql-relocated.cf">
717 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-relocated.cf</i>
718     # mysql-relocated.cf
719 zhen 1.1
720 rajiv 1.14 user = mailsql
721     password = $password
722     dbname = mailsql
723     table = relocated
724     select_field = destination
725     where_field = email
726     hosts = unix:/var/run/mysqld/mysqld.sock
727     </pre>
728 neysx 1.39
729     <pre caption="/etc/postfix/mysql-transport.cf (optional)">
730 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-transport.cf</i>
731     # mysql-transport.cf
732 zhen 1.1
733 rajiv 1.14 user = mailsql
734     password = $password
735     dbname = mailsql
736     table = transport
737     select_field = destination
738     where_field = domain
739     hosts = unix:/var/run/mysqld/mysqld.sock
740     </pre>
741 neysx 1.39
742     <pre caption="/etc/postfix/mysql-virtual-gid.cf (optional)">
743 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-gid.cf</i>
744     #myql-virtual-gid.cf
745 zhen 1.1
746 rajiv 1.14 user = mailsql
747     password = $password
748     dbname = mailsql
749     table = users
750     select_field = gid
751     where_field = email
752     additional_conditions = and postfix = 'y'
753     hosts = unix:/var/run/mysqld/mysqld.sock
754     </pre>
755 neysx 1.39
756     <pre caption="/etc/postfix/mysql-virtual-maps.cf">
757 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-maps.cf</i>
758     #myql-virtual-maps.cf
759 zhen 1.1
760 rajiv 1.14 user = mailsql
761     password = $password
762     dbname = mailsql
763     table = users
764     select_field = maildir
765     where_field = email
766     additional_conditions = and postfix = 'y'
767     hosts = unix:/var/run/mysqld/mysqld.sock
768     </pre>
769 neysx 1.39
770     <pre caption="/etc/postfix/mysql-virtual-uid.cf (optional)">
771 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-uid.cf</i>
772     # mysql-virtual-uid.cf
773 zhen 1.1
774 rajiv 1.14 user = mailsql
775     password = $password
776     dbname = mailsql
777     table = users
778     select_field = uid
779     where_field = email
780     additional_conditions = and postfix = 'y'
781     hosts = unix:/var/run/mysqld/mysqld.sock
782     </pre>
783 neysx 1.39
784     <pre caption="/etc/postfix/mysql-virtual.cf">
785 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual.cf</i>
786     # mysql-virtual.cf
787 zhen 1.1
788 rajiv 1.14 user = mailsql
789     password = $password
790     dbname = mailsql
791     table = virtual
792     select_field = destination
793     where_field = email
794     hosts = unix:/var/run/mysqld/mysqld.sock
795     </pre>
796 neysx 1.39
797     <p>
798     Lastly, edit <path>/etc/postfix/main.cf</path> one more time.
799     </p>
800    
801     <pre caption="/etc/postfix/main.cf">
802 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
803     alias_maps = mysql:/etc/postfix/mysql-aliases.cf
804     relocated_maps = mysql:/etc/postfix/mysql-relocated.cf
805    
806     local_transport = local
807     local_recipient_maps = $alias_maps $virtual_mailbox_maps unix:passwd.byname
808    
809     virtual_transport = virtual
810     virtual_mailbox_domains =
811     virt-bar.com,
812     $other-virtual-domain.com
813    
814     virtual_minimum_uid = 1000
815     virtual_gid_maps = static:$vmail-gid
816     virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-maps.cf
817     virtual_alias_maps = mysql:/etc/postfix/mysql-virtual.cf
818     virtual_uid_maps = static:$vmail-uid
819     virtual_mailbox_base = /
820     #virtual_mailbox_limit =
821     </pre>
822 swift 1.24
823     <p>
824     For security reasons you should change the permissions of the various
825     <path>/etc/mail/mysql-*.cf</path>:
826     </p>
827    
828     <pre caption="Changing file permission">
829     # <i>chmod 640 /etc/postfix/mysql-*.cf</i>
830     # <i>chgrp postfix /etc/postfix/mysql-*.cf</i>
831     </pre>
832    
833 neysx 1.39 <p>
834     As of Postfix 2.0.x, there were a number of significant changes over the 1.1.x
835     release. Notably the transport, virtual-gid, and virtual-uid tables are no
836     longer necessary. The tables are still included if you wish to use them.
837     </p>
838    
839     <note>
840     It is recommended that you read VIRTUAL_README included with the postfix docs
841     for more information.
842     </note>
843    
844     <pre caption="Make postfix reload its tables">
845     # <i>postfix reload</i>
846 zhen 1.3 </pre>
847 neysx 1.39
848     <p>
849     Now, if all went well, you should have a functioning mailhost. Users should be
850     able to authenticate against the sql database, using their full email address,
851     for pop3, imap, and smtp. I would highly suggest that you verify that
852     everything is working at this point. If you run into problems (with as many
853     things as this setup has going on, it's likely that you will) check the
854     troubleshooting section of this howto.
855     </p>
856    
857 zhen 1.3 </body>
858 swift 1.26 </section>
859 zhen 1.1 </chapter>
860 neysx 1.39
861 zhen 1.1 <chapter>
862     <title>Squirrelmail</title>
863 swift 1.26 <section>
864 zhen 1.3 <body>
865 neysx 1.39
866     <pre caption="Install squirrelmail">
867 rajiv 1.14 # <i>emerge squirrelmail</i>
868 swift 1.40 <comment>(Install squirrelmail to localhost so that it's accessed by http://localhost/mail)
869     (Substitute 1.4.3a-r2 with the version you use)</comment>
870 zhen 1.3
871 swift 1.40 # <i>webapp-config -I -h localhost -d /mail squirrelmail 1.4.3a-r2</i>
872 swift 1.31 # <i>cd /var/www/localhost/htdocs/mail/config</i>
873     # <i>perl ./conf.pl</i>
874 neysx 1.39 <comment>(Change your Organization, Server, and Folder settings for squirrelmail.
875     Now you should be able to login to squirrelmail, again - with your full email address,
876     and use your new webmail setup.)</comment>
877 zhen 1.3 </pre>
878 neysx 1.39
879 zhen 1.3 </body>
880 swift 1.26 </section>
881 zhen 1.1 </chapter>
882 neysx 1.39
883 zhen 1.1 <chapter>
884     <title>Mailman</title>
885 swift 1.26 <section>
886 zhen 1.3 <body>
887 neysx 1.39
888     <p>
889     Last step: mailman. The new version of mailman has very nice virtual domain
890     support, which is why I use it, not to mention it's really a great package. To
891     get this package installed and working correctly for virtual domains is going
892     to require a bit of hacking. I really recommend reading all of the mailman
893     documentation, including README.POSTFIX.gz, to understand what's being done
894     here.
895     </p>
896    
897     <p>
898     One further note, current versions of mailman install to /usr/local/mailman. If
899     you're like me and wish to change the default install location, it can be
900     overridden in the ebuild filoe by changing the INSTALLDIR variable.
901     </p>
902    
903 zhen 1.3 <pre caption="/usr/portage/net-mail/mailman/mailman-$ver.ebuild">
904 rajiv 1.14 # <i>nano -w /usr/portage/net-mail/mailman/mailman-$ver.ebuild</i>
905     MAILGID="280"
906 neysx 1.39 <comment>(Set MAILGID to the mailman group instead of nobody
907     This is needed for postfix integration.)</comment>
908 zhen 1.3 </pre>
909 neysx 1.39
910     <pre caption="Install mailman">
911 rajiv 1.14 # <i>emerge mailman</i>
912 neysx 1.39 <comment>(This package is currently masked as well, so you'll need to unmask it or give
913     emerge an explicit path to the ebuild. Once it's installed, follow the directions
914     in the README.gentoo.gz *except* do not add your aliases to /etc/mail/aliases.
915     We will instead be linking the entire alias db into postfix.)</comment>
916 zhen 1.3
917 rajiv 1.14 # <i>zless /usr/share/doc/mailman-$ver/README.gentoo.gz</i>
918 zhen 1.3 </pre>
919 neysx 1.39
920 antifa 1.12 <pre caption="Setting defaults: Mailman/Defaults.py">
921 rajiv 1.14 # <i> nano -w /var/mailman/Mailman/Defaults.py</i>
922 neysx 1.39 <comment>(Change the values below to reflect your primary domain, virtuals will be set next.)</comment>
923 rajiv 1.14 DEFAULT_EMAIL_HOST = 'domain.com'
924     DEFAULT_URL_HOST = 'www.domain.com'
925 antifa 1.12 </pre>
926 neysx 1.39
927 zhen 1.3 <pre caption="mailman config: mm_cfg.py">
928 rajiv 1.14 # <i>nano -w /var/mailman/Mailman/mm_cfg.py</i>
929     MTA = "Postfix"
930     POSTFIX_STYLE_VIRTUAL_DOMAINS = ['virt-domain.com', 'virt.domain2.com']
931     add_virtualhost('www.virt.domain.com', 'virt.domain.com')
932     add_virtualhost('www.virt.domain2.com', 'virt.domain2.com')
933 neysx 1.39 <comment>(This is required for your virtual domains for mailman to function.)</comment>
934 zhen 1.3 </pre>
935 neysx 1.39
936     <pre caption="And last but not least">
937     <comment>(Once that's finished, add your first list.)</comment>
938 zhen 1.3
939 rajiv 1.14 # <i>su mailman</i>
940     # <i>cd ~</i>
941     # <i>bin/newlist test</i>
942 neysx 1.39 Enter the email of the person running the list: <i>your@email.address</i>
943 rajiv 1.14 Initial test password:
944     Hit enter to continue with test owner notification...
945 neysx 1.39 <comment>(Virtual domain lists may be specified with
946     list@domain.com style list names.)</comment>
947 rajiv 1.14 # <i>bin/genaliases</i>
948 neysx 1.39 <comment>(Now that your aliases have been generated,
949     verify that they were added successfully.)</comment>
950 rajiv 1.14
951     # <i>nano -w data/aliases</i>
952     # STANZA START: test
953     # CREATED:
954     test: "|/var/mailman/mail/mailman post test"
955     test-admin: "|/var/mailman/mail/mailman admin test"
956     test-bounces: "|/var/mailman/mail/mailman bounces test"
957     test-confirm: "|/var/mailman/mail/mailman confirm test"
958     test-join: "|/var/mailman/mail/mailman join test"
959     test-leave: "|/var/mailman/mail/mailman leave test"
960     test-owner: "|/var/mailman/mail/mailman owner test"
961     test-request: "|/var/mailman/mail/mailman request test"
962     test-subscribe: "|/var/mailman/mail/mailman subscribe test"
963     test-unsubscribe: "|/var/mailman/mail/mailman unsubscribe test"
964     # STANZA END: test
965    
966     # <i>/etc/init.d/mailman start</i>
967     # <i>rc-update add mailman default</i>
968 neysx 1.39 <comment>(To start mailman at once and on every reboot.)</comment>
969 zhen 1.3 </pre>
970    
971     <pre caption="Adding mailman alias support to postfix">
972 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
973     owner_request_special = no
974     recipient_delimiter = +
975 neysx 1.39 <comment>(Read README.POSTFIX.gz for details on this.)</comment>
976 rajiv 1.14
977     alias_maps =
978     hash:/var/mailman/data/aliases,
979     mysql:/etc/postfix/mysql-aliases.cf
980    
981     virtual_alias_maps =
982     hash:/var/mailman/data/virtual-mailman,
983     mysql:/etc/postfix/mysql-virtual.cf
984 neysx 1.39 <comment>(This adds mailman alias file support to postfix
985     You may of course use the mysql tables for this,
986     but I hate doing that by hand. Also, if you are not
987     using virtual domains, adding the virtual alias maps
988     to postfix may cause problems, be warned.)</comment>
989 zhen 1.3 </pre>
990 neysx 1.39
991     <p>
992     You should now be able to setup mailing lists for any domain on your box. Last
993     note on this, make sure you run all mailman commands as the user mailman (<c>su
994     mailman</c>) or else the permissions will be wrong and you'll have to fix them.
995     Read the mailman doc's for more information on setting up and managing mailman
996     lists.
997     </p>
998    
999 zhen 1.3 </body>
1000 swift 1.26 </section>
1001 zhen 1.3 </chapter>
1002 neysx 1.39
1003 zhen 1.3 <chapter>
1004     <title>Content Filtering and Anti-Virus</title>
1005 swift 1.26 <section>
1006 neysx 1.39 <body>
1007    
1008     <p>
1009 neysx 1.42 For content filtering and Anti-Virus, please consult our <uri
1010     link="/doc/en/mailfilter-guide.xml">mail filtering gateway guide</uri>.
1011 neysx 1.39 </p>
1012    
1013     </body>
1014 swift 1.26 </section>
1015 zhen 1.1 </chapter>
1016 neysx 1.39
1017 zhen 1.1 <chapter>
1018     <title>Wrap Up</title>
1019 swift 1.26 <section>
1020 zhen 1.3 <body>
1021 neysx 1.39
1022     <p>
1023     Ok, you're all set, edit <path>/etc/postfix/master.cf</path> and turn off
1024     verbose mode for production use. You'll probably also want to add the services
1025     to your startup routine to make sure everything comes back up on a reboot. Make
1026     sure to add all the services you're using - apache, mysql, saslauthd, postfix,
1027     courier-imapd, courier-imapd-ssl, courier-pop3d, and courier-pop3d-ssl are all
1028     up to your decision on what access you want to provide. I generally have all
1029     the services enabled.
1030     </p>
1031    
1032     <pre caption="Wrap up">
1033 rajiv 1.14 # <i>postfix reload</i>
1034     # <i>rc-update add $service default</i>
1035 zhen 1.3 </pre>
1036 neysx 1.39
1037 zhen 1.3 <p>
1038     <e>Have fun!</e>
1039     </p>
1040 neysx 1.39
1041 zhen 1.3 </body>
1042 swift 1.26 </section>
1043 zhen 1.1 </chapter>
1044 neysx 1.39
1045 zhen 1.1 <chapter>
1046     <title>Troubleshooting</title>
1047     <section>
1048 zhen 1.3 <title>Introduction</title>
1049     <body>
1050 neysx 1.39
1051     <p>
1052     Troubleshooting: This is a short troubleshooting guide for the set up we've
1053     detailed how to install here. It is not exhaustive, but meant as a place to get
1054     you started in figuring out problems. With a complicated setup such as this,
1055     it's imperative that you narrow down the problem to the particular component
1056     that is malfunctioning. In general I do that by following a few steps. Start
1057     from the base of the system and work your way up, ruling out components that
1058     work along the way until you discover which component is having the problem.
1059     </p>
1060    
1061 zhen 1.3 </body>
1062 zhen 1.1 </section>
1063     <section>
1064 neysx 1.39 <title>Step 1: Check your config files</title>
1065 zhen 1.3 <body>
1066 neysx 1.39
1067     <p>
1068     Typos are killers, especially when dealing with authentication systems. Scan
1069     your config's and mailsql database for typo's. You can debug all you want, but
1070     if you're not passing the right information back and forth to your mail system,
1071     it's not going to work. If you make a change to a config file for a service,
1072     make sure you restart that service so that the config change gets picked up.
1073     </p>
1074    
1075     <pre caption="How to restart a service">
1076 rajiv 1.14 # <i>/etc/init.d/service restart</i>
1077 zhen 1.3 </pre>
1078 neysx 1.39
1079 zhen 1.3 </body>
1080 zhen 1.1 </section>
1081     <section>
1082 zhen 1.3 <title>Step 2: Are all the necessary services actually running?</title>
1083     <body>
1084 neysx 1.39
1085     <p>
1086     If it's not running, start it up. It's awful hard to debug a service that isn't
1087     running. Sometimes a service will act like it's started but still not function.
1088     Sometimes, when a bad config is used, or a bad transmission comes into a mail
1089     component, the service will hang and keep the port from being used by another
1090     process. Sometimes you can detect this with netstat. Or, if you've been at it
1091     awhile, just take a break and reboot your box in the meantime. That will clear
1092     out any hung services. Then you can come back fresh and try it again.
1093     </p>
1094    
1095     <pre caption="Checking the status of a service">
1096 rajiv 1.14 # <i>/etc/init.d/$service status</i>
1097     # <i>netstat -a | grep $service (or $port)</i>
1098 zhen 1.3 </pre>
1099 neysx 1.39
1100 zhen 1.3 </body>
1101 zhen 1.1 </section>
1102     <section>
1103 zhen 1.3 <title>Step 3: Are all the service using the current config's?</title>
1104     <body>
1105 neysx 1.39
1106     <p>
1107     If you've recently made a change to a config file, restart that service to make
1108     sure it's using the current version. Some of the components will dump their
1109     current config's to you, like postfix.
1110     </p>
1111    
1112     <pre caption="Some services can dump their current config">
1113 rajiv 1.14 # <i>apachectl fullstatus</i> (needs lynx installed)
1114     # <i>apachectl configtest</i> (checks config sanity)
1115     # <i>postconf -n</i> (will tell you exactly what param's postfix is using)
1116     # <i>/etc/init.d/$service restart</i>
1117 zhen 1.3 </pre>
1118 neysx 1.39
1119 zhen 1.3 </body>
1120 zhen 1.1 </section>
1121     <section>
1122 neysx 1.39 <title>Step 4: Check the logs</title>
1123 zhen 1.3 <body>
1124 neysx 1.39
1125     <p>
1126     Repeat after me, logs are my friend. My next troubleshooting stop is always the
1127     logs. Sometimes it's helpful to try a failed operation again then check the
1128     logs so that the error message is right at the bottom (or top depending on your
1129     logger) instead of buried in there somewhere. See if there is any information
1130     in your log that can help you diagnose the problem, or at the very least,
1131     figure out which component is having the problem.
1132     </p>
1133    
1134     <pre caption="Checking the logs">
1135 rajiv 1.14 # <i>kill -USR1 `ps -C metalog -o pid=`</i>(to turn off metalog buffering)
1136     # <i>nano -w /var/log/mail/current</i>
1137     # <i>cat /var/log/mysql/mysql.log</i>
1138     # <i>tail /var/log/apache/error_log</i>
1139 zhen 1.3 </pre>
1140 neysx 1.39
1141     <p>
1142     You may also find the debug_peer parameters in main.cf helpful. Setting these
1143     will increase log output over just verbose mode.
1144     </p>
1145    
1146 zhen 1.3 <pre caption="adding debug_peer support">
1147 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
1148     debug_peer_level = 5
1149     debug_peer_list = $host.domain.name
1150 neysx 1.39 <comment>(Uncomment one of the suggested debugger
1151     commands as well.)</comment>
1152 zhen 1.3 </pre>
1153 neysx 1.39
1154 zhen 1.3 </body>
1155 zhen 1.1 </section>
1156     <section>
1157 neysx 1.39 <title>Step 5: Talk to the service itself</title>
1158 zhen 1.3 <body>
1159 neysx 1.39
1160     <p>
1161     SMTP, IMAP, and POP3 all respond to telnet sessions. As we've seen earlier when
1162     we verified postfix's config. Sometimes it's helpful to open a telnet session
1163     to the service itself and see what's happening.
1164     </p>
1165    
1166     <pre caption="Connect to a service with telnet">
1167 rajiv 1.14 # <i>telnet localhost $port</i>
1168 neysx 1.39 <comment>(SMTP is 25, IMAP is 143, POP3 is 110. You should receive at least an OK string,
1169     letting you know that the service is running and ready to respond to requests.)</comment>
1170 zhen 1.1
1171 rajiv 1.14 Trying 127.0.0.1...
1172     Connected to localhost.
1173     Escape character is '^]'.
1174 rajiv 1.15 * OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc.
1175 rajiv 1.14 </pre>
1176 neysx 1.39
1177 zhen 1.3 </body>
1178 zhen 1.1 </section>
1179     <section>
1180 neysx 1.39 <title>Step 6: Sometimes only the big guns will give you the information you need: strace</title>
1181 zhen 1.3 <body>
1182 neysx 1.39
1183     <p>
1184     You should have this installed anyway. This is an invaluable tool for debugging
1185     software. You can start commands from the command line with strace and watch
1186     all the system calls as they happen. It often dumps a huge amount of
1187     information, so you'll either need to watch it realtime as you retry a failed
1188     transaction with the mail system, or dump the output to a file for review.
1189     </p>
1190    
1191     <pre caption="Using strace">
1192 rajiv 1.14 # <i>emerge strace</i>
1193     # <i>strace $command</i>
1194     # <i>strace -p `ps -C $service -o pid=`</i>
1195 zhen 1.3 </pre>
1196 neysx 1.39
1197 zhen 1.3 </body>
1198 zhen 1.1 </section>
1199     <section>
1200 zhen 1.3 <title>Step 7: Research</title>
1201     <body>
1202 neysx 1.39
1203     <p>
1204     Once you have the information, if you can diagnose and fix the problem, great!
1205     If not, you'll probably need to go digging on the net for information that will
1206     help you fix it. Here's a list of sites you can check to see if your error has
1207     already been resolved. There's also a really good howto on setting up smtp-auth
1208     which contains some great debugging ideas.
1209     </p>
1210 cam 1.30
1211 zhen 1.3 <ul>
1212 neysx 1.39 <li><uri>http://forums.gentoo.org/</uri> - Great forums for gentoo users</li>
1213     <li>
1214     <uri>http://bugs.gentoo.org/</uri> - Bugs database for gentoo - great place
1215     to look for specific errors
1216     </li>
1217     <li><uri>http://postfix.state-of-mind.de/</uri> - smtp-auth howto</li>
1218     <li>
1219     <uri>http://marc.theaimsgroup.com/?l=postfix-users</uri> - Postfix mailing
1220     lists - searchable
1221     </li>
1222     <li>
1223     <uri>http://sourceforge.net/mailarchive/forum.php?forum_id=6705</uri> -
1224     Courier-imap mailing list archives - not searchable
1225     </li>
1226     <li>
1227     <uri>http://www.google.com/</uri> - If all else fails, there's always
1228     google, which has never failed me
1229     </li>
1230     <li>
1231     I also spend a lot of time on irc.freenode.net #gentoo. Irc is a great
1232     place to go for help.
1233     </li>
1234 zhen 1.3 </ul>
1235 cam 1.30
1236 zhen 1.3 </body>
1237 zhen 1.1 </section>
1238     </chapter>
1239     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20