From 3ebf213049f937b3fb4db45797f1a8861c0f94a6 Mon Sep 17 00:00:00 2001 From: Vsevolod Stakhov Date: Tue, 11 May 2010 05:10:38 +0400 Subject: [PATCH] * Add chapter about config file structure and atoms --- doc/rspamd.texi | 116 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) 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{} tag that have @strong{src} attribute that defines +relative path to lua file (relative to placement of rspamd.xml): +@example +fake +@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 + + + + ... + + + ... + + ... + + + ... + + ... + + + + + ... + + ... + +@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 -- 2.39.5