• Design
• Lua

Dovecot Lua support

Since v2.3.0 dovecot supports Lua scripting. Dovecot supports lua 5.0 or newer. See also:

• Lua based authentication. Since v2.3.0

• Lua push notifications. Since v2.3.4

lib-lua

Dovecot provides a lib-lua internal helper as part of libdovecot.so. It has facilities for loading scripts from various sources, and also helps with reusing scripts by keeping track of which scripts are loaded. Each script has it's own memory pool, which is guaranteed to be released when script is unloaded.

When script is loaded, script_load function is called if found. This can return non-zero to indicate that the script has a problem.

C API

• dlua_register_dovecot(script)

Register dovecot variable. This item can also be extended by context specific tables, like authentication database adds dovecot.auth.

• dlua_push_event(event)

Pushes an Dovecot Event to stack.

Lua API

• i_debug(text)

• i_error(text)

• i_info(text)

• i_warning(text)

Functions within dovecot variable that do generic logging

Event functions are available from v2.3.4 on

• dovecot.event()

• dovecot.event(parent)

Creates a new event for dovecot

object event

Note:

• object event_passthrough has same API, except the passthrough_event method is not present.

Functions:

• append_log_prefix("prefix") - set prefix to append

• replace_log_prefix("prefix") - replace append prefix

• set_name("name") - set name for event

• add_str("key","value") - add a key-value pair to event

• add_int("key",1) - add a key-value pair to event

• add_timeval("key",seconds) - add a key-value pair to event

• inc_int("key",1) - increment key-value pair

• log_debug("message") - emit debug message

• log_info("message") - emit info message

• log_warning("message") - emit warning message

• log_error("message") - emit error message

• passthrough_event() - returns an passthrough event. A log message *must be* logged or else a panic will occur.

mail-lua

Available from v2.3.4 on

mail-lua is a plugin that can be loaded to provide API for mail storage Lua plugins. Mail-lua provides a common script to be used in mail storage instead of per-plugin scripts.

C API

• dlua_register_mail_storage(script)

Register storage Lua interface to script context

• bool mail_lua_plugin_get_script(user, script_r)

Returns script context if available. If FALSE is returned, no Lua script has been loaded, and you should optionally deal this yourself.

• dlua_push_mail_user(script, user)

Pushes a mail user on top of stack.

• dlua_push_mailbox(script, box)

Pushes a mailbox on top of stack.

• dlua_push_mail(script, mail)

Pushes a mail on top of stack.

Lua API

When mail user is created, a script is loaded if present as mail_lua_script and mail_user_created is called if present in script.

On deinitialization, mail_user_deinit_pre is called first, if present, followed by mail_user_deinit.

dovecot.storage

Following constants are specified

• STATUS_MESSAGES

• STATUS_RECENT

• STATUS_UIDNEXT

• STATUS_UIDVALIDITY

• STATUS_UNSEEN

• STATUS_FIRST_UNSEEN_SEQ

• STATUS_KEYWORDS

• STATUS_HIGHESTMODSEQ

• STATUS_PERMANENT_FLAGS

• STATUS_FIRST_RECENT_UID

• STATUS_HIGHESTPVTMODSEQ

• MAILBOX_FLAG_READONLY

• MAILBOX_FLAG_SAVEONLY

• MAILBOX_FLAG_DROP_RECENT

• MAILBOX_FLAG_NO_INDEX_FILES

• MAILBOX_FLAG_KEEP_LOCKED

• MAILBOX_FLAG_IGNORE_ACLS

• MAILBOX_FLAG_AUTO_CREATE

• MAILBOX_FLAG_AUTO_SUBSCRIBE

• MAILBOX_SYNC_FLAG_FULL_READ

• MAILBOX_SYNC_FLAG_FULL_WRITE

• MAILBOX_SYNC_FLAG_FAST

• MAILBOX_SYNC_FLAG_NO_EXPUNGES

• MAILBOX_SYNC_FLAG_FIX_INCONSISTENT

• MAILBOX_SYNC_FLAG_EXPUNGE

• MAILBOX_SYNC_FLAG_FORCE_RESYNC

object mail_user

Meta:

• has tostring
• is comparable (by username)

Functions:

• plugin_getenv(key) - returns key from user plugin settings or userdb environment

• var_expand(template) - expands mail user variables (see Variables)

• mailbox(name, flags) - allocates a mailbox, flags optional

Variables:

• home - home directory (if available)

• username - user's name

• uid - system uid

• gid - system gid

• service - IMAP/POP3/LMTP/LDA/...

• session_id - Current session ID

• session_create_time - When session was created

• nonexistent - If user does not really exist

• anonymous - If user is anonymous

• autocreated - If user was automatically created internally for some operation

• mail_debug - If debugging is turned on

• fuzzy_search - FIXME: Undocumented

• dsyncing - If user is being dsync'd

• session_restored - If this is a restored session

object mailbox

Meta:

• has tostring
• is comparable (by full mailbox name)

Functions:

• open() - opens the mailbox

• close() - closes the mailbox

• free() - releases mailbox (must be done)

• sync(flags) - synchronizes the mailbox (should usually be done, flags optional)

• status(item,item,item...) - returns requested mailbox status items as table

Variables:

• vname - Full mailbox name

• name - Mailbox name

table mailbox status

Variables:

• mailbox - full name of mailbox

• messages - number of messages

• recent - number of \Recent messages

• unseen - number of \Unseen messages

• uidvalidity - current UID validity

• uidnext - next UID

• first_unseen_seq - first seqno of unseen mail

• first_recent_uid - first UID of unseen mail

• highest_modseq - highest modification sequence

• highest_pvt_modseq - highest private modification sequence

• permanent_flags - supported permanent flags as a bitmask

• flags - supported flags as a bitmask

• permanent_keywords - if permanent keywords are supported

• allow_new_keywords - if new keywords can be added

• nonpermanent_modseqs - whether non-permanent keywords are allowed

• no_modseq_tracking - no modification sequence tracking

• have_guids - whether GUIDs exist

• have_save_guids - whether GUIDs can be saved

• have_only_guid128 - whether GUIDs are 128 bit always

• keywords - table of current keywords

object mail

Meta:

• has tostring
• is comparable (within same mailbox, by UID)

Functions:

• None yet

Variables:

• mailbox - mailbox object

• seq - Sequence number (can change)

• uid - UID number (immutable)