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

DESCRIPTION

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

METHODS

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