Dovecot Lua support

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

See also:

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

void dlua_register_dovecot(struct dlua_script *script)

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

void dlua_push_event(struct event *event)

Pushes an Dovecot Event to stack.

Lua API

i_debug(text)

Log debug level message

Parameters

text (str) – Message to log

i_info(text)

Log info level message

Parameters

text (str) – Message to log

i_warning(text)

Log warning level message

Parameters

text (str) – Message to log

i_error(text)

Log error level message

Parameters

text (str) – Message to log

Event functions are available from

New in version v2.3.4.

dovecot.event()

Generate new event with lua script as parent.

dovecot.event(parent)

Generate new event with given parent event.

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 into log messages

Parameters

prefix (str) – Prefix to append

replace_log_prefix(prefix)

replace append prefix for messages

Parameters

prefix (str) – Prefix to append

set_name(name)

set name for event

Parameters

name (str) – Event name

add_str(key, value)

Add a key-value pair to event

Parameters
  • key (str) – Key name

  • value (str) – A value

add_int(key, value)

Add a key-value pair to event

Parameters
  • key (str) – Key name

  • value (int) – Integer value

add_timeval(key, seconds)

add a key-value pair to event

Parameters
  • key (str) – Key name

  • value (int) – Unix timestamp

inc_int(key, diff)

increment key-value pair

Parameters
  • key (str) – Key name

  • diff (int) – Difference to add, can be negative

log_debug(message)

Emit debug message

Parameters

message (str) – Message to log

log_info(message)

Emit info message

Parameters

message (str) – Message to log

log_warning(message)

Emit warning message

Parameters

message (str) – Message to log

log_error("message")

Emit error message

Parameters

message (str) – Message to log

passthrough_event()

Returns an passthrough event. A log message must be logged or else a panic will occur.

mail-lua

New in version v2.3.4.

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

void dlua_register_mail_storage(struct dlua_script *script)

Register storage Lua interface to script context

Parameters
  • scriptdlua_script to add mail storage

bool mail_lua_plugin_get_script(struct mail_user *user, struct dlua_script **script_r)

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

Parameters
  • usermail_user

  • scriptdlua_script

void dlua_push_mail_user(struct dlua_script *script, struct mail_user *user)

Pushes a mail user on top of stack.

Parameters
  • scriptdlua_script

  • usermail_user

void dlua_push_mailbox(struct dlua_script *script, struct mailbox *box)

Pushes a mailbox on top of stack.

Parameters
  • scriptdlua_script

  • boxmailbox

void dlua_push_mail(struct dlua_script *script, struct mail *mail)

Pushes a mail on top of stack.

Parameters
  • scriptdlua_script

  • boxmail

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:

enum STATUS_MESSAGES
enum STATUS_RECENT
enum STATUS_UIDNEXT
enum STATUS_UIDVALIDITY
enum STATUS_UNSEEN
enum STATUS_FIRST_UNSEEN_SEQ
enum STATUS_KEYWORDS
enum STATUS_HIGHESTMODSEQ
enum STATUS_PERMANENT_FLAGS
enum STATUS_FIRST_RECENT_UID
enum STATUS_HIGHESTPVTMODSEQ
enum MAILBOX_FLAG_READONLY
enum MAILBOX_FLAG_SAVEONLY
enum MAILBOX_FLAG_DROP_RECENT
enum MAILBOX_FLAG_NO_INDEX_FILES
enum MAILBOX_FLAG_KEEP_LOCKED
enum MAILBOX_FLAG_IGNORE_ACLS
enum MAILBOX_FLAG_AUTO_CREATE
enum MAILBOX_FLAG_AUTO_SUBSCRIBE
enum MAILBOX_SYNC_FLAG_FULL_READ
enum MAILBOX_SYNC_FLAG_FULL_WRITE
enum MAILBOX_SYNC_FLAG_FAST
enum MAILBOX_SYNC_FLAG_NO_EXPUNGES
enum MAILBOX_SYNC_FLAG_FIX_INCONSISTENT
enum MAILBOX_SYNC_FLAG_EXPUNGE
enum MAILBOX_SYNC_FLAG_FORCE_RESYNC
enum MAILBOX_ATTRIBUTE_PREFIX_DOVECOT

String constant vendor/vendor.dovecot/

New in version 2.3.7.

enum MAILBOX_ATTRIBUTE_PREFIX_DOVECOT_PVT

String constant vendor/vendor.dovecot/pvt/

New in version 2.3.7.

enum MAILBOX_ATTRIBUTE_PREFIX_DOVECOT_PVT_SERVER

String constant vendor/vendor.dovecot/pvt/server/

New in version 2.3.7.

object mail_user

