Add settings description.

3 files changed, 76 insertions, 0 deletions

diff --git a/doc/markdown/configuration/index.md b/doc/markdown/configuration/index.md
index ae9ce7496..bfb0012ea 100644
--- a/doc/markdown/configuration/index.md
+++ b/doc/markdown/configuration/index.md
@@ -4,6 +4,19 @@ Rspamd uses UCL for its configuration. UCL format is described in details in
 this [document](ucl.md). Rspamd defines several variables and macros to extend
 UCL functionality.
 
+## Configuration subtopics
+Here is the list of all subtopics.
+- [UCL](ucl.md)
+- [Options](options.md)
+- [Logging](logging.md)
+- [Metrics](metrics.md)
+- [Workers](workers.md)
+- [Composites](composites.md)
+- [Statistic](statistic.md)
+- [Modules](modules.md)
+- [Dynamic configuration](dynamic_conf.md)
+- [User settings](settings.md)
+
 ## Rspamd variables
 
 - *CONFDIR*: configuration directory for rspamd, it is $PREFIX/etc/rspamd/
diff --git a/doc/markdown/configuration/settings.md b/doc/markdown/configuration/settings.md
new file mode 100644
index 000000000..b7aea8055
--- /dev/null
+++ b/doc/markdown/configuration/settings.md
@@ -0,0 +1,63 @@
+# Rspamd user settings
+
+Rspamd allows to specify custom settings according to incoming messages. Each setting define some set
+of custom metric weights, symbols or actions. An administrator can also skip spam checks for certain
+messages completely. Unlike the most of configuration options, rspamd settings can be loaded dynamically
+and thus they are updated automatically if a corresponding file or URL has changed since last update.
+
+To load rspamd settings one may specify `.include_map "</file|url>"` or use the ordinary `.include` macro:
+
+~~~nginx
+.include_map "$CONFDIR/settings.conf"
+~~~
+
+## Settings structure
+
+The settings file itself should contain a single section called "settings":
+
+~~~nginx
+settings {
+	some_users {
+		priority = 0;
+		from = "@example.com";
+		rcpt = "admin";
+		rcpt = "/user.*/";
+		ip = "172.16.0.0/16";
+		apply "default" {
+			symbol1 = 10.0;
+			symbol2 = 0.0;
+			actions {
+				reject = 100.0
+				greylist = 10.0
+			}
+		}
+	}
+	whitelist {
+		priority = 1;
+		rcpt = "postmaster@example.com";
+		want_spam = yes;
+	}
+}
+~~~
+
+So each setting has the following attributes:
+
+- `name` - section name that identify this specific setting (e.g. `some_users`)
+- `priority` - 0 or 1, 0 is higher priority than 1 and is matched first (default priority is 1)
+- `match list` - list of rules when this rule matches:
+	+ `from` - match SMTP from
+	+ `rcpt` - match RCPT
+	+ `ip` - match source IP address
+- `apply` - list of applied rules, identified by metric name (e.g. `default`)
+	+ `symbol` - modify weight of a symbol
+	+ `actions` - section of modified actions
+
+Match section performs `AND` operation on different matches, for example, if you have
+`from` and `rcpt` in the same rule, then rule matches only when `from` `AND` `rcpt` match.
+For the same matches `OR` rule applies. Therefore, if you have multiple `rcpt` matches, then any of
+these `rcpt` will trigger the rule. If a setting applies no more rules are matched.
+
+Regexp rules are slow and should not be used intensively. All other rules are matched very quickly.
+The picture below describes the architecture of settings matching.
+
+[Settings match procedure](settings.png "Settings match procedure")
\ No newline at end of file
diff --git a/doc/markdown/configuration/settings.png b/doc/markdown/configuration/settings.png
new file mode 100644
index 000000000..b0677b81d
--- /dev/null
+++ b/doc/markdown/configuration/settings.png