If you're having trouble with Cyrus, please read the CyrusFAQ as well, as your question may be answered there. This page is designed to talk about general Cyrus troubleshooting techniques and tools.

Diagnosing problems with CyrusImapd and CyrusSasl may be a daunting task at first, but there are many tools available to help you do this.

• CyrusImapd Troubleshooting
  • Logging: Often the syslog level you are running at is either too high (and thus reporting confusing error messages that are essentially meaningless and increasing system load) or too low (and thus not reporting enough data to help determine the cause of a problem). You'll want to make sure your syslog.conf is properly configured (see CyrusLoggingDocumentation^?).
  • imtest and other protocol test utilites (smtptest, pop3test, etc) can be useful to determine if SASL authentication is working against the server for that particular protocol. If authentication succeeds, these applications will allow you to write protocol directly to the server. For those who don't know the IMAP protocol, a few hints can be found at the ImtestByHand page.
  • It is often useful to get a protocol trace from an IMAP (or other CyrusImap protocol) session, to do this, create a directory for the username in question in <CyrusImapConfigDirectory>/log (e.g. /var/imap/log/rjs3), ensure that this directory is writable by the cyrus user, and then connect using your client application that is having trouble. This will dump the total (unencrypted) protocol log from the session. Note that this is not useful for debugging authentication problems, since the log will only be created after the user successfully authenticates.
  • You can run the Cyrus "master" process in debug mode to see addittional information. To do this, simply run "master -D" on the command line. (Note: You may also want to add something like "debug_command: /usr/bin/gdb /usr/cyrus/bin/%s %d" to your /etc/imapd.conf.)
  • The imaplib module in recent (preferably 2.3) versions of Python can be very useful when used in the Python interpreter's interactive mode. It's reasonably well documented, too, and can be considered a useful alternative to writing IMAP protocol by hand in some situations. Unfortunately, it doesn't support SASL as of the version in Python 2.3.
  • If the not-so-self-explanatory message "master[xxxx]: Servname not supported for ai_socktype, disabling sieve" appears in your log files, you may simply have forgotten to add the sieve portnumber (tcp port 2000) to /etc/service.
  • If you are having trouble with mail deliveries, a.k.a. 'Permission Denied' to your mta, make sure that you have appropriate permissions on the mailboxes themselves: i.e. use cyradm to add anonymous with post privs. cyradm.... 'sam account anonymous p' if you are using 'deliver'
• CyrusSasl Troubleshooting
  • testsaslauthd can be useful to diagnose if CyrusSaslauthd^? is causing you trouble in your CyrusSaslConfiguration^?. if it succeeds, then saslauthd is working properly and you can move your diagnosis further down the line (is CyrusSasl looking at the correct socket, etc).
  • CyrusSasl ships with a sample server and a sample client application. These may be useful to help show if CyrusSasl is working properly on your system and the problem may be with the configuration of the specific application. See UsingCyrusSaslSamplePrograms.
  • Other CyrusSaslErrors

-- RobSiemborski^? - 24 Jul 2003