From: Vsevolod Stakhov <vsevolod@highsecure.ru>
Date: Thu, 10 Mar 2016 17:29:24 +0000 (+0000)
Subject: [Doc] Describe new way to redefine symbols
X-Git-Tag: 1.2.0~78
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=83940fa64f41f0cdba8e52326c91c8dca1588b68;p=thirdparty%2Frspamd.git

[Doc] Describe new way to redefine symbols
---

diff --git a/doc/markdown/tutorials/writing_rules.md b/doc/markdown/tutorials/writing_rules.md
index 92b4b24a7c..38e1f56a92 100644
--- a/doc/markdown/tutorials/writing_rules.md
+++ b/doc/markdown/tutorials/writing_rules.md
@@ -101,6 +101,35 @@ section "name" {
 }
 ~~~
 
+For each individual configuration file shipped with rspamd, there are two special includes:
+
+    .include(try=true,priority=1) "$CONFDIR/local.d/config.conf"
+    .include(try=true,priority=1) "$CONFDIR/override.d/config.conf"
+
+Therefore, you can either extend (using local.d) or ultimately override (using override.d) any settings in rspamd configuration.
+
+For example, let's override some default symbols shipped with rspamd. To do that we can create and edit `etc/rspamd/local.d/metrics.conf`:
+
+    symbol "BLAH" {
+        score = 20.0;
+    }
+
+We can also use override file, for example, let's redefine actions and set more restrictive `reject` score. For these purposes, we create `etc/rspamd/override.d/metrics.conf` with the following content:
+
+    actions {
+      reject = 150;
+      add_header = 6;
+      greylist = 4;
+    }
+
+You need to set the complete objects to redefine the existing ones. For example, you **cannot** write something like
+
+    actions {
+      reject = 150;
+    }
+
+as this will set all other actions undefined.
+
 The conjunction of `override` and `local` configs should allow to resolve complicated issues without having a Turing complete language to distinguish cases.
 
 ## Writing rules