/[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.57 - (hide annotations) (download) (as text)
Mon Jul 23 15:44:42 2007 UTC (7 years, 2 months ago) by swift
Branch: MAIN
Changes since 1.56: +63 -68 lines
File MIME type: application/xml
Small updates to virt-mail-howto

1 vapier 1.32 <?xml version='1.0' encoding='UTF-8'?>
2 swift 1.57 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.56 2007/07/20 09:09:04 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 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 swift 1.57 <version>1.5</version>
30     <date>2007-07-23</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.45 The following packages are used in this setup: apache, courier-imap, courier-authlib
74 neysx 1.39 postfix, mod_php, phpmyadmin, squirrelmail, cyrus-sasl, mysql, php, and
75     mailman.
76     </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 zhen 1.3
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.45 actually passing your auth variables to courier-auth, which will in turn pass that
242 neysx 1.39 information to mysql for authentication of smtp users. For this howto, we'll
243     not even try to verify that sasl is working until mysql is set up and contains
244     a test user. Which is fine since we'll be authenticating against mysql in the
245     end anyway.
246     </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     permit_sasl_authenticated,
342     permit_mynetworks,
343     reject_unauth_destination
344    
345    
346 vanquirius 1.48 <comment>(The next two options enable outgoing encryption.)</comment>
347 nightmorph 1.49 smtp_use_tls = yes
348 vanquirius 1.48 smtp_tls_note_starttls_offer = yes
349 rajiv 1.14 smtpd_use_tls = yes
350     #smtpd_tls_auth_only = yes
351 nightmorph 1.56 smtpd_tls_key_file = /etc/postfix/newkey.pem
352 rajiv 1.14 smtpd_tls_cert_file = /etc/postfix/newcert.pem
353     smtpd_tls_CAfile = /etc/postfix/cacert.pem
354     smtpd_tls_loglevel = 3
355     smtpd_tls_received_header = yes
356     smtpd_tls_session_cache_timeout = 3600s
357     tls_random_source = dev:/dev/urandom
358    
359 neysx 1.39 <comment>(smtpd_tls_auth_only is commented out to ease testing the system.
360     You can turn this on later if you desire.)</comment>
361 rajiv 1.14
362     # <i>postfix reload</i>
363 zhen 1.3 </pre>
364 neysx 1.39
365     <p>
366     Now we're going to verify that the config's we added were picked up by postfix.
367 swift 1.57 For this we are going to use <c>telnet</c> (provided by for instance
368     <c>net-misc/netkit-telnetd</c>) although you can also use <c>nc</c> (provided by
369     <c>net-analyzer/netcat</c>):
370 neysx 1.39 </p>
371    
372     <pre caption="Verifying sasl and tls support">
373 rajiv 1.14 # <i>telnet localhost 25</i>
374 zhen 1.1
375 rajiv 1.14 Trying 127.0.0.1...
376     Connected to localhost.
377     Escape character is '^]'.
378     220 mail.domain.com ESMTP Postfix
379     <i>EHLO domain.com</i>
380     250-mail.domain.com
381     250-PIPELINING
382     250-SIZE 10240000
383     250-VRFY
384     250-ETRN
385     250-STARTTLS
386     250-AUTH LOGIN PLAIN
387     250-AUTH=LOGIN PLAIN
388     250-XVERP
389     250 8BITMIME
390     <i>^]</i>
391     telnet> <i>quit</i>
392 zhen 1.3 </pre>
393 neysx 1.39
394     <p>
395     Verify that the above AUTH and STARTTLS lines now appear in your postfix
396     install. As I said before, as it stands now AUTH will not work. that's because
397     sasl will try to auth against it's sasldb, instead of the shadow file for some
398     unknown reason, which we have not set up. So we're going to just plow through
399     and set up mysql to hold all of our auth and virtual domain information.
400     </p>
401    
402 zhen 1.3 </body>
403 swift 1.26 </section>
404 zhen 1.1 </chapter>
405 neysx 1.39
406 zhen 1.1 <chapter>
407 swift 1.57 <title>The vmail user</title>
408     <section>
409     <body>
410    
411     <p>
412     Before we set up our virtual mailhosting environment, we create a functional
413     user under which the virtual mailboxes will be hosted. For clarity's sake we
414     will call this <e>vmail</e>:
415     </p>
416    
417     <pre caption="Adding the vmail user">
418     # <i>adduser -d /home/vmail -s /bin/false -m vmail</i>
419     </pre>
420    
421     <p>
422     So now you've set up the vmail account. You can create multiple accounts if you
423     want (to keep some structure in your set of virtual mail accounts). The user id,
424     group id and home dirs are referenced in the MySQL tables.
425     </p>
426    
427     <p>
428     Next to the user account we also need to create the location where the mailboxes
429     will reside:
430     </p>
431    
432     <pre caption="Creating mailboxes">
433     # <i>mkdir /home/vmail/virt-domain.com/foo</i>
434     # <i>chown -R vmail:vmail /home/vmail/virt-domain.com</i>
435     # <i>maildirmake /home/vmail/virt-domain.com/foo/.maildir</i>
436     </pre>
437    
438     </body>
439     </section>
440     </chapter>
441    
442     <chapter>
443 zhen 1.1 <title>MySQL</title>
444 swift 1.26 <section>
445 zhen 1.3 <body>
446 neysx 1.39
447     <p>
448     Next we're going to install and configure MySQL. You'll need the <uri
449     link="http://www.gentoo.org/doc/en/files/genericmailsql.sql">genericmailsql.sql</uri>
450     dumpfile for this step.
451     </p>
452    
453     <pre caption="Installing and configuring MySQL">
454 rajiv 1.14 # <i>emerge mysql</i>
455 zhen 1.3
456 rajiv 1.14 # <i>/usr/bin/mysql_install_db</i>
457 neysx 1.39 <comment>(After this command runs follow the onscreen directions
458     for adding a root password with mysql,
459     not mysqladmin, otherwise your db will be wide open.)</comment>
460 zhen 1.1
461 rajiv 1.14 # <i>/etc/init.d/mysql start</i>
462     # <i>mysqladmin -u root -p create mailsql</i>
463     # <i>mysql -u root -p mailsql &lt; genericmailsql.sql</i>
464    
465     # <i>mysql -u root -p mysql</i>
466     mysql> <i>GRANT SELECT,INSERT,UPDATE,DELETE</i>
467     -> <i>ON mailsql.*</i>
468     -> <i>TO mailsql@localhost</i>
469     -> <i>IDENTIFIED BY '$password';</i>
470 neysx 1.46 Query OK, 0 rows affected (0.02 sec)
471 rajiv 1.14
472 neysx 1.46 mysql> <i>FLUSH PRIVILEGES;</i>
473     Query OK, 0 rows affected (0.00 sec)
474    
475     mysql> <i>quit</i>
476 neysx 1.39 <comment>(Verify that the new mailsql user can connect to the mysql server.)</comment>
477 rajiv 1.14
478     # <i>mysql -u mailsql -p mailsql</i>
479 zhen 1.3 </pre>
480 cam 1.30
481     <p>
482 neysx 1.39 Your new database has default values and tables set up for two domains. The
483     following tables are included:
484 cam 1.30 </p>
485    
486     <ul>
487 neysx 1.39 <li>alias - local email alias and mailman alias information.</li>
488     <li>relocated - relocated user email address maps</li>
489     <li>
490     transport - default mail transport information for all domains you are
491     hosting
492     </li>
493     <li>users - all user account information</li>
494     <li>virtual - virtual domain email alias maps</li>
495 zhen 1.3 </ul>
496 cam 1.30
497 neysx 1.39 <pre caption="alias table sample">
498 rajiv 1.15 id alias destination
499     1 root foo@bar.com
500     2 postmaster foo@bar.com
501 rajiv 1.14 </pre>
502 neysx 1.39
503     <pre caption="user table sample">
504     <comment>(Line wrapped for clarity.)</comment>
505 rajiv 1.15 id email clear name uid gid homedir \
506     maildir quota postfix
507 swift 1.57 10 foo@virt-domain.com $password realname virtid virtid /home/vmail \
508     /home/vmail/virt-domain.com/foo/.maildir/ y
509 rajiv 1.15 13 foo@bar.com $password realname localid localid /home/foo \
510     /home/foo/.maildir/ y
511 rajiv 1.14 </pre>
512 swift 1.37
513     <p>
514     The values of the <c>virtid</c> uid and gid should be those of the <c>vmail</c>
515     user and group.
516     </p>
517    
518 neysx 1.39 <pre caption="transport table sample">
519 swift 1.57 id domain destination
520     1 bar.com local:
521     2 virt-domain.com virtual:
522 rajiv 1.14 </pre>
523 neysx 1.39
524     <pre caption="virtual table sample">
525 swift 1.57 id email destination
526     3 root@virt-domain.com other@email.address
527 rajiv 1.14 </pre>
528 neysx 1.39
529 zhen 1.3 </body>
530 swift 1.26 </section>
531 zhen 1.1 </chapter>
532 neysx 1.39
533 zhen 1.1 <chapter>
534     <title>Apache and phpMyAdmin</title>
535 swift 1.26 <section>
536 zhen 1.3 <body>
537 neysx 1.39
538     <p>
539     Next we'll set up apache and add an interface to interact with the database
540     more easily.
541     </p>
542    
543     <pre caption="Setting up apache and phpmyadmin">
544 nightmorph 1.55 # <i>emerge apache phpmyadmin</i>
545 zhen 1.3 </pre>
546 cam 1.30
547     <p>
548 nightmorph 1.55 There are plenty of guides out there about how to set up apache with php,
549     including guides provided by the <uri link="/proj/en/php/">Gentoo PHP
550     Project</uri>. There are also numerous posts on
551     <uri>http://forums.gentoo.org</uri> detailing how to solve problems with the
552     installation. So, that said, we're not going to cover it here. Set up the
553     apache and php installs, then continue with this howto. Now, a word for the
554     wise: .htaccess the directory that you put phpmyadmin in. If you do not do this,
555     search engine spiders will come along and index the page which in turn will mean
556     that anyone will be able to find your phpmyadmin page via google and in turn be
557     able to come change your database however they want which is <e>BAD!</e> There
558     are many howtos on this including:
559     <uri>http://www.csoft.net/docs/micro/htaccess.html.en</uri>.
560 neysx 1.39 </p>
561    
562     <p>
563     Now we're going to install the Apache certificates we made previously. The
564     Apache-SSL directives that you need to use the resulting cert are:
565 cam 1.30 </p>
566    
567     <ul>
568 neysx 1.39 <li>SSLCertificateFile /path/to/certs/new.cert.cert</li>
569     <li>SSLCertificateKeyFile /path/to/certs/new.cert.key</li>
570 zhen 1.3 </ul>
571 cam 1.30
572 neysx 1.39 <pre caption="Install Apache SSL certificates">
573 nightmorph 1.55 # <i>cp /etc/ssl/misc/new.cert.cert /etc/apache2/ssl/</i>
574     # <i>cp /etc/ssl/misc/new.cert.key /etc/apache2/ssl/</i>
575     # <i>cd /etc/apache2/vhosts.d</i>
576     <comment>(Check if you have an ssl-vhost template already.
577     Copy that one instead of the default_vhost if that is the case)</comment>
578     # <i>cp 00_default_vhost.conf ssl-vhost.conf</i>
579     # <i>nano -w ssl-vhost.conf</i>
580 neysx 1.39
581     <comment>(Change the following parameters)</comment>
582 nightmorph 1.55 NameVirtualHost host.domain.name:443
583    
584     &lt;VirtualHost host.domain.name:443&gt;
585     ServerName host.domain.name
586     ServerAdmin your@email.address
587    
588     DocumentRoot "/var/www/localhost/htdocs/phpmyadmin";
589     &lt;Directory "/var/www/localhost/htdocs/phpmyadmin"&gt;
590     ...
591     &lt;/Directory&gt;
592    
593     SSLCertificateFile /etc/apache2/ssl/new.cert.cert
594     SSLCertificateKeyFile /etc/apache2/ssl/new.cert.key
595     SSLEngine on
596     ...
597     &lt;/VirtualHost&gt;
598 rajiv 1.14
599 nightmorph 1.55 # <i>nano -w /etc/conf.d/apache2</i>
600     <comment>(Add -D SSL -D PHP5 to the APACHE2_OPTS)</comment>
601 rajiv 1.14
602 nightmorph 1.55 # <i>/etc/init.d/apache2 restart</i>
603 zhen 1.3 </pre>
604 neysx 1.39
605     <p>
606     Next, configure phpMyAdmin.
607     </p>
608    
609     <pre caption="Configuring phpMyAdmin">
610 nightmorph 1.55 # <i>cd /var/www/localhost/htdocs/phpmyadmin</i>
611     # <i>cp config.sample.inc.php config.inc.php</i>
612     # <i>nano -w config.inc.php</i>
613 neysx 1.39 <comment>(Change the following parameters.)</comment>
614 nightmorph 1.55 $cfg['blowfish_secret'] = 'someverysecretpassphraze';
615 rajiv 1.14
616 rajiv 1.15 $cfg['Servers'][$i]['host'] = 'localhost'; // MySQL hostname
617     $cfg['Servers'][$i]['controluser'] = 'mailsql'; // MySQL control user settings
618     // (this user must have read-only
619 neysx 1.39 $cfg['Servers'][$i]['controlpass'] = '$password'; // access to the "mysql/user"
620     // and "mysql/db" tables)
621 rajiv 1.15 $cfg['Servers'][$i]['user'] = 'mailsql'; // MySQL user
622     $cfg['Servers'][$i]['password'] = '$password'; // MySQL password
623 rajiv 1.14 </pre>
624 neysx 1.39
625     <p>
626     Now enter the phpmyadmin page and browse the tables. You'll want to add in your
627     local aliases, edit your user table to add a test user, and change your
628     transport table to add information about your domains. The default values
629     supplied with the dumpfile should be a sufficient guide to what values need to
630     go where. Make sure that if you put information in the database that it is
631 nightmorph 1.53 accurate. For instance, make sure the local user's home dir exists and that the
632 neysx 1.39 correct uid/gid values are in place. The maildirs should be created
633     automatically by postfix when the user receives their first email. So, in
634 nightmorph 1.53 general, it's a good idea to send a "Welcome" mail to a new user after you
635     setup their account to make sure the .maildir gets created.
636 neysx 1.39 </p>
637    
638 zhen 1.3 </body>
639 swift 1.26 </section>
640 zhen 1.1 </chapter>
641 neysx 1.39
642 zhen 1.1 <chapter>
643     <title>Configuring MySQL Authentication and vhosts</title>
644 swift 1.26 <section>
645 zhen 1.3 <body>
646 neysx 1.39
647     <p>
648     Next we'll reconfigure our authentication to use the mailsql database in
649     courier-imap and postfix. In all of the following examples, replace
650     <c>$password</c> with the password you set for the mailsql mysql user.
651     </p>
652    
653     <pre caption="Configuring authentication">
654 swift 1.45 # <i>nano -w /etc/courier/authlib/authdaemonrc</i>
655 neysx 1.39 authmodulelist="authmysql authpam"
656 zhen 1.1
657 swift 1.45 # <i>nano -w /etc/courier/authlib/authmysqlrc</i>
658 rajiv 1.14 MYSQL_SERVER localhost
659     MYSQL_USERNAME mailsql
660     MYSQL_PASSWORD $password
661     MYSQL_DATABASE mailsql
662     MYSQL_USER_TABLE users
663 neysx 1.39 <comment>(Make sure the following line is commented out since we're storing plaintext.)</comment>
664     #MYSQL_CRYPT_PWFIELD crypt
665 rajiv 1.14 MYSQL_CLEAR_PWFIELD clear
666     MYSQL_UID_FIELD uid
667     MYSQL_GID_FIELD gid
668     MYSQL_LOGIN_FIELD email
669     MYSQL_HOME_FIELD homedir
670     MYSQL_NAME_FIELD name
671     MYSQL_MAILDIR_FIELD maildir
672 zhen 1.1
673 swift 1.44 # <i>/etc/init.d/courier-authlib restart</i>
674 rajiv 1.14 # <i>/etc/init.d/saslauthd restart</i>
675 zhen 1.3 </pre>
676 neysx 1.39
677     <p>
678 nightmorph 1.53 We're almost there, I promise! Next, set up the rest of the necessary configs
679     for postfix to interract with the database for all its other transport needs.
680     Remember to replace each value with the name of your own user, user id,
681     password, alias, email address, and so on.
682 neysx 1.39 </p>
683    
684     <pre caption="/etc/postfix/mysql-aliases.cf">
685 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-aliases.cf</i>
686     # mysql-aliases.cf
687 zhen 1.1
688 rajiv 1.14 user = mailsql
689     password = $password
690     dbname = mailsql
691     table = alias
692     select_field = destination
693     where_field = alias
694     hosts = unix:/var/run/mysqld/mysqld.sock
695     </pre>
696 neysx 1.39
697     <pre caption="/etc/postfix/mysql-relocated.cf">
698 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-relocated.cf</i>
699     # mysql-relocated.cf
700 zhen 1.1
701 rajiv 1.14 user = mailsql
702     password = $password
703     dbname = mailsql
704     table = relocated
705     select_field = destination
706     where_field = email
707     hosts = unix:/var/run/mysqld/mysqld.sock
708     </pre>
709 neysx 1.39
710     <pre caption="/etc/postfix/mysql-transport.cf (optional)">
711 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-transport.cf</i>
712     # mysql-transport.cf
713 zhen 1.1
714 rajiv 1.14 user = mailsql
715     password = $password
716     dbname = mailsql
717     table = transport
718     select_field = destination
719     where_field = domain
720     hosts = unix:/var/run/mysqld/mysqld.sock
721     </pre>
722 neysx 1.39
723     <pre caption="/etc/postfix/mysql-virtual-gid.cf (optional)">
724 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-gid.cf</i>
725 nightmorph 1.55 # mysql-virtual-gid.cf
726 zhen 1.1
727 rajiv 1.14 user = mailsql
728     password = $password
729     dbname = mailsql
730     table = users
731     select_field = gid
732     where_field = email
733     additional_conditions = and postfix = 'y'
734     hosts = unix:/var/run/mysqld/mysqld.sock
735     </pre>
736 neysx 1.39
737     <pre caption="/etc/postfix/mysql-virtual-maps.cf">
738 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-maps.cf</i>
739 swift 1.57 # mysql-virtual-maps.cf
740 zhen 1.1
741 rajiv 1.14 user = mailsql
742     password = $password
743     dbname = mailsql
744     table = users
745     select_field = maildir
746     where_field = email
747     additional_conditions = and postfix = 'y'
748     hosts = unix:/var/run/mysqld/mysqld.sock
749     </pre>
750 neysx 1.39
751     <pre caption="/etc/postfix/mysql-virtual-uid.cf (optional)">
752 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual-uid.cf</i>
753     # mysql-virtual-uid.cf
754 zhen 1.1
755 rajiv 1.14 user = mailsql
756     password = $password
757     dbname = mailsql
758     table = users
759     select_field = uid
760     where_field = email
761     additional_conditions = and postfix = 'y'
762     hosts = unix:/var/run/mysqld/mysqld.sock
763     </pre>
764 neysx 1.39
765     <pre caption="/etc/postfix/mysql-virtual.cf">
766 rajiv 1.14 # <i>nano -w /etc/postfix/mysql-virtual.cf</i>
767     # mysql-virtual.cf
768 zhen 1.1
769 rajiv 1.14 user = mailsql
770     password = $password
771     dbname = mailsql
772     table = virtual
773     select_field = destination
774     where_field = email
775     hosts = unix:/var/run/mysqld/mysqld.sock
776     </pre>
777 neysx 1.39
778     <p>
779     Lastly, edit <path>/etc/postfix/main.cf</path> one more time.
780     </p>
781    
782     <pre caption="/etc/postfix/main.cf">
783 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
784 nightmorph 1.55 <comment>(Ensure that there are no other alias_maps definitions)</comment>
785 rajiv 1.14 alias_maps = mysql:/etc/postfix/mysql-aliases.cf
786     relocated_maps = mysql:/etc/postfix/mysql-relocated.cf
787    
788     local_transport = local
789     local_recipient_maps = $alias_maps $virtual_mailbox_maps unix:passwd.byname
790    
791     virtual_transport = virtual
792 nightmorph 1.55 <comment>(The domains listed by the mydestination should not be listed in
793     the virtual_mailbox_domains parameter)</comment>
794 swift 1.57 virtual_mailbox_domains = virt-domain.com, $other-virtual-domain.com
795 rajiv 1.14
796     virtual_minimum_uid = 1000
797 nightmorph 1.55 <comment>(Substitute $vmail-gid with the GID of the vmail group)</comment>
798 rajiv 1.14 virtual_gid_maps = static:$vmail-gid
799     virtual_mailbox_maps = mysql:/etc/postfix/mysql-virtual-maps.cf
800     virtual_alias_maps = mysql:/etc/postfix/mysql-virtual.cf
801 nightmorph 1.55 <comment>(Substitute $vmail-uid with the UID of the vmail user)</comment>
802 rajiv 1.14 virtual_uid_maps = static:$vmail-uid
803     virtual_mailbox_base = /
804     #virtual_mailbox_limit =
805     </pre>
806 swift 1.24
807     <p>
808     For security reasons you should change the permissions of the various
809     <path>/etc/mail/mysql-*.cf</path>:
810     </p>
811    
812     <pre caption="Changing file permission">
813     # <i>chmod 640 /etc/postfix/mysql-*.cf</i>
814     # <i>chgrp postfix /etc/postfix/mysql-*.cf</i>
815     </pre>
816    
817 neysx 1.39 <p>
818     As of Postfix 2.0.x, there were a number of significant changes over the 1.1.x
819     release. Notably the transport, virtual-gid, and virtual-uid tables are no
820     longer necessary. The tables are still included if you wish to use them.
821     </p>
822    
823     <note>
824     It is recommended that you read VIRTUAL_README included with the postfix docs
825     for more information.
826     </note>
827    
828     <pre caption="Make postfix reload its tables">
829     # <i>postfix reload</i>
830 zhen 1.3 </pre>
831 neysx 1.39
832     <p>
833     Now, if all went well, you should have a functioning mailhost. Users should be
834     able to authenticate against the sql database, using their full email address,
835     for pop3, imap, and smtp. I would highly suggest that you verify that
836     everything is working at this point. If you run into problems (with as many
837     things as this setup has going on, it's likely that you will) check the
838     troubleshooting section of this howto.
839     </p>
840    
841 zhen 1.3 </body>
842 swift 1.26 </section>
843 zhen 1.1 </chapter>
844 neysx 1.39
845 zhen 1.1 <chapter>
846     <title>Squirrelmail</title>
847 swift 1.26 <section>
848 zhen 1.3 <body>
849 neysx 1.39
850     <pre caption="Install squirrelmail">
851 rajiv 1.14 # <i>emerge squirrelmail</i>
852 swift 1.40 <comment>(Install squirrelmail to localhost so that it's accessed by http://localhost/mail)
853     (Substitute 1.4.3a-r2 with the version you use)</comment>
854 zhen 1.3
855 swift 1.40 # <i>webapp-config -I -h localhost -d /mail squirrelmail 1.4.3a-r2</i>
856 swift 1.31 # <i>cd /var/www/localhost/htdocs/mail/config</i>
857     # <i>perl ./conf.pl</i>
858 neysx 1.39 <comment>(Change your Organization, Server, and Folder settings for squirrelmail.
859     Now you should be able to login to squirrelmail, again - with your full email address,
860     and use your new webmail setup.)</comment>
861 zhen 1.3 </pre>
862 neysx 1.39
863 zhen 1.3 </body>
864 swift 1.26 </section>
865 zhen 1.1 </chapter>
866 neysx 1.39
867 zhen 1.1 <chapter>
868     <title>Mailman</title>
869 swift 1.26 <section>
870 zhen 1.3 <body>
871 neysx 1.39
872     <p>
873     Last step: mailman. The new version of mailman has very nice virtual domain
874     support, which is why I use it, not to mention it's really a great package. To
875     get this package installed and working correctly for virtual domains is going
876     to require a bit of hacking. I really recommend reading all of the mailman
877     documentation, including README.POSTFIX.gz, to understand what's being done
878     here.
879     </p>
880    
881     <pre caption="Install mailman">
882 rajiv 1.14 # <i>emerge mailman</i>
883 zhen 1.3 </pre>
884 neysx 1.39
885 antifa 1.12 <pre caption="Setting defaults: Mailman/Defaults.py">
886 nightmorph 1.55 # <i> nano -w /usr/local/mailman/Mailman/Defaults.py</i>
887 neysx 1.39 <comment>(Change the values below to reflect your primary domain, virtuals will be set next.)</comment>
888 rajiv 1.14 DEFAULT_EMAIL_HOST = 'domain.com'
889     DEFAULT_URL_HOST = 'www.domain.com'
890 antifa 1.12 </pre>
891 neysx 1.39
892 zhen 1.3 <pre caption="mailman config: mm_cfg.py">
893 nightmorph 1.55 # <i>nano -w /usr/local/mailman/Mailman/mm_cfg.py</i>
894 rajiv 1.14 MTA = "Postfix"
895     POSTFIX_STYLE_VIRTUAL_DOMAINS = ['virt-domain.com', 'virt.domain2.com']
896     add_virtualhost('www.virt.domain.com', 'virt.domain.com')
897     add_virtualhost('www.virt.domain2.com', 'virt.domain2.com')
898 neysx 1.39 <comment>(This is required for your virtual domains for mailman to function.)</comment>
899 zhen 1.3 </pre>
900 neysx 1.39
901     <pre caption="And last but not least">
902     <comment>(Once that's finished, add your first list.)</comment>
903 zhen 1.3
904 rajiv 1.14 # <i>su mailman</i>
905     # <i>cd ~</i>
906 swift 1.57 # <i>./bin/newlist --urlhost='www.virt-domain.com' --emailhost='virt-domain.com' test</i>
907 neysx 1.39 Enter the email of the person running the list: <i>your@email.address</i>
908 rajiv 1.14 Initial test password:
909     Hit enter to continue with test owner notification...
910 swift 1.57 <comment>(Virtual domain lists may also be specified with
911 neysx 1.39 list@domain.com style list names.)</comment>
912 nightmorph 1.55 # <i>./bin/genaliases</i>
913 neysx 1.39 <comment>(Now that your aliases have been generated,
914     verify that they were added successfully.)</comment>
915 rajiv 1.14
916     # <i>nano -w data/aliases</i>
917     # STANZA START: test
918     # CREATED:
919 swift 1.57 test: "|/usr/local/mailman/mail/mailman post test"
920     test-admin: "|/usr/local/mailman/mail/mailman admin test"
921     test-bounces: "|/usr/local/mailman/mail/mailman bounces test"
922     test-confirm: "|/usr/local/mailman/mail/mailman confirm test"
923     test-join: "|/usr/local/mailman/mail/mailman join test"
924     test-leave: "|/usr/local/mailman/mail/mailman leave test"
925     test-owner: "|/usr/local/mailman/mail/mailman owner test"
926     test-request: "|/usr/local/mailman/mail/mailman request test"
927     test-subscribe: "|/usr/local/mailman/mail/mailman subscribe test"
928     test-unsubscribe: "|/usr/local/mailman/mail/mailman unsubscribe test"
929 rajiv 1.14 # STANZA END: test
930    
931 nightmorph 1.55 <comment>(Create the required mailman list)</comment>
932     # <i>./bin/newlist mailman</i>
933     # <i>./bin/genaliases</i>
934    
935     <comment>(Return to the root user)</comment>
936     # <i>exit</i>
937    
938 rajiv 1.14 # <i>/etc/init.d/mailman start</i>
939     # <i>rc-update add mailman default</i>
940 neysx 1.39 <comment>(To start mailman at once and on every reboot.)</comment>
941 zhen 1.3 </pre>
942    
943     <pre caption="Adding mailman alias support to postfix">
944 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
945     owner_request_special = no
946     recipient_delimiter = +
947 neysx 1.39 <comment>(Read README.POSTFIX.gz for details on this.)</comment>
948 rajiv 1.14
949     alias_maps =
950 nightmorph 1.55 hash:/usr/local/mailman/data/aliases,
951 rajiv 1.14 mysql:/etc/postfix/mysql-aliases.cf
952    
953     virtual_alias_maps =
954 nightmorph 1.55 hash:/usr/local/mailman/data/virtual-mailman,
955 rajiv 1.14 mysql:/etc/postfix/mysql-virtual.cf
956 neysx 1.39 <comment>(This adds mailman alias file support to postfix
957     You may of course use the mysql tables for this,
958     but I hate doing that by hand. Also, if you are not
959     using virtual domains, adding the virtual alias maps
960     to postfix may cause problems, be warned.)</comment>
961 zhen 1.3 </pre>
962 neysx 1.39
963     <p>
964     You should now be able to setup mailing lists for any domain on your box. Last
965     note on this, make sure you run all mailman commands as the user mailman (<c>su
966     mailman</c>) or else the permissions will be wrong and you'll have to fix them.
967     Read the mailman doc's for more information on setting up and managing mailman
968     lists.
969     </p>
970    
971 zhen 1.3 </body>
972 swift 1.26 </section>
973 zhen 1.3 </chapter>
974 neysx 1.39
975 zhen 1.3 <chapter>
976     <title>Content Filtering and Anti-Virus</title>
977 swift 1.26 <section>
978 neysx 1.39 <body>
979    
980     <p>
981 neysx 1.42 For content filtering and Anti-Virus, please consult our <uri
982     link="/doc/en/mailfilter-guide.xml">mail filtering gateway guide</uri>.
983 neysx 1.39 </p>
984    
985     </body>
986 swift 1.26 </section>
987 zhen 1.1 </chapter>
988 neysx 1.39
989 zhen 1.1 <chapter>
990     <title>Wrap Up</title>
991 swift 1.26 <section>
992 zhen 1.3 <body>
993 neysx 1.39
994     <p>
995     Ok, you're all set, edit <path>/etc/postfix/master.cf</path> and turn off
996     verbose mode for production use. You'll probably also want to add the services
997     to your startup routine to make sure everything comes back up on a reboot. Make
998     sure to add all the services you're using - apache, mysql, saslauthd, postfix,
999     courier-imapd, courier-imapd-ssl, courier-pop3d, and courier-pop3d-ssl are all
1000     up to your decision on what access you want to provide. I generally have all
1001     the services enabled.
1002     </p>
1003    
1004     <pre caption="Wrap up">
1005 rajiv 1.14 # <i>postfix reload</i>
1006     # <i>rc-update add $service default</i>
1007 zhen 1.3 </pre>
1008 neysx 1.39
1009 zhen 1.3 <p>
1010     <e>Have fun!</e>
1011     </p>
1012 neysx 1.39
1013 zhen 1.3 </body>
1014 swift 1.26 </section>
1015 zhen 1.1 </chapter>
1016 neysx 1.39
1017 zhen 1.1 <chapter>
1018     <title>Troubleshooting</title>
1019     <section>
1020 zhen 1.3 <title>Introduction</title>
1021     <body>
1022 neysx 1.39
1023     <p>
1024     Troubleshooting: This is a short troubleshooting guide for the set up we've
1025     detailed how to install here. It is not exhaustive, but meant as a place to get
1026     you started in figuring out problems. With a complicated setup such as this,
1027     it's imperative that you narrow down the problem to the particular component
1028     that is malfunctioning. In general I do that by following a few steps. Start
1029     from the base of the system and work your way up, ruling out components that
1030     work along the way until you discover which component is having the problem.
1031     </p>
1032    
1033 zhen 1.3 </body>
1034 zhen 1.1 </section>
1035     <section>
1036 neysx 1.39 <title>Step 1: Check your config files</title>
1037 zhen 1.3 <body>
1038 neysx 1.39
1039     <p>
1040     Typos are killers, especially when dealing with authentication systems. Scan
1041     your config's and mailsql database for typo's. You can debug all you want, but
1042     if you're not passing the right information back and forth to your mail system,
1043     it's not going to work. If you make a change to a config file for a service,
1044     make sure you restart that service so that the config change gets picked up.
1045     </p>
1046    
1047     <pre caption="How to restart a service">
1048 rajiv 1.14 # <i>/etc/init.d/service restart</i>
1049 zhen 1.3 </pre>
1050 neysx 1.39
1051 zhen 1.3 </body>
1052 zhen 1.1 </section>
1053     <section>
1054 zhen 1.3 <title>Step 2: Are all the necessary services actually running?</title>
1055     <body>
1056 neysx 1.39
1057     <p>
1058     If it's not running, start it up. It's awful hard to debug a service that isn't
1059     running. Sometimes a service will act like it's started but still not function.
1060     Sometimes, when a bad config is used, or a bad transmission comes into a mail
1061     component, the service will hang and keep the port from being used by another
1062     process. Sometimes you can detect this with netstat. Or, if you've been at it
1063     awhile, just take a break and reboot your box in the meantime. That will clear
1064     out any hung services. Then you can come back fresh and try it again.
1065     </p>
1066    
1067     <pre caption="Checking the status of a service">
1068 rajiv 1.14 # <i>/etc/init.d/$service status</i>
1069     # <i>netstat -a | grep $service (or $port)</i>
1070 zhen 1.3 </pre>
1071 neysx 1.39
1072 zhen 1.3 </body>
1073 zhen 1.1 </section>
1074     <section>
1075 zhen 1.3 <title>Step 3: Are all the service using the current config's?</title>
1076     <body>
1077 neysx 1.39
1078     <p>
1079     If you've recently made a change to a config file, restart that service to make
1080     sure it's using the current version. Some of the components will dump their
1081     current config's to you, like postfix.
1082     </p>
1083    
1084     <pre caption="Some services can dump their current config">
1085 nightmorph 1.55 # <i>apache2ctl fullstatus</i> (needs lynx installed)
1086     # <i>apache2ctl configtest</i> (checks config sanity)
1087 rajiv 1.14 # <i>postconf -n</i> (will tell you exactly what param's postfix is using)
1088     # <i>/etc/init.d/$service restart</i>
1089 zhen 1.3 </pre>
1090 neysx 1.39
1091 zhen 1.3 </body>
1092 zhen 1.1 </section>
1093     <section>
1094 neysx 1.39 <title>Step 4: Check the logs</title>
1095 zhen 1.3 <body>
1096 neysx 1.39
1097     <p>
1098     Repeat after me, logs are my friend. My next troubleshooting stop is always the
1099     logs. Sometimes it's helpful to try a failed operation again then check the
1100     logs so that the error message is right at the bottom (or top depending on your
1101     logger) instead of buried in there somewhere. See if there is any information
1102     in your log that can help you diagnose the problem, or at the very least,
1103     figure out which component is having the problem.
1104     </p>
1105    
1106     <pre caption="Checking the logs">
1107 rajiv 1.14 # <i>kill -USR1 `ps -C metalog -o pid=`</i>(to turn off metalog buffering)
1108     # <i>nano -w /var/log/mail/current</i>
1109     # <i>cat /var/log/mysql/mysql.log</i>
1110 nightmorph 1.55 # <i>tail /var/log/apache2/error_log</i>
1111 zhen 1.3 </pre>
1112 neysx 1.39
1113     <p>
1114     You may also find the debug_peer parameters in main.cf helpful. Setting these
1115     will increase log output over just verbose mode.
1116     </p>
1117    
1118 zhen 1.3 <pre caption="adding debug_peer support">
1119 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
1120     debug_peer_level = 5
1121     debug_peer_list = $host.domain.name
1122 neysx 1.39 <comment>(Uncomment one of the suggested debugger
1123     commands as well.)</comment>
1124 zhen 1.3 </pre>
1125 neysx 1.39
1126 zhen 1.3 </body>
1127 zhen 1.1 </section>
1128     <section>
1129 neysx 1.39 <title>Step 5: Talk to the service itself</title>
1130 zhen 1.3 <body>
1131 neysx 1.39
1132     <p>
1133     SMTP, IMAP, and POP3 all respond to telnet sessions. As we've seen earlier when
1134     we verified postfix's config. Sometimes it's helpful to open a telnet session
1135     to the service itself and see what's happening.
1136     </p>
1137    
1138     <pre caption="Connect to a service with telnet">
1139 rajiv 1.14 # <i>telnet localhost $port</i>
1140 neysx 1.39 <comment>(SMTP is 25, IMAP is 143, POP3 is 110. You should receive at least an OK string,
1141     letting you know that the service is running and ready to respond to requests.)</comment>
1142 zhen 1.1
1143 rajiv 1.14 Trying 127.0.0.1...
1144     Connected to localhost.
1145     Escape character is '^]'.
1146 rajiv 1.15 * OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc.
1147 rajiv 1.14 </pre>
1148 neysx 1.39
1149 zhen 1.3 </body>
1150 zhen 1.1 </section>
1151     <section>
1152 neysx 1.39 <title>Step 6: Sometimes only the big guns will give you the information you need: strace</title>
1153 zhen 1.3 <body>
1154 neysx 1.39
1155     <p>
1156     You should have this installed anyway. This is an invaluable tool for debugging
1157     software. You can start commands from the command line with strace and watch
1158     all the system calls as they happen. It often dumps a huge amount of
1159     information, so you'll either need to watch it realtime as you retry a failed
1160     transaction with the mail system, or dump the output to a file for review.
1161     </p>
1162    
1163     <pre caption="Using strace">
1164 rajiv 1.14 # <i>emerge strace</i>
1165     # <i>strace $command</i>
1166     # <i>strace -p `ps -C $service -o pid=`</i>
1167 zhen 1.3 </pre>
1168 neysx 1.39
1169 zhen 1.3 </body>
1170 zhen 1.1 </section>
1171     <section>
1172 zhen 1.3 <title>Step 7: Research</title>
1173     <body>
1174 neysx 1.39
1175     <p>
1176     Once you have the information, if you can diagnose and fix the problem, great!
1177     If not, you'll probably need to go digging on the net for information that will
1178     help you fix it. Here's a list of sites you can check to see if your error has
1179     already been resolved. There's also a really good howto on setting up smtp-auth
1180     which contains some great debugging ideas.
1181     </p>
1182 cam 1.30
1183 zhen 1.3 <ul>
1184 neysx 1.39 <li><uri>http://forums.gentoo.org/</uri> - Great forums for gentoo users</li>
1185     <li>
1186     <uri>http://bugs.gentoo.org/</uri> - Bugs database for gentoo - great place
1187     to look for specific errors
1188     </li>
1189     <li><uri>http://postfix.state-of-mind.de/</uri> - smtp-auth howto</li>
1190     <li>
1191     <uri>http://marc.theaimsgroup.com/?l=postfix-users</uri> - Postfix mailing
1192     lists - searchable
1193     </li>
1194     <li>
1195     <uri>http://sourceforge.net/mailarchive/forum.php?forum_id=6705</uri> -
1196     Courier-imap mailing list archives - not searchable
1197     </li>
1198     <li>
1199     <uri>http://www.google.com/</uri> - If all else fails, there's always
1200     google, which has never failed me
1201     </li>
1202     <li>
1203     I also spend a lot of time on irc.freenode.net #gentoo. Irc is a great
1204     place to go for help.
1205     </li>
1206 zhen 1.3 </ul>
1207 cam 1.30
1208 zhen 1.3 </body>
1209 zhen 1.1 </section>
1210     </chapter>
1211     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20