1Mail::SpamAssassin::BayUesseSrtoCroen:t:rRiebduitse(d3M)Paeirll::DSopcaummAesnstaastsiionn::BayesStore::Redis(3)
2
3
4

NAME

6       Mail::SpamAssassin::BayesStore::Redis - Redis Bayesian Storage Module
7       Implementation
8

SYNOPSIS

DESCRIPTION

11       This module implementes a Redis based bayesian storage module.
12
13       Apache SpamAssassin v3.4.0 introduces support for keeping a Bayes
14       database on a Redis server, either running locally, or accessed over
15       network. Similar to SQL backends, the database may be concurrently used
16       by several hosts running SpamAssassin.
17
18       The current implementation only supports a global Bayes database, i.e.
19       per-recipient sub-databases are not supported. The Redis 2.6.* server
20       supports access over IPv4 or over a Unix socket, starting with Redis
21       version 2.8.0 also IPv6 is supported. Bear in mind that Redis server
22       only offers limited access controls, so it is advisable to let the
23       Redis server bind to a loopback interface only, or to use other
24       mechanisms to limit access, such as local firewall rules.
25
26       The Redis backend for Bayes can put a Lua scripting support in a Redis
27       server to good use, improving performance. The Lua support is available
28       in Redis server since version 2.6.  In absence of a Lua support, the
29       Redis backend uses batched (pipelined) traditional Redis commands, so
30       it should work with a Redis server version 2.4 (untested), although
31       this is not recommended for busy sites.
32
33       Expiration of token and 'seen' message id entries is left to the Redis
34       server. There is no provision for manually expiring a database, so it
35       is highly recommended to leave the setting bayes_auto_expire to its
36       default value 1 (i.e. enabled).
37
38       Example configuration:
39
40         bayes_store_module  Mail::SpamAssassin::BayesStore::Redis
41         bayes_sql_dsn       server=127.0.0.1:6379;password=foo;database=2
42         bayes_token_ttl 21d
43         bayes_seen_ttl   8d
44         bayes_auto_expire 1
45
46       A redis server with a Lua support (2.6 or higher) is recommended for
47       performance reasons.
48
49       The bayes_sql_dsn config variable has been hijacked for our purposes:
50
51         bayes_sql_dsn
52
53           Optional config parameters affecting a connection to a redis server.
54
55           This is a semicolon-separated list of option=value pairs, where an option
56           can be: server, password, database. Unrecognized options are silently
57           ignored.
58
59           The 'server' option specifies a socket on which a redis server is
60           listening. It can be an absolute path of a Unix socket, or a host:port
61           pair, where a host can be an IPv4 or IPv6 address or a host name.
62           An IPv6 address must be enclosed in brackets, e.g. [::1]:6379
63           (IPv6 support in a redis server is available since version 2.8.0).
64           A default is to connect to an INET socket at 127.0.0.1, port 6379.
65
66           The value of a 'password' option is sent in an AUTH command to a redis
67           server on connecting if a server requests authentication. A password is
68           sent in plain text and a redis server only offers an optional rudimentary
69           authentication. To limit access to a redis server use its 'bind' option
70           to bind to a specific interface (typically to a loopback interface),
71           or use a host-based firewall.
72
73           The value of a 'database' option can be an non-negative (small) integer,
74           which is passed to a redis server with a SELECT command on connecting,
75           and chooses a sub-database index. A default database index is 0.
76
77           Example: server=localhost:6379;password=foo;database=2
78
79         bayes_token_ttl
80
81           Controls token expiry (ttl value in SECONDS, sent as-is to Redis)
82           when bayes_auto_expire is true. Default value is 3 weeks (but check
83           Mail::SpamAssassin::Conf.pm to make sure).
84
85         bayes_seen_ttl
86
87           Controls 'seen' expiry (ttl value in SECONDS, sent as-is to Redis)
88           when bayes_auto_expire is true. Default value is 8 days (but check
89           Mail::SpamAssassin::Conf.pm to make sure).
90
91       Expiry is done internally in Redis using *_ttl settings mentioned
92       above, but only if bayes_auto_expire is true (which is a default).
93       This is why --force-expire etc does nothing, and token counts and atime
94       values are shown as zero in statistics.
95
96       LIMITATIONS: Only global bayes storage is implemented, per-user bayes
97       is not currently available. Dumping (sa-learn --backup, or --dump) of a
98       huge database may not be possible if all keys do not fit into process
99       memory.
100

