view release on metacpan or  search on metacpan

lib/Mail/SpamAssassin/BayesStore/Redis.pm  view on Meta::CPAN

# <@LICENSE>
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to you under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at:
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# </@LICENSE>

=head1 NAME

Mail::SpamAssassin::BayesStore::Redis - Redis Bayesian Storage Module Implementation

=head1 DESCRIPTION

This module implements a Redis based bayesian storage module with support
for separate read and write servers.

Apache SpamAssassin v3.4.0 introduces support for keeping
a Bayes database on a Redis server, either running locally, or accessed
over network. Similar to SQL backends, the database may be concurrently
used by several hosts running SpamAssassin.

The current implementation only supports a global Bayes database, i.e.
per-recipient sub-databases are not supported. The Redis server supports
access over IPv4 or over a Unix socket, and since Redis version 2.8.0 also
IPv6 is supported. Bear in mind that Redis server only offers limited access
controls, so it is advisable to let the Redis server bind to a loopback interface
only, or to use other mechanisms to limit access, such as local firewall rules.

The Redis backend for Bayes can put a Lua scripting support in a Redis
server to good use, improving performance. The Lua support is available
in Redis server since version 2.6. In absence of a Lua support, the Redis
backend uses batched (pipelined) traditional Redis commands, so it should
work with a Redis server version 2.4 (untested), although this is not
recommended for busy sites.

Expiration of token and 'seen' message id entries is left to the Redis
server. There is no provision for manually expiring a database, so it is
highly recommended to leave the setting bayes_auto_expire to its default
value 1 (i.e. enabled).

The module supports separate read and write servers, allowing for Redis
replication-based scaling and high availability. Multiple read servers can
be configured, with automatic failover if one becomes unavailable.

Example configuration:

  # Basic configuration with single server
  bayes_store_module      Mail::SpamAssassin::BayesStore::Redis
  bayes_redis_write_server server=127.0.0.1:6379;password=foo
  bayes_redis_read_servers server=127.0.0.1:6379;password=foo
  bayes_redis_database    2
  bayes_token_ttl         21d
  bayes_seen_ttl          8d
  bayes_auto_expire       1

  # Configuration with primary/replica setup
  bayes_store_module      Mail::SpamAssassin::BayesStore::Redis
  bayes_redis_write_server server=redis-master.example.com:6379;password=foo
  bayes_redis_read_servers server=redis-replica1.example.com:6379;password=foo,server=redis-replica2.example.com:6379;password=foo
  bayes_redis_database    2
  bayes_redis_prefix      bayes:
  bayes_token_ttl         21d
  bayes_seen_ttl          8d
  bayes_auto_expire       1

A redis server with a Lua support (2.6 or higher) is recommended
for performance reasons.

The following configuration options are available:

  bayes_redis_read_servers

    Comma-separated list of Redis read servers with connection parameters.
    Each server specification is a semicolon-separated list of option=value
    pairs.

    Example: server=replica1.example.com:6379;password=foo,server=replica2.example.com:6379;password=foo

  bayes_redis_write_server

    Redis write server with connection parameters as a semicolon-separated
    list of option=value pairs.

    Example: server=master.example.com:6379;password=foo

  bayes_redis_database

    Database index to use (default: 0). This is passed to a Redis server
    with a SELECT command on connecting and chooses a sub-database index.

  bayes_redis_password

    Password for authentication with Redis servers. This can be overridden
    in individual server specifications.