* Add chapter about config file structure and atoms

1 files changed, 116 insertions, 0 deletions

diff --git a/doc/rspamd.texi b/doc/rspamd.texi
index 73c1cbba0..85c63c7ba 100644
--- a/doc/rspamd.texi
+++ b/doc/rspamd.texi
@@ -341,4 +341,120 @@ required to make DNS or other network request and to wait result. So modules can
 pause message's processing while waiting for some event. This is true for lua
 modules as well.
 
+@section Rspamd config file structure.
+
+Rspamd config file is placed in PREFIX/etc/rspamd.xml by default. You can
+specify other location by passing @emph{-c} option to rspamd. Rspamd config file
+contains configuration parameters in XML format. XML was selected for rather
+simple manual editing config file and for simple automatic generation as well as
+for dynamic configuration. I've decided to move rules logic from XML file to
+keep it small and simple. So rules are defined in @code{lua} language and rspamd
+parameters are defined in xml file (rspamd.xml). Configuration rules are
+included by @strong{<lua>} tag that have @strong{src} attribute that defines
+relative path to lua file (relative to placement of rspamd.xml):
+@example
+<lua src="rspamd/lua/rspamd.lua">fake</lua>
+@end example
+@noindent
+Note that it is not currently possible to have empty tags. I hope this
+restriction would be fixed in future. Rspamd xml config consists of several
+sections:
+@itemize @bullet
+@item Main section - section where main config parameters are placed.
+@item Workers section - section where workers are described.
+@item Classifiers section - section where you define your classify logic
+@item Modules section - a set of sections that describes module's rules (in fact
+these rules should be in lua code)
+@item Factors section - a section where you can set numeric values for symbols
+@item Logging section - a section that describes rspamd logging
+@item Views section - a section that defines rspamd views
+@end itemize
+
+So common structure of rspamd.xml can be described this way:
+@example
+<? xml version="1.0" encoding="utf-8" ?>
+<rspamd>
+ <!-- Main section directives -->
+ ...
+ <!-- Workers directives -->
+ <worker>
+  ...
+ </worker>
+ ...
+ <!-- Classifiers directives -->
+ <classifier>
+  ...
+ </classifier>
+ ...
+ <!-- Factors -->
+ <factors>
+  <factor name="MIME_HTML_ONLY>1.1</factor>
+  ...
+ </factors>
+ <!-- Logging section -->
+ <logging>
+  <type>console</type>
+  <level>info</level>
+  ...
+ </logging>
+ <!-- Views section -->
+ <view>
+  ...
+ </view>
+ ...
+ <!-- Modules settings -->
+ <module name="regexp">
+  <option name="test">test</option>
+  ...
+ </module>
+ ...
+</rspamd>
+@end example
+
+Each of these section would be described further in details.
+
+@section Rspamd configuration atoms.
+
+There are several primitive types of rspamd configuration parameters:
+@itemize @bullet
+@item String - common string that defines option.
+@item Number - integer or fractional number (e.g.: 10 or -1.5).
+@item Time - ammount of time in milliseconds, may has suffixes: 
+@itemize @bullet
+@item @emph{s} - for seconds (e.g. @emph{10s});
+@item @emph{m} - for minutes (e.g. @emph{10m});
+@item @emph{h} - for hours (e.g. @emph{10h});
+@item @emph{d} - for days (e.g. @emph{10d});
+@end itemize
+@item Size - like number numerci reprezentation of size, but may have a suffix:
+@itemize @bullet
+@item @emph{k} - 'kilo' - number * 1024 (e.g. @emph{10k});
+@item @emph{m} - 'mega' - number * 1024 * 1024 (e.g. @emph{10m});
+@item @emph{g} - 'giga' - number * 1024 * 1024 * 1024 (e.g. @emph{1g});
+@end itemize
+@noindent
+Size atoms are used for memory limits for example.
+@item Lists - path to dynamic rspamd list (e.g. @emph{http://some.host/some/path}).
+@end itemize
+
+While practically all atoms are rather trivial to understand rspamd lists may
+cause some confusion. Lists are widely used in rspamd for getting data that can
+be often changed for example white or black lists, lists of ip addresses, lists
+of domains. So for such purposes it is possible to use files that can be get
+either from local filesystem (e.g. @code{file:///var/run/rspamd/whitelsist}) or
+by HTTP (e.g. @code{http://some.host/some/path/list.txt}). Rspamd constantly
+looks for changes in this files, if using HTTP it also set
+@emph{If-Modified-Since} header and check for @emph{Not modified} reply. So it
+causes no overhead when lists are not modified and may allow to store huge lists
+and to distribute them over HTTP. Monitoring of lists is done with some random
+delay (jitter), so if you have many rspamd servers in cluster that are
+monitoring a single list they would come to check or download it in slightly different
+time. The two most common list formats are @emph{IP list} and @emph{domains
+list}. IP list contains of ip addresses in dot notation (e.g.
+@code{192.168.1.1}) or ip/network pairs in CIDR notation (e.g.
+@code{172.16.0.0/16}). Items in lists are separated by newline symbol. Lines
+that begin with @emph{#} symbol are considered as comments and are ignored while
+parsing. Domains list is very like ip list with difference that it contains
+domain names.
+
 @bye