Module rspamd_config

This module is used to configure rspamd and is normally available as global variable named rspamd_config. Unlike other modules, it is not necessary to require it before usage.

Example:

-- Register some callback symbol
local function foo(task)
    -- do something
end
rspamd_config:register_symbol('SYMBOL', 1.0, foo)

-- Get configuration
local tab = rspamd_config:get_all_opt('module') -- get table for module's options
local opts = rspamd_config:get_key('options') -- get content of the specified key in rspamd configuration

Brief content:

Methods:

rspamd_config:get_module_opt(mname, optname)

rspamd_config:get_all_opt(mname)

rspamd_config:get_ucl()

rspamd_config:get_mempool()

rspamd_config:get_resolver()

rspamd_config:add_radix_map(mapline[, description])

rspamd_config:radix_from_config(mname, optname)

rspamd_config:add_hash_map(mapline[, description])

rspamd_config:add_kv_map(mapline[, description])

rspamd_config:add_map({args})

rspamd_config:get_classifier(name)

rspamd_config:register_symbol(table)

rspamd_config:register_symbols(callback, [weight], callback_name, [, symbol, ...])

rspamd_config:register_virtual_symbol(name, weight,)

rspamd_config:register_callback_symbol(name, weight, callback)

rspamd_config:register_dependency(id, dep)

rspamd_config:register_pre_filter(callback[, order])

rspamd_config:register_post_filter(callback[, order])

rspamd_config:get_key(name)

rspamd_config:add_condition(symbol, condition)

rspamd_config:enable_symbol(symbol)

rspamd_config:disable_symbol(symbol)

rspamd_config:__newindex(name, callback)

rspamd_config:register_regexp(params)

rspamd_config:replace_regexp(params)

rspamd_config:register_worker_script(worker_type, script)

rspamd_config:add_on_load(function(cfg, ev_base) ... end)

rspamd_config:add_periodic(event_base, timeout, function(cfg, ev_base) ... end, [jitter = false])

rspamd_config:get_symbols_count()

rspamd_config:get_symbols_cksum()

rspamd_config:get_symbol_callback(name)

rspamd_config:get_symbol_stat(name)

rspamd_config:set_symbol_callback(name, callback)

rspamd_config:register_finish_script(callback)

rspamd_config:register_monitored(url, type, [{params}])

rspamd_config:add_doc(path, option, doc_string, [{params}])

rspamd_config:add_example(path, option, doc_string, example)

rspamd_config:set_peak_cb(function)

rspamd_config:get_cpu_flags()

Methods

The module rspamd_config defines the following methods.

Method rspamd_config:get_module_opt(mname, optname)

Returns value of specified option optname for a module mname,

Parameters:

• mname {string}: name of module
• optname {string}: option to get

Returns:

• {string or table}: value of the option or nil if option is not found

Back to module description.

Method rspamd_config:get_all_opt(mname)

Returns value of all options for a module mname, flattening values into a single table consisting of all sections with such a name.

Parameters:

• mname {string}: name of module

Returns:

• {table}: table of all options for mname or nil if a module’s configuration is not found

Back to module description.

Method rspamd_config:get_ucl()

Returns full configuration as a native Lua object (ucl to lua conversion). This method uses caching if possible.

Parameters:

No parameters

Returns:

• {table}: table of all options in the configuration

Back to module description.

Method rspamd_config:get_mempool()

Returns static configuration memory pool.

Parameters:

No parameters

Returns:

• {mempool}: memory pool object

Back to module description.

Method rspamd_config:get_resolver()

Returns DNS resolver.

Parameters:

No parameters

Returns:

• {dns_resolver}: opaque DNS resolver pointer if any

Back to module description.

Method rspamd_config:add_radix_map(mapline[, description])

Creates new dynamic map of IP/mask addresses.

Parameters:

• mapline {string}: URL for a map
• description {string}: optional map description

Returns:

• {map}: radix tree object

Example:

local ip_map = rspamd_config:add_radix_map ('file:///path/to/file', 'my radix map')
...
local function foo(task)
	local ip = task:get_from_ip()
	if ip_map:get_key(ip) then
		return true
	end
	return false
end

Back to module description.

Method rspamd_config:radix_from_config(mname, optname)

Creates new embedded map of IP/mask addresses from config.

Parameters:

• mname {string}: name of module
• optname {string}: option to get

Returns:

• {map}: radix tree object

Example:

local ip_map = rspamd_config:radix_from_config ('mymodule', 'ips')
...
local function foo(task)
	local ip = task:get_from_ip()
	if ip_map:get_key(ip) then
		return true
	end
	return false
end

Back to module description.

Method rspamd_config:add_hash_map(mapline[, description])

