/[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.60 - (hide annotations) (download) (as text)
Sun Sep 28 20:29:25 2008 UTC (5 years, 9 months ago) by nightmorph
Branch: MAIN
Changes since 1.59: +6 -5 lines
File MIME type: application/xml
fixed irc references per council mandate

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

  ViewVC Help
Powered by ViewVC 1.1.20