diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/markdown/configuration/metrics.md | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/doc/markdown/configuration/metrics.md b/doc/markdown/configuration/metrics.md index bba36a650..ffc2d0c13 100644 --- a/doc/markdown/configuration/metrics.md +++ b/doc/markdown/configuration/metrics.md @@ -12,3 +12,101 @@ * [Modules](../modules/index.md) ## Introduction + +Metrics section provides configuration for symbols weights and actions apllied for a message by rspamd. +You could imagine metric as a decision used by rspamd for a specific message by a set of +rules. Each rule can insert a `symbol` to the metric, that means that this rule is true +for this message. Each symbol can have a floating point value called `weight` that means +the significance of the correspoinding rule. Rules with positive weight icrease `spam` like +property whilst rules with negative weight increase `ham` like property. The final estimation +is the messages's score. + +After a score is evaluated, rspamd selects an appropriate `action` for a message. Action +means the desired operation that should be applied for a message based on the specific +metric. Rspamd defines the following actions ordered by `spam like` property in ascending +order: + +1. `no action` - a message is likely ham +2. `greylist` - a message should be greylisted to ensure sender's validity +3. `add header` - add the specific `spam` header indicating that a message is likely spam +4. `rewrite subject` - add spam subject to a message +5. `soft reject` - temporary reject a message +6. `reject` - permamently reject a message + +Actions are assumed to be applied simultaneously, meaning that `add header` action implies, +for example, `greylist` action. `add header` and `rewrite subject` have actually the same +power in terms of rspamd. They are just two options of the same purpose: to mark a message +as probable spam. `soft reject` action is mainly used to indicate temporary issues in mail +delivery, for instance, rate limit reaching. + +There is also special purpose metric called as `default` that acts as the main metric +to treat a message as spam or ham. Actually, all clients that use rspamd just check the +default metric to determine whether a message is spam or ham. Therefore, the distribution +configuration defines merely the `default` metric. + +## Configuring metrics +Each metric is defined by a `metric` object in rspamd configuration. This object has one +mandatory attribute - `name` which defines the name of this metric: + +~~~nginx +metric { + # Define default metric + name = "default"; +} +~~~ +It is also possible to define some generic attributes for the metric: + +* `grow_factor` - the multiplicator applied for the subsequent symbols inserting by the follwing rule: + + score = score + grow_factor * symbol_weight + grow_factor = grow_factor * grow_factor + +by default this value is `1.0` meaning that no weight growing is defined. By increasing this value you +increase the efficient score of messages with multiple `spam` rules matched. This value +is not affected by negative score values. + +* `subject` - string value that is prepended to the messages's subject if `rewrite subject` +action is applied +* `unknown_weight` - weight for unknown rules. If this parameter is specified, then all rules can +insert symbols to this metric. If such a rule is not specified by this metric then its weight is equal +to this option's value. Please note, that adding this option means that all rules will be checked by rspamd, on the +contrary, if no `unknown_weight` metric is specified then rules that are not registered anywhere are silently ignored +by rspamd. + + +The content of this section is separated to the two main parts: symbols and actions. +Actions section is an object of all actions defined by this metric. If some actions are skipped, +they won't be ever suggested by rspamd. Actions section looks as following: + +~~~nginx +metric { +... + actions { + reject = 15; + add_header = 6; + greylist = 4; + }; +... +} +~~~ + +You can use `_` symbol instead of space in action names to simplify the configuration. + +Symbols are defined by an object with the following properties: + +* `weight` - the symbol weight as floating point number (negative or positive), by default the weight is `1.0` +* `name` - symbolic name for a symbol (mandatory attribute) +* `group` - a group of symbol, for example `DNSBL symbols` (as shown in webui) +* `description` - optional symbolic description for webui + +So far, the symbol definition looks like this one: + +~~~nginx +symbol { + name = "RWL_SPAMHAUS_WL_IND"; + weight = -0.7; + description = "Sender listed at Spamhaus whitelist"; +} +~~~ + +A single metric can contain multiple symbols definitions.
\ No newline at end of file |