diff options
Diffstat (limited to 'doc/markdown/lua/index.md')
| -rw-r--r-- | doc/markdown/lua/index.md | 72 |
1 files changed, 36 insertions, 36 deletions
diff --git a/doc/markdown/lua/index.md b/doc/markdown/lua/index.md index d003959d9..8015c6171 100644 --- a/doc/markdown/lua/index.md +++ b/doc/markdown/lua/index.md @@ -1,10 +1,10 @@ -# Rspamd lua API {#top} +# Rspamd Lua API {#top} -Rspamd lua api is a core part of rspamd functionality. Lua is used for writing rules and plugins in rspamd. There are several objects and libraries that simplify classifying of mail. +Lua api is a core part of Rspamd functionality. [Lua language](http://www.lua.org) is used for writing rules and plugins. -## Using lua API from rules {#luarules} +## Using Lua API from rules {#luarules} -Many lua rules are shipped with rspamd. They can be included to rspamd by using tag **lua** in rspamd.conf: +Many Lua rules are shipped with Rspamd. They can be included to Rspamd by using tag **lua** in Rspamd.conf: ~~~ucl lua = "$CONFDIR/lua/rspamd.lua" @@ -12,7 +12,7 @@ lua = "$CONFDIR/lua/rspamd.lua" ### Global configuration tables {#luaglobal} -While load of this file rspamd defines two global variables: +While load of this file Rspamd defines two global variables: - *config* - a global table of modules configuration. Here is a sample of usage of this table: ~~~lua @@ -70,7 +70,7 @@ classifiers['bayes'] = function(classifier, task, is_learn, is_spam) for _,st in pairs(classifier:get_statfiles()) do local st_l = st:get_param('language') if st_l and st_l == language then - -- Insert statfile with specified language + -- Insert statfile with specified language table.insert(selected, st) end end @@ -100,7 +100,7 @@ end ## Writing advanced rules {#luarules} -So by using these two tables it is possible to configure rules and metrics. Also note that it is possible to use any lua functions and rspamd libraries: +So by using these two tables it is possible to configure rules and metrics. Also note that it is possible to use any Lua functions and Rspamd libraries: ~~~lua -- Declare variable that contains regexp rule definition @@ -110,14 +110,14 @@ local rulebody = string.format('%s & !%s', '/re1/', '/re2') rspamd_logger.info('Loaded test rule: ' .. rulebody) ~~~ -Also it is possible to declare functions and use `closures` when defining rspamd rules: +Also it is possible to declare functions and use `closures` when defining Rspamd rules: ~~~lua -- Here is a sample of using closure function inside rule local function check_headers_tab(task, header_name) -- Extract raw headers from message local raw_headers = task:get_raw_header(header_name) - -- Make match of headers, that are separated with tabs, not spaces + -- Make match of headers, that are separated with tabs, not spaces if raw_headers then for _,rh in ipairs(raw_headers) do if rh['tab_separated'] then @@ -127,7 +127,7 @@ local function check_headers_tab(task, header_name) end end return false -end +end rspamd_config.HEADER_TAB_FROM_WHITELISTED = function(task) return check_headers_tab(task, "From") end rspamd_config.HEADER_TAB_TO_WHITELISTED = function(task) return check_headers_tab(task, "To") end @@ -137,15 +137,15 @@ rspamd_config.HEADER_TAB_DATE_WHITELISTED = function(task) return check_headers_ rspamd_config.R_EMPTY_IMAGE = { callback = function(task) local tp = task:get_text_parts() -- get text parts in a message - + for _,p in ipairs(tp) do -- iterate over text parts array using `ipairs` if p:is_html() then -- if the current part is html part local hc = p:get_html() -- we get HTML context local len = p:get_length() -- and part's length - + if len < 50 then -- if we have a part that has less than 50 bytes of text local images = hc:get_images() -- then we check for HTML images - + if images then -- if there are images for _,i in ipairs(images) do -- then iterate over images in the part if i['height'] + i['width'] >= 400 then -- if we have a large image @@ -169,19 +169,19 @@ rspamd_config.R_EMPTY_IMAGE = { } ~~~ -Using lua in rules provides many abilities to write complex mail filtering rules. +Using Lua in rules provides many abilities to write complex mail filtering rules. -## Writing lua plugins {#luaplugins} +## Writing Lua plugins {#luaplugins} -Plugins are more complex filters than ordinary rules. Plugins can have their own configuration parameters and multiple callbacks. Plugins can make DNS requests, read from rspamd maps and insert custom results. +Plugins are more complex filters than ordinary rules. Plugins can have their own configuration parameters and multiple callbacks. Plugins can make DNS requests, read from Rspamd maps and insert custom results. ### Structure of the typical plugin -Each rspamd plugin has a common structure: +Each Rspamd plugin has a common structure: - Registering configuration parameters - Reading configuration parameters and set up callbacks -- Callbacks that are called by rspamd during message processing +- Callbacks that are called by Rspamd during message processing Here is a simple plugin example: @@ -195,12 +195,12 @@ end -- Reading configuration -- Get all options for this plugin -local opts = rspamd_config:get_all_opt('sample') +local opts = Rspamd_config:get_all_opt('sample') if opts then if opts['config'] then - config_param = opts['config'] + config_param = opts['config'] -- Register callback - rspamd_config:register_symbol('some_symbol', sample_callback) + Rspamd_config:register_symbol('some_symbol', sample_callback) end end ~~~ @@ -209,10 +209,10 @@ This plugin uses global variable *rspamd_config* to extract configuration option ### Using DNS requests inside plugins -It is often required to make DNS requests for messages checks. Here is an example of making asynchronous DNS request from rspamd lua plugin: +It is often required to make DNS requests for messages checks. Here is an example of making asynchronous DNS request from Rspamd Lua plugin: ~~~lua --- Function-callback of rspamd rule +-- Function-callback of Rspamd rule local function symbol_cb(task) -- Task is now local variable @@ -224,37 +224,37 @@ local function symbol_cb(task) end end -- Resolve 'example.com' using primitives from the task passed - task:get_resolver():resolve_a(task:get_session(), task:get_mempool(), + task:get_resolver():resolve_a(task:get_session(), task:get_mempool(), 'example.com', dns_cb, 'sample string') end ~~~ -### Using maps from lua plugin +### Using maps from Lua plugin Maps hold dynamically loaded data like lists or ip trees. It is possible to use 3 types of maps: -* **radix_tree** stores ip addresses +* **radix_tree** stores ip addresses * **hash_map** stores plain strings (domains usually) -* **callback** call for a specified lua callback when a map is loaded or changed, map's content is passed to that callback as a parameter +* **callback** call for a specified Lua callback when a map is loaded or changed, map's content is passed to that callback as a parameter -Here is a sample of using maps from lua API: +Here is a sample of using maps from Lua API: ~~~lua -local rspamd_logger = require "rspamd_logger" +local Rspamd_logger = require "rspamd_logger" -- Add two maps in configuration section -local hash_map = rspamd_config:add_hash_map('file:///path/to/file', 'sample map') -local radix_tree = rspamd_config:add_radix_map('http://somehost.com/test.dat', 'sample ip map') -local generic_map = rspamd_config:add_map('file:///path/to/file', 'sample generic map', +local hash_map = Rspamd_config:add_hash_map('file:///path/to/file', 'sample map') +local radix_tree = Rspamd_config:add_radix_map('http://somehost.com/test.dat', 'sample ip map') +local generic_map = Rspamd_config:add_map('file:///path/to/file', 'sample generic map', function(str) -- This callback is called when a map is loaded or changed -- Str contains map content - rspamd_logger.info('Got generic map content: ' .. str) + Rspamd_logger.info('Got generic map content: ' .. str) end) local function sample_symbol_cb(task) -- Check whether hash map contains from address of message - if hash_map:get_key(task:get_from()) then + if hash_map:get_key(task:get_from()) then -- Check whether radix map contains client's ip if radix_map:get_key(task:get_from_ip_num()) then ... @@ -265,9 +265,9 @@ end ## Conclusions {#luaconclusion} -Lua plugins is a powerful tool for creating complex filters that can access practically all features of rspamd. Lua plugins can be used for writing custom rules and interact with rspamd in many ways, can use maps and make DNS requests. Rspamd is shipped with a couple of lua plugins that can be used as examples while writing your own plugins. +Lua plugins is a powerful tool for creating complex filters that can access practically all features of Rspamd. Lua plugins can be used for writing custom rules and interact with Rspamd in many ways, can use maps and make DNS requests. Rspamd is shipped with a couple of Lua plugins that can be used as examples while writing your own plugins. ## References {#luareference} - [Lua manual](http://www.lua.org/manual/5.2/) -- [Programming in lua](http://www.lua.org/pil/) +- [Programming in Lua](http://www.lua.org/pil/) |