Virtual Mailhosting System Guide

Troubleshooting

Introduction

Troubleshooting: This is a short troubleshooting guide for the set up= we've detailed how to install here. It is not exhaustive, but meant as a p= lace to get you started in figuring out problems. With a complicated setup = such as this, it's imperative that you narrow down the problem to the parti= cular component that is malfunctioning. In general I do that by following a= few steps. Start from the base of the system and work your way up, ruling = out components that work along the way until you discover which component i= s having the problem.

Step 1: Check your config files.

Typos are killers, especially when dealing with authentication systems= . Scan your config's and mailsql database for typo's. You can debug all you= want, but if you're not passing the right information back and forth to yo= ur mail system, it's not going to work. If you make a change to a config fi= le for a service, make sure you restart that service so that the config cha= nge gets picked up.

=09

		# /etc/init.d/service restart

Step 2: Are all the necessary services actually running?

If it's not running, start it up. It's awful hard to debug a service t= hat isn't running. Sometimes a service will act like it's started but still= not function. Sometimes, when a bad config is used, or a bad transmission = comes into a mail component, the service will hang and keep the port from b= eing used by another process. Sometimes you can detect this with netstat. O= r, if you've been at it awhile, just take a break and reboot your box in th= e meantime. That will clear out any hung services. Then you can come back f= resh and try it again.

		# /etc/init.d/$service status
		# netstat -a | grep $service (or $port)

Step 3: Are all the service using the current config's?

If you've recently made a change to a config file, restart that servic= e to make sure it's using the current version. Some of the components will = dump their current config's to you, like postfix.

		# apachectl fullstatus (needs lynx installed)
		# apachectl configtest (checks config sanity)
		# postconf (will tell you exactly what param's postfix is using)
		# /etc/init.d/$service restart=20

Step 4: Check the logs.

Repeat after me, logs are my friend. My next troubleshooting stop is a= lways the logs. Sometimes it's helpful to try a failed operation again then= check the logs so that the error message is right at the bottom (or top de= pending on your logger) instead of buried in there somewhere. See if there = is any information in your log that can help you diagnose the problem, or a= t the very least, figure out which component is having the problem.

		# kill -USR1 `ps -C metalog -o pid=3D`(to turn off metalog bufferi=
ng)
		# nano /var/log/everything/current
		# cat /var/log/mysql/mysql.log
		# tail /var/log/apache/error_log

Step 5: Talk to the service itself.

SMTP, IMAP, and POP3 all respond to telnet sessions. As we've seen ear= lier when we verified postfix's config. Sometimes it's helpful to open a te= lnet session to the service itself and see what's happening.

		# telnet localhost $port
	=09
		SMTP is 25, IMAP is 143, POP3 is 110. You should receive at lea=
st an OK string,
		letting you know that the service is running and ready to respo=
nd to requests.

		Trying 127.0.0.1...
		Connected to localhost.
		Escape character is '^]'.
		* OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc.  See =
COPYING for distribution information.

Step 6: Sometimes only the big guns will give you the information y= ou need: strace.

You should have this installed anyway. This is an invaluable tool for = debugging software. You can start commands from the command line with strac= e and watch all the system calls as they happen. It often dumps a huge amou= nt of information, so you'll either need to watch it realtime as you retry = a failed transaction with the mail system, or dump the output to a file for= review.

		# emerge strace
		# strace $command
		# strace -p `ps -C $service -o pid=3D`

Step 7: Research

Once you have the information, if you can diagnose and fix the problem= , great! If not, you'll probably need to go digging on the net for informat= ion that will help you fix it. Here's a list of sites you can check to see = if your error has already been resolved. There's also a really good howto o= n setting up smtp-auth which contains some great debugging ideas.

http://forums.gentoo.org/ - Great forums for gentoo users<= /li>
http://bugs.gentoo.org/ - Bugs database for gentoo - great= place to look for specific errors
http://postfix.state-of-mind.de/ - smtp-auth howto
http://marc.theaimsgroup.com/?l=3Dpostfix-users - Postfix = mailing lists - searchable
http://sourceforge.net/mailarchive/forum.php?forum_id=3D6705 - Courier-imap mailing list archives - not searchable
http://www.google.com/ - If all else fails, there's always= google, which has never failed me
I also spend a lot of time on irc.freenode.net #gentoo. Irc is a grea= t place to go for help.