/[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.57 - (show annotations) (download) (as text)
Mon Jul 23 15:44:42 2007 UTC (7 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.56: +63 -68 lines
File MIME type: application/xml
Small updates to virt-mail-howto

1 <?xml version='1.0' encoding='UTF-8'?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.56 2007/07/20 09:09:04 nightmorph 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 <author title="Editor">
21 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
22 </author>
23
24 <abstract>
25 This document details how to create a virtual mailhosting system based upon
26 postfix, mysql, courier-imap, and cyrus-sasl.
27 </abstract>
28
29 <version>1.5</version>
30 <date>2007-07-23</date>
31
32 <chapter>
33 <title>Introduction</title>
34 <section>
35 <body>
36
37 <p>
38 For most Gentoo users, a simple mail client and fetchmail will do. However, if
39 you're hosting a domain with your system, you'll need a full blown MTA (Mail
40 Transfer Agent). And if you're hosting multiple domains, then you'll definitely
41 need something more robust to handle all of the email for your users. This
42 system was designed to be an elegant solution to that problem.
43 </p>
44
45 <p>
46 A virtual mail system needs to be able to handle email for numerous domains
47 with multiple users over a variety of interfaces. This presents some issues
48 that must be dealt with. For instance, what if you have two users on different
49 domains that want the same user name? If you are providing imap access and
50 smtp-auth, how do combine the various authentication daemons into a single
51 system? How do you provide security for the numerous components that comprise
52 the system? How do you manage it all?
53 </p>
54
55 <p>
56 This howto will show you how to set up with a mail system capable of handling
57 mail for as many domains as your hardware can handle, supports virtual mail
58 users that don't require shell accounts, has domain specific user names, can
59 authenticate web, imap, smtp, and pop3 clients against a single database,
60 utilizes ssl for transport layer security, has a web interface, can handle
61 mailing lists for any domain on the machine, and is controlled by a nice,
62 central and easy mysql database.
63 </p>
64
65 <p>
66 There are quite a variety of ways to go about setting up a virtual mailhosting
67 system. With so may options, another may be the best choice for your specific
68 needs. Consider investigating <uri>http://www.qmail.org/</uri> and
69 <uri>http://www.exim.org/</uri> to explore your options.
70 </p>
71
72 <p>
73 The following packages are used in this setup: apache, courier-imap, courier-authlib
74 postfix, mod_php, phpmyadmin, squirrelmail, cyrus-sasl, mysql, php, and
75 mailman.
76 </p>
77
78 <p>
79 Make sure to turn on the following USE variables in <path>/etc/make.conf</path>
80 before compiling the packages: <c>USE="mysql imap libwww maildir
81 sasl ssl"</c>. Otherwise you will most likely have to recompile things to
82 get the support you need for all the protocols. Further, it's a good idea to
83 turn off any other mail and network variables, like ipv6.
84 </p>
85
86 <impo>
87 You need a domain name to run a public mail server, or at least an MX record
88 for a domain. Ideally you would have control of at least two domains to take
89 advantage of your new virtual domain functionality.
90 </impo>
91
92 <impo>
93 Make sure <path>/etc/conf.d/hostname</path> is set to the right hostname for
94 your mail server. You can apply any changes you make to this file by running
95 <c>/etc/init.d/hostname restart</c>. Verify your hostname is set correctly with
96 <c>hostname</c>. Also verify that there are no conflicting entries in
97 <path>/etc/hosts</path>.
98 </impo>
99
100 <note>
101 It is recommended that you read this entire document and familiarize yourself
102 with all the steps before attempting the install. If you run into problems with
103 any of the steps, check the troubleshooting guide at the end of this document.
104 Also, not all the referenced packages are necessary, this set up is very
105 flexible. For instance, if you do not desire a web interface, feel free to skip
106 the squirrelmail section.
107 </note>
108
109 </body>
110 </section>
111 </chapter>
112
113 <chapter>
114 <title>Postfix Basics</title>
115 <section>
116 <body>
117
118 <pre caption="Install postfix">
119 # <i>emerge postfix</i>
120 </pre>
121
122 <warn>
123 Verify that you have not installed any other MTA, such as ssmtp, exim, or
124 netqmail, or you will surely have BIG problems.
125 </warn>
126
127 <p>
128 After postfix is installed, it's time to configure it. Change the following
129 options in <path>/etc/postfix/main.cf</path>. Remember to replace
130 <c>$variables</c> with your own names.
131 </p>
132
133 <pre caption="/etc/postfix/main.cf">
134 myhostname = $host.domain.name
135 mydomain = $domain.name
136 inet_interfaces = all
137 mydestination = $myhostname, localhost.$mydomain $mydomain
138 mynetworks = my.ip.net.work/24, 127.0.0.0/8
139 home_mailbox = .maildir/
140 local_destination_concurrency_limit = 2
141 default_destination_concurrency_limit = 10
142 </pre>
143
144 <p>
145 Next change the following in <path>/etc/postfix/master.cf</path>. This will
146 turn on verbose output for debugging:
147 </p>
148
149 <pre caption="/etc/postfix/master.cf">
150 # service type private unpriv chroot wakeup maxproc command + args
151 # (yes) (yes) (yes) (never) (50)
152 #
153 ==========================================================================
154 <comment>(Just add the "-v" after the smtpd in the following line)</comment>
155 smtp inet n - n - - smtpd -v
156 </pre>
157
158 <p>
159 Next, edit <path>/etc/mail/aliases</path> to add your local aliases. There
160 should at least be an alias for root like: <c>root: your@email.address</c>.
161 </p>
162
163 <pre caption="Starting postfix for the first time">
164 # <i>/usr/bin/newaliases</i>
165 <comment>(This will install the new aliases. You only need to do this
166 when you update or install aliases.)</comment>
167
168 # <i>/etc/init.d/postfix start</i>
169 </pre>
170
171 <p>
172 Now that postfix is running, fire up your favorite console mail client and send
173 yourself an email. I use <c>mutt</c> for all my console mail. Verify that
174 postfix is delivering mail to local users, once that's done, we're on to the
175 next step.
176 </p>
177
178 <note>
179 I strongly recommend that you verify this basic postfix setup is functioning
180 before you progress to the next step of the howto.
181 </note>
182
183 </body>
184 </section>
185 </chapter>
186
187 <chapter>
188 <title>Courier-imap</title>
189 <section>
190 <body>
191
192 <pre caption="Install courier-imap and courier-authlib">
193 # <i>emerge courier-imap courier-authlib</i>
194 </pre>
195
196 <pre caption="Courier-imap configuration">
197 # <i>cd /etc/courier-imap</i>
198 <comment>(If you want to use the ssl capabilities of courier-imap or pop3,
199 you'll need to create certs for this purpose.
200 This step is recommended. If you do not want to use ssl, skip this step.)</comment>
201
202 # <i>nano -w pop3d.cnf</i>
203 # <i>nano -w imapd.cnf</i>
204 <comment>(Change the C, ST, L, CN, and email parameters to match your server.)</comment>
205
206 # <i>mkpop3dcert</i>
207 # <i>mkimapdcert</i>
208 </pre>
209
210 <pre caption="Start the courier services you need.">
211 # <i>/etc/init.d/courier-imapd start</i>
212 # <i>/etc/init.d/courier-imapd-ssl start</i>
213 # <i>/etc/init.d/courier-pop3d start</i>
214 # <i>/etc/init.d/courier-pop3d-ssl start</i>
215 </pre>
216
217 <p>
218 Start up your favorite mail client and verify that all connections you've
219 started work for receiving and sending mail. Of course, you won't be able to log
220 on to any of the services because authentication hasn't been configured yet, but
221 it is wise to check if the connections themselves work or not.
222 </p>
223
224 <p>
225 Now that the basics work, we're going to do a whole bunch of stuff at once to
226 get the rest of the system running. Again, please verify that what we've
227 installed already works before progressing.
228 </p>
229
230 </body>
231 </section>
232 </chapter>
233
234 <chapter>
235 <title>Cyrus-sasl</title>
236 <section>
237 <body>
238
239 <p>
240 Next we're going to install cyrus-sasl. Sasl is going to play the role of
241 actually passing your auth variables to courier-auth, which will in turn pass that
242 information to mysql for authentication of smtp users. For this howto, we'll
243 not even try to verify that sasl is working until mysql is set up and contains
244 a test user. Which is fine since we'll be authenticating against mysql in the
245 end anyway.
246 </p>
247
248 <pre caption="Configuring and installing the cyrus-sasl ebuild">
249 # <i>emerge cyrus-sasl</i>
250 </pre>
251
252 <p>
253 Next, edit <path>/etc/sasl2/smtpd.conf</path>.
254 </p>
255
256 <pre caption="Starting sasl">
257 # <i>nano -w /etc/sasl2/smtpd.conf</i>
258 mech_list: PLAIN LOGIN
259 pwcheck_method: saslauthd
260 # <i>nano -w /etc/conf.d/saslauthd</i>
261 SASLAUTHD_OPTS="${SASLAUTH_MECH} -a rimap -r"
262 SASLAUTHD_OPTS="${SASLAUTHD_OPTS} -O localhost"
263 # <i>/etc/init.d/saslauthd start</i>
264 </pre>
265
266 </body>
267 </section>
268 </chapter>
269
270 <chapter>
271 <title>SSL Certs for Postfix and Apache</title>
272 <section>
273 <body>
274
275 <p>
276 Next we're going to make a set of ssl certificates for postfix and apache.
277 </p>
278
279 <pre caption="Making ssl certicates">
280 # <i>cd /etc/ssl/</i>
281 # <i>nano -w openssl.cnf</i>
282
283 <comment>Change the following default values for your domain:</comment>
284 countryName_default
285 stateOrProvinceName_default
286 localityName_default
287 0.organizationName_default
288 commonName_default
289 emailAddress_default.
290
291 <comment>(If the variables are not already present, just add them in a sensible place.)</comment>
292
293 # <i>cd misc</i>
294 # <i>./CA.pl -newreq-nodes</i>
295 # <i>./CA.pl -newca</i>
296 # <i>./CA.pl -sign</i>
297 # <i>cp newcert.pem /etc/postfix</i>
298 # <i>cp newkey.pem /etc/postfix</i>
299 # <i>cp demoCA/cacert.pem /etc/postfix</i>
300 <comment>(Now we do the same thing for apache.)</comment>
301
302 # <i>openssl req -new > new.cert.csr</i>
303 # <i>openssl rsa -in privkey.pem -out new.cert.key</i>
304 # <i>openssl x509 -in new.cert.csr -out new.cert.cert -req -signkey new.cert.key -days 365</i>
305 <comment>(Just leave the resulting certificates here for now.
306 We'll install them after Apache is installed.)</comment>
307 </pre>
308
309 </body>
310 </section>
311
312 </chapter>
313 <chapter>
314 <title>Adding SSL and SASL support to Postfix</title>
315 <section>
316 <body>
317
318 <p>
319 Now edit the postfix config's to make it aware of your new sasl and ssl
320 capabilities. Add the following parameters to the end of the file where they
321 will be easy to find.
322 </p>
323
324 <pre caption="/etc/postfix/main.cf">
325 # <i>nano -w /etc/postfix/main.cf</i>
326
327 smtpd_sasl_auth_enable = yes
328 smtpd_sasl2_auth_enable = yes
329 smtpd_sasl_security_options = noanonymous
330 broken_sasl_auth_clients = yes
331 smtpd_sasl_local_domain =
332
333 <comment>(The broken_sasl_auth_clients option and the login auth method
334 are for outlook and outlook express only and are undocumented.
335 Isn't having to hack software for stupid, broken, M$ BS great?
336 smtpd_sasl_local_domain appends a domain name to clients using
337 smtp-auth. Make sure it's blank or your user names will get
338 mangled by postfix and be unable to auth.)</comment>
339
340 smtpd_recipient_restrictions =
341 permit_sasl_authenticated,
342 permit_mynetworks,
343 reject_unauth_destination
344
345
346 <comment>(The next two options enable outgoing encryption.)</comment>
347 smtp_use_tls = yes
348 smtp_tls_note_starttls_offer = yes
349 smtpd_use_tls = yes
350 #smtpd_tls_auth_only = yes
351 smtpd_tls_key_file = /etc/postfix/newkey.pem
352 smtpd_tls_cert_file = /etc/postfix/newcert.pem
353 smtpd_tls_CAfile = /etc/postfix/cacert.pem
354 smtpd_tls_loglevel = 3
355 smtpd_tls_received_header = yes
356 smtpd_tls_session_cache_timeout = 3600s
357 tls_random_source = dev:/dev/urandom
358
359 <comment>(smtpd_tls_auth_only is commented out to ease testing the system.
360 You can turn this on later if you desire.)</comment>
361
362 # <i>postfix reload</i>
363 </pre>
364
365 <p>
366 Now we're going to verify that the config's we added were picked up by postfix.
367 For this we are going to use <c>telnet</c> (provided by for instance
368 <c>net-misc/netkit-telnetd</c>) although you can also use <c>nc</c> (provided by
369 <c>net-analyzer/netcat</c>):
370 </p>
371
372 <pre caption="Verifying sasl and tls support">
373 # <i>telnet localhost 25</i>
374
375 Trying 127.0.0.1...
376 Connected to localhost.
377 Escape character is '^]'.
378 220 mail.domain.com ESMTP Postfix
379 <i>EHLO domain.com</i>
380 250-mail.domain.com
381 250-PIPELINING
382 250-SIZE 10240000
383 250-VRFY
384 250-ETRN
385 250-STARTTLS
386 250-AUTH LOGIN PLAIN
387 250-AUTH=LOGIN PLAIN
388 250-XVERP
389 250 8BITMIME
390 <i>^]</i>
391 telnet> <i>quit</i>
392 </pre>
393
394 <p>
395 Verify that the above AUTH and STARTTLS lines now appear in your postfix
396 install. As I said before, as it stands now AUTH will not work. that's because
397 sasl will try to auth against it's sasldb, instead of the shadow file for some
398 unknown reason, which we have not set up. So we're going to just plow through
399 and set up mysql to hold all of our auth and virtual domain information.
400 </p>
401
402 </body>
403 </section>
404 </chapter>
405
406 <chapter>
407 <title>The vmail user</title>
408 <section>
409 <body>
410
411 <p>
412 Before we set up our virtual mailhosting environment, we create a functional
413 user under which the virtual mailboxes will be hosted. For clarity's sake we
414 will call this <e>vmail</e>:
415 </p>
416
417 <pre caption="Adding the vmail user">
418 # <i>adduser -d /home/vmail -s /bin/false -m vmail</i>
419 </pre>
420
421 <p>
422 So now you've set up the vmail account. You can create multiple accounts if you
423 want (to keep some structure in your set of virtual mail accounts). The user id,
424 group id and home dirs are referenced in the MySQL tables.
425 </p>
426
427 <p>
428 Next to the user account we also need to create the location where the mailboxes
429 will reside:
430 </p>
431
432 <pre caption="Creating mailboxes">
433 # <i>mkdir /home/vmail/virt-domain.com/foo</i>
434 # <i>chown -R vmail:vmail /home/vmail/virt-domain.com</i>
435 # <i>maildirmake /home/vmail/virt-domain.com/foo/.maildir</i>
436 </pre>
437
438 </body>
439 </section>
440 </chapter>
441
442 <chapter>
443 <title>MySQL</title>
444 <section>
445 <body>
446
447 <p>
448 Next we're going to install and configure MySQL. You'll need the <uri
449 link="http://www.gentoo.org/doc/en/files/genericmailsql.sql">genericmailsql.sql</uri>
450 dumpfile for this step.
451 </p>
452
453 <pre caption="Installing and configuring MySQL">
454 # <i>emerge mysql</i>
455
456 # <i>/usr/bin/mysql_install_db</i>
457 <comment>(After this command runs follow the onscreen directions
458 for adding a root password with mysql,
459 not mysqladmin, otherwise your db will be wide open.)</comment>
460
461 # <i>/etc/init.d/mysql start</i>
462 # <i>mysqladmin -u root -p create mailsql</i>
463 # <i>mysql -u root -p mailsql &lt; genericmailsql.sql</i>
464
465 # <i>mysql -u root -p mysql</i>
466 mysql> <i>GRANT SELECT,INSERT,UPDATE,DELETE</i>
467 -> <i>ON mailsql.*</i>
468 -> <i>TO mailsql@localhost</i>
469 -> <i>IDENTIFIED BY '$password';</i>
470 Query OK, 0 rows affected (0.02 sec)
471
472 mysql> <i>FLUSH PRIVILEGES;</i>
473 Query OK, 0 rows affected (0.00 sec)
474
475 mysql> <i>quit</i>
476 <comment>(Verify that the new mailsql user can connect to the mysql server.)</comment>
477
478 # <i>mysql -u mailsql -p mailsql</i>
479 </pre>
480
481 <p>
482 Your new database has default values and tables set up for two domains. The
483 following tables are included:
484 </p>
485
486 <ul>
487 <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 </ul>
496
497 <pre caption="alias table sample">
498 id alias destination
499 1 root foo@bar.com
500 2 postmaster foo@bar.com
501 </pre>
502
503 <pre caption="user table sample">
504 <comment>(Line wrapped for clarity.)</comment>
505 id email clear name uid gid homedir \
506 maildir quota postfix
507 10 foo@virt-domain.com $password realname virtid virtid /home/vmail \
508 /home/vmail/virt-domain.com/foo/.maildir/ y
509 13 foo@bar.com $password realname localid localid /home/foo \
510 /home/foo/.maildir/ y
511 </pre>
512
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 <pre caption="transport table sample">
519 id domain destination
520 1 bar.com local:
521 2 virt-domain.com virtual:
522 </pre>
523
524 <pre caption="virtual table sample">
525 id email destination
526 3 root@virt-domain.com other@email.address
527 </pre>
528
529 </body>
530 </section>
531 </chapter>
532
533 <chapter>
534 <title>Apache and phpMyAdmin</title>
535 <section>
536 <body>
537
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 # <i>emerge apache phpmyadmin</i>
545 </pre>
546
547 <p>
548 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 </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 </p>
566
567 <ul>
568 <li>SSLCertificateFile /path/to/certs/new.cert.cert</li>
569 <li>SSLCertificateKeyFile /path/to/certs/new.cert.key</li>
570 </ul>
571
572 <pre caption="Install Apache SSL certificates">
573 # <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 <comment>(Check if you have an ssl-vhost template already.
577 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
581 <comment>(Change the following parameters)</comment>
582 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
599 # <i>nano -w /etc/conf.d/apache2</i>
600 <comment>(Add -D SSL -D PHP5 to the APACHE2_OPTS)</comment>
601
602 # <i>/etc/init.d/apache2 restart</i>
603 </pre>
604
605 <p>
606 Next, configure phpMyAdmin.
607 </p>
608
609 <pre caption="Configuring phpMyAdmin">
610 # <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 <comment>(Change the following parameters.)</comment>
614 $cfg['blowfish_secret'] = 'someverysecretpassphraze';
615
616 $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 $cfg['Servers'][$i]['controlpass'] = '$password'; // access to the "mysql/user"
620 // and "mysql/db" tables)
621 $cfg['Servers'][$i]['user'] = 'mailsql'; // MySQL user
622 $cfg['Servers'][$i]['password'] = '$password'; // MySQL password
623 </pre>
624
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 accurate. For instance, make sure the local user's home dir exists and that the
632 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 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 </p>
637
638 </body>
639 </section>
640 </chapter>
641
642 <chapter>
643 <title>Configuring MySQL Authentication and vhosts</title>
644 <section>
645 <body>
646
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 # <i>nano -w /etc/courier/authlib/authdaemonrc</i>
655 authmodulelist="authmysql authpam"
656
657 # <i>nano -w /etc/courier/authlib/authmysqlrc</i>
658 MYSQL_SERVER localhost
659 MYSQL_USERNAME mailsql
660 MYSQL_PASSWORD $password
661 MYSQL_DATABASE mailsql
662 MYSQL_USER_TABLE users
663 <comment>(Make sure the following line is commented out since we're storing plaintext.)</comment>
664 #MYSQL_CRYPT_PWFIELD crypt
665 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
673 # <i>/etc/init.d/courier-authlib restart</i>
674 # <i>/etc/init.d/saslauthd restart</i>
675 </pre>
676
677 <p>
678 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 </p>
683
684 <pre caption="/etc/postfix/mysql-aliases.cf">
685 # <i>nano -w /etc/postfix/mysql-aliases.cf</i>
686 # mysql-aliases.cf
687
688 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 </pre>
696
697 <pre caption="/etc/postfix/mysql-relocated.cf">
698 # <i>nano -w /etc/postfix/mysql-relocated.cf</i>
699 # mysql-relocated.cf
700
701 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 </pre>
709
710 <pre caption="/etc/postfix/mysql-transport.cf (optional)">
711 # <i>nano -w /etc/postfix/mysql-transport.cf</i>
712 # mysql-transport.cf
713
714 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 </pre>
722
723 <pre caption="/etc/postfix/mysql-virtual-gid.cf (optional)">
724 # <i>nano -w /etc/postfix/mysql-virtual-gid.cf</i>
725 # mysql-virtual-gid.cf
726
727 user = mailsql
728 password = $password
729 dbname = mailsql
730 table = users
731 select_field = gid
732 where_field = email
733 additional_conditions = and postfix = 'y'
734 hosts = unix:/var/run/mysqld/mysqld.sock
735 </pre>
736
737 <pre caption="/etc/postfix/mysql-virtual-maps.cf">
738 # <i>nano -w /etc/postfix/mysql-virtual-maps.cf</i>
739 # mysql-virtual-maps.cf
740
741 user = mailsql
742 password = $password
743 dbname = mailsql
744 table = users
745 select_field = maildir
746 where_field = email
747 additional_conditions = and postfix = 'y'
748 hosts = unix:/var/run/mysqld/mysqld.sock
749 </pre>
750
751 <pre caption="/etc/postfix/mysql-virtual-uid.cf (optional)">
752 # <i>nano -w /etc/postfix/mysql-virtual-uid.cf</i>
753 # mysql-virtual-uid.cf
754
755 user = mailsql
756 password = $password
757 dbname = mailsql
758 table = users
759 select_field = uid
760 where_field = email
761 additional_conditions = and postfix = 'y'
762 hosts = unix:/var/run/mysqld/mysqld.sock
763 </pre>
764
765 <pre caption="/etc/postfix/mysql-virtual.cf">
766 # <i>nano -w /etc/postfix/mysql-virtual.cf</i>
767 # mysql-virtual.cf
768
769 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 </pre>
777
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 # <i>nano -w /etc/postfix/main.cf</i>
784 <comment>(Ensure that there are no other alias_maps definitions)</comment>
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 <comment>(The domains listed by the mydestination should not be listed in
793 the virtual_mailbox_domains parameter)</comment>
794 virtual_mailbox_domains = virt-domain.com, $other-virtual-domain.com
795
796 virtual_minimum_uid = 1000
797 <comment>(Substitute $vmail-gid with the GID of the vmail group)</comment>
798 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 <comment>(Substitute $vmail-uid with the UID of the vmail user)</comment>
802 virtual_uid_maps = static:$vmail-uid
803 virtual_mailbox_base = /
804 #virtual_mailbox_limit =
805 </pre>
806
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 <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 </pre>
831
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 </body>
842 </section>
843 </chapter>
844
845 <chapter>
846 <title>Squirrelmail</title>
847 <section>
848 <body>
849
850 <pre caption="Install squirrelmail">
851 # <i>emerge squirrelmail</i>
852 <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
855 # <i>webapp-config -I -h localhost -d /mail squirrelmail 1.4.3a-r2</i>
856 # <i>cd /var/www/localhost/htdocs/mail/config</i>
857 # <i>perl ./conf.pl</i>
858 <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 </pre>
862
863 </body>
864 </section>
865 </chapter>
866
867 <chapter>
868 <title>Mailman</title>
869 <section>
870 <body>
871
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 # <i>emerge mailman</i>
883 </pre>
884
885 <pre caption="Setting defaults: Mailman/Defaults.py">
886 # <i> nano -w /usr/local/mailman/Mailman/Defaults.py</i>
887 <comment>(Change the values below to reflect your primary domain, virtuals will be set next.)</comment>
888 DEFAULT_EMAIL_HOST = 'domain.com'
889 DEFAULT_URL_HOST = 'www.domain.com'
890 </pre>
891
892 <pre caption="mailman config: mm_cfg.py">
893 # <i>nano -w /usr/local/mailman/Mailman/mm_cfg.py</i>
894 MTA = "Postfix"
895 POSTFIX_STYLE_VIRTUAL_DOMAINS = ['virt-domain.com', 'virt.domain2.com']
896 add_virtualhost('www.virt.domain.com', 'virt.domain.com')
897 add_virtualhost('www.virt.domain2.com', 'virt.domain2.com')
898 <comment>(This is required for your virtual domains for mailman to function.)</comment>
899 </pre>
900
901 <pre caption="And last but not least">
902 <comment>(Once that's finished, add your first list.)</comment>
903
904 # <i>su mailman</i>
905 # <i>cd ~</i>
906 # <i>./bin/newlist --urlhost='www.virt-domain.com' --emailhost='virt-domain.com' test</i>
907 Enter the email of the person running the list: <i>your@email.address</i>
908 Initial test password:
909 Hit enter to continue with test owner notification...
910 <comment>(Virtual domain lists may also be specified with
911 list@domain.com style list names.)</comment>
912 # <i>./bin/genaliases</i>
913 <comment>(Now that your aliases have been generated,
914 verify that they were added successfully.)</comment>
915
916 # <i>nano -w data/aliases</i>
917 # STANZA START: test
918 # CREATED:
919 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 # STANZA END: test
930
931 <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 # <i>/etc/init.d/mailman start</i>
939 # <i>rc-update add mailman default</i>
940 <comment>(To start mailman at once and on every reboot.)</comment>
941 </pre>
942
943 <pre caption="Adding mailman alias support to postfix">
944 # <i>nano -w /etc/postfix/main.cf</i>
945 owner_request_special = no
946 recipient_delimiter = +
947 <comment>(Read README.POSTFIX.gz for details on this.)</comment>
948
949 alias_maps =
950 hash:/usr/local/mailman/data/aliases,
951 mysql:/etc/postfix/mysql-aliases.cf
952
953 virtual_alias_maps =
954 hash:/usr/local/mailman/data/virtual-mailman,
955 mysql:/etc/postfix/mysql-virtual.cf
956 <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 </pre>
962
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 </body>
972 </section>
973 </chapter>
974
975 <chapter>
976 <title>Content Filtering and Anti-Virus</title>
977 <section>
978 <body>
979
980 <p>
981 For content filtering and Anti-Virus, please consult our <uri
982 link="/doc/en/mailfilter-guide.xml">mail filtering gateway guide</uri>.
983 </p>
984
985 </body>
986 </section>
987 </chapter>
988
989 <chapter>
990 <title>Wrap Up</title>
991 <section>
992 <body>
993
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 # <i>postfix reload</i>
1006 # <i>rc-update add $service default</i>
1007 </pre>
1008
1009 <p>
1010 <e>Have fun!</e>
1011 </p>
1012
1013 </body>
1014 </section>
1015 </chapter>
1016
1017 <chapter>
1018 <title>Troubleshooting</title>
1019 <section>
1020 <title>Introduction</title>
1021 <body>
1022
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 </body>
1034 </section>
1035 <section>
1036 <title>Step 1: Check your config files</title>
1037 <body>
1038
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 # <i>/etc/init.d/service restart</i>
1049 </pre>
1050
1051 </body>
1052 </section>
1053 <section>
1054 <title>Step 2: Are all the necessary services actually running?</title>
1055 <body>
1056
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 # <i>/etc/init.d/$service status</i>
1069 # <i>netstat -a | grep $service (or $port)</i>
1070 </pre>
1071
1072 </body>
1073 </section>
1074 <section>
1075 <title>Step 3: Are all the service using the current config's?</title>
1076 <body>
1077
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 # <i>apache2ctl fullstatus</i> (needs lynx installed)
1086 # <i>apache2ctl configtest</i> (checks config sanity)
1087 # <i>postconf -n</i> (will tell you exactly what param's postfix is using)
1088 # <i>/etc/init.d/$service restart</i>
1089 </pre>
1090
1091 </body>
1092 </section>
1093 <section>
1094 <title>Step 4: Check the logs</title>
1095 <body>
1096
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 # <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 # <i>tail /var/log/apache2/error_log</i>
1111 </pre>
1112
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 <pre caption="adding debug_peer support">
1119 # <i>nano -w /etc/postfix/main.cf</i>
1120 debug_peer_level = 5
1121 debug_peer_list = $host.domain.name
1122 <comment>(Uncomment one of the suggested debugger
1123 commands as well.)</comment>
1124 </pre>
1125
1126 </body>
1127 </section>
1128 <section>
1129 <title>Step 5: Talk to the service itself</title>
1130 <body>
1131
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 # <i>telnet localhost $port</i>
1140 <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
1143 Trying 127.0.0.1...
1144 Connected to localhost.
1145 Escape character is '^]'.
1146 * OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc.
1147 </pre>
1148
1149 </body>
1150 </section>
1151 <section>
1152 <title>Step 6: Sometimes only the big guns will give you the information you need: strace</title>
1153 <body>
1154
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 # <i>emerge strace</i>
1165 # <i>strace $command</i>
1166 # <i>strace -p `ps -C $service -o pid=`</i>
1167 </pre>
1168
1169 </body>
1170 </section>
1171 <section>
1172 <title>Step 7: Research</title>
1173 <body>
1174
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
1183 <ul>
1184 <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 I also spend a lot of time on irc.freenode.net #gentoo. Irc is a great
1204 place to go for help.
1205 </li>
1206 </ul>
1207
1208 </body>
1209 </section>
1210 </chapter>
1211 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20