/[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.52 - (hide annotations) (download) (as text)
Tue Jul 4 00:21:20 2006 UTC (8 years, 2 months ago) by rane
Branch: MAIN
Changes since 1.51: +4 -4 lines
File MIME type: application/xml
fixing a link from .org to .com, thx to mathieu_davy@ekynoxe.com (gentoo-doc@) for reporting

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

  ViewVC Help
Powered by ViewVC 1.1.20