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
projects / rspamd.git / commitdiff