Evil Home Stereo

Executive summary: This is yet another rant about underdocumented software. My conclusion: What I hate more than undocumented software projects is documentation which first looks nice but later misses some essential details. Why? Because when I choose a software I often select one by the amount of documentation available. And when I then hit the point where I miss those pesky little details, I often invested too much time into this solution to step back.

And sometimes that’s the moment when I’m glad that I chose an open source project because I can start looking at the source code to find a solution instead of paying loads of money to an over-priced consultant.

In this case its only about a private project/server and I spent only one day on the topic. In a nutshell, I updated PHP on Kai’s server to PHP5 because I planned to use Swift. The only actual PHP application running there is Horde. And after the upgrade, that one suddenly didn’t work anymore. It was completely dead, showing only a blank page. After fiddling a bit I decided to go the Windows way to solve the problem: I reinstalled it, from the Groupware Webmail Edition.

It immediately worked again, seems like the setup script does some magic based on the PHP version or the plugins available or whatever. And now we have not only a shiny new theme but also a bunch of fancy new features. Like Ingo.

Well, probably I should have stopped there but I discovered that config file backends.php. Which tempted me by promising me a GUI for my procmail rules. Yay.

That was the first case of documentation which looked good but fogot to mention the essential details. With the driver “vfs” Ingo will “Use Horde VFS”. Cool, I already configured a local VFS storage for Horde, would be cool if Ingo could drop the procmail files into /var/lib/horde/ingo/$USER.conf and each user can use INCLUDERC from his procmailrc to use it.

Hmmm… but how do I do this? The example only mentions a vfstype of ftp. What else is available? I can’t remember if I already started to grep through the source or just sticked with FTP. vsftpd started from
xinetd isn’t much overhead and can easily be restricted so that only localhost can access it.

That seemed to work like a charm but I discovered a bug after I played around a bit: Deliveries to the inbox are translated as $DEFAULT. Thats fine, the global procmailrc changes that to the correct Maildir in the home directory. Deliveries to other folders are created as $DEFAULT/.foo. Fine, too, we’ll have a double slash because the inbox is a Maildir but it will find the correct folder anyway. But: Subfolders of the inbox are translated to $DEFAULT/.foo as well. Dovecot expects those to be $DEFAULT/.INBOX.foo. So those won’t work.

I should really have stopped here but I remembered that the backend also supported Sieve filters. I always wanted those, all I needed was a Sieve implementation available on Debian Sarge (never touch a running system). And the GNU Mailutils offered me one. And you know what? The documentation looked excellent.

So I decided to give them a try.

To shorten the story: The sieve command works well but always tries to file mails into ./foo instead of ./.foo. There is the option --mail-spool which might change that behaviour. But it didn’t seem to work. (Where’s that one-tool-does-what-it-can-do-best approach here which would be sieve calling some kind of deliver command instead of doing some inside magic?)

Maybe I could have found a solution. Because all the magic the vague documentation on the API call mu_mailbox_create_default doesn’t mention is documented inline. (The fact that the environment variable $FOLDER takes precedence over $MAIL is also not documented.) And the definition of mu_register_all_formats, in the documentation only mentioned in an example, looks like you can file to a whole lot of different storages (including IMAP and NNTP?), based on some half-documented URL format. Or not.

At some point I got tired trying to guess how that software works and sticked with the suboptimal procmail solution.