/[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.62 - (hide annotations) (download) (as text)
Thu Oct 14 06:14:35 2010 UTC (3 years, 10 months ago) by nightmorph
Branch: MAIN
Changes since 1.61: +4 -1 lines
File MIME type: application/xml
the adduser command does not exist, bug 340915

1 vapier 1.32 <?xml version='1.0' encoding='UTF-8'?>
2 swift 1.16 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 nightmorph 1.62 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.61 2010/10/14 06:11:38 nightmorph Exp $ -->
4 swift 1.16
5 nightmorph 1.61 <guide>
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 nightmorph 1.61 <version>2</version>
33     <date>2010-10-13</date>
34 zhen 1.1
35 neysx 1.39 <chapter>
36 zhen 1.1 <title>Introduction</title>
37 swift 1.26 <section>
38 zhen 1.3 <body>
39 neysx 1.39
40     <p>
41 nightmorph 1.51 For most Gentoo users, a simple mail client and fetchmail will do. However, if
42 neysx 1.39 you're hosting a domain with your system, you'll need a full blown MTA (Mail
43     Transfer Agent). And if you're hosting multiple domains, then you'll definitely
44     need something more robust to handle all of the email for your users. This
45     system was designed to be an elegant solution to that problem.
46     </p>
47    
48     <p>
49     A virtual mail system needs to be able to handle email for numerous domains
50     with multiple users over a variety of interfaces. This presents some issues
51     that must be dealt with. For instance, what if you have two users on different
52     domains that want the same user name? If you are providing imap access and
53     smtp-auth, how do combine the various authentication daemons into a single
54     system? How do you provide security for the numerous components that comprise
55     the system? How do you manage it all?
56     </p>
57    
58     <p>
59     This howto will show you how to set up with a mail system capable of handling
60     mail for as many domains as your hardware can handle, supports virtual mail
61     users that don't require shell accounts, has domain specific user names, can
62     authenticate web, imap, smtp, and pop3 clients against a single database,
63     utilizes ssl for transport layer security, has a web interface, can handle
64     mailing lists for any domain on the machine, and is controlled by a nice,
65     central and easy mysql database.
66     </p>
67    
68     <p>
69     There are quite a variety of ways to go about setting up a virtual mailhosting
70     system. With so may options, another may be the best choice for your specific
71     needs. Consider investigating <uri>http://www.qmail.org/</uri> and
72     <uri>http://www.exim.org/</uri> to explore your options.
73     </p>
74    
75     <p>
76 swift 1.59 The following packages are used in this setup: apache, courier-imap,
77     courier-authlib postfix, mod_php, phpmyadmin, squirrelmail, cyrus-sasl, mysql,
78     php, and mailman.
79 neysx 1.39 </p>
80    
81     <p>
82     Make sure to turn on the following USE variables in <path>/etc/make.conf</path>
83 swift 1.45 before compiling the packages: <c>USE="mysql imap libwww maildir
84 neysx 1.39 sasl ssl"</c>. Otherwise you will most likely have to recompile things to
85     get the support you need for all the protocols. Further, it's a good idea to
86     turn off any other mail and network variables, like ipv6.
87     </p>
88    
89     <impo>
90     You need a domain name to run a public mail server, or at least an MX record
91     for a domain. Ideally you would have control of at least two domains to take
92     advantage of your new virtual domain functionality.
93     </impo>
94    
95     <impo>
96 nightmorph 1.51 Make sure <path>/etc/conf.d/hostname</path> is set to the right hostname for
97     your mail server. You can apply any changes you make to this file by running
98     <c>/etc/init.d/hostname restart</c>. Verify your hostname is set correctly with
99     <c>hostname</c>. Also verify that there are no conflicting entries in
100     <path>/etc/hosts</path>.
101 neysx 1.39 </impo>
102    
103     <note>
104     It is recommended that you read this entire document and familiarize yourself
105     with all the steps before attempting the install. If you run into problems with
106     any of the steps, check the troubleshooting guide at the end of this document.
107     Also, not all the referenced packages are necessary, this set up is very
108     flexible. For instance, if you do not desire a web interface, feel free to skip
109     the squirrelmail section.
110     </note>
111    
112 zhen 1.3 </body>
113 swift 1.26 </section>
114 zhen 1.1 </chapter>
115 swift 1.26
116 zhen 1.1 <chapter>
117     <title>Postfix Basics</title>
118 swift 1.26 <section>
119 zhen 1.3 <body>
120 neysx 1.39
121     <pre caption="Install postfix">
122     # <i>emerge postfix</i>
123 zhen 1.3 </pre>
124 neysx 1.39
125     <warn>
126     Verify that you have not installed any other MTA, such as ssmtp, exim, or
127 nightmorph 1.54 netqmail, or you will surely have BIG problems.
128 neysx 1.39 </warn>
129    
130     <p>
131     After postfix is installed, it's time to configure it. Change the following
132 nightmorph 1.53 options in <path>/etc/postfix/main.cf</path>. Remember to replace
133     <c>$variables</c> with your own names.
134 neysx 1.39 </p>
135    
136     <pre caption="/etc/postfix/main.cf">
137 rajiv 1.14 myhostname = $host.domain.name
138     mydomain = $domain.name
139     inet_interfaces = all
140     mydestination = $myhostname, localhost.$mydomain $mydomain
141     mynetworks = my.ip.net.work/24, 127.0.0.0/8
142     home_mailbox = .maildir/
143     local_destination_concurrency_limit = 2
144 neysx 1.39 default_destination_concurrency_limit = 10
145     </pre>
146    
147     <p>
148     Next change the following in <path>/etc/postfix/master.cf</path>. This will
149     turn on verbose output for debugging:
150     </p>
151    
152     <pre caption="/etc/postfix/master.cf">
153 rajiv 1.14 # service type private unpriv chroot wakeup maxproc command + args
154     # (yes) (yes) (yes) (never) (50)
155     #
156     ==========================================================================
157 neysx 1.39 <comment>(Just add the "-v" after the smtpd in the following line)</comment>
158 rajiv 1.14 smtp inet n - n - - smtpd -v
159 neysx 1.39 </pre>
160 rajiv 1.14
161 neysx 1.39 <p>
162     Next, edit <path>/etc/mail/aliases</path> to add your local aliases. There
163     should at least be an alias for root like: <c>root: your@email.address</c>.
164     </p>
165    
166     <pre caption="Starting postfix for the first time">
167 rajiv 1.14 # <i>/usr/bin/newaliases</i>
168 neysx 1.39 <comment>(This will install the new aliases. You only need to do this
169     when you update or install aliases.)</comment>
170 swift 1.59
171 rajiv 1.14 # <i>/etc/init.d/postfix start</i>
172 zhen 1.3 </pre>
173 neysx 1.39
174     <p>
175     Now that postfix is running, fire up your favorite console mail client and send
176     yourself an email. I use <c>mutt</c> for all my console mail. Verify that
177     postfix is delivering mail to local users, once that's done, we're on to the
178     next step.
179     </p>
180    
181     <note>
182     I strongly recommend that you verify this basic postfix setup is functioning
183     before you progress to the next step of the howto.
184     </note>
185    
186 zhen 1.3 </body>
187 swift 1.26 </section>
188 zhen 1.1 </chapter>
189 neysx 1.39
190 zhen 1.1 <chapter>
191     <title>Courier-imap</title>
192 swift 1.26 <section>
193 zhen 1.3 <body>
194 neysx 1.39
195 swift 1.45 <pre caption="Install courier-imap and courier-authlib">
196     # <i>emerge courier-imap courier-authlib</i>
197 zhen 1.3 </pre>
198 neysx 1.39
199     <pre caption="Courier-imap configuration">
200 rajiv 1.14 # <i>cd /etc/courier-imap</i>
201 neysx 1.39 <comment>(If you want to use the ssl capabilities of courier-imap or pop3,
202     you'll need to create certs for this purpose.
203     This step is recommended. If you do not want to use ssl, skip this step.)</comment>
204 rajiv 1.14
205     # <i>nano -w pop3d.cnf</i>
206     # <i>nano -w imapd.cnf</i>
207 neysx 1.39 <comment>(Change the C, ST, L, CN, and email parameters to match your server.)</comment>
208 rajiv 1.14
209     # <i>mkpop3dcert</i>
210     # <i>mkimapdcert</i>
211 zhen 1.3 </pre>
212 neysx 1.39
213     <pre caption="Start the courier services you need.">
214 rajiv 1.14 # <i>/etc/init.d/courier-imapd start</i>
215     # <i>/etc/init.d/courier-imapd-ssl start</i>
216     # <i>/etc/init.d/courier-pop3d start</i>
217     # <i>/etc/init.d/courier-pop3d-ssl start</i>
218 zhen 1.3 </pre>
219 neysx 1.39
220     <p>
221     Start up your favorite mail client and verify that all connections you've
222 nightmorph 1.55 started work for receiving and sending mail. Of course, you won't be able to log
223     on to any of the services because authentication hasn't been configured yet, but
224     it is wise to check if the connections themselves work or not.
225     </p>
226    
227     <p>
228     Now that the basics work, we're going to do a whole bunch of stuff at once to
229     get the rest of the system running. Again, please verify that what we've
230     installed already works before progressing.
231 neysx 1.39 </p>
232    
233 zhen 1.3 </body>
234 swift 1.26 </section>
235 zhen 1.1 </chapter>
236 neysx 1.39
237 zhen 1.1 <chapter>
238     <title>Cyrus-sasl</title>
239 swift 1.26 <section>
240 zhen 1.3 <body>
241 neysx 1.39
242     <p>
243     Next we're going to install cyrus-sasl. Sasl is going to play the role of
244 swift 1.59 actually passing your auth variables to courier-auth, which will in turn pass
245     that information to mysql for authentication of smtp users. For this howto,
246     we'll not even try to verify that sasl is working until mysql is set up and
247     contains a test user. Which is fine since we'll be authenticating against
248     mysql in the end anyway.
249 neysx 1.39 </p>
250    
251     <pre caption="Configuring and installing the cyrus-sasl ebuild">
252 swift 1.36 # <i>emerge cyrus-sasl</i>
253 zhen 1.3 </pre>
254 neysx 1.39
255     <p>
256     Next, edit <path>/etc/sasl2/smtpd.conf</path>.
257     </p>
258    
259     <pre caption="Starting sasl">
260 swift 1.27 # <i>nano -w /etc/sasl2/smtpd.conf</i>
261 swift 1.41 mech_list: PLAIN LOGIN
262 rajiv 1.14 pwcheck_method: saslauthd
263 swift 1.41 # <i>nano -w /etc/conf.d/saslauthd</i>
264 swift 1.45 SASLAUTHD_OPTS="${SASLAUTH_MECH} -a rimap -r"
265     SASLAUTHD_OPTS="${SASLAUTHD_OPTS} -O localhost"
266 rajiv 1.14 # <i>/etc/init.d/saslauthd start</i>
267 zhen 1.3 </pre>
268 neysx 1.39
269 zhen 1.3 </body>
270 swift 1.26 </section>
271 zhen 1.1 </chapter>
272 neysx 1.39
273 zhen 1.1 <chapter>
274     <title>SSL Certs for Postfix and Apache</title>
275 swift 1.26 <section>
276 zhen 1.3 <body>
277 neysx 1.39
278     <p>
279     Next we're going to make a set of ssl certificates for postfix and apache.
280     </p>
281    
282     <pre caption="Making ssl certicates">
283 rajiv 1.14 # <i>cd /etc/ssl/</i>
284     # <i>nano -w openssl.cnf</i>
285    
286 neysx 1.39 <comment>Change the following default values for your domain:</comment>
287 rajiv 1.14 countryName_default
288     stateOrProvinceName_default
289     localityName_default
290     0.organizationName_default
291     commonName_default
292     emailAddress_default.
293    
294 neysx 1.39 <comment>(If the variables are not already present, just add them in a sensible place.)</comment>
295 zhen 1.1
296 rajiv 1.14 # <i>cd misc</i>
297 nightmorph 1.55 # <i>./CA.pl -newreq-nodes</i>
298 rajiv 1.14 # <i>./CA.pl -newca</i>
299     # <i>./CA.pl -sign</i>
300     # <i>cp newcert.pem /etc/postfix</i>
301 nightmorph 1.56 # <i>cp newkey.pem /etc/postfix</i>
302 rajiv 1.14 # <i>cp demoCA/cacert.pem /etc/postfix</i>
303 neysx 1.39 <comment>(Now we do the same thing for apache.)</comment>
304 zhen 1.3
305 rajiv 1.14 # <i>openssl req -new > new.cert.csr</i>
306     # <i>openssl rsa -in privkey.pem -out new.cert.key</i>
307     # <i>openssl x509 -in new.cert.csr -out new.cert.cert -req -signkey new.cert.key -days 365</i>
308 neysx 1.39 <comment>(Just leave the resulting certificates here for now.
309     We'll install them after Apache is installed.)</comment>
310 zhen 1.3 </pre>
311 neysx 1.39
312 zhen 1.3 </body>
313 swift 1.26 </section>
314 neysx 1.39
315 zhen 1.1 </chapter>
316     <chapter>
317     <title>Adding SSL and SASL support to Postfix</title>
318 swift 1.26 <section>
319 zhen 1.3 <body>
320 neysx 1.39
321     <p>
322     Now edit the postfix config's to make it aware of your new sasl and ssl
323     capabilities. Add the following parameters to the end of the file where they
324     will be easy to find.
325     </p>
326    
327     <pre caption="/etc/postfix/main.cf">
328 rajiv 1.14 # <i>nano -w /etc/postfix/main.cf</i>
329    
330     smtpd_sasl_auth_enable = yes
331     smtpd_sasl2_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