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

DANGER

Never use os.exit() from a Lua script. This will cause the whole process to exit instead of just the script.

Initialization

When script is loaded, script_init() function is called, if found.

Changed: 2.4.0

script_init() return value is no longer checked. Use error() instead if necessary.

De-initialization

When script is being unloaded, script_deinit() function is called, if found.

C API

void dlua_dovecot_register(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

Base Functions

dovecot.i_debug()

Signature	dovecot.i_debug(text)
Arguments	Name Type Description text string Message to log.

Log debug level message.

dovecot.i_info()

Signature	dovecot.i_info(text)
Arguments	Name Type Description text string Message to log.

Log info level message.

dovecot.i_warning()

Signature	dovecot.i_warning(text)
Arguments	Name Type Description text string Message to log.

Log warning level message.

dovecot.i_error()

Signature	dovecot.i_error(text)
Arguments	Name Type Description text string Message to log.

Log error level message.

dovecot.event()

Signature	dovecot.event(parent)
Arguments	Name Type Description parent parent Use as parent event.

Generate new event. If parent is not specified, the lua script is used as the parent.

dovecot.restrict_global_variables()

Signature	dovecot.restrict_global_variables(toggle)
Arguments	Name Type Description toggle boolean Enable or disable defining new global variables.

Enable or disable restricting new global variables.

If enabled, the rest of the script won't be allowed to declare global non-function variables but they can declare local variables and use already defined global variables.

If a script needs to define a variable, they must declare them as local i.e. instead of my_var = "some value", do local my_var = "some value". Restrictions will remain in place until the end of the execution of the script or until they are lifted by calling dovecot.restrict_global_variables(false).

Default is permissive mode, i.e., same as lua's default, global variables are not restricted.

HTTP Functions

dovecot.http.client()

Signature	dovecot.http.client({ debug=boolean, no_auto_redirect=boolean, no_auto_retry=boolean, connect_backoff_time_msecs=int, connect_backoff_max_time_msecs=int, connect_timeout_msecs=int, event_parent=event, max_attempts=int, max_auto_retry_delay_secs=int, max_connect_attempts=int, max_idle_time_msecs=int, max_redirects=int, proxy_url=string, request_absolute_timeout_msecs=int, request_timeout_msecs=int, soft_connect_timeout_msecs=int, rawlog_dir=string, user_agent=string })
Arguments	Name Type Description debug boolean Enable debug logging. no_auto_redirect boolean Don't automatically act upon redirect responses. no_auto_retry boolean Never automatically retry requests. connect_backoff_time_msecs int Initial backoff time; doubled at each connection failure.(Default: 100 msec) connect_backoff_max_time_msecs int Maximum backoff time.(Default: 60000 msec) connect_timeout_msecs int Max time to wait for connect() (and SSL handshake) to finish before retrying.(Default: <request_timeout_msecs>) event_parent event Parent event to use. max_attempts int Maximum number of attempts for a request.(Default: 1) max_auto_retry_delay_secs int Maximum acceptable delay in seconds for automatically retrying/redirecting requests. If a server sends a response with a Retry-After header that causes a delay longer than this, the request is not automatically retried and the response is returned. max_connect_attempts int Maximum number of connection attempts to a host before all associated requests fail. If > 1, the maximum will be enforced across all IPs for that host, meaning that IPs may be tried more than once eventually if the number of IPs is smaller than the specified maximum attempts. If the number of IPs is higher than the maximum attempts, not all IPs are tried. If <= 1, all IPs are tried at most once. max_idle_time_msecs int Maximum time a connection will idle before disconnecting. If parallel connections are idle, the duplicates will end earlier based on how many idle connections exist to that same service. max_redirects int Maximum number of redirects for a request.(Default: 0; redirects refused) proxy_url string Proxy URL to use, can include username and password. request_absolute_timeout_msecs int Max total time to wait for HTTP request to finish, including retries and everything else.(Default: 0; no timeout) request_timeout_msecs int Max time to wait for HTTP response before retrying.(Default: 60000 msec) soft_connect_timeout_msecs int Time to wait for connect() (and SSL handshake) to finish for the first connection before trying the next IP in parallel.(Default: 0; wait until current connection attempt finishes) rawlog_dir string Directory for writing raw log data for debugging purposes. Must be writable by the process creating this log. user_agent string User-Agent: header.(Default: <none>)
Returns	An http_client object.

Create a new http client object that can be used to submit requests to remote servers.

Object http_client

http_client.request()

Signature	http_client.request({ url=string, method=string })
Arguments	Name Type Description url string Full url address. Parameters will be parsed from the string. TLS encryption is implied with use of https. method string HTTP method to use.
Returns	An http_request object.

Create a new request object.

By default, the request has Host, and Date headers with relevant values, as well as Connection: Keep-Alive.

Object http_request

http_request.add_header()

Signature	http_request.add_header(name, value)
Arguments	Name Type Description name string Name of the HTTP header. value string Value of the header.

Add a header to the request.

http_request.remove_header()

Signature	http_request.remove_header(name)
Arguments	Name Type Description name string Name of the HTTP header.

Do a lookup of the header in the request and remove it if found.

http_request.set_payload()

Signature	http_request.set_payload(value, synchronous)
Arguments	Name Type Description value string Payload of the request as string data. synchronous boolean Expect 100 Continue header before sending data. Defaults to false.

Set payload data to the request.

Optionally you can set synchronous, which will cause "100 Continue" header to be sent.

http_request.submit()

Signature	http_request.submit()
Returns	An http_response object.

Connect to the remote server and submit the request.

This function blocks until the HTTP response is fully received.

Object http_response

http_response.status()

Signature	http_response.status()
Returns	Status code of the http response.

Get the status code of the HTTP response.

The codes contain error codes as well as HTTP codes, e.g., '200 HTTP_OK' and error code that denote connection to remote server failed.

A human-readable string of the error can then be read using reason() function.

http_response.reason()

Signature	http_response.reason()
Returns	String representation of the status.

Returns a human-readable string of HTTP status codes, e.g. "OK", "Bad Request", "Service Unavailable", as well as connection errors, e.g., "connect(...) failed: Connection refused".

http_response.header()

Signature	http_response.header(name)
Arguments	Name Type Description name string Header to retrieve.
Returns	Value of the HTTP response header.

Get value of a header in the HTTP request.

If header is not found from the response, an empty string is returned.

http_response.payload()

Signature	http_response.payload()
Returns	Payload of the HTTP response as a string.

Get the payload of the HTTP response.

Example HTTP Client Code

local json = require "json"
local http_client = dovecot.http.client {
    timeout = 10000;
    max_attempts = 3;
    debug = true;
}

function auth_password_verify(request, password)
    local auth_request = http_client:request {
        url = "https://endpoint/";
        method = "POST";
    }
    local req = {user=request.user, password=password}
    auth_request:set_payload(json.encode(req))
    local auth_response = auth_request:submit()
    local resp_status = auth_response:status()

    if resp_status == 200
    then
        return dovecot.auth.PASSDB_RESULT_OK, ""
    else
        return dovecot.auth.PASSDB_RESULT_PASSWORD_MISMATCH, ""
    end
end

Object event

event.append_log_prefix()

Signature	event.append_log_prefix(prefix)
Arguments	Name Type Description prefix string Prefix to append.

Set prefix to append into log messages.

event.replace_log_prefix()

Signature	event.replace_log_prefix(prefix)
Arguments	Name Type Description prefix string Prefix to append.

Append prefix for log messages.

event.set_name()

Signature	event.set_name(name)
Arguments	Name Type Description name string Event name.

Set name for event.

event.add_str()

Signature	event.add_str(key, value)
Arguments	Name Type Description key string Key name. value string A value.

Add a key-value pair to event.

event.add_int()

Signature	event.add_int(key, value)
Arguments	Name Type Description key string Key name. value int Integer value.

Add a key-value pair to event.

event.add_timeval()

Signature	event.add_timeval(key, value)
Arguments	Name Type Description key string Key name. value int Unix timestamp.

Add a key-value pair to event.

event.inc_int()

Signature	event.inc_int(key, diff)
Arguments	Name Type Description key string Key name. diff int Difference to add. Can be negative.

Increment key-value pair.

event.log_debug()

Signature	event.log_debug(message)
Arguments	Name Type Description message string Message to log.

Emit debug message.

event.log_info()

Signature	event.log_info(message)
Arguments	Name Type Description message string Message to log.

Emit info message.

event.log_warning()

Signature	event.log_warning(message)
Arguments	Name Type Description message string Message to log.

Emit warning message.

event.log_error()

Signature	event.log_error(message)
Arguments	Name Type Description message string Message to log.

Emit error message.

event.passthrough_event()

Returns an passthrough event.

A log message must be logged or else a panic will occur.

Object event_passthrough

event_passthrough.append_log_prefix()

Signature	event_passthrough.append_log_prefix(prefix)
Arguments	Name Type Description prefix string Prefix to append.

Set prefix to append into log messages.

event_passthrough.replace_log_prefix()

Signature	event_passthrough.replace_log_prefix(prefix)
Arguments	Name Type Description prefix string Prefix to append.

Append prefix for log messages.

event_passthrough.set_name()

Signature	event_passthrough.set_name(name)
Arguments	Name Type Description name string Event name.

Set name for event.

event_passthrough.add_str()

Signature	event_passthrough.add_str(key, value)
Arguments	Name Type Description key string Key name. value string A value.

Add a key-value pair to event.

event_passthrough.add_int()

Signature	event_passthrough.add_int(key, value)
Arguments	Name Type Description key string Key name. value int Integer value.

Add a key-value pair to event.

event_passthrough.add_timeval()

Signature	event_passthrough.add_timeval(key, value)
Arguments	Name Type Description key string Key name. value int Unix timestamp.

Add a key-value pair to event.

event_passthrough.inc_int()

Signature	event_passthrough.inc_int(key, diff)
Arguments	Name Type Description key string Key name. diff int Difference to add. Can be negative.

Increment key-value pair.

event_passthrough.log_debug()

Signature	event_passthrough.log_debug(message)
Arguments	Name Type Description message string Message to log.

Emit debug message.

event_passthrough.log_info()

Signature	event_passthrough.log_info(message)
Arguments	Name Type Description message string Message to log.

Emit info message.

event_passthrough.log_warning()

Signature	event_passthrough.log_warning(message)
Arguments	Name Type Description message string Message to log.

Emit warning message.

event_passthrough.log_error()

Signature	event_passthrough.log_error(message)
Arguments	Name Type Description message string Message to log.

Emit error message.

Object dict

Note

Currently, this object cannot be created within the Lua code itself.

dict.lookup()

Signature	dict.lookup(key[, username])
Arguments	Name Type Description key string Key to lookup. username string Username for private dict keys.

Lookup key from dict. If key is found, returns a table with values.

If key is not found, returns nil.

dict.iterate()

Signature	dict.iterate(path, flags[, username])
Arguments	Name Type Description path string Path prefix to iterate. flags int Iteration flags. Currently raw numbers must be used for these. See enum dict_iterate_flags in the C code. username string Username for private dict paths.

Returns an iteration step function and dict iter userdata. For example:

for key, values in dict:iterate(key_prefix, 0) do
    dovecot.i_debug('key='..key..', first value='..values[1])
end

dict.transaction_begin()

Signature	dict.transaction_begin([username])
Arguments	Name Type Description username string Username for private dict keys.

Returns a new transaction object.

Object dict.transaction

dict.transaction.set()

Signature	dict.transaction.set(key, value)
Arguments	Name Type Description key string Key to set. value string Value to set.

Set key=value in the dict transaction.

dict.transaction.unset()

Signature	dict.transaction.unset(key)
Arguments	Name Type Description key string Key to unset.

Unset key in the dict transaction.

dict.transaction.set_timestamp()

Signature	dict.transaction.set_timestamp({ seconds=int, nanoseconds=int })
Arguments	Name Type Description seconds int UNIX timestamp. nanoseconds int Nanoseconds part of the timestamp.

Set timestamp to the dict transaction.

This is currently used only with Cassandra.

dict.transaction.commit()

Commit the transaction.

dict.transaction.rollback()

Rollback the transaction.

Object dns_client

Added: 2.4.0

Note

Currently, this object cannot be created within the Lua code itself.

dns_client.lookup()

Signature	dns_client.lookup(hostname[, event])
Arguments	Name Type Description hostname string Hostname to lookup. event event Event to use for logging.
Returns	On succesful DNS lookup, returns a table with IP addresses (which has at least one IP). On failure, returns nil, error string, net_gethosterror() compatible error code (similar to e.g. Lua io.* calls).

Lookup hostname asynchronously via dns-client process.