/[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.42 - (hide annotations) (download) (as text)
Fri Mar 25 14:39:17 2005 UTC (9 years, 3 months ago) by neysx
Branch: MAIN
Changes since 1.41: +5 -5 lines
File MIME type: application/xml
#86475: link to mailfilter-guide.xml

1 vapier 1.32 <?xml version='1.0' encoding='UTF-8'?>
2 neysx 1.42 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.41 2005/02/05 15:24:39 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 neysx 1.42 <version>1.0.19</version>
24     <date>2005-03-25</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 rajiv 1.14 # <i>nano -w /etc/pam.d/imap</i>
655 neysx 1.39 <comment>(Comment out the existing auth lines and add the following as shown.)</comment>
656 zhen 1.1
657 rajiv 1.14 #auth required pam_nologin.so
658     #auth required pam_stack.so service=system-auth
659     #account required pam_stack.so service=system-auth
660     #session required pam_stack.so service=system-auth
661    
662 swift 1.18 auth optional pam_mysql.so host=localhost db=mailsql user=mailsql \
663 rajiv 1.14 passwd=$password table=users usercolumn=email passwdcolumn=clear crypt=0
664 swift 1.18 account required pam_mysql.so host=localhost db=mailsql user=mailsql \
665 rajiv 1.14 passwd=$password table=users usercolumn=email passwdcolumn=clear crypt=0
666 zhen 1.1
667 rajiv 1.14 # <i>nano -w /etc/pam.d/pop3</i>
668     # <i>nano -w /etc/pam.d/smtp</i>
669 neysx 1.39 <comment>(Make the same changes to the pop3 and smtp files.)</comment>
670 zhen 1.3 </pre>
671 neysx 1.39
672     <p>
673     Next, we need to edit courier's authentication config's.
674     </p>
675    
676     <pre caption="Configuring authentication">
677 rajiv 1.14 # <i>nano -w /etc/courier-imap/authdaemonrc</i>
678 neysx 1.39 authmodulelist="authmysql authpam"
679 zhen 1.1
680 rajiv 1.14 # <i>nano -w /etc/courier-imap/authdaemond.conf</i>
681 neysx 1.39 AUTHDAEMOND="authdaemond.mysql"
682 zhen 1.1
683 rajiv 1.14 # <i>nano -w /etc/courier-imap/authmysqlrc</i>
684     MYSQL_SERVER localhost
685     MYSQL_USERNAME mailsql
686     MYSQL_PASSWORD $password
687     MYSQL_DATABASE mailsql
688     MYSQL_USER_TABLE users
689 neysx 1.39 <comment>(Make sure the following line is commented out since we're storing plaintext.)</comment>
690     #MYSQL_CRYPT_PWFIELD crypt
691 rajiv 1.14 MYSQL_CLEAR_PWFIELD clear
692     MYSQL_UID_FIELD uid
693     MYSQL_GID_FIELD gid
694     MYSQL_LOGIN_FIELD email
695     MYSQL_HOME_FIELD homedir
696     MYSQL_NAME_FIELD name
697     MYSQL_MAILDIR_FIELD maildir
698 zhen 1.1
699 rajiv 1.14 # <i>/etc/init.d/authdaemond restart</i>
700     # <i>/etc/init.d/saslauthd restart</i>
701 zhen 1.3 </pre>
702 neysx 1.39
703     <p>
704     We're almost there I promise! Next, set up the rest of the necessary config's
705     for postfix to interract with the database for all it's other transport needs.
706     </p>
707    
708     <pre caption="/etc/postfix/mysql-aliases.cf">
709 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-aliases.cf</i>
710     # mysql-aliases.cf
711 zhen 1.1
712 rajiv 1.14 user = mailsql
713     password = $password
714     dbname = mailsql
715     table = alias
716     select_field = destination
717     where_field = alias
718     hosts = unix:/var/run/mysqld/mysqld.sock
719     </pre>
720 neysx 1.39
721     <pre caption="/etc/postfix/mysql-relocated.cf">
722 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-relocated.cf</i>
723     # mysql-relocated.cf
724 zhen 1.1
725 rajiv 1.14 user = mailsql
726     password = $password
727     dbname = mailsql
728     table = relocated
729     select_field = destination
730     where_field = email
731     hosts = unix:/var/run/mysqld/mysqld.sock
732     </pre>
733 neysx 1.39
734     <pre caption="/etc/postfix/mysql-transport.cf (optional)">
735 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-transport.cf</i>
736     # mysql-transport.cf
737 zhen 1.1
738 rajiv 1.14 user = mailsql
739     password = $password
740     dbname = mailsql
741     table = transport
742     select_field = destination
743     where_field = domain
744     hosts = unix:/var/run/mysqld/mysqld.sock
745     </pre>
746 neysx 1.39
747     <pre caption="/etc/postfix/mysql-virtual-gid.cf (optional)">
748 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-gid.cf</i>
749     #myql-virtual-gid.cf
750 zhen 1.1
751 rajiv 1.14 user = mailsql
752     password = $password
753     dbname = mailsql
754     table = users
755     select_field = gid
756     where_field = email
757     additional_conditions = and postfix = 'y'
758     hosts = unix:/var/run/mysqld/mysqld.sock
759     </pre>
760 neysx 1.39
761     <pre caption="/etc/postfix/mysql-virtual-maps.cf">
762 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-maps.cf</i>
763     #myql-virtual-maps.cf
764 zhen 1.1
765 rajiv 1.14 user = mailsql
766     password = $password
767     dbname = mailsql
768     table = users
769     select_field = maildir
770     where_field = email
771     additional_conditions = and postfix = 'y'
772     hosts = unix:/var/run/mysqld/mysqld.sock
773     </pre>
774 neysx 1.39
775     <pre caption="/etc/postfix/mysql-virtual-uid.cf (optional)">
776 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-uid.cf</i>
777     # mysql-virtual-uid.cf
778 zhen 1.1
779 rajiv 1.14 user = mailsql
780     password = $password
781     dbname = mailsql
782     table = users
783     select_field = uid
784     where_field = email
785     additional_conditions = and postfix = 'y'
786     hosts = unix:/var/run/mysqld/mysqld.sock
787     </pre>
788 neysx 1.39
789     <pre caption="/etc/postfix/mysql-virtual.cf">
790 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual.cf</i>
791     # mysql-virtual.cf
792 zhen 1.1
793 rajiv 1.14 user = mailsql
794     password = $password
795     dbname = mailsql
796     table = virtual
797     select_field = destination
798     where_field = email
799     hosts = unix:/var/run/mysqld/mysqld.sock
800     </pre>
801 neysx 1.39
802     <p>
803     Lastly, edit <path>/etc/postfix/main.cf</path> one more time.
804     </p>
805    
806     <pre caption="/etc/postfix/main.cf">
807 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
808     alias_maps = mysql:/etc/postfix/mysql-aliases.cf
809     relocated_maps = mysql:/etc/postfix/mysql-relocated.cf
810    
811     local_transport = local
812     local_recipient_maps = $alias_maps $virtual_mailbox_maps unix:passwd.byname
813    
814     virtual_transport = virtual
815     virtual_mailbox_domains =
816     virt-bar.com,
817     $other-virtual-domain.com
818    
819     virtual_minimum_uid = 1000
820     virtual_gid_maps = static:$vmail-gid
821     virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-maps.cf
822     virtual_alias_maps = mysql:/etc/postfix/mysql-virtual.cf
823     virtual_uid_maps = static:$vmail-uid
824     virtual_mailbox_base = /
825     #virtual_mailbox_limit =
826     </pre>
827 swift 1.24
828     <p>
829     For security reasons you should change the permissions of the various
830     <path>/etc/mail/mysql-*.cf</path>:
831     </p>
832    
833     <pre caption="Changing file permission">
834     # <i>chmod 640 /etc/postfix/mysql-*.cf</i>
835     # <i>chgrp postfix /etc/postfix/mysql-*.cf</i>
836     </pre>
837    
838 neysx 1.39 <p>
839     As of Postfix 2.0.x, there were a number of significant changes over the 1.1.x
840     release. Notably the transport, virtual-gid, and virtual-uid tables are no
841     longer necessary. The tables are still included if you wish to use them.
842     </p>
843    
844     <note>
845     It is recommended that you read VIRTUAL_README included with the postfix docs
846     for more information.
847     </note>
848    
849     <pre caption="Make postfix reload its tables">
850     # <i>postfix reload</i>
851 zhen 1.3 </pre>
852 neysx 1.39
853     <p>
854     Now, if all went well, you should have a functioning mailhost. Users should be
855     able to authenticate against the sql database, using their full email address,
856     for pop3, imap, and smtp. I would highly suggest that you verify that
857     everything is working at this point. If you run into problems (with as many
858     things as this setup has going on, it's likely that you will) check the
859     troubleshooting section of this howto.
860     </p>
861    
862 zhen 1.3 </body>
863 swift 1.26 </section>
864 zhen 1.1 </chapter>
865 neysx 1.39
866 zhen 1.1 <chapter>
867     <title>Squirrelmail</title>
868 swift 1.26 <section>
869 zhen 1.3 <body>
870 neysx 1.39
871     <pre caption="Install squirrelmail">
872 rajiv 1.14 # <i>emerge squirrelmail</i>
873 swift 1.40 <comment>(Install squirrelmail to localhost so that it's accessed by http://localhost/mail)
874     (Substitute 1.4.3a-r2 with the version you use)</comment>
875 zhen 1.3
876 swift 1.40 # <i>webapp-config -I -h localhost -d /mail squirrelmail 1.4.3a-r2</i>
877 swift 1.31 # <i>cd /var/www/localhost/htdocs/mail/config</i>
878     # <i>perl ./conf.pl</i>
879 neysx 1.39 <comment>(Change your Organization, Server, and Folder settings for squirrelmail.
880     Now you should be able to login to squirrelmail, again - with your full email address,
881     and use your new webmail setup.)</comment>
882 zhen 1.3 </pre>
883 neysx 1.39
884 zhen 1.3 </body>
885 swift 1.26 </section>
886 zhen 1.1 </chapter>
887 neysx 1.39
888 zhen 1.1 <chapter>
889     <title>Mailman</title>
890 swift 1.26 <section>
891 zhen 1.3 <body>
892 neysx 1.39
893     <p>
894     Last step: mailman. The new version of mailman has very nice virtual domain
895     support, which is why I use it, not to mention it's really a great package. To
896     get this package installed and working correctly for virtual domains is going
897     to require a bit of hacking. I really recommend reading all of the mailman
898     documentation, including README.POSTFIX.gz, to understand what's being done
899     here.
900     </p>
901    
902     <p>
903     One further note, current versions of mailman install to /usr/local/mailman. If
904     you're like me and wish to change the default install location, it can be
905     overridden in the ebuild filoe by changing the INSTALLDIR variable.
906     </p>
907    
908 zhen 1.3 <pre caption="/usr/portage/net-mail/mailman/mailman-$ver.ebuild">
909 rajiv 1.14 # <i>nano -w /usr/portage/net-mail/mailman/mailman-$ver.ebuild</i>
910     MAILGID="280"
911 neysx 1.39 <comment>(Set MAILGID to the mailman group instead of nobody
912     This is needed for postfix integration.)</comment>
913 zhen 1.3 </pre>
914 neysx 1.39
915     <pre caption="Install mailman">
916 rajiv 1.14 # <i>emerge mailman</i>
917 neysx 1.39 <comment>(This package is currently masked as well, so you'll need to unmask it or give
918     emerge an explicit path to the ebuild. Once it's installed, follow the directions
919     in the README.gentoo.gz *except* do not add your aliases to /etc/mail/aliases.
920     We will instead be linking the entire alias db into postfix.)</comment>
921 zhen 1.3
922 rajiv 1.14 # <i>zless /usr/share/doc/mailman-$ver/README.gentoo.gz</i>
923 zhen 1.3 </pre>
924 neysx 1.39
925 antifa 1.12 <pre caption="Setting defaults: Mailman/Defaults.py">
926 rajiv 1.14 # <i> nano -w /var/mailman/Mailman/Defaults.py</i>
927 neysx 1.39 <comment>(Change the values below to reflect your primary domain, virtuals will be set next.)</comment>
928 rajiv 1.14 DEFAULT_EMAIL_HOST = 'domain.com'
929     DEFAULT_URL_HOST = 'www.domain.com'
930 antifa 1.12 </pre>
931 neysx 1.39
932 zhen 1.3 <pre caption="mailman config: mm_cfg.py">
933 rajiv 1.14 # <i>nano -w /var/mailman/Mailman/mm_cfg.py</i>
934     MTA = "Postfix"
935     POSTFIX_STYLE_VIRTUAL_DOMAINS = ['virt-domain.com', 'virt.domain2.com']
936     add_virtualhost('www.virt.domain.com', 'virt.domain.com')
937     add_virtualhost('www.virt.domain2.com', 'virt.domain2.com')
938 neysx 1.39 <comment>(This is required for your virtual domains for mailman to function.)</comment>
939 zhen 1.3 </pre>
940 neysx 1.39
941     <pre caption="And last but not least">
942     <comment>(Once that's finished, add your first list.)</comment>
943 zhen 1.3
944 rajiv 1.14 # <i>su mailman</i>
945     # <i>cd ~</i>
946     # <i>bin/newlist test</i>
947 neysx 1.39 Enter the email of the person running the list: <i>your@email.address</i>
948 rajiv 1.14 Initial test password:
949     Hit enter to continue with test owner notification...
950 neysx 1.39 <comment>(Virtual domain lists may be specified with
951     list@domain.com style list names.)</comment>
952 rajiv 1.14 # <i>bin/genaliases</i>
953 neysx 1.39 <comment>(Now that your aliases have been generated,
954     verify that they were added successfully.)</comment>
955 rajiv 1.14
956     # <i>nano -w data/aliases</i>
957     # STANZA START: test
958     # CREATED:
959     test: "|/var/mailman/mail/mailman post test"
960     test-admin: "|/var/mailman/mail/mailman admin test"
961     test-bounces: "|/var/mailman/mail/mailman bounces test"
962     test-confirm: "|/var/mailman/mail/mailman confirm test"
963     test-join: "|/var/mailman/mail/mailman join test"
964     test-leave: "|/var/mailman/mail/mailman leave test"
965     test-owner: "|/var/mailman/mail/mailman owner test"
966     test-request: "|/var/mailman/mail/mailman request test"
967     test-subscribe: "|/var/mailman/mail/mailman subscribe test"
968     test-unsubscribe: "|/var/mailman/mail/mailman unsubscribe test"
969     # STANZA END: test
970    
971     # <i>/etc/init.d/mailman start</i>
972     # <i>rc-update add mailman default</i>
973 neysx 1.39 <comment>(To start mailman at once and on every reboot.)</comment>
974 zhen 1.3 </pre>
975    
976     <pre caption="Adding mailman alias support to postfix">
977 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
978     owner_request_special = no
979     recipient_delimiter = +
980 neysx 1.39 <comment>(Read README.POSTFIX.gz for details on this.)</comment>
981 rajiv 1.14
982     alias_maps =
983     hash:/var/mailman/data/aliases,
984     mysql:/etc/postfix/mysql-aliases.cf
985    
986     virtual_alias_maps =
987     hash:/var/mailman/data/virtual-mailman,
988     mysql:/etc/postfix/mysql-virtual.cf
989 neysx 1.39 <comment>(This adds mailman alias file support to postfix
990     You may of course use the mysql tables for this,
991     but I hate doing that by hand. Also, if you are not
992     using virtual domains, adding the virtual alias maps
993     to postfix may cause problems, be warned.)</comment>
994 zhen 1.3 </pre>
995 neysx 1.39
996     <p>
997     You should now be able to setup mailing lists for any domain on your box. Last
998     note on this, make sure you run all mailman commands as the user mailman (<c>su
999     mailman</c>) or else the permissions will be wrong and you'll have to fix them.
1000     Read the mailman doc's for more information on setting up and managing mailman
1001     lists.
1002     </p>
1003    
1004 zhen 1.3 </body>
1005 swift 1.26 </section>
1006 zhen 1.3 </chapter>
1007 neysx 1.39
1008 zhen 1.3 <chapter>
1009     <title>Content Filtering and Anti-Virus</title>
1010 swift 1.26 <section>
1011 neysx 1.39 <body>
1012    
1013     <p>
1014 neysx 1.42 For content filtering and Anti-Virus, please consult our <uri
1015     link="/doc/en/mailfilter-guide.xml">mail filtering gateway guide</uri>.
1016 neysx 1.39 </p>
1017    
1018     </body>
1019 swift 1.26 </section>
1020 zhen 1.1 </chapter>
1021 neysx 1.39
1022 zhen 1.1 <chapter>
1023     <title>Wrap Up</title>
1024 swift 1.26 <section>
1025 zhen 1.3 <body>
1026 neysx 1.39
1027     <p>
1028     Ok, you're all set, edit <path>/etc/postfix/master.cf</path> and turn off
1029     verbose mode for production use. You'll probably also want to add the services
1030     to your startup routine to make sure everything comes back up on a reboot. Make
1031     sure to add all the services you're using - apache, mysql, saslauthd, postfix,
1032     courier-imapd, courier-imapd-ssl, courier-pop3d, and courier-pop3d-ssl are all
1033     up to your decision on what access you want to provide. I generally have all
1034     the services enabled.
1035     </p>
1036    
1037     <pre caption="Wrap up">
1038 rajiv 1.14 # <i>postfix reload</i>
1039     # <i>rc-update add $service default</i>
1040 zhen 1.3 </pre>
1041 neysx 1.39
1042 zhen 1.3 <p>
1043     <e>Have fun!</e>
1044     </p>
1045 neysx 1.39
1046 zhen 1.3 </body>
1047 swift 1.26 </section>
1048 zhen 1.1 </chapter>
1049 neysx 1.39
1050 zhen 1.1 <chapter>
1051     <title>Troubleshooting</title>
1052     <section>
1053 zhen 1.3 <title>Introduction</title>
1054     <body>
1055 neysx 1.39
1056     <p>
1057     Troubleshooting: This is a short troubleshooting guide for the set up we've
1058     detailed how to install here. It is not exhaustive, but meant as a place to get
1059     you started in figuring out problems. With a complicated setup such as this,
1060     it's imperative that you narrow down the problem to the particular component
1061     that is malfunctioning. In general I do that by following a few steps. Start
1062     from the base of the system and work your way up, ruling out components that
1063     work along the way until you discover which component is having the problem.
1064     </p>
1065    
1066 zhen 1.3 </body>
1067 zhen 1.1 </section>
1068     <section>
1069 neysx 1.39 <title>Step 1: Check your config files</title>
1070 zhen 1.3 <body>
1071 neysx 1.39
1072     <p>
1073     Typos are killers, especially when dealing with authentication systems. Scan
1074     your config's and mailsql database for typo's. You can debug all you want, but
1075     if you're not passing the right information back and forth to your mail system,
1076     it's not going to work. If you make a change to a config file for a service,
1077     make sure you restart that service so that the config change gets picked up.
1078     </p>
1079    
1080     <pre caption="How to restart a service">
1081 rajiv 1.14 # <i>/etc/init.d/service restart</i>
1082 zhen 1.3 </pre>
1083 neysx 1.39
1084 zhen 1.3 </body>
1085 zhen 1.1 </section>
1086     <section>
1087 zhen 1.3 <title>Step 2: Are all the necessary services actually running?</title>
1088     <body>
1089 neysx 1.39
1090     <p>
1091     If it's not running, start it up. It's awful hard to debug a service that isn't
1092     running. Sometimes a service will act like it's started but still not function.
1093     Sometimes, when a bad config is used, or a bad transmission comes into a mail
1094     component, the service will hang and keep the port from being used by another
1095     process. Sometimes you can detect this with netstat. Or, if you've been at it
1096     awhile, just take a break and reboot your box in the meantime. That will clear
1097     out any hung services. Then you can come back fresh and try it again.
1098     </p>
1099    
1100     <pre caption="Checking the status of a service">
1101 rajiv 1.14 # <i>/etc/init.d/$service status</i>
1102     # <i>netstat -a | grep $service (or $port)</i>
1103 zhen 1.3 </pre>
1104 neysx 1.39
1105 zhen 1.3 </body>
1106 zhen 1.1 </section>
1107     <section>
1108 zhen 1.3 <title>Step 3: Are all the service using the current config's?</title>
1109     <body>
1110 neysx 1.39
1111     <p>
1112     If you've recently made a change to a config file, restart that service to make
1113     sure it's using the current version. Some of the components will dump their
1114     current config's to you, like postfix.
1115     </p>
1116    
1117     <pre caption="Some services can dump their current config">
1118 rajiv 1.14 # <i>apachectl fullstatus</i> (needs lynx installed)
1119     # <i>apachectl configtest</i> (checks config sanity)
1120     # <i>postconf -n</i> (will tell you exactly what param's postfix is using)
1121     # <i>/etc/init.d/$service restart</i>
1122 zhen 1.3 </pre>
1123 neysx 1.39
1124 zhen 1.3 </body>
1125 zhen 1.1 </section>
1126     <section>
1127 neysx 1.39 <title>Step 4: Check the logs</title>
1128 zhen 1.3 <body>
1129 neysx 1.39
1130     <p>
1131     Repeat after me, logs are my friend. My next troubleshooting stop is always the
1132     logs. Sometimes it's helpful to try a failed operation again then check the
1133     logs so that the error message is right at the bottom (or top depending on your
1134     logger) instead of buried in there somewhere. See if there is any information
1135     in your log that can help you diagnose the problem, or at the very least,
1136     figure out which component is having the problem.
1137     </p>
1138    
1139     <pre caption="Checking the logs">
1140 rajiv 1.14 # <i>kill -USR1 `ps -C metalog -o pid=`</i>(to turn off metalog buffering)
1141     # <i>nano -w /var/log/mail/current</i>
1142     # <i>cat /var/log/mysql/mysql.log</i>
1143     # <i>tail /var/log/apache/error_log</i>
1144 zhen 1.3 </pre>
1145 neysx 1.39
1146     <p>
1147     You may also find the debug_peer parameters in main.cf helpful. Setting these
1148     will increase log output over just verbose mode.
1149     </p>
1150    
1151 zhen 1.3 <pre caption="adding debug_peer support">
1152 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
1153     debug_peer_level = 5
1154     debug_peer_list = $host.domain.name
1155 neysx 1.39 <comment>(Uncomment one of the suggested debugger
1156     commands as well.)</comment>
1157 zhen 1.3 </pre>
1158 neysx 1.39
1159 zhen 1.3 </body>
1160 zhen 1.1 </section>
1161     <section>
1162 neysx 1.39 <title>Step 5: Talk to the service itself</title>
1163 zhen 1.3 <body>
1164 neysx 1.39
1165     <p>
1166     SMTP, IMAP, and POP3 all respond to telnet sessions. As we've seen earlier when
1167     we verified postfix's config. Sometimes it's helpful to open a telnet session
1168     to the service itself and see what's happening.
1169     </p>
1170    
1171     <pre caption="Connect to a service with telnet">
1172 rajiv 1.14 # <i>telnet localhost $port</i>
1173 neysx 1.39 <comment>(SMTP is 25, IMAP is 143, POP3 is 110. You should receive at least an OK string,
1174     letting you know that the service is running and ready to respond to requests.)</comment>
1175 zhen 1.1
1176 rajiv 1.14 Trying 127.0.0.1...
1177     Connected to localhost.
1178     Escape character is '^]'.
1179 rajiv 1.15 * OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc.
1180 rajiv 1.14 </pre>
1181 neysx 1.39
1182 zhen 1.3 </body>
1183 zhen 1.1 </section>
1184     <section>
1185 neysx 1.39 <title>Step 6: Sometimes only the big guns will give you the information you need: strace</title>
1186 zhen 1.3 <body>
1187 neysx 1.39
1188     <p>
1189     You should have this installed anyway. This is an invaluable tool for debugging
1190     software. You can start commands from the command line with strace and watch
1191     all the system calls as they happen. It often dumps a huge amount of
1192     information, so you'll either need to watch it realtime as you retry a failed
1193     transaction with the mail system, or dump the output to a file for review.
1194     </p>
1195    
1196     <pre caption="Using strace">
1197 rajiv 1.14 # <i>emerge strace</i>
1198     # <i>strace $command</i>
1199     # <i>strace -p `ps -C $service -o pid=`</i>
1200 zhen 1.3 </pre>
1201 neysx 1.39
1202 zhen 1.3 </body>
1203 zhen 1.1 </section>
1204     <section>
1205 zhen 1.3 <title>Step 7: Research</title>
1206     <body>
1207 neysx 1.39
1208     <p>
1209     Once you have the information, if you can diagnose and fix the problem, great!
1210     If not, you'll probably need to go digging on the net for information that will
1211     help you fix it. Here's a list of sites you can check to see if your error has
1212     already been resolved. There's also a really good howto on setting up smtp-auth
1213     which contains some great debugging ideas.
1214     </p>
1215 cam 1.30
1216 zhen 1.3 <ul>
1217 neysx 1.39 <li><uri>http://forums.gentoo.org/</uri> - Great forums for gentoo users</li>
1218     <li>
1219     <uri>http://bugs.gentoo.org/</uri> - Bugs database for gentoo - great place
1220     to look for specific errors
1221     </li>
1222     <li><uri>http://postfix.state-of-mind.de/</uri> - smtp-auth howto</li>
1223     <li>
1224     <uri>http://marc.theaimsgroup.com/?l=postfix-users</uri> - Postfix mailing
1225     lists - searchable
1226     </li>
1227     <li>
1228     <uri>http://sourceforge.net/mailarchive/forum.php?forum_id=6705</uri> -
1229     Courier-imap mailing list archives - not searchable
1230     </li>
1231     <li>
1232     <uri>http://www.google.com/</uri> - If all else fails, there's always
1233     google, which has never failed me
1234     </li>
1235     <li>
1236     I also spend a lot of time on irc.freenode.net #gentoo. Irc is a great
1237     place to go for help.
1238     </li>
1239 zhen 1.3 </ul>
1240 cam 1.30
1241 zhen 1.3 </body>
1242 zhen 1.1 </section>
1243     </chapter>
1244     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20