Creates new dynamic map string objects.

Parameters:

• mapline {string}: URL for a map
• description {string}: optional map description

Returns:

• {map}: hash set object

Example:

local hash_map = rspamd_config:add_hash_map ('file:///path/to/file', 'my hash map')
...
local function foo(task)
	local from = task:get_from()
	if hash_map:get_key(from['user']) then
		return true
	end
	return false
end

Back to module description.

Method rspamd_config:add_kv_map(mapline[, description])

Creates new dynamic map of key/values associations.

Parameters:

• mapline {string}: URL for a map
• description {string}: optional map description

Returns:

• {map}: hash table object

Example:

local kv_map = rspamd_config:add_kv_map ('file:///path/to/file', 'my kv map')
...
local function foo(task)
	local from = task:get_from()
	if from then
		local value = kv_map:get_key(from['user'])
		if value then
			return true,value
		end
	end
	return false
end

Back to module description.

Method rspamd_config:add_map({args})

Creates new dynamic map according to the attributes passed.

• type: type of map to be created, can be one of the following set:
• set: set of strings
• radix: map of IP addresses to strings
• map: map of strings to strings
• regexp: map of regexps to strings
• callback: map processed by lua callback
• url: url to load map from
• description: map’s description
• callback: lua callback for the map

Parameters:

No parameters

Returns:

• {map}: true if map has been added

Example:

local str = ''
local function process_map(in)
	str = in
end

rspamd_config:add_map('http://example.com/map', "settings map", process_map)

Back to module description.

Method rspamd_config:get_classifier(name)

Returns classifier config.

Parameters:

• name {string}: name of classifier (e.g. bayes)

Returns:

• {classifier}: classifier object or nil

Back to module description.

Method rspamd_config:register_symbol(table)

Register symbol of a specified type in rspamd. This function accepts table of arguments:

• name: name of symbol (can be missing for callback symbols)
• callback: function to be called for symbol’s check (can be absent for virtual symbols)
• weight: weight of symbol (should normally be 1 or missing)
• priority: priority of symbol (normally 0 or missing)
• type: type of symbol: normal (default), virtual or callback
• flags: various flags split by commas or spaces:
• nice if symbol can produce negative score;
• empty if symbol can be called for empty messages
• skip if symbol should be skipped now
• nostat if symbol should be excluded from stat tokens
• parent: id of parent symbol (useful for virtual symbols)

Parameters:

No parameters

Returns:

• {number}: id of symbol registered

Back to module description.

Method rspamd_config:register_symbols(callback, [weight], callback_name, [, symbol, ...])

Register callback function to be called for a set of symbols with initial weight.

Parameters:

• callback {function}: callback function to be called for a specified symbol
• weight {number}: initial weight of symbol (can be less than zero to specify non-spam symbols)
• callback_name {string}: symbolic name of callback
• symbol {list of strings}: list of symbols registered by this function

Returns:

No return

Back to module description.

Method rspamd_config:register_virtual_symbol(name, weight,)

Register virtual symbol that is not associated with any callback.

**This method is deprecated and should not be used in newly written code **

Parameters:

• virtual {string}: name symbol’s name
• weight {number}: initial weight of symbol (can be less than zero to specify non-spam symbols)

Returns:

No return

Back to module description.

Method rspamd_config:register_callback_symbol(name, weight, callback)

Register callback function to be called for a specified symbol with initial weight. Symbol itself is not registered in the metric and is not intended to be visible by a user.

**This method is deprecated and should not be used in newly written code **

Parameters:

• name {string}: symbol’s name (just for unique id purposes)
• weight {number}: initial weight of symbol (can be less than zero to specify non-spam symbols)
• callback {function}: callback function to be called for a specified symbol

Returns:

No return

Back to module description.

Method rspamd_config:register_dependency(id, dep)

Create a dependency between symbol identified by id and a symbol identified by some symbolic name dep

Parameters:

• id {number|string}: id or name of source (numeric id is returned by all register_*_symbol)
• dep {string}: dependency name

Returns:

No return

Example:

local function cb(task)
...
end

local id = rspamd_config:register_symbol('SYM', 1.0, cb)
rspamd_config:register_dependency(id, 'OTHER_SYM')
-- Alternative form
rspamd_config:register_dependency('SYMBOL_FROM', 'SYMBOL_TO')

Back to module description.

Method rspamd_config:register_pre_filter(callback[, order])

Register function to be called prior to symbols processing.

Parameters:

• callback {function}: callback function
• order {number}: filters are called from lower orders to higher orders, order is equal to 0 by default

Returns:

No return

Example:

local function check_function(task)
	-- It is possible to manipulate the task object here: set settings, set pre-action and so on
	...
