/[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.65 - (hide annotations) (download) (as text)
Tue Jul 23 14:24:02 2013 UTC (13 months, 3 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.64: +5 -4 lines
File MIME type: application/xml
Mark virtual mailhosting document as obsolete, refer to https://wiki.gentoo.org/wiki/Complete_Virtual_Mail_Server

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

  ViewVC Help
Powered by ViewVC 1.1.20