From: Vsevolod Stakhov <vsevolod@highsecure.ru>
Date: Fri, 11 Oct 2019 08:34:40 +0000 (+0100)
Subject: [Conf] Clarify documentation in the config files
X-Git-Tag: 2.0~14
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f0004af0229a615d166716ed65ea1c3aff11f9fb;p=thirdparty%2Frspamd.git

[Conf] Clarify documentation in the config files
---

diff --git a/conf/actions.conf b/conf/actions.conf
index 75b0d2f73d..a141be7780 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 fd71fa5a6b..436713cff7 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 a8025f314a..023fd5125f 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 2204f1e713..def043f1b6 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 51e2a6522d..bf783cc2f2 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 ebdbfc1102..00dba3915a 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 3da04ae2cf..b37da06d59 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 4489ed29ff..504e06a012 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 c03c134778..95d71e4bfd 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 0d76cd3993..60b6dcb3e1 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 ac4c1355df..1fdffff662 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 bd4029bc3f..5cf788c085 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 532455d0ad..285a17a18b 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 cfc18c059b..96417e3897 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