/[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.45 - (show annotations) (download) (as text)
Sun May 29 16:12:29 2005 UTC (9 years, 9 months ago) by swift
Branch: MAIN
Changes since 1.44: +15 -33 lines
File MIME type: application/xml
#93842 - Improve authentication, update on latest software titles. Added scygro as editor so we know an additional contact in case of future issues :)

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

  ViewVC Help
Powered by ViewVC 1.1.20