From 2fa3f26efff008ba65d8f32f5f41e71181d0bd59 Mon Sep 17 00:00:00 2001
From: Vsevolod Stakhov <vsevolod@rspamd.com>
Date: Wed, 6 Nov 2024 13:44:19 +0000
Subject: [PATCH] [Conf] Add more ways to extend Rspamd configuration

+ Add examples of all that we can do
---
 conf/local.d/module.conf.example         | 20 ++++++++++++++++++++
 conf/modules.conf                        |  3 ++-
 conf/modules.local.d/module.conf.example | 21 +++++++++++++++++++++
 conf/override.d/module.conf.example      | 18 ++++++++++++++++++
 4 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 conf/local.d/module.conf.example
 create mode 100644 conf/modules.local.d/module.conf.example
 create mode 100644 conf/override.d/module.conf.example

diff --git a/conf/local.d/module.conf.example b/conf/local.d/module.conf.example
new file mode 100644
index 000000000..ba3d0b7bb
--- /dev/null
+++ b/conf/local.d/module.conf.example
@@ -0,0 +1,20 @@
+# Define local parameters that you need to merge with the main configuration from
+# either modules.d (for the modules shipped with Rspamd) or modules.local.d (for
+# the modules that you have written).
+#
+# !!! Ensure NOT to enclose your configuration in the outer block with the module
+
+# DON'T DO THIS:
+# module_name { <--- Don't do this
+#   param = "other_value";
+# }
+
+# Just define your parameters here:
+
+param = "other_value";
+
+# Merge with the default complex param
+complex_param {
+  key = "new_value";
+}
+
diff --git a/conf/modules.conf b/conf/modules.conf
index b37da06d5..f99eab8dc 100644
--- a/conf/modules.conf
+++ b/conf/modules.conf
@@ -14,4 +14,5 @@
 #
 # See https://rspamd.com/doc/tutorials/writing_rules.html for details
 
-.include(glob=true) "${CONFDIR}/modules.d/*.conf"
\ No newline at end of file
+.include(glob=true) "${CONFDIR}/modules.d/*.conf"
+.include(glob=true) "${CONFDIR}/modules.local.d/*.conf"
\ No newline at end of file
diff --git a/conf/modules.local.d/module.conf.example b/conf/modules.local.d/module.conf.example
new file mode 100644
index 000000000..9e6ba20e5
--- /dev/null
+++ b/conf/modules.local.d/module.conf.example
@@ -0,0 +1,21 @@
+# This directory is scanned for *.conf files to define configuration for the
+# modules that are not shipped by Rspamd by default.
+# So you can add your own configuration for the modules you have written.
+# Please bear in mind, that each file *MUST* have the outer block with
+# the actual module name, e.g.:
+
+module_name {
+  param = "value";
+  complex_param = {
+    key = "value";
+    other_key = "other value";
+    flag = false;
+  };
+  limit = 10;
+  duration = 10d;
+
+  # If you want to redefine something alternatively
+  .include(try=true,priority=5) "${DBDIR}/dynamic/module_name.conf"
+  .include(try=true,priority=1,duplicate=merge) "$LOCAL_CONFDIR/local.d/module_name.conf"
+  .include(try=true,priority=10) "$LOCAL_CONFDIR/override.d/module_name.conf"
+}
\ No newline at end of file
diff --git a/conf/override.d/module.conf.example b/conf/override.d/module.conf.example
new file mode 100644
index 000000000..2028a94b9
--- /dev/null
+++ b/conf/override.d/module.conf.example
@@ -0,0 +1,18 @@
+# Define local parameters that you need to override the main configuration from
+# either modules.d (for the modules shipped with Rspamd) or modules.local.d (for
+# the modules that you have written).
+#
+# !!! Ensure NOT to enclose your configuration in the outer block with the module
+
+# DON'T DO THIS:
+# module_name { <--- Don't do this
+#   complex_param = null;
+# }
+
+# Just define your parameters here:
+
+# Redefine the whole complex param instead of merging like in `local.d`
+# All other keys in `complex_param` will be removed
+complex_param {
+  key = "new_value";
+}
\ No newline at end of file
-- 
2.39.5