end

rspamd_config:register_pre_filter(check_function)

Back to module description.

Method rspamd_config:register_post_filter(callback[, order])

Register function to be called after symbols are processed.

Parameters:

• callback {function}: callback function
• order {number}: filters are called from lower orders to higher orders, order is equal to 0 by default

Returns:

No return

Back to module description.

Method rspamd_config:get_key(name)

Returns configuration section with the specified name.

Parameters:

• name {string}: name of config section

Returns:

• {variant}: specific value of section

Example:

local set_section = rspamd_config:get_key("settings")
if type(set_section) == "string" then
  -- Just a map of ucl
  if rspamd_config:add_map(set_section, "settings map", process_settings_map) then
    rspamd_config:register_pre_filter(check_settings)
  end
elseif type(set_section) == "table" then
  if process_settings_table(set_section) then
    rspamd_config:register_pre_filter(check_settings)
  end
end

Back to module description.

Method rspamd_config:add_condition(symbol, condition)

Adds condition callback for specified symbol

Parameters:

• symbol {string}: symbol’s name
• condition {function}: condition callback

Returns:

• {boolean}: true if condition has been added

Example:

rspamd_config:add_condition('FUZZY_DENIED', function(task)
  if some_map:find_key(task:get_from()) then return false end
  return true
end)

Back to module description.

Method rspamd_config:enable_symbol(symbol)

Enables execution for the specified symbol

Parameters:

• symbol {string}: symbol’s name

Returns:

No return

Back to module description.

Method rspamd_config:disable_symbol(symbol)

Disables execution for the specified symbol

Parameters:

• symbol {string}: symbol’s name

Returns:

No return

Back to module description.

Method rspamd_config:__newindex(name, callback)

This metamethod is called if new indicies are added to the rspamd_config object. Technically, it is the equivalent of rspamd_config:register_symbol where weight is 1.0. There is also table form invocation that allows to control more things:

• callback: has the same meaning and acts as function of task
• score: default score for a symbol
• group: default group for a symbol
• description: default symbol’s description
• priority: additional priority value
• one_shot: default value for one shot attribute
• condition: function of task that can enable or disable this specific rule’s execution

Parameters:

• name {string}: index name
• callback {function/table}: callback to be called

Returns:

• {number}: id of the new symbol added

Example:

rspamd_config.R_EMPTY_IMAGE = function (task)
	parts = task:get_text_parts()
	if parts then
		for _,part in ipairs(parts) do
			if part:is_empty() then
				images = task:get_images()
				if images then
					-- Symbol `R_EMPTY_IMAGE` is inserted
					return true
				end
				return false
			end
		end
	end
	return false
end

rspamd_config.SYMBOL = {
	callback = function(task)
 	...
 	end,
 	score = 5.1,
 	description = 'sample symbol',
 	group = 'sample symbols',
 	condition = function(task)
 		if task:get_from()[1]['addr'] == 'user@example.com' then
 			return false
 		end
 		return true
 	end

Back to module description.

Method rspamd_config:register_regexp(params)

Registers new re for further cached usage Params is the table with the following fields (mandatory fields are marked with *):

• re* : regular expression object
• type*: type of regular expression:
• mime: mime regexp
• rawmime: raw mime regexp
• header: header regexp
• rawheader: raw header expression
• body: raw body regexp
• url: url regexp
• header: for header and rawheader regexp means the name of header
• pcre_only: flag regexp as pcre only regexp

Parameters:

No parameters

Returns:

No return

Back to module description.

Method rspamd_config:replace_regexp(params)

Replaces regexp with a new one Params is the table with the following fields (mandatory fields are marked with *):

• old_re* : old regular expression object (must be in the cache)
• new_re* : old regular expression object (must not be in the cache)

Parameters:

No parameters

Returns:

No return

Back to module description.

Method rspamd_config:register_worker_script(worker_type, script)

Registers the following script for workers of a specified type. The exact type of script function depends on worker type

Parameters:

• worker_type {string}: worker type (e.g. “normal”)
• script {function}: script for a worker

Returns:

• {boolean}: true if a script has been registered

Back to module description.

Method rspamd_config:add_on_load(function(cfg, ev_base) ... end)

Registers the following script to be executed when configuration is completely loaded

Parameters:

• script {function}: function to be executed

Returns:

No return

Example:

rspamd_config:add_on_load(function(cfg, ev_base)
	rspamd_config:add_periodic(ev_base, 1.0, function(cfg, ev_base)
		local logger = require "rspamd_logger"
		logger.infox(cfg, "periodic function")
		return true
	end)
end)

Back to module description.

Method rspamd_config:add_periodic(event_base, timeout, function(cfg, ev_base) ... end, [jitter = false])

Registers function to be periodically executed by Rspamd

Parameters:

• event_base {ev_base}: event base that is needed for async events
• timeout {number}: time in seconds (could be fractional)
• script {function}: function to be executed
• jitter {boolean}: true if timeout jittering is needed

Returns:

No return

Example:

rspamd_config:add_on_load(function(cfg, ev_base)
	rspamd_config:add_periodic(ev_base, 1.0, function(cfg, ev_base)
		local logger = require "rspamd_logger"
		logger.infox(cfg, "periodic function")
		return true -- if return false, then the periodic event is removed
	end)
end)

Back to module description.

Method rspamd_config:get_symbols_count()

Returns number of symbols registered in rspamd configuration

Parameters:

No parameters

Returns:

• {number}: number of symbols registered in the configuration

Back to module description.

Method rspamd_config:get_symbols_cksum()

Returns checksum for all symbols in the cache

Parameters:

No parameters

Returns:

• {int64}: boxed value of the 64 bit checksum

Back to module description.

Method rspamd_config:get_symbol_callback(name)

Returns callback function for the specified symbol if it is a lua registered callback

Parameters:

No parameters

Returns:

• {function}: callback function or nil

Back to module description.

Method rspamd_config:get_symbol_stat(name)

Returns table with statistics for a specific symbol:

• frequency: frequency for symbol’s hits
• stddev: standard deviation of frequency
• time: average time in seconds (floating point)
• count: total number of hits

Parameters:

No parameters

Returns:

• {table}: symbol stats

Back to module description.

Method rspamd_config:set_symbol_callback(name, callback)

Sets callback for the specified symbol

Parameters:

No parameters

Returns:

• {boolean}: true if function has been replaced

Back to module description.

Method rspamd_config:register_finish_script(callback)

Adds new callback that is called on worker process termination when all tasks pending are processed

Parameters:

• callback: {function} a function with one argument (rspamd_task)

Returns:

No return

Back to module description.

Method rspamd_config:register_monitored(url, type, [{params}])

Registers monitored resource to watch its availability. Supported types:

• dns: DNS monitored object

Params are optional table specific for each type. For DNS it supports the following options:

• prefix: prefix to add before making request
• type: type of request (e.g. ‘a’ or ‘txt’)
• ipnet: array of ip/networks to expect on reply
• rcode: expected return code (e.g. nxdomain)

Returned object has the following methods:

• alive: returns true if monitored resource is alive
• offline: returns number of seconds of the current offline period (or 0 if alive)
• total_offline: returns number of seconds of the overall offline
• latency: returns the current average latency in seconds (or 0 if offline)

Parameters:

• url {string}: resource to monitor
• type {string}: type of monitoring
• opts {table}: optional parameters

Returns:

• {rspamd_monitored}: rspamd monitored object

Back to module description.

Method rspamd_config:add_doc(path, option, doc_string, [{params}])

Adds new documentation string for an option option at path path Options defines optional params, such as:

• default: default option value
• type: type of an option (string, number, object, array etc)
• reqired: if an option is required

Parameters:

• path {string}: documentation path (e.g. module name)
• option {string}: name of the option
• doc_string {string}: documentation string
• params {table}: optional parameters

Returns:

No return

Back to module description.

Method rspamd_config:add_example(path, option, doc_string, example)

Adds new documentation

Parameters:

• path {string}: documentation path (e.g. module name or nil for top)
• option {string}: name of the option
• doc_string {string}: documentation string
• example {string}: example in ucl format, comments are also parsed

Returns:

No return

Back to module description.

Method rspamd_config:set_peak_cb(function)

Sets a function that will be called when frequency of some symbol goes out of stddev * 2 over the last period of refreshment.

Parameters:

No parameters

Returns:

No return

Example:

rspamd_config:set_peak_cb(function(ev_base, sym, mean, stddev, value, error)
  -- ev_base: event base for async events (e.g. redis)
  -- sym: symbol's name
  -- mean: mean frequency value
  -- stddev: standard deviation of frequency
  -- value: current frequency value
  -- error: squared error
  local logger = require "rspamd_logger"
  logger.infox(rspamd_config, "symbol %s has changed frequency significantly: %s(%s) over %s(%s)",
      sym, value, error, mean, stddev)
end)

Back to module description.

Method rspamd_config:get_cpu_flags()

Returns architecture dependent flags supported by the CPU Currently, only x86 flags are supported:

• ‘ssse3’
• ‘sse42’
• ‘avx’
• ‘avx2’

Parameters:

No parameters

Returns:

• {table}: flag -> true table

Back to module description.

Back to top.