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

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)

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

dlua_register_mail_storage(script)

Register storage Lua interface to script context

Parameters:
  • script – dlua_script to add mail storage
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.

Parameters:
  • user – mail_user
  • script – dlua_script
dlua_push_mail_user(script, user)

Pushes a mail user on top of stack.

Parameters:
  • script – dlua_script
  • user – mail_user
dlua_push_mailbox(script, box)

Pushes a mailbox on top of stack.

Parameters:
  • script – dlua_script
  • box – mailbox
dlua_push_mail(script, mail)

Pushes a mail on top of stack.

Parameters:
  • script – dlua_script
  • box – mail

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
MAILBOX_ATTRIBUTE_PREFIX_DOVECOT

String constant vendor/vendor.dovecot/

New in version 2.3.7.

MAILBOX_ATTRIBUTE_PREFIX_DOVECOT_PVT

String constant vendor/vendor.dovecot/pvt/

New in version 2.3.7.

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

plugin_getenv(key)

Returns key from user plugin settings or userdb environment

Parameters:key (str) – Setting name
var_expand(template)

Expands mail user variables (see Variables )

Parameters:template (str) – Variable template string
mailbox(name, flags)

Allocates a mailbox, flags optional

Parameters:
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.

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.

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.

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

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

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)

Parameters:flags (int) – See dovecot.storage
status(item, item, item...)

Returns requested mailbox status items as table

Parameters:item (str) – Item name
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.

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.

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.

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

vname

Full mailbox name

Mailbox 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)