/[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.62 - (show annotations) (download) (as text)
Thu Oct 14 06:14:35 2010 UTC (4 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.61: +4 -1 lines
File MIME type: application/xml
the adduser command does not exist, bug 340915

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

  ViewVC Help
Powered by ViewVC 1.1.20