Skip to main content

Module rspamd_config

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:

MethodDescription
rspamd_config:get_module_opt(mname, optname)Returns value of specified option optname for a module mname,.
rspamd_config:get_all_opt(mname)Returns value of all options for a module mname, flattening values into a single table consisting.
rspamd_config:get_ucl()Returns full configuration as a native Lua object (ucl to lua conversion).
rspamd_config:get_mempool()Returns static configuration memory pool.
rspamd_config:get_resolver()Returns DNS resolver.
rspamd_config:add_radix_map(mapline[, description])Creates new dynamic map of IP/mask addresses.
rspamd_config:radix_from_config(mname, optname)Creates new embedded map of IP/mask addresses from config.
rspamd_config:radix_from_ucl(obj, description)Creates new embedded map of IP/mask addresses from object.
rspamd_config:add_hash_map(mapline[, description])Creates new dynamic map string objects.
rspamd_config:add_kv_map(mapline[, description])Creates new dynamic map of key/values associations.
rspamd_config:add_map({args})Creates new dynamic map according to the attributes passed.
rspamd_config:get_maps()Get all maps defined as an array of rspamd{map} objects.
rspamd_config:get_classifier(name)Returns classifier config.
rspamd_config:register_symbol(table)Register symbol of a specified type in rspamd.
rspamd_config:register_symbols(callback, [weight], callback_name, [, symbol, ...])Register callback function to be called for a set of symbols with initial weight.
rspamd_config:register_virtual_symbol(name, weight,)Register virtual symbol that is not associated with any callback.
rspamd_config:register_callback_symbol(name, weight, callback)Register callback function to be called for a specified symbol with initial weight.
[`rspamd_config:register_dependency(idname, depname[, hard])`](#m35f6d)
rspamd_config:get_symbol_flags(name)Returns symbol flags.
rspamd_config:get_symbol_type(name)Returns the declared type of a symbol and its execution plan.
rspamd_config:add_symbol_flags(name, flags)Adds flags to a symbol.
rspamd_config:register_pre_filter(callback[, order])Register function to be called prior to symbols processing.
rspamd_config:register_post_filter(callback[, order])Register function to be called after symbols are processed.
rspamd_config:get_key(name)Returns configuration section with the specified name.
rspamd_config:add_condition(symbol, condition)Adds condition callback for specified symbol.
rspamd_config:enable_symbol(symbol)Enables execution for the specified symbol.
rspamd_config:disable_symbol(symbol, [disable_parent=true])Disables execution for the specified symbol.
rspamd_config:get_symbol_parent(symbol)Returns a parent symbol for specific symbol (or symbol itself if top level).
rspamd_config:get_group_symbols(group)Returns list of symbols for a specific group.
rspamd_config:get_groups([need_private])Returns list of all groups defined.
rspamd_config:promote_symbols_cache_resort()Promote symbols cache resort after dynamic symbol registration.
rspamd_config:register_settings_id(name, symbols_enabled, symbols_disabled[, policy])Register new static settings id in config.
rspamd_config:__newindex(name, callback)This metamethod is called if new indices are added to the rspamd_config object.
rspamd_config:register_regexp(params)Registers new re for further cached usage.
rspamd_config:replace_regexp(params)Replaces regexp with a new one.
rspamd_config:register_regexp_scoped(scope, params)Registers new re for further cached usage in a specific scope.
rspamd_config:replace_regexp_scoped(scope, params)Replaces regexp with a new one in a specific scope.
rspamd_config:register_re_selector_scoped(scope, name, selector_str, [delimiter, [flatten]])Registers selector with the specific name in a specific scope to use in regular expressions.
rspamd_config:find_regexp_scope(scope)Checks if a regexp scope exists.
rspamd_config:remove_regexp_scope(scope)Removes a regexp scope from the cache.
rspamd_config:count_regexp_scopes()Returns the number of regexp scopes.
rspamd_config:list_regexp_scopes()Returns a list of all regexp scope names.
rspamd_config:set_regexp_scope_flags(scope, flags)Sets flags for a regexp scope.
rspamd_config:clear_regexp_scope_flags(scope, flags)Clears flags for a regexp scope.
rspamd_config:get_regexp_scope_flags(scope)Gets flags for a regexp scope.
rspamd_config:is_regexp_scope_loaded(scope)Checks if a regexp scope is loaded and ready for use.
rspamd_config:set_regexp_scope_loaded(scope, loaded)Sets the loaded state of a regexp scope.
rspamd_config:register_worker_script(worker_type, script)Registers the following script for workers of a specified type.
rspamd_config:add_on_load(function(cfg, ev_base, worker) ... end)Registers the following script to be executed when configuration is completely loaded.
rspamd_config:add_periodic(event_base, timeout, function(cfg, ev_base) ... end, [jitter = false])Registers function to be periodically executed by Rspamd.
rspamd_config:add_post_init(function(cfg) ... end)Registers the following script to be executed when configuration is completely loaded.
rspamd_config:add_config_unload(function(cfg) ... end)Registers the following script to be executed when configuration is unloaded.
rspamd_config:get_symbols_count()Returns number of symbols registered in rspamd configuration.
rspamd_config:get_symbols_cksum()Returns checksum for all symbols in the cache.
rspamd_config:get_symbols_counters()Returns table of all counters in the cache (weights, frequencies etc).
rspamd_config:get_symbols()Returns table of all scores defined in config.
rspamd_config:get_symbol(sym_name)Returns table for a specific symbol getting data from the static config.
rspamd_config:get_symbol_callback(name)Returns callback function for the specified symbol if it is a lua registered callback.
rspamd_config:get_symbol_stat(name)Returns table with statistics for a specific symbol.
rspamd_config:set_symbol_callback(name, callback)Sets callback for the specified symbol.
rspamd_config:register_finish_script(callback)Adds new callback that is called on worker process termination when all.
rspamd_config:register_monitored(url, type, [{params}])Registers monitored resource to watch its availability.
rspamd_config:add_doc(path, option, doc_string, [{params}])Adds new documentation string for an option option at path path.
rspamd_config:add_example(path, option, doc_string, example)Adds new documentation.
rspamd_config:set_peak_cb(function)Sets a function that will be called when frequency of some symbol goes out of.
rspamd_config:get_cpu_flags()Returns architecture dependent flags supported by the CPU.
rspamd_config:has_torch()Returns true if Rspamd is compiled with torch support and the runtime CPU.
rspamd_config:is_mime_utf8()Returns true if Rspamd is configured to use UTF for mime processing.
rspamd_config:experimental_enabled()Returns true if experimental plugins are enabled.
rspamd_config:load_ucl(filename[, include_trace])Loads config from the UCL file (but does not perform parsing using rcl).
rspamd_config:parse_rcl([skip_sections])Parses RCL using loaded ucl file.
rspamd_config:init_modules()Initialize lua and internal modules.
rspamd_config:init_subsystem(str)Initialize config subsystem from a comma separated list.
rspamd_config:get_tld_path()Returns path to TLD file.
rspamd_config:get_dns_max_requests()Returns limit of DNS requests per task.
rspamd_config:get_dns_timeout()Returns timeout for a DNS request.
rspamd_config:load_custom_tokenizers()Loads custom tokenizers from configuration.
rspamd_config:unload_custom_tokenizers()Unloads custom tokenizers and frees memory.

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, description)​

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); for prefilters, connfilters, postfilters and idempotent symbols it defines the execution level within the stage (see below), for normal symbols it is merely a soft ordering hint

  • 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

    All types share one dependency graph. Prefilters (and connfilters) with a higher priority run before the ones with a lower priority, and a prefilter may not start until every prefilter with a higher priority has finished; prefilters of the same priority run concurrently. Postfilters and idempotent symbols are ordered the other way round: a higher priority runs later. A prefilter may depend on a normal symbol (see register_dependency): that symbol, with its own dependencies, is then executed at the prefilter stage at the level of the depending prefilter.

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

  • score: default score of the symbol

  • description: description of the symbol

  • group: group of the symbol (ungrouped if missing)

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

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), unless hard is set: then the dependent symbol is not executed when its dependency has been disabled or skipped.

