From 2c95b5e5a60ae5ce2f0bb804e586b990f48cf677 Mon Sep 17 00:00:00 2001 From: Vsevolod Stakhov Date: Thu, 14 Aug 2014 13:48:06 +0100 Subject: [PATCH] Add basic configuration documentation. --- doc/markdown/configuration/composites.md | 61 ++++++++++++++++++++++++ doc/markdown/configuration/index.md | 17 +++++-- doc/markdown/configuration/logging.md | 0 doc/markdown/configuration/metrics.md | 0 doc/markdown/configuration/options.md | 0 doc/markdown/configuration/statistic.md | 0 6 files changed, 75 insertions(+), 3 deletions(-) create mode 100644 doc/markdown/configuration/composites.md create mode 100644 doc/markdown/configuration/logging.md create mode 100644 doc/markdown/configuration/metrics.md create mode 100644 doc/markdown/configuration/options.md create mode 100644 doc/markdown/configuration/statistic.md diff --git a/doc/markdown/configuration/composites.md b/doc/markdown/configuration/composites.md new file mode 100644 index 000000000..2fa3ea568 --- /dev/null +++ b/doc/markdown/configuration/composites.md @@ -0,0 +1,61 @@ +# Rspamd composite rules + +Rspamd composites are used to combine rules and create more complex rules. +Composite rules are defined by `composite` keys. The value of this key should be +an object that defines composite's name and value, which is the combination of rules +in a joint expression. + +For example, you can define a composite that is added when two of symbols are found: + +~~~nginx +composite { + name = "TEST_COMPOSITE"; + expression = "SYMBOL1 and SYMBOL2"; +} +~~~ + +In this case, if a message has `SYMBOL1` and `SYMBOL2` simultaneously then they are replaced by +symbol `TEST_COMPOSITE`. The weights of `SYMBOL1` and `SYMBOL2` are substracted from the metric +accordingly. + +## Composite expression + +You can use the following operations in a composite expression: + +* `AND` `&` - matches true only if both of operands are true +* `OR` `|` - matches true if any of operands are true +* `NOT` `!` - matches true if operand is false + +You also can use braces to define priorities. Otherwise operators are evaluated from left to right. +For example: + +~~~nginx +composite { + name = "TEST"; + expression = "SYMBOL1 and SYMBOL2 and ( not SYMBOL3 | not SYMBOL4 | not SYMBOL5 )"; +} +~~~ + +Composite rule can include other composites in the body. There is no restriction of definition order: +~~~nginx +composite { + name = "TEST1"; + expression = "SYMBOL1 AND TEST2"; +} +composite { + name = "TEST2"; + expression = "SYMBOL2 OR NOT SYMBOL3"; +} +~~~ + +Composites should not be recursive and it is normally detected by rspamd. + +## Composite weights rules +Composites can leave the symbols in a metric or leave their weights. That could be used to create +non-captive composites. +For example, you have symbol `A` and `B` with weights `W_a` and `W_b` and a composite `C` with weight `W_c`. + +* If `C` is `A & B` then if rule `A` and rule `B` matched then these symbols are *removed* and their weights are removed as well, leading to a single symbol `C` with weight `W_c`. +* If `C` is `-A & B`, then rule `A` is preserved, but the symbol `C` is inserted. The weight of `A` is preserved as well, so the total weight of `-A & B` will be `W_a + W_c`. +* If `C` is `~A & B`, then rule `A` is *removed* but its weight is *preserved*, leading to a single symbol `C` with weight `W_a + W_c` + diff --git a/doc/markdown/configuration/index.md b/doc/markdown/configuration/index.md index ae9ce7496..9ddf49689 100644 --- a/doc/markdown/configuration/index.md +++ b/doc/markdown/configuration/index.md @@ -4,6 +4,17 @@ Rspamd uses UCL for its configuration. UCL format is described in details in this [document](ucl.md). Rspamd defines several variables and macros to extend UCL functionality. +## Table of Contents + +* [Options](options.md) +* [Logging](logging.md) +* [Metrics](metrics.md) +* [Composites](composites.md) +* [User settings](settings.md) +* [Statistic configuration](statistic.md) +* [Workers](../workers/index.md) +* [Modules](../modules/index.md) + ## Rspamd variables - *CONFDIR*: configuration directory for rspamd, it is $PREFIX/etc/rspamd/ @@ -50,7 +61,7 @@ metric settings, including rules weights and rspamd actions. [Workers](workers.m section specifies rspamd workers settings. [Composites](composites.md) is an utility section that describes composite symbols. Statistical filters are defined in [statistic](statistic.md) section. Rspamd stores modules configuration (for both lua -and internal modules) in [modules](modules.md) section while modules itself are +and internal modules) in [modules](../modules/index.md) section while modules itself are loaded from the following portion of configuration: ~~~nginx @@ -65,7 +76,7 @@ If directory is used then all files with suffix `.lua` are loaded as lua plugins This configuration is not intended to be changed by user, but you can include your own configuration in further. To redefine symbols weight and actions rspamd encourages -to use [dynamic configuration](dynamic_conf.md). Nevertheless, rspamd installation +to use [dynamic configuration](settings.md). Nevertheless, rspamd installation script will never rewrite user's configuration if it exists already. So please read ChangeLog carefully if you upgrade rspamd to a new version for all incompatible -configuration changes. \ No newline at end of file +configuration changes. diff --git a/doc/markdown/configuration/logging.md b/doc/markdown/configuration/logging.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/markdown/configuration/metrics.md b/doc/markdown/configuration/metrics.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/markdown/configuration/options.md b/doc/markdown/configuration/options.md new file mode 100644 index 000000000..e69de29bb diff --git a/doc/markdown/configuration/statistic.md b/doc/markdown/configuration/statistic.md new file mode 100644 index 000000000..e69de29bb