Gentoo Wiki


Please format this article according to the guidelines and Wikification suggestions, then remove this notice {{Wikify}} from the article

Complete Virtual Mail Server

Getting Started

Basic Mail Setup

Enhanced Mail Services

Anti-Spam Configuration

Anti-Virus Configuration

Log Analyzer

Wrapping it Up

  • Final Changes and Troubleshooting

Wrap Up

Ok, you're all set, edit /etc/postfix/ and turn off verbose mode for production use. You'll probably also want to add the services to your startup routine to make sure everything comes back up on a reboot. Make sure to add all the services you're using - apache, postgresql, saslauthd, postfix, courier-imapd, courier-imapd-ssl, courier-pop3d, and courier-pop3d-ssl are all up to your decision on what access you want to provide. I generally only have the SSL services enabled.

Code: Autostarting Services
# postfix reload
# rc-update add $service default

Code: /etc/postfix/
#nano /etc/postfix/

# service type  private unpriv  chroot  wakeup  maxproc command + args
#               (yes)   (yes)   (yes)   (never) (50)
smtp      inet  n       -       n       -       -       smtpd -v

// Just remove the "-v" after the smtpd in the above line


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 place 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 particular 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 is 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 your mail system, it's not going to work. If you make a change to a config file for a service, make sure you restart that service so that the config change gets picked up.

Code: Restarting Services
# /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 that 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 being used by another process. Sometimes you can detect this with netstat. Or, if you've been at it awhile, just take a break and reboot your box in the meantime. That will clear out any hung services. Then you can come back fresh and try it again.

Code: Checking Services
# /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 service to make sure it's using the current version. Some of the components will dump their current config's to you, like postfix.

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

Step 4: Check the logs. Repeat after me, logs are my friend. My next troubleshooting stop is always 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 depending 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 at the very least, figure out which component is having the problem.

Code: Checking Error Logs
# kill -USR1 `ps -C metalog -o pid=`(to turn off metalog buffering)
# nano -w /var/log/mail/current
# cat /var/log/mysql/mysql.log
# tail /var/log/apache/error_log

You may also find the debug_peer parameters in helpful. Setting these will increase log output over just verbose mode.

Code: Adding Debug Support
# nano -w /etc/postfix/
debug_peer_level = 5
debug_peer_list = $
// Uncomment one of the suggested debugger
// commands as well.

Step 5: Talk to the service itself. SMTP, IMAP, and POP3 all respond to telnet sessions. As we've seen earlier when we verified postfix's config. Sometimes it's helpful to open a telnet session to the service itself and see what's happening.

Code: Testing with Telnet
# telnet localhost $port
// SMTP is 25, IMAP is 143, POP3 is 110. You should receive at least an OK string,
// letting you know that the service is running and ready to respond to requests.

Connected to localhost.
Escape character is '^]'.
* OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc.

Step 6: Sometimes only the big guns will give you the information you 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 strace and watch all the system calls as they happen. It often dumps a huge amount of information, so you'll either need to watch it real-time as you retry a failed transaction with the mail system, or dump the output to a file for review.

Code: Setting Trace
# emerge strace
# strace $command
# strace -p `ps -C $service -o pid=`

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 information 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 on setting up smtp-auth which contains some great debugging ideas.

Retrieved from ""

Last modified: Sun, 18 May 2008 07:14:00 +0000 Hits: 8,602