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:radix_from_ucl(obj)

rspamd_config:add_hash_map(mapline[, description])

rspamd_config:add_kv_map(mapline[, description])

rspamd_config:add_map({args})

rspamd_config:get_maps()

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, worker) ... 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_symbols_counters()

rspamd_config:get_symbols_scores()

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

rspamd_config:has_torch()

rspamd_config:experimental_enabled()

rspamd_config:load_ucl(filename)

rspamd_config:parse_rcl([skip_sections])

rspamd_config:init_modules()

rspamd_config:init_subsystem(str)

rspamd_config:get_tld_path()

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:

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:radix_from_ucl(obj)

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

Parameters:

  • obj {ucl}: object

Returns:

  • {map}: radix tree object

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_maps()

Get all maps defined as an array of rspamd{map} objects

Parameters:

No parameters

Returns:

  • {table|rspamd{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
  • trivial symbol is trivial (e.g. no network requests)
  • 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, worker) ... 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, worker)
	rspamd_config:add_periodic(ev_base, 1.0, function(cfg, ev_base)
		local logger = require "rspamd_logger"
		logger.infox(cfg, "periodic function in worker %s", worker:get_name())
		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_symbols_counters()

Returns table of all counters in the cache (weights, frequencies etc)

Parameters:

No parameters

Returns:

  • {table|tables}: all symbols indexed by name

Back to module description.

Method rspamd_config:get_symbols_scores()

Returns table of all scores defined in config

Parameters:

No parameters

Returns:

  • {table|tables}: all symbols indexed by name

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.

Method rspamd_config:has_torch()

Returns true if Rspamd is compiled with torch support and the runtime CPU supports sse4.2 required for torch.

Parameters:

No parameters

Returns:

  • {boolean}: true if torch is compiled and supported

Back to module description.

Method rspamd_config:experimental_enabled()

Returns true if experimental plugins are enabled

Parameters:

No parameters

Returns:

  • {boolean}: true if experimental plugins are enabled

Back to module description.

Method rspamd_config:load_ucl(filename)

Loads config from the UCL file (but does not perform parsing using rcl)

Parameters:

  • filename {string}: file to load

Returns:

  • true or false + error message

Back to module description.

Method rspamd_config:parse_rcl([skip_sections])

Parses RCL using loaded ucl file

Parameters:

  • sections {table|string}: to skip

Returns:

  • true or false + error message

Back to module description.

Method rspamd_config:init_modules()

Initialize lua and internal modules

Parameters:

No parameters

Returns:

  • true or false

Back to module description.

Method rspamd_config:init_subsystem(str)

Initialize config subsystem from a comma separated list:

  • modules - init modules
  • langdet - language detector
  • dns - DNS resolver
  • TODO: add more

Parameters:

No parameters

Returns:

No return

Back to module description.

Method rspamd_config:get_tld_path()

Returns path to TLD file

Parameters:

No parameters

Returns:

  • {string}: path to tld file

Back to module description.

Back to top.