Dovecot Dict Protocol

INFO

This document describes Dovecot Dict protocol v3.2 which is supported in Dovecot v2.3.17+.

Changed: 3.0.0 Dict protocol version was updated to v4, but it's otherwise compatible with v3.2.

Dovecot's dict protocol is a line based protocol between the dict client and server processes. The dict server receives lines containing commands and responds to the client with results. Each line ends with an LF character and the maximum line the client is allowed to send a command is 65536 (64KB of data). There is no maximum length enforced for dict server's response.

Each command is in format:

<command short name><parameters separated with TAB>

The command short name is a single character and the rest of the line containing the command parameters are followed immediately without any whitespace in between.

Commands available in dict protocol and their corresponding short name:

Command	Command Short Name
HELLO	H
LOOKUP	L
ITERATE	I
BEGIN	B
COMMIT	C
ROLLBACK	R
SET	S
UNSET	U
ATOMIC_INC	A
TIMESTAMP	T

The reply from dict server is in the same format.

<result short status>(<optional extra values separated with TAB>)

Result statuses relevant for each command and their corresponding short name explained in each command section.

Command parameters and extra result values are tab-escaped using the dovecot's generic tab-escaping. Escaping is described in more details in auth protocol.

After responses to certain commands, an execution duration summary line is also sent to the client containing timestamp information about how long the command took to finish. The commands that trigger this timestamp response are LOOKUP, ITERATE, and COMMIT. Format of this line is as follows:

TAB<start sec>TAB<start usec>TAB<end sec>TAB<end usec>

Where the unix timestamp is <sec>.<usec> for each pair.

The connection starts by the client sending a HELLO message. The message contains the initial handshake information.

C: H<major>TAB<minor>TAB<value type>TAB<obsolete user>TAB<dict name>

INFO

Prior to Dovecot v2.3.17, user was included in the initial handshake but it's currently not used and the field is empty.

The server then checks client's protocol version and can either accept the handshake and proceed to response with OK or reject the HELLO and close the connection.

If the handshake is accepted by server, the optional extra values in the response line contain server's major and minor protocol versions (tab separated). The client also checks the protocol version and can decide to close the connection if versions do not match.

Currently, Dovecot's client and server check that they support the same major version number. Minor version can be ignored.

Other dict commands and their line format is described as follows.

INFO

Prior to Dovecot v2.3.17 none of the following commands included the username for which the dict operation is performed. Instead, the username from the initial handshake message was used.

LOOKUP Command

Used to lookup a key value from dict.

C: L<key>TAB<user>

Result Status	Status Short Name	Description
OK	O	Lookup was performed successfully and there was a single value for the key. Value is then appended to the response line.
MULTI_OK	M	Lookup was performed successfully and there were multiple values for the key. In this case all results are joined together with a tab and then double-escaped so the end result looks like a single value. Client would then need to unescape twice to get the list of values separated by tabs.
NOTFOUND	N	Lookup was performed successfully but no value was found with this key.
FAIL	F	Lookup failed due to an error. A tab-escaped error string is appended to the response line.

ITERATE Command

Used to iterate over a key path.

C: I<flags>TAB<max rows>TAB<path>TAB<user>

The iteration flag is a integer with following options, which can be ORed together.

Flag	Value	Description
RECURSE	0x01	Recurse to all the sub-hierarchies
SORT_BY_KEY	0x02	Sort returned results by key
SORT_BY_VALUE	0x04	Sort returned results by value
NO_VALUE	0x08	Don't return values, only keys
EXACT_KEY	0x10	Don't recurse at all. This is basically the same as LOOKUP command but it will return all of the rows instead of only the first one.
FLAG_ASYNC	0x20	Perform iteration asynchronously

Possible responses include:

Result Status	Status Short Name	Description
OK	O	Iteration was done successfully. Note that for each key-value pair A separate OK status is appended to the response line with the key following immediately and all values associated to it joined with tabs.
FAIL	F	Iteration failed due to an error. A tab-escaped error string is appended to the response line.
ITER_FINISHED	<empty line>	Iteration completed. This is sent after all key value pairs are added to the response.

BEGIN Command

Begins a dict transaction with the given ID.

C: B<id>TAB<user>

Note that transactions commands don't have replies with the exception of COMMIT. After a transaction is successfully started, transaction operations i.e. SET, UNSET, ATOMIC_INC, and TIMESTAMP can be used.

COMMIT Command

Commit the transaction corresponding to the given ID.

C: C<transaction id>

Note that the transaction is looked up from the ID so no username is required.

Possible responses include:

Result Status	Status Short Name	Description
OK	O	Commit was done successfully and all transaction operations completed.
NOTFOUND	N	Transaction ID specified in the commit was not found.
WRITE_UNCERTAIN	W	The transaction may or may not have succeeded (e.g. a write timeout occurred or the connection to dict backend was closed by the backend server). A tab-escaped error string is appended to the response line.
FAIL	F	Iteration failed due to an error. A tab-escaped error string is appended to the response line.

ROLLBACK Command

Rollback changes made in the transaction.

C: R<transaction id>

SET Command

Set a value for the given key.

C: S<transaction id>TAB<key>TAB<value>

UNSET Command

Unset a record in the dictionary given the key.

C: U<transaction id>TAB<key>

ATOMIC_INC Command

Atomically increment numeric value of a key with the given increment value. Note that the value is changed when transaction is being committed, so it's not known beforehand what the value will become. The value is updated only if it already exists.

C: A<transaction id>TAB<key>TAB<increment>

TIMESTAMP Command

Set the unix timestamp for the given transaction. Note that this will set the timestamp for the entire transaction. This must be set before any changes are done and can't be changed afterwards. Currently only dict-sql with Cassandra backend does anything with this.

C: T<transaction id>TAB<sec>TAB<nsec>