A dependency may point to the same stage or to an earlier one (e.g. a normal symbol depending on a prefilter, a postfilter depending on a normal symbol). A prefilter may also depend on a normal symbol: that symbol is then hoisted to the prefilter stage together with its own dependencies, so the cost of the dependency is paid before the prefilter decision. Other edges to a later stage are rejected at the configuration time; rspamadm configdump -e shows the resulting execution plan.

Parameters:

  • id {number|string}: id or name of source (numeric id is returned by all register_*_symbol)
  • depname {string}: dependency name
  • hard {boolean}: if true, the source is skipped when the dependency is disabled or skipped

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:get_symbol_type(name)​

Returns the declared type of a symbol and its execution plan. The type is one of connfilter, prefilter, filter, postfilter, idempotent, composite, classifier or virtual. For the executed symbols (and for the virtual symbols of executed parents) the stage that runs the symbol (connfilters, prefilters, filters, postfilters, idempotent) and its level within the stage are also returned.

Parameters:

  • name {string}: symbol's name

Returns:

  • {string,string,number}: type, stage, level (or nil if the symbol is unknown)

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:promote_symbols_cache_resort()​

Promote symbols cache resort after dynamic symbol registration

Parameters:

No parameters

Returns:

  • {boolean}: true if successful

Back to module description.

