/[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.63 - (hide annotations) (download) (as text)
Tue Mar 1 09:52:38 2011 UTC (3 years, 5 months ago) by nightmorph
Branch: MAIN
Changes since 1.62: +3 -4 lines
File MIME type: application/xml
remove an option that seems to have been removed, bug 356943

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

  ViewVC Help
Powered by ViewVC 1.1.20