/[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.56 - (hide annotations) (download) (as text)
Fri Jul 20 09:09:04 2007 UTC (6 years, 11 months ago) by nightmorph
Branch: MAIN
Changes since 1.55: +5 -5 lines
File MIME type: application/xml
fixed newreq/newkey stuff, bug 185556

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

  ViewVC Help
Powered by ViewVC 1.1.20