Method rspamd_config:register_settings_id(name, symbols_enabled, symbols_disabled[, policy])​

Register new static settings id in config implicit_allow is assumed if symbols_enabled is empty, default (whitelist) otherwise

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)
  • policy {string}: one of default, implicit_allow or implicit_deny; when omitted,

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_regexp_scoped(scope, params)​

Registers new re for further cached usage in a specific scope 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
    • selector: selector regexp
  • header: for header and rawheader regexp means the name of header
  • selector: for selector regexp means selector name (registered in scope)
  • pcre_only: flag regexp as pcre only regexp

Parameters:

  • scope {string}: scope name for the regexp
  • params {table}: regexp parameters

Returns:

No return

Back to module description.

Method rspamd_config:replace_regexp_scoped(scope, params)​

Replaces regexp with a new one in a specific scope 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)
  • pcre_only: flag regexp as pcre only regexp

Parameters:

  • scope {string}: scope name for the regexp
  • params {table}: regexp parameters

Returns:

No return

Back to module description.

Method rspamd_config:register_re_selector_scoped(scope, name, selector_str, [delimiter, [flatten]])​

Registers selector with the specific name in a specific scope to use in regular expressions

Parameters:

  • scope {string}: scope name for the selector
  • name {string}: name of the selector
  • selector_str {string}: selector definition
  • delimiter {string}: delimiter to use when joining strings if flatten is false
  • flatten {bool}: if true then selector will return a table of captures instead of a single string

Returns:

  • true if selector has been registered

Back to module description.

Method rspamd_config:find_regexp_scope(scope)​

Checks if a regexp scope exists

Parameters:

  • scope {string}: scope name to check (can be nil for default scope)

Returns:

  • {boolean}: true if scope exists

Back to module description.

Method rspamd_config:remove_regexp_scope(scope)​

Removes a regexp scope from the cache

Parameters:

  • scope {string}: scope name to remove

Returns:

  • {boolean}: true if scope was removed successfully

Back to module description.

Method rspamd_config:count_regexp_scopes()​

Returns the number of regexp scopes

Parameters:

No parameters

Returns:

  • {number}: number of scopes

Back to module description.

Method rspamd_config:list_regexp_scopes()​

Returns a list of all regexp scope names

Parameters:

No parameters

Returns:

  • {table}: array of scope names (default scope is named "default")

Back to module description.

Method rspamd_config:set_regexp_scope_flags(scope, flags)​

Sets flags for a regexp scope

Parameters:

  • scope {string}: scope name (can be nil for default scope)
  • flags {number}: flags to set

Returns:

No return

Back to module description.

Method rspamd_config:clear_regexp_scope_flags(scope, flags)​

Clears flags for a regexp scope

Parameters:

  • scope {string}: scope name (can be nil for default scope)
  • flags {number}: flags to clear

Returns:

No return

Back to module description.

Method rspamd_config:get_regexp_scope_flags(scope)​

Gets flags for a regexp scope

Parameters:

  • scope {string}: scope name (can be nil for default scope)

Returns:

  • {number}: current flags value

Back to module description.

Method rspamd_config:is_regexp_scope_loaded(scope)​

Checks if a regexp scope is loaded and ready for use

Parameters:

  • scope {string}: scope name (can be nil for default scope)

Returns:

  • {boolean}: true if scope is loaded

Back to module description.

Method rspamd_config:set_regexp_scope_loaded(scope, loaded)​

Sets the loaded state of a regexp scope

Parameters:

  • scope {string}: scope name (can be nil for default scope)
  • loaded {boolean}: whether scope should be marked as loaded (defaults to true)

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.

Method rspamd_config:load_custom_tokenizers()​

Loads custom tokenizers from configuration

Parameters:

No parameters

Returns:

  • {boolean}: true if successful

Back to module description.

Method rspamd_config:unload_custom_tokenizers()​

Unloads custom tokenizers and frees memory

Parameters:

No parameters

Returns:

No return

Back to module description.

Back to top.