1 |
<?xml version='1.0' encoding='UTF-8'?> |
2 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/virt-mail-howto.xml,v 1.58 2007/08/24 18:59:45 swift Exp $ --> |
3 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
4 |
|
5 |
<guide link="/doc/en/virt-mail-howto.xml"> |
6 |
<title>Virtual Mailhosting System with Postfix Guide</title> |
7 |
|
8 |
<author title="Author"> |
9 |
<mail link="antifa@gentoo.org">Ken Nowack</mail> |
10 |
</author> |
11 |
<author title="Author"> |
12 |
<mail link="ezra@revoltltd.org">Ezra Gorman</mail> |
13 |
</author> |
14 |
<author title="Editor"> |
15 |
<mail link="klasikahl@gentoo.org">Zack Gilburd</mail> |
16 |
</author> |
17 |
<author title="Editor"> |
18 |
<mail link="seather@scygro.za.net">Scygro</mail> |
19 |
</author> |
20 |
<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.6</version> |
30 |
<date>2007-08-24</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>adduser -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 < 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 |
<VirtualHost host.domain.name:443> |
583 |
ServerName host.domain.name |
584 |
ServerAdmin your@email.address |
585 |
|
586 |
DocumentRoot "/var/www/localhost/htdocs/phpmyadmin"; |
587 |
<Directory "/var/www/localhost/htdocs/phpmyadmin"> |
588 |
... |
589 |
</Directory> |
590 |
|
591 |
SSLCertificateFile /etc/apache2/ssl/new.cert.cert |
592 |
SSLCertificateKeyFile /etc/apache2/ssl/new.cert.key |
593 |
SSLEngine on |
594 |
... |
595 |
</VirtualHost> |
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 irc.freenode.net #gentoo. Irc is a great |
1202 |
place to go for help. |
1203 |
</li> |
1204 |
</ul> |
1205 |
|
1206 |
</body> |
1207 |
</section> |
1208 |
</chapter> |
1209 |
</guide> |