Meta

  • has tostring

  • is comparable (by username)

Functions

mail_user.plugin_getenv(key)

Returns key from user plugin settings or userdb environment

Parameters

key (str) – Setting name

mail_user.var_expand(template)

Expands mail user variables (see Variables )

Parameters

template (str) – Variable template string

mail_user.mailbox(name, flags)

Allocates a mailbox, flags optional

Parameters
mail_user.metadata_get(key)

Returns given metadata key for the user.

Parameters

key (str) – Metadata key, must begin with /private/ or /shared/

New in version 2.3.7.

mail_user.metadata_set(key, value)

Sets user metadata key to value. Setting value to nil unsets value.

Parameters
  • key (str) – Metadata key, must begin with /private/ or /shared/

  • value (str) – Value to set, nil unsets value

New in version 2.3.7.

mail_user.metadata_unset(key)

Unsets value, same as calling metadata_set() with nil.

Parameters

key (str) – Metadata key, must begin with /private/ or /shared/

New in version 2.3.7.

mail_user.metadata_list(prefix, prefix, prefix...)

Lists all keys for the user metadata under prefix.

Parameters

prefix (str) – Metadata prefix, must begin with /private/ or /shared/

New in version 2.3.7.

Variables

mail_user.home

home directory (if available)

mail_user.username

user’s name

mail_user.uid

system uid

mail_user.gid

system gid

mail_user.service

IMAP/POP3/LMTP/LDA/…

mail_user.session_id

Current session ID

mail_user.session_create_time

When session was created

mail_user.nonexistent

If user does not really exist

mail_user.anonymous

If user is anonymous

mail_user.autocreated

If user was automatically created internally for some operation

mail_user.mail_debug

If debugging is turned on

mail_user.dsyncing

If user is being dsync’d

mail_user.session_restored

If this is a restored session

object mailbox

Meta

  • has tostring

  • is comparable (by full mailbox name)

Functions

mailbox.open()

Opens the mailbox

mailbox.close()

Closes the mailbox

mailbox.free()

Releases mailbox (must be done)

mailbox.sync(flags)

Synchronizes the mailbox (should usually be done, flags optional)

Parameters

flags (int) – See dovecot.storage

mailbox.status(item, item, item...)

Returns requested mailbox status items as table

Parameters

item (str) – Item name

mailbox.metadata_get(key)

Returns given metadata key for the mailbox.

Parameters

key (str) – Metadata key, must begin with /private/ or /shared/

New in version 2.3.7.

mailbox.metadata_set(key, value)

Sets mailbox metadata key to value. Setting value to nil unsets value.

Parameters
  • key (str) – Metadata key, must begin with /private/ or /shared/

  • value (str) – Value to set, nil unsets value

New in version 2.3.7.

mailbox.metadata_unset(key)

Unsets value, same as calling metadata_set() with nil.

Parameters

key (str) – Metadata key, must begin with /private/ or /shared/

New in version 2.3.7.

mailbox.metadata_list(prefix, prefix, prefix...)

Lists all keys for the mailbox metadata under prefix.

Parameters

prefix (str) – Metadata prefix, must begin with /private/ or /shared/

New in version 2.3.7.

Variables

mailbox.vname

Full mailbox name

Mailbox name

Mailbox name

table mailbox status

Variables

mailbox_status.mailbox

full name of mailbox

mailbox_status.messages

number of messages

mailbox_status.recent

number of Recent messages

mailbox_status.unseen

number of Unseen messages

mailbox_status.uidvalidity

current UID validity

mailbox_status.uidnext

next UID

mailbox_status.first_unseen_seq

first seqno of unseen mail

mailbox_status.first_recent_uid

first UID of unseen mail

mailbox_status.highest_modseq

highest modification sequence

mailbox_status.highest_pvt_modseq

highest private modification sequence

mailbox_status.permanent_flags

supported permanent flags as a bitmask

mailbox_status.flags

supported flags as a bitmask

mailbox_status.permanent_keywords

if permanent keywords are supported

mailbox_status.allow_new_keywords

if new keywords can be added

mailbox_status.nonpermanent_modseqs

whether non-permanent keywords are allowed

mailbox_status.no_modseq_tracking

no modification sequence tracking

mailbox_status.have_guids

whether GUIDs exist

mailbox_status.have_save_guids

whether GUIDs can be saved

mailbox_status.have_only_guid128

whether GUIDs are 128 bit always

mailbox_status.keywords

table of current keywords

object mail

Meta

  • has tostring

  • is comparable (within same mailbox, by UID)

Functions

None yet

Variables

mailbox_status.mailbox

mailbox object

mailbox_status.seq

Sequence number (can change)

mailbox_status.uid

UID number (immutable)