1Mail::SpamAssassin::BayUesseSrtoCroen:t:rRiebduitse(d3M)Paeirll::DSopcaummAesnstaastsiionn::BayesStore::Redis(3)
2
3
4
6 Mail::SpamAssassin::BayesStore::Redis - Redis Bayesian Storage Module
7 Implementation
8
10 This module implementes 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
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 specificed 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 perfoms 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.28.0 2018-M0a9i-l1:4:SpamAssassin::BayesStore::Redis(3)