METHODS

102   new
103       public class (Mail::SpamAssassin::BayesStore::Redis) new
104       (Mail::Spamassassin::Plugin::Bayes $bayes)
105
106       Description: This methods creates a new instance of the
107       Mail::SpamAssassin::BayesStore::Redis object.  It expects to be passed
108       an instance of the Mail::SpamAssassin:Bayes object which is passed into
109       the Mail::SpamAssassin::BayesStore parent object.
110
111   prefork_init
112       public instance (Boolean) prefork_init ();
113
114       Description: This optional method is called in the parent process
115       shortly before forking off child processes.
116
117   spamd_child_init
118       public instance (Boolean) spamd_child_init ();
119
120       Description: This optional method is called in a child process shortly
121       after being spawned.
122
123   tie_db_readonly
124       public instance (Boolean) tie_db_readonly ();
125
126       Description: This method ensures that the database connection is
127       properly setup and working.
128
129   tie_db_writable
130       public instance (Boolean) tie_db_writable ()
131
132       Description: This method ensures that the database connection is
133       properly setup and working. If necessary it will initialize the
134       database so that they can begin using the database immediately.
135
136   _open_db
137       private instance (Boolean) _open_db (Boolean $writable)
138
139       Description: This method ensures that the database connection is
140       properly setup and working.  It will initialize bayes variables so that
141       they can begin using the database immediately.
142
143   untie_db
144       public instance () untie_db ()
145
146       Description: Closes any open db handles.  You can safely call this at
147       any time.
148
149   sync_due
150       public instance (Boolean) sync_due ()
151
152       Description: This method determines if a database sync is currently
153       required.
154
155       Unused for Redis implementation.
156
157   expiry_due
158       public instance (Boolean) expiry_due ()
159
160       Description: This methods determines if an expire is due.
161
162       Unused for Redis implementation.
163
164   seen_get
165       public instance (String) seen_get (string $msgid)
166
167       Description: This method retrieves the stored value, if any, for
168       $msgid.  The return value is the stored string ('s' for spam and 'h'
169       for ham) or undef if $msgid is not found.
170
171   seen_put
172       public (Boolean) seen_put (string $msgid, char $flag)
173
174       Description: This method records $msgid as the type given by $flag.
175       $flag is one of two values 's' for spam and 'h' for ham.
176
177   seen_delete
178       public instance (Boolean) seen_delete (string $msgid)
179
180       Description: This method removes $msgid from the database.
181
182   get_storage_variables
183       public instance (@) get_storage_variables ()
184
185       Description: This method retrieves the various administrative variables
186       used by the Bayes process and database.
187
188       The values returned in the array are in the following order:
189
190       0: scan count base 1: number of spam 2: number of ham 3: number of
191       tokens in db 4: last expire atime 5: oldest token in db atime 6: db
192       version value 7: last journal sync 8: last atime delta 9: last expire
193       reduction count 10: newest token in db atime
194
195       Only 1,2,6 are used with Redis, others return zero always.
196
197   get_running_expire_tok
198       public instance (String $time) get_running_expire_tok ()
199
200       Description: This method determines if an expire is currently running
201       and returns the last time set.
202
203   set_running_expire_tok
204       public instance (String $time) set_running_expire_tok ()
205
206       Description: This method sets the time that an expire starts running.
207
208   remove_running_expire_tok
209       public instance (Boolean) remove_running_expire_tok ()
210
211       Description: This method removes the row in the database that indicates
212       that and expire is currently running.
213
214   tok_get
215       public instance (Integer, Integer, Integer) tok_get (String $token)
216
217       Description: This method retrieves a specificed token ($token) from the
218       database and returns its spam_count, ham_count and last access time.
219
220   tok_get_all
221       public instance (\@) tok_get (@ $tokens)
222
223       Description: This method retrieves the specified tokens ($tokens) from
224       storage and returns a ref to arrays spam count, ham count and last
225       access time.
226
227   tok_count_change
228       public instance (Boolean) tok_count_change (
229         Integer $dspam, Integer $dham, String $token, String $newatime)
230
231       Description: This method takes a $spam_count and $ham_count and adds it
232       to $tok along with updating $toks atime with $atime.
233
234   multi_tok_count_change
235       public instance (Boolean) multi_tok_count_change (
236         Integer $dspam, Integer $dham, \% $tokens, String $newatime)
237
238       Description: This method takes a $dspam and $dham and adds it to all of
239       the tokens in the $tokens hash ref along with updating each token's
240       atime with $atime.
241
242   nspam_nham_get
243       public instance ($spam_count, $ham_count) nspam_nham_get ()
244
245       Description: This method retrieves the total number of spam and the
246       total number of ham learned.
247
248   nspam_nham_change
249       public instance (Boolean) nspam_nham_change (Integer $num_spam,
250                                                    Integer $num_ham)
251
252       Description: This method updates the number of spam and the number of
253       ham in the database.
254
255   tok_touch
256       public instance (Boolean) tok_touch (String $token,
257                                            String $atime)
258
259       Description: This method updates the given tokens ($token) atime.
260
261       The assumption is that the token already exists in the database.
262
263       We will never update to an older atime
264
265   tok_touch_all
266       public instance (Boolean) tok_touch (\@ $tokens
267                                            String $atime)
268
269       Description: This method does a mass update of the given list of tokens
270       $tokens, if the existing token atime is < $atime.
271
272   cleanup
273       public instance (Boolean) cleanup ()
274
275       Description: This method perfoms any cleanup necessary before moving
276       onto the next operation.
277
278   get_magic_re
279       public instance (String) get_magic_re ()
280
281       Description: This method returns a regexp which indicates a magic
282       token.
283
284   sync
285       public instance (Boolean) sync (\% $opts)
286
287       Description: This method performs a sync of the database
288
289   perform_upgrade
290       public instance (Boolean) perform_upgrade (\% $opts);
291
292       Description: Performs an upgrade of the database from one version to
293       another, not currently used in this implementation.
294
295   clear_database
296       public instance (Boolean) clear_database ()
297
298       Description: This method deletes all records for a particular user.
299
300       Callers should be aware that any errors returned by this method could
301       causes the database to be inconsistent for the given user.
302
303   dump_db_toks
304       public instance () dump_db_toks (String $template, String $regex, Array
305       @vars)
306
307       Description: This method loops over all tokens, computing the
308       probability for the token and then printing it out according to the
309       passed in token.
310
311   backup_database
312       public instance (Boolean) backup_database ()
313
314       Description: This method will dump the users database in a machine
315       readable format.
316
317   restore_database
318       public instance (Boolean) restore_database (String $filename, Boolean
319       $showdots)
320
321       Description: This method restores a database from the given filename,
322       $filename.
323
324       Callers should be aware that any errors returned by this method could
325       causes the database to be inconsistent for the given user.
326
327   db_readable
328       public instance (Boolean) db_readable()
329
330       Description: This method returns a boolean value indicating if the
331       database is in a readable state.
332
333   db_writable
334       public instance (Boolean) db_writable()
335
336       Description: This method returns a boolean value indicating if the
337       database is in a writable state.
338
339
340
341perl v5.16.3                      2014-M0a2i-l0:7:SpamAssassin::BayesStore::Redis(3)