This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.
Differences between revisions 18 and 19
Revision 18 as of 2018-11-27 06:54:06
Size: 6727
Comment: Change upcoming v2.3.4 to since v2.3.4
Revision 19 as of 2021-07-21 20:38:37
Size: 52
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= Dovecot Lua support =
Since v2.3.0 dovecot supports Lua scripting. Dovecot supports lua 5.0 or newer. See also:

 * [[AuthDatabase/Lua|Lua based authentication]]. Since v2.3.0
 * [[Plugins/PushNotification#lua|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)
Moved to https://doc.dovecot.org/admin_manual/lua/

None: Design/Lua (last edited 2021-07-21 20:38:37 by MichaelSlusarz)