/[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.39 - (show annotations) (download) (as text)
Fri Dec 10 17:32:41 2004 UTC (9 years, 7 months ago) by neysx
Branch: MAIN
Changes since 1.38: +631 -210 lines
File MIME type: application/xml
Applied coding style

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

  ViewVC Help
Powered by ViewVC 1.1.20