[Conf] Clarify documentation in the config files

14 files changed, 185 insertions, 93 deletions

diff --git a/conf/actions.conf b/conf/actions.conf
index 75b0d2f73..a141be778 100644
--- a/conf/actions.conf
+++ b/conf/actions.conf
@@ -2,17 +2,16 @@
 # 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.d/actions.conf' to add and merge
+# parameters defined inside this section
 #
-# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
-# parameters defined on the top level
+# You can modify 'override.d/actions.conf' to strictly override all
+# parameters defined inside this section
 #
-# 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/faq.html#what-are-the-locald-and-overrided-directories
+# for details
 #
-# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+# See also https://rspamd.com/doc/faq.html#what-are-rspamd-actions for actions definition
 
 actions {
     reject = 15; # Reject when reaching this score
diff --git a/conf/cgp.inc b/conf/cgp.inc
index fd71fa5a6..436713cff 100644
--- a/conf/cgp.inc
+++ b/conf/cgp.inc
@@ -1,3 +1,9 @@
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# This file defines some specific settings that are applicable merely when using
+# CommuniGate Pro MTA and it's specific integration
+
 arc {
     sign_networks = [127.2.4.7];
 }
diff --git a/conf/common.conf b/conf/common.conf
index a8025f314..023fd5125 100644
--- a/conf/common.conf
+++ b/conf/common.conf
@@ -1,4 +1,4 @@
-# A common rspamd configuration file
+# A common rspamd configuration file (should never ever be changed)
 # Please don't modify this file as your changes might be overwritten with
 # the next update.
 #
diff --git a/conf/composites.conf b/conf/composites.conf
index 2204f1e71..def043f1b 100644
--- a/conf/composites.conf
+++ b/conf/composites.conf
@@ -2,15 +2,14 @@
 # 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.d/composites.conf' to add and merge
+# parameters defined inside this section
 #
-# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
-# parameters defined on the top level
+# You can modify 'override.d/composites.conf' to strictly override all
+# parameters defined inside this section
 #
-# 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/faq.html#what-are-the-locald-and-overrided-directories
+# for details
 #
 # See https://rspamd.com/doc/tutorials/writing_rules.html and
 # https://rspamd.com/doc/configuration/composites.html for details
diff --git a/conf/groups.conf b/conf/groups.conf
index 51e2a6522..bf783cc2f 100644
--- a/conf/groups.conf
+++ b/conf/groups.conf
@@ -4,17 +4,16 @@
 # 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.d/groups.conf' to add and merge
+# parameters defined inside this section
 #
-# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
-# parameters defined on the top level
+# You can modify 'override.d/groups.conf' to strictly override all
+# parameters defined inside this section
 #
-# 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/faq.html#what-are-the-locald-and-overrided-directories
+# for details
 #
-# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+# See also: https://rspamd.com/doc/faq.html#how-to-change-score-for-some-symbol
 
 group "headers" {
     .include "$CONFDIR/scores.d/headers_group.conf"
diff --git a/conf/logging.inc b/conf/logging.inc
index ebdbfc110..00dba3915 100644
--- a/conf/logging.inc
+++ b/conf/logging.inc
@@ -1,4 +1,17 @@
-# Included from top-level .conf file
+# Logging configuration
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify 'local.d/logging.inc' to add and merge
+# parameters defined inside this section
+#
+# You can modify 'override.d/logging.inc' to strictly override all
+# parameters defined inside this section
+#
+# See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
+# for details
+#
+# Relevant documentation: https://rspamd.com/doc/configuration/logging.html
 
 level = "info";
 log_format =<<EOD
diff --git a/conf/modules.conf b/conf/modules.conf
index 3da04ae2c..b37da06d5 100644
--- a/conf/modules.conf
+++ b/conf/modules.conf
@@ -1,3 +1,17 @@
-# Rspamd modules configuration
+# A common rspamd configuration file (should never ever be changed)
+# 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(glob=true) "${CONFDIR}/modules.d/*.conf"
\ No newline at end of file
diff --git a/conf/options.inc b/conf/options.inc
index 4489ed29f..504e06a01 100644
--- a/conf/options.inc
+++ b/conf/options.inc
@@ -1,4 +1,17 @@
-# Included from top-level .conf file
+# Logging configuration
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify 'local.d/options.inc' to add and merge
+# parameters defined inside this section
+#
+# You can modify 'override.d/options.inc' to strictly override all
+# parameters defined inside this section
+#
+# See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
+# for details
+#
+# Relevant documentation: https://rspamd.com/doc/configuration/options.html
 
 filters = "chartable,dkim,spf,regexp,fuzzy_check";
 raw_mode = false;
diff --git a/conf/settings.conf b/conf/settings.conf
index c03c13477..95d71e4bf 100644
--- a/conf/settings.conf
+++ b/conf/settings.conf
@@ -1,14 +1,17 @@
-# You can modify '$LOCAL_CONFDIR/rspamd.conf.local.override' to redefine
-# parameters defined on the top level
+# Settings 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' to add
-# parameters defined on the top level
+# You can modify 'local.d/settings.conf' to add and merge
+# parameters defined inside this section
 #
-# 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
+# You can modify 'override.d/settings.conf' to strictly override all
+# parameters defined inside this section
 #
-# See https://rspamd.com/doc/tutorials/writing_rules.html for details
+# See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
+# for details
+#
+# Module documentation: https://rspamd.com/doc/configuration/settings.html
 
 # If you want to use settings map, then please define something like:
 #
@@ -17,48 +20,47 @@
 # in rspamd.conf.override
 
 settings {
-/* Commented out
   # Some examples below (define in local.d/settings.conf without `settings {}`!)
-  some_users {
-    id = "some_users";
-    priority = high;
-    from = "@example.com";
-    rcpt = "admin";
-    rcpt = "/user.*/";
-    ip = "172.16.0.0/16";
-    user = "@example.net";
-    request_header = {
-      "MTA-Tag" = "\.example\.net$";
-    }
-    apply {
-      symbol1 = 10.0;
-      symbol2 = 0.0;
-      actions {
-        reject = 100.0;
-        greylist = 10.0;
-        "add header" = 5.0; # Please note the space, NOT an underscore
-      }
-    }
-    # Always add these symbols when settings rule has matched
-    symbols [
-      "symbol2", "symbol4"
-    ]
-  }
-  whitelist {
-    priority = low;
-    rcpt = "postmaster@example.com";
-    want_spam = yes;
-  }
+  #some_users {
+  #  id = "some_users";
+  #  priority = high;
+  #  from = "@example.com";
+  #  rcpt = "admin";
+  #  rcpt = "/user.*/";
+  #  ip = "172.16.0.0/16";
+  #  user = "@example.net";
+  #  request_header = {
+  #    "MTA-Tag" = "\.example\.net$";
+  #  }
+  #  apply {
+  #    symbol1 = 10.0;
+  #    symbol2 = 0.0;
+  #    actions {
+  #      reject = 100.0;
+  #      greylist = 10.0;
+  #      "add header" = 5.0; # Please note the space, NOT an underscore
+  #    }
+  #  }
+  # Always add these symbols when settings rule has matched
+  #  symbols [
+  #    "symbol2", "symbol4"
+  #  ]
+  #}
+  #whitelist {
+  #  priority = low;
+  #  rcpt = "postmaster@example.com";
+  #  want_spam = yes;
+  #}
   # Disable some checks for authenticated users
-  authenticated {
-    priority = high;
-    authenticated = yes;
-    apply {
-      groups_disabled = ["rbl", "spf"];
-    }
-  }
-  # End of example
-*/
+  #authenticated {
+  #  priority = high;
+  #  authenticated = yes;
+  #  apply {
+  #    groups_disabled = ["rbl", "spf"];
+  #  }
+  #}
+  # End of examples
+
   .include(try=true,priority=1,duplicate=merge) "$LOCAL_CONFDIR/local.d/settings.conf"
   .include(try=true; priority=10) "$LOCAL_CONFDIR/override.d/settings.conf"
 }
\ No newline at end of file
diff --git a/conf/statistic.conf b/conf/statistic.conf
index 0d76cd399..60b6dcb3e 100644
--- a/conf/statistic.conf
+++ b/conf/statistic.conf
@@ -1,23 +1,22 @@
+# Statistics 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.d/statistics.conf' to add and merge
+# parameters defined inside this section
 #
-# You can modify '$LOCAL_CONFDIR/rspamd.conf.local' to add
-# parameters defined on the top level
+# You can modify 'override.d/statistics.conf' to strictly override all
+# parameters defined inside this section
 #
-# 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
+# If you just need to change the default bayes classifier, you can also use
+# 'local.d/classifier-bayes.conf' or 'override.d/classifier-bayes.conf'. But
+# never ever use both `statistics.conf` and `classifier-bayes.conf` locals files
+# together!
 #
-# See https://rspamd.com/doc/tutorials/writing_rules.html for details
-
-# Rspamd statistic setup
-# Pre-built files could be loaded from:
-# http://rspamd.com/rspamd_statistics/bayes.spam.sqlite
-#  - and -
-# http://rspamd.com/rspamd_statistics/bayes.ham.sqlite
+# See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
+# for details
+#
+# Module documentation: https://rspamd.com/doc/configuration/statistic.html
 
 classifier "bayes" {
   tokenizer {
diff --git a/conf/worker-controller.inc b/conf/worker-controller.inc
index ac4c1355d..1fdffff66 100644
--- a/conf/worker-controller.inc
+++ b/conf/worker-controller.inc
@@ -1,4 +1,16 @@
-# Included from top-level .conf file
+# Controller worker setup
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify 'local.d/worker-controller.inc' to add and merge
+# parameters defined inside this section
+#
+# You can modify 'override.d/worker-controller.inc' to strictly override all
+# parameters defined inside this section
+#
+# See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
+# for details
+# Module documentation: https://rspamd.com/doc/workers/controller.html
 
 count = 1;
 password = "q1";
diff --git a/conf/worker-fuzzy.inc b/conf/worker-fuzzy.inc
index bd4029bc3..5cf788c08 100644
--- a/conf/worker-fuzzy.inc
+++ b/conf/worker-fuzzy.inc
@@ -1,4 +1,16 @@
-# Included from top-level .conf file
+# Fuzzy storage worker setup
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify 'local.d/worker-fuzzy.inc' to add and merge
+# parameters defined inside this section
+#
+# You can modify 'override.d/worker-fuzzy.inc' to strictly override all
+# parameters defined inside this section
+#
+# See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
+# for details
+# Module documentation: https://rspamd.com/doc/workers/fuzzy_storage.html
 
 backend = "redis";
 
diff --git a/conf/worker-normal.inc b/conf/worker-normal.inc
index 532455d0a..285a17a18 100644
--- a/conf/worker-normal.inc
+++ b/conf/worker-normal.inc
@@ -1,3 +1,15 @@
-# Included from top-level .conf file
+# Normal scanner worker setup
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify 'local.d/worker-normal.inc' to add and merge
+# parameters defined inside this section
+#
+# You can modify 'override.d/worker-normal.inc' to strictly override all
+# parameters defined inside this section
+#
+# See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
+# for details
+# Module documentation: https://rspamd.com/doc/workers/normal.html
 
 mime = true;
diff --git a/conf/worker-proxy.inc b/conf/worker-proxy.inc
index cfc18c059..96417e389 100644
--- a/conf/worker-proxy.inc
+++ b/conf/worker-proxy.inc
@@ -1,4 +1,16 @@
-# Included from top-level .conf file
+# Proxy worker setup
+# Please don't modify this file as your changes might be overwritten with
+# the next update.
+#
+# You can modify 'local.d/worker-proxy.inc' to add and merge
+# parameters defined inside this section
+#
+# You can modify 'override.d/worker-proxy.inc' to strictly override all
+# parameters defined inside this section
+#
+# See https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
+# for details
+# Module documentation: https://rspamd.com/doc/workers/rspamd_proxy.html
 
 milter = yes; # Enable milter mode
 timeout = 120s; # Needed for Milter usually