Cyrus IMAPd 2.3 and ANNOTATEMORE

Warning: This is very preliminary and buggy and experimental! That said, people are using it with great success.

This has been performed, tested, and written up for Cyrus IMAPd 2.3.7. Since being implemented in cyrus, the ANNOTATEMORE extension has undegone revisions including the changing of command and extension names. The last version using the old syntax is the revision 7, at the time of writing, revision 10 has been published, the IETF has the current version.

Status Quo and Problem

The ANNOTATEMORE IMAP extension implemented in Cyrus IMAPd version 2.3.7 (and likely above) allows mail clients to store private or shared data (annotations) attached to mailboxes or - if they have sufficient priviledges - the server. Some such annotations (e.g. a generic /comment one, some that store information on the user's preferences with respect to regular checking the inbox for new mail) are defined in the draft standard. It also allows for vendor extensions.
This seems very useful and applications like the Kolab Groupware make use of it.
Unfortunately, the fields defined are currently hardwired in the cyrus source code.

Solution

This patch introduces a new configuration directive in the imapd.conf, annotation_definitions: <definitionfile>. The definition file contains lines containing the comma-separated fields specifying for each possible annotation field

name, annotation scope, attribute type, annotation proxy type, attribute names, acl

The fields have the following meaning.

name: is the hierarchical name as in he draft standard, most likely of the form /vendor/you/something,
annotation scope: specifies whether the annotation is to the server or a mailbox. Note that the implementation seems to enforce certain ACLs, e.g. you have to be administrator to set server annotations.
attribute type: specifies the data type and is one of string,boolean,int,uint, and content-type. content-type might enforce some correctness, but currently doesn't.
annotation proxy type: specifies whether this attribute is for the backend or proxy servers or both (proxy_and_backend).
attribute names: the (space-separated) list of available attributes for the annotation field. Possible attribute names are (where the suffixless foo permits both foo.priv and foo.shared): value, value.shared, value.priv, size, size.shared, size.priv, modifiedsince, modifiedsince.shared, modifiedsince.priv, content-type, content-type.shared, content-type.priv.
acl: extra ACL requirements for setting annotations. This is the usual Cyrus IMAPd ACL permission bit string format. Particularly useful seem to be the empty string to allow users to annotate or a to require admin privileges. Note that some ACL requirements (read and write on the mailbox) are hard-wired in Cyurs IMAPd.

Note that while Cyrus has a implements a few "magic" annotations (e.g. switching MODSEQ from the condstore extension on and off), we're only concerned with annotations that store data with the mailboxes.

A note for people having trouble compiling the patch

You might want to make sure that imapoptions is newer than imapopts.c after patching in order to have the build process regenerate imapopts.[ch].

Revision history

2007-05-30: Added note about regenerating imapopts.[ch]
2006-11-23: Initial realease