Say you've got a user who's email box has been corrupted by some spam-relaying jerk in Aruba. Somehow the hash in "cyrus.header" inside that user's mailbox has gone bad, and changing the password on the account no longer works.
So you delete the account from the system, then recreate it. Unfortunately, the email server fails to delete the mailbox for the old user, and now the new user cannot create its mailbox - so it can't receive any mail.
First, initiate a secure shell connection to your server:
ssh emailserver.mydomain.com -l myadminaccount
You'll need to be an admin because we've got to edit a config file or two.
Now that you're connected, let me tell you what you should NOT go and do. You should NOT simply delete the mailbox file from the filesystem. That will get you nowhere, since the username is still present in the IMAP database.
Perhaps you reply, "Ah hah, so let's just delete the database reference to the user, then, too!" Perhaps you think you can use the common procedure of dumping the IMAP database into a plain text file, editing it, and then importing it back, like so:
su - cyrusimap -c "/usr/bin/cyrus/bin/ctl_mboxlist -d > mboxlist"
pico mboxlist (you delete the line(s) and save the file)
su - cyrusimap -c "/usr/bin/cyrus/bin/ctl_mboxlist -u < mboxlist"
Well guess what: Doing this on 10.4.3 results in NO CHANGE. The database refuses to accept the update. Dump it back out and see for yourself. Hooray! That's quality time wasted, there!
Anyway, here's how to really fix the problem.
You've got your SSH session running, and that's good. Now, use the Workgroup Manager tool that comes with OS X to create an IMAP administrator account. It's best if this is not an account that actually receives mail on your system. Think of this account as a root user for your IMAP server. There is no need for this user to be an actual admin on your server, so just leave it as a normal user. Enable mail access in the Workgroup Manager for this user, and save your changes.
Now you'll need to add the account's shortname to the "admins: " line of imapd.conf, so fire up the "pico" editor:
The cyrus user should already be in there, so just add your mail admin's shortname after the cyrus user, using a space to separate the two. After adding a new admin, it's best to restart Cyrus to make the change known. Use the Server Admin Tool for that.
Now, from your command shell, launch the cyrus admin tool like so:
/usr/bin/cyrus/admin/cyradm --user garote --auth login localhost
You'll need to enter the password for the user you created (garote in this example), and then you'll be in.
To confirm you're an admin, list all the mailboxes at your disposal with the "lm" command. Everybody with a cyrus mailbox should roll up your screen. (If you just get a couple of local folders, you aren't an admin user. Check over your work so far.)
Note that you can't just recreate the mailbox for the user: "cm user/username" responds with "Mailbox already exists". First you've gotta get rid of this old one.
To delete that mailbox, you need to grant appropriate rights to do so, by issuing the command:
sam user/mailbox username all
where 'username' is the name of your admin account, and 'mailbox' is the box to be deleted (typically the same as the shortname of the owner). Yes, a slash is necessary, not a period - OS X Server uses the unix-style mailbox naming convention in its database.
(As I mentioned earlier: You should NOT have gone and deleted the user's maildrop on your own, perhaps by issuing a "rmdir /var/spool/imap/user/username". If you have, you're here because that tactic didn't work, and now you're up a stump. Without the various "cyrus." files, you'll get "System I/O error" when trying to grant permissions, or rebuild or delete the box. That sucks. The quick workaround? Duplicate some other user's mail folder at the command prompt. Don't even bother changing the cyrus.header file inside. Then grant permissions like normal.)
Now, issue a:
where 'mailbox' is the box you want removed. The command should succeed, so immediately issue a:
to create a structure that has a proper hash in the "cyrus.header" file.
Then go home, and get some sleep!