[Doc] Add comments about configuration

26 files changed, 424 insertions, 2 deletions

diff --git a/conf/common.conf b/conf/common.conf
index b6ad9192a..ebb52bf78 100644
--- a/conf/common.conf
+++ b/conf/common.conf
@@ -1,4 +1,18 @@
 # A common rspamd configuration file
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
 
 lua = "$RULESDIR/rspamd.lua"
 
diff --git a/conf/composites.conf b/conf/composites.conf
index 70021a7f0..bfa0b1b47 100644
--- a/conf/composites.conf
+++ b/conf/composites.conf
@@ -1,4 +1,18 @@
 # Composites setup
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
 
 composite {
     name = "FORGED_RECIPIENTS_MAILLIST";
diff --git a/conf/metrics.conf b/conf/metrics.conf
index b61b28bc2..4be8325c5 100644
--- a/conf/metrics.conf
+++ b/conf/metrics.conf
@@ -1,4 +1,18 @@
 # Metrics settings
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
 
 metric {
     name = "default";
diff --git a/conf/modules.d/chartable.conf b/conf/modules.d/chartable.conf
index 0f4374fbb..24f4811d0 100644
--- a/conf/modules.d/chartable.conf
+++ b/conf/modules.d/chartable.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 chartable {
     .include(try=true,priority=5) "${DBDIR}/dynamic/chartable.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/chartable.conf"
diff --git a/conf/modules.d/dkim.conf b/conf/modules.d/dkim.conf
index 189c13346..7a2795d59 100644
--- a/conf/modules.d/dkim.conf
+++ b/conf/modules.d/dkim.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 dkim {
     .include(try=true,priority=5) "${DBDIR}/dynamic/dkim.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/dkim.conf"
diff --git a/conf/modules.d/dmarc.conf b/conf/modules.d/dmarc.conf
index fad8c9bf2..75d9342a9 100644
--- a/conf/modules.d/dmarc.conf
+++ b/conf/modules.d/dmarc.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 dmarc {
     .include(try=true,priority=5) "${DBDIR}/dynamic/dmarc.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/dmarc.conf"
diff --git a/conf/modules.d/emails.conf b/conf/modules.d/emails.conf
index 67263ec24..8f6a163e5 100644
--- a/conf/modules.d/emails.conf
+++ b/conf/modules.d/emails.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 emails {
     .include(try=true,priority=5) "${DBDIR}/dynamic/emails.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/emails.conf"
diff --git a/conf/modules.d/forged_recipients.conf b/conf/modules.d/forged_recipients.conf
index e71d2ee24..7ecdbce52 100644
--- a/conf/modules.d/forged_recipients.conf
+++ b/conf/modules.d/forged_recipients.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 forged_recipients {
     .include(try=true,priority=5) "${DBDIR}/dynamic/forged_recipients.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/forged_recipients.conf"
diff --git a/conf/modules.d/fuzzy_check.conf b/conf/modules.d/fuzzy_check.conf
index eb347b656..7b95bfda6 100644
--- a/conf/modules.d/fuzzy_check.conf
+++ b/conf/modules.d/fuzzy_check.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 fuzzy_check {
     # Include dynamic conf for the rule
     .include(try=true,priority=5) "${DBDIR}/dynamic/fuzzy_check.conf"
diff --git a/conf/modules.d/hfilter.conf b/conf/modules.d/hfilter.conf
index 46cc78cb4..7da35403e 100644
--- a/conf/modules.d/hfilter.conf
+++ b/conf/modules.d/hfilter.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 hfilter {
     .include(try=true,priority=5) "${DBDIR}/dynamic/hfilter.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/hfilter.conf"
diff --git a/conf/modules.d/ip_score.conf b/conf/modules.d/ip_score.conf
index a37eef100..f8599fc06 100644
--- a/conf/modules.d/ip_score.conf
+++ b/conf/modules.d/ip_score.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 ip_score {
     .include(try=true,priority=5) "${DBDIR}/dynamic/ip_score.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/ip_score.conf"
diff --git a/conf/modules.d/maillist.conf b/conf/modules.d/maillist.conf
index 59e24ad5d..26e0ca7ad 100644
--- a/conf/modules.d/maillist.conf
+++ b/conf/modules.d/maillist.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 maillist {
     .include(try=true,priority=5) "${DBDIR}/dynamic/maillist.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/maillist.conf"
diff --git a/conf/modules.d/mime_types.conf b/conf/modules.d/mime_types.conf
index fac9aa63b..c42ea9e76 100644
--- a/conf/modules.d/mime_types.conf
+++ b/conf/modules.d/mime_types.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 mime_types {
     .include(try=true,priority=5) "${DBDIR}/dynamic/mime_types.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/mime_types.conf"
diff --git a/conf/modules.d/multimap.conf b/conf/modules.d/multimap.conf
index aeaaef5e5..72f567177 100644
--- a/conf/modules.d/multimap.conf
+++ b/conf/modules.d/multimap.conf
@@ -1,5 +1,49 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 multimap {
     .include(try=true,priority=5) "${DBDIR}/dynamic/multimap.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/multimap.conf"
     .include(try=true,priority=10) "$LOCAL_CONFDIR/override.d/multimap.conf"
 }
+
+/* Example setup
+sender_from_whitelist_user {
+            type = "from";
+            filter = "email:user";
+            map = "file:///tmp/from.map";
+            symbol = "SENDER_FROM_WHITELIST_USER";
+            action = "accept"; # Prefilter mode
+}
+sender_from_regexp {
+            type = "header";
+            header = "from";
+            filter = "regexp:/.*@/";
+            map = "file:///tmp/from_re.map";
+            symbol = "SENDER_FROM_REGEXP";
+}
+url_map {
+            type = "url";
+            filter = "tld";
+            map = "file:///tmp/url.map";
+            symbol = "URL_MAP";
+}
+url_tld_re {
+            type = "url";
+            filter = "tld:regexp:/\.[^.]+$/"; # Extracts the last component of URL
+            map = "file:///tmp/url.map";
+            symbol = "URL_MAP_RE";
+}
+*/
diff --git a/conf/modules.d/once_received.conf b/conf/modules.d/once_received.conf
index 84431888e..65efa20a7 100644
--- a/conf/modules.d/once_received.conf
+++ b/conf/modules.d/once_received.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 once_received {
     .include(try=true,priority=5) "${DBDIR}/dynamic/once_received.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/once_received.conf"
diff --git a/conf/modules.d/phishing.conf b/conf/modules.d/phishing.conf
index e48b13407..15b724a10 100644
--- a/conf/modules.d/phishing.conf
+++ b/conf/modules.d/phishing.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 phishing {
     .include(try=true,priority=5) "${DBDIR}/dynamic/phishing.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/phishing.conf"
diff --git a/conf/modules.d/ratelimit.conf b/conf/modules.d/ratelimit.conf
index 04654840a..97833c6f5 100644
--- a/conf/modules.d/ratelimit.conf
+++ b/conf/modules.d/ratelimit.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 ratelimit {
     .include(try=true,priority=5) "${DBDIR}/dynamic/ratelimit.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/ratelimit.conf"
diff --git a/conf/modules.d/rbl.conf b/conf/modules.d/rbl.conf
index 27ecdc229..6b103230b 100644
--- a/conf/modules.d/rbl.conf
+++ b/conf/modules.d/rbl.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 rbl {
     .include(try=true,priority=5) "${DBDIR}/dynamic/rbl.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/rbl.conf"
diff --git a/conf/modules.d/regexp.conf b/conf/modules.d/regexp.conf
index e1ef21032..56c4fe46c 100644
--- a/conf/modules.d/regexp.conf
+++ b/conf/modules.d/regexp.conf
@@ -1,4 +1,21 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 regexp {
-    .include(try=true,priority=1) "${DBDIR}/dynamic/regexp.conf"
+    .include(try=true,priority=5) "${DBDIR}/dynamic/regexp.conf"
+    .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/regexp.conf"
+    .include(try=true,priority=10) "$LOCAL_CONFDIR/override.d/regexp.conf"
     max_size = 1M;
-}
\ No newline at end of file
+}
diff --git a/conf/modules.d/rspamd_update.conf b/conf/modules.d/rspamd_update.conf
index dde210060..be34888a2 100644
--- a/conf/modules.d/rspamd_update.conf
+++ b/conf/modules.d/rspamd_update.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 rspamd_update {
     .include(try=true,priority=5) "${DBDIR}/dynamic/rspamd_update.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/rspamd_update.conf"
diff --git a/conf/modules.d/spf.conf b/conf/modules.d/spf.conf
index d81590205..e25158d34 100644
--- a/conf/modules.d/spf.conf
+++ b/conf/modules.d/spf.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 spf {
     .include(try=true,priority=5) "${DBDIR}/dynamic/spf.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/spf.conf"
diff --git a/conf/modules.d/surbl.conf b/conf/modules.d/surbl.conf
index bdcdc8f57..e9411b8c6 100644
--- a/conf/modules.d/surbl.conf
+++ b/conf/modules.d/surbl.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 surbl {
     .include(try=true,priority=5) "${DBDIR}/dynamic/surbl.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/surbl.conf"
diff --git a/conf/modules.d/whitelist.conf b/conf/modules.d/whitelist.conf
index 05f18847a..13013ff53 100644
--- a/conf/modules.d/whitelist.conf
+++ b/conf/modules.d/whitelist.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 whitelist {
     .include(try=true,priority=5) "${DBDIR}/dynamic/whitelist.conf"
     .include(try=true,priority=1) "$LOCAL_CONFDIR/local.d/whitelist.conf"
diff --git a/conf/rspamd.systemd.conf b/conf/rspamd.systemd.conf
index cf60b7c21..6ab25f6a4 100644
--- a/conf/rspamd.systemd.conf
+++ b/conf/rspamd.systemd.conf
@@ -1,3 +1,20 @@
+# Systemd enabled top level configuration file
+
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 .include "$CONFDIR/common.conf"
 
 options {
diff --git a/conf/rspamd.sysvinit.conf b/conf/rspamd.sysvinit.conf
index e24fe8902..f5db62294 100644
--- a/conf/rspamd.sysvinit.conf
+++ b/conf/rspamd.sysvinit.conf
@@ -1,3 +1,20 @@
+# System V init adopted top level configuration
+
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 .include "$CONFDIR/common.conf"
 
 options {
diff --git a/conf/statistic.conf b/conf/statistic.conf
index 3cc2bfcda..3315fe4b4 100644
--- a/conf/statistic.conf
+++ b/conf/statistic.conf
@@ -1,3 +1,18 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
+# parameters defined on the top level
+#
+# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
+# parameters defined on the top level
+#
+# For specific modules or configuration you can also modify
+# '$LOCAL_CONFDIR/local.d/file.conf' - to add your options or rewrite defaults
+# '$LOCAL_CONFDIR/override.d/file.conf' - to override the defaults
+#
+# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+
 # Rspamd statistic setup
 # Pre-build files could be loaded from:
 # http://rspamd.com/rspamd_statistics/bayes.spam.sqlite