Sophie: cyrus-imapd-2.5.11-7.1.mga7 i586

cyrus-imapd-2.5.11-7.1.mga7.i586.rpm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="author" content="Ken Murchison" />

<title>Database Formats</title>
</head>

<body>
<h1>Database Formats</h1>

<h2>Introduction</h2>

<p>
This is an attempt to document the cyrus database formats.  It should not
be considered authoritative and is subject to change.</p>

<p> No external tools should make use of this information.  The only
supported method of access to the databases is via the API specific to
the database and the underlying cyrusdb interface.</p>

<h2>Mailbox List (mailboxes.db)</h2>

<p>
This database contains the master list of all mailboxes on the
system.  The database is indexed by mailbox name and each data record
contains the mailbox type, the partition on which the mailbox resides
and the ACL on the mailbox.  The format of each record is as follows:</p>

<pre>
Key: &lt;Mailbox Name&gt;

Data: &lt;Type Number&gt;SP&lt;Partition&gt;SP&lt;ACL (space-separated userid/rights pairs)&gt;
</pre>

<h2>Annotations (annotations.db)</h2>

<p>This database contains mailbox and server annotations.  The
database is indexed by mailbox name (empty for server annotations) +
annotation name + userid (empty for shared annotations) and each data
record contains the value size, value data, content-type of the data
and timestamp of the record.  The format is each record is as follows:</p>

<pre>
Key: &lt;Mailbox Name&gt;\0&lt;Annotation Name&gt;\0&lt;Userid&gt;\0

Data: &lt;Value Size (4 bytes)&gt;&lt;Value&gt;\0&lt;Content-Type&gt;\0&lt;Timestamp (4 bytes)&gt;
</pre>

<h2>Quotas (quotas.db)</h2>

<p>This database contains the master list of quotaroots on the
system.  The database is indexed by quota root and each data record
contains the current usage of all mailboxes under the quota root and
the limit of the quota root.  The format of each record is as
follows:</p>

<pre>
Key: &lt;Quota Root&gt;

Data: &lt;Usage (in bytes)&gt;SP&lt;Limit (in Kbytes)&gt;
</pre>

<h3>Legacy Quotas</h3>

<p>The legacy quota database uses a distributed system in which each
quota root is stored in a separate file named by quota root and the
contents has the following format:</p>

<pre>
&lt;Usage (in bytes)&gt;\n
&lt;Limit (in Kbytes)&gt;\n
</pre>

<p>The translation to/from this data record format is handled by the
quota_legacy cyrusdb backend.</p>

<h2>Duplicate Delivery (deliver.db)</h2>

<p>This database is used for duplicate delivery suppression, retrieving
usenet articles by message-id, and tracking Sieve redirects and
vacation responses. The database is indexed by message-id +
recipient (either mailbox or email address) and each data record
contains the timestamp of the record and the UID of the message within
the mailbox (if delivered locally). The format of each record is as
follows:</p>

<pre>
Key: &lt;Message-ID&gt;\0&lt;Recipient&gt;\0

Data: &lt;Timestamp (4 bytes)&gt;&lt;Message UID (4 bytes)&gt;
</pre>

<h2>TLS cache (tls_sessions.db)</h2>

<p>This database caches SSL/TLS sessions so that subsequent
connections using the same session-id can bypass the SSL/TLS
handshaking, resulting is shorter connection times.  The database is
indexed by session-id and each data record contains the timestamp of
the record and the ASN1 representation of the session data.  The
format of each record is as follows:</p>

<pre>
Key: &lt;Session-ID (multi-byte)&gt;

Data: &lt;Timestamp (4 bytes)&gt;&lt;Session Data (multi-byte)&gt;
</pre>

<h2>PTS cache (ptscache.db)</h2>

<p>This database caches authentication state records, resulting in
shorter authentication/canonicalization times.  The database is
indexed by userid and each data record contains an authentication
state for the userid.  The format of each record is as follows:</p>

<pre>
Key: &lt;Userid&gt;

Data: &lt;Auth State (multi-byte)&gt;
</pre>

<h2>STATUS cache (statuscache.db)</h2>

<p>This database caches IMAP STATUS information resulting in less I/O
when the STATUS information hasn't changed (mailbox and \Seen state
unchanged).  The database is indexed by mailbox name + userid and each
data record contains the database version number, a bitmask of the
stored status items, the mtime, inode, and size of the cyrus.index
file at the time the record was written, the total number of messages
in the mailbox, the number of recent messages, the next UID value, the
mailbox UID validity value, the number of unseen messages, and the highest
modification sequence in the mailbox.  The format of each record is as
follows:</p>

<pre>
Key: &lt;Mailbox Name&gt;\0&lt;Userid&gt;\0

Data: &lt;Version&gt;SP&lt;Bitmask of Items&gt;SP&lt;Mtime of Index&gt;SP&lt;Inode of Index&gt;SP&lt;Size of Index&gt;SP&lt;# of Messages&gt;SP&lt;# of Recent Messages&gt;SP&lt;Next UID&gt;SP&lt;UID Validity&gt;SP&lt;# of Unseen Messages&gt;SP&lt;Highest Mod Sequence&gt;
</pre>

<h2>User Access (user_deny.db)</h2>

<p>This database contains a list of users that are denied access to
Cyrus services.  The database is indexed by userid and each data
record contains the database version number (currently 2), a list
of <a href="http://tools.ietf.org/html/rfc3977#section-4">wildmat</a>
patterns specifying Cyrus services to be denied, and a text message to
be displayed to the user upon denial.  The service names to
be matched are those as used  in <tt>cyrus.conf(5)</tt>.  The format
of each record is as follows:</p>

<pre>
Key: &lt;Userid&gt;

Data: &lt;Version&gt;TAB&lt;Deny List (comma-separated wildmat patterns)&gt;TAB&lt;Deny Message&gt;
</pre>

<h2>Timezone Info (zoneinfo.db)</h2>

<p>This database is used for the timezone service and contains records
  relating to timezones and their aliases.  The database is indexed by
  timezone ID and each data record contains the database version
  number, a record type, a timestamp, and an optional list of strings
  (either aliases for a timezone or the reference timezone for an
  alias).  The format of each record is as follows:</p>

<pre>
Key: &lt;TZID&gt;

Data: &lt;Version&gt;SP&lt;Record Type&gt;SP&lt;Timestamp&gt;SP&lt;Data Strings (TAB-separated)&gt;
</pre>

<h2>Seen State (&lt;userid&gt;.seen)</h2>

<p>This database is a per-user database and maintains the list of
messages that the user has read in each mailbox.  The database is
indexed by mailbox unique-id and each data record contains the
database version number, the timestamp of when a message was last
read, the message unique-id of the last read message, the timestamp of
the last record change and a list of message unique-ids which have
been read.  The format of each record is as follows:</p>

<pre>
Key: &lt;Mailbox UID&gt;

Data: &lt;Version&gt;SP&lt;Last Read Time&gt;SP&lt;Last Read UID&gt;SP&lt;Last Change Time&gt;SP&lt;List of Read UIDs&gt;
</pre>

<h2>Subscriptions (&lt;userid&gt;.sub)</h2>

<p>This database is per-user and contains the list of
mailboxes to which the user has subscribed.  The database is indexed
by mailbox name and each data record contains no data.  The format of
each record is follows:</p>

<pre>
Key: &lt;Mailbox Name&gt;

Data: None
</pre>


<h2>Mailbox Keys (&lt;userid&gt;.mboxkey)</h2>

<p>This database is per-user and contains the list of
mailbox access keys which are used for generating URLAUTH-authorized
URLs.  The database is indexed by mailbox name and each data record
contains the database version number and the associated access key.
The format of each record is follows:</p>

<pre>
Key: &lt;Mailbox Name&gt;

Data: &lt;Version (2 bytes)&gt;&lt;Access Key (multi-byte)&gt;
</pre>


<h2>DAV Index (&lt;userid&gt;.dav)</h2>

<p>This SQLite database is per-user and primarily maintains a
  mapping from DAV resource names (URLs) to the corresponding Cyrus
  mailboxes and IMAP message UIDs.  The database is designed to have
  one table per resource type (iCalendar, vCard, etc) with each table
  containing metadata specific to that resource type.</p>

<h3>CalDAV</h3>

<p>The format of the iCalendar table used by CalDAV is as follows:</p>

<pre>
CREATE TABLE ical_objs (
 rowid INTEGER PRIMARY KEY,
 creationdate INTEGER,
 mailbox TEXT NOT NULL,
 resource TEXT NOT NULL,
 imap_uid INTEGER,
 lock_token TEXT,
 lock_owner TEXT,
 lock_ownerid TEXT,
 lock_expire INTEGER,
 comp_type INTEGER,
 ical_uid TEXT,
 organizer TEXT,
 dtstart TEXT,
 dtend TEXT,
 comp_flags INTEGER,
 sched_tag TEXT,
 UNIQUE( mailbox, resource )
);
</pre>

<p>Because CalDAV Scheduling requires the server to locate a resource
  by iCalendar UID regardless of which calendar collection (mailbox)
  it resides in, the iCalendar table has an additional index as follows:</p>

<pre>
CREATE INDEX idx_ical_uid ON ical_objs ( ical_uid );
</pre>

<h3>CardDAV</h3>

<p>The format of the vCard table used by CardDAV is as follows (work
  in progress):</p>

<pre>
CREATE TABLE vcard_objs (
 rowid INTEGER PRIMARY KEY,
 creationdate INTEGER,
 mailbox TEXT NOT NULL,
 resource TEXT NOT NULL,
 imap_uid INTEGER,
 lock_token TEXT,
 lock_owner TEXT,
 lock_ownerid TEXT,
 lock_expire INTEGER,
 version INTEGER,
 vcard_uid TEXT,
 kind INTEGER,
 fullname TEXT,
 name TEXT,
 nickname TEXT,
 email TEXT,
 UNIQUE( mailbox, resource )
);
</pre>

</body>
</html>