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{
  name = 'SYMBOL',
  score = 1.0,
  callback = 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:

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: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: executed after prefilters, according to dependency graph or in undefined order
  • callback: a check that merely inserts virtual symbols
  • connfilter: executed early; before message body is available
  • idempotent: cannot change result in any way; executed last
  • postfilter: executed after most other checks
  • prefilter: executed before most other checks
  • virtual: a symbol inserted by its parent check
• 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)
  • explicit_disable requires explicit disabling (e.g. via settings)
  • ignore_passthrough executed even if passthrough result has been set
• 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|name, depname)

Create a dependency on symbol identified by name for symbol identified by ID or name. This affects order of checks only (a symbol is still checked if its dependencies are disabled).

Parameters:

• id {number|string}: id or name of source (numeric id is returned by all register_*_symbol)
• depname {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
-- Symbol MY_RULE needs result from SPF_CHECK
rspamd_config:register_dependency('MY_RULE', 'SPF_CHECK')

Back to module description.

Method rspamd_config:get_symbol_flags(name)

Returns symbol flags

Parameters:

• name {string}: symbols’s name

Returns:

• {table|string}: list of flags for symbol or nil

Back to module description.

Method rspamd_config:add_symbol_flags(name, flags)

Adds flags to a symbol

Parameters:

• name {string}: symbols’s name
• flags {table|string}: flags to add

Returns:

• {table|string}: new set of flags

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:

local condition_map = rspamd_config:add_map{
  type = "hash",
  urls = ['file:///path/to/file'],
  description = 'SMTP from map that allows FUZZY_DENIED skip for the listed addresses'

rspamd_config:add_condition('FUZZY_DENIED', function(task)
  local E = {}
  -- Check for the smtp from address adding fail safe checks
  if condition_map:find_key(((task:get_from('smtp') or E)[1] or E).addr) then
    return false
  end
  -- Allow execution otherwise
  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, [disable_parent=true])

Disables execution for the specified symbol

Parameters:

• symbol {string}: symbol’s name
• disable_parent {boolean}: if true then disable parent execution in case of a virtual symbol

Returns:

No return

Back to module description.

Method rspamd_config:get_symbol_parent(symbol)

Returns a parent symbol for specific symbol (or symbol itself if top level)

Parameters:

• symbol {string}: symbol’s name

Returns:

No return

Back to module description.

Method rspamd_config:get_group_symbols(group)

Returns list of symbols for a specific group

Parameters:

• group {string}: group’s name

Returns:

• {list|string}: list of all symbols in a specific group

Available in: 2.0+

Back to module description.

Method rspamd_config:get_groups([need_private])

Returns list of all groups defined

Parameters:

• need_private {boolean}: optional flag to include private groups

Returns:

• {list|table}: list of all groups

Available in: 2.3+

Back to module description.

Method rspamd_config:register_settings_id(name, symbols_enabled, symbols_disabled)

Register new static settings id in config

Parameters:

• name {string}: id name (not numeric!)
• symbols_enabled {map|string->string}: map from symbol’s name to boolean (currently)
• symbols_disabled {map|string->string}: map from symbol’s name to boolean (currently)

Returns:

No return

Available in: 2.0+

Back to module description.

Method rspamd_config:__newindex(name, callback)

This metamethod is called if new indices 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 and the worker is already started (forked)

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 numeric, a new interval is set. if return false, then the periodic event is removed
	end)
end)

Back to module description.

Method rspamd_config:add_post_init(function(cfg) ... end)

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

Parameters:

• script {function}: function to be executed

Returns:

No return

Available in: 2.0+

Back to module description.

Method rspamd_config:add_config_unload(function(cfg) ... end)

Registers the following script to be executed when configuration is unloaded

Parameters:

• script {function}: function to be executed

Returns:

No return

Available in: 2.0+

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

Returns table of all scores defined in config. From version 2.0 returns table:

• name
• score
• flags (e.g. ignore or oneparam)
• nshots (== maxhits)
• group - main group
• groups - array of all groups

Parameters:

No parameters

Returns:

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

Available in: 2.0+

Back to module description.

Method rspamd_config:get_symbol(sym_name)

Returns table for a specific symbol getting data from the static config:

• name
• score
• flags (e.g. ignore or oneparam)
• nshots (== maxhits)
• group - main group
• groups - array of all groups

Parameters:

No parameters

Returns:

• {table}: symbol data (or nil)

Available in: 3.3+

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 {no type}: {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)
• required: 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:is_mime_utf8()

Returns true if Rspamd is configured to use UTF for mime processing

Parameters:

No parameters

Returns:

• {boolean}: true if mime utf is enabled

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[, include_trace])

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.

Method rspamd_config:get_dns_max_requests()

Returns limit of DNS requests per task

Parameters:

No parameters

Returns:

• {number}: number of dns requests allowed

Back to module description.

Method rspamd_config:get_dns_timeout()

Returns timeout for a DNS request

Parameters:

No parameters

Returns:

• {number}: DNS timeout in second or 0 if not defined

Back to module description.

Back to top.