[Doc] Add comments about configuration

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"
 

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";

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";

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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";
+}
+*/

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"

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"

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"

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"

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;
-}
+}

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"

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"

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"

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"

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 {

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 {

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