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

  ViewVC Help
Powered by ViewVC 1.1.20