Installation and configuration

Getting spmfilter

  • Configuring is done using CMake (http://www.cmake.org), version 2.4.5 is the minimum required version. This means there is no configure-script, but you need to run cmake. Use ccmake to see all available settings.

System requirements

spmfilter runs on any Unix-based/Unix-style operating system. There are only few requirements:

  • GLib2 >= 2.04
  • GMime >= 2.2
  • libesmtp >= 1.0
  • pcre >= 6.0

Installing from Source

spmfilter uses cmake instead of the autotools "configure" script. Cmake normally uses a separate build directory - follow these steps to configure,
build and install this package from source:

tar xvfz spmfilter-<VERSION>.tar.gz
cd spmfilter-<VERSION>
mkdir build
cd build
cmake ../ <configure parameters>
make
make install

If you encounter problems with cmake, it may help to set these two environment variables: 
CMAKE_INCLUDE_PATH
CMAKE_LIBRARY_PATH

Configure Parameters

Some systems require unusual options for compilation or linking that the 'cmake' script does not know about. Run './cmake -h' for details on some of the pertinent environment variables. You can give 'cmake' initial values for configuration parameters by setting variables in the command line or in the environment. Here is an example:

./cmake ../ -DPREFIX:STRING=/usr/local

Instead of defining parameters on the command line you can also create a "build.properties"-file in the source of spmfilter and define your configuration parameters there. Here is an example for a "build.properties"-file:

set(PREFIX /opt/spmfilter)
set(ENABLE_DEBUG TRUE)
set(WITHOUT_ZDB TRUE)
set(WITHOUT_DB4 TRUE)
set(WITHOUT_LDAP TRUE)

Consult the INSTALL-document which is included in the source of spmfilter for further information.

Configuration

The spmfilter.conf file is the runtime configuration file for spmfilter and controls available modules, logging, header checking and delivery options. The file consists of a global section, modules and relevant parameters for these sections. Each section begins with the name of the module in square brackets and continues until the next module begins, e.g.

[plugin]

Each Section may have parameters which are specified in the form "option = value", e.g.

[plugin]
option = value

The file is line-based -- that is, each newline-terminated line represents either a comment, a module name or a parameter. Only the first equals sign in a parameter is significant. Whitespace before or after the first equals sign is discarded. Leading, trailing and internal whitespace in module and parameter names is irrelevant. Leading and trailing whitespace in a parameter value is discarded. Internal whitespace within a parameter value is retained verbatim. Any line beginning with a hash (#) is ignored, as are lines containing only whitespace. Any line ending in a \ is "continued" on the next line in the customary UNIX fashion. The values following the equals sign in parameters are all either a string (no quotes needed) or a boolean, which may be given as true/false. Case is not significant in boolean values, but is preserved in string values.

The [global] section

Parameters in this section are global and do not affect any modules.

  • engine
    The "engine" option allows you to specify the spmfilter engine. It's possible to switch the engine for receiving mails. There are two engines in spmfilter for receiving emails:
    smtpd This engine allows to inject emails via smtp to spmfilter. But please note, with this engine, spmfilter has to be started with inetd, Postfix or similar TCP server programs.
    pipe The pipe engine lets you inject emails via shell pipe to spmfilter. This is usefully, when you don't need a full smtp server.
  • debug
    Enables verbose debugging output. Debugging output will be written to the configured syslog facility, there are to values for the debug-option:
    true debugging enabled
    false debugging disabled (default)
  • modules
    Specifies all modules, which will be loaded at runtime. All modules will be process in the same order, as listed. Modules names have to be separated by a semicolon.
  • module_fail
    If one module fails, the behaviour of spmfilter can be configured. Possible values are:
    1 proceed and ignore
    2 cancel further processing and return permanent error
    3 cancel further processing and return temporary error (default)
  • nexthop
    This parameter specifies the final destination, after a mail is processed by spmfilter. The value can be a hostname or IP address, with a port number, e.g. localhost:2525 to send filtered mails to localhost at port 2525.
  • backend
    Define lookup backend, this can be either sql or ldap. Every backend has it's own config section, sql and ldap.
  • backend_connection
    If there are multiple server configured in the specified backend, it's possible to define a failover or load-balancing behaviour. Possible values are:
    balance when you configure the backend profile for load balancing, spmfilter distributes connections across the list of hosts. If the actual host is not reachable, spmfilter switches back to failover configuration.
    failover when you configure the backend profile for failover, spmfilter fails over to the next host in the list if it cannot connect to the first host.
  • add_header
    If true, spmfilter will add a header with the processed modules.
  • max_size
    The maximal size in bytes of a message
  • tls_enable
    Enable TLS for client connections. If set to 2 the protocol will quit rather than transferring any messages if the STARTTLS extension is not available.
    0 disable starttls
    1 use STARTTLS, if available (default)
    2 require STARTTLS
  • tls_pass
    Passphrase for SSL certificate, if needed.

The [smptd] section

Parameters in this section affect the smtpd engine and smtp delivery.

  • nexthop_fail_code
    If the delivery to the final destination fails for any reason, this code is used as response to the sending MTA (default 451).
  • nexthop_fail_msg
    If the delivery to the final destination fails for any reason, this message is used as reponse for the sending MTA. (default "Requested action aborted: local error in processing").

If you ever need to define SMTP response messages for other error codes, such as 500, than it's possible to configure
these in the smtpd section. The following example will configure spmfilter to send the message "Customized error message"
with a 500 error code:

[smtpd]
500=Customized error message.

The [sql] section

Parameters in this section affect the sql backend configuration.

  • drvier
    SQL database driver. Supported drivers are mysql, pgsql, sqlite.
  • host
    List of available database hosts, separated by a semicolon. Set to localhost if database is on the same host as spmfilter.
  • port
    TCP/IP port of database host, if the database is running on a non-standard port.
  • name
    Database name, or path to database if driver is set to sqlite.
  • user
    Database username.
  • pass
    Database password.
  • encoding
    Encoding to match database/table encoding, e.g., latin1, utf8
  • user_query
    If you store user information within a SQL database in your network infrastructure, you can configure spmfilter to query your SQL database to determine either a user exists in your system or not. This parameter supports the following '%' expansions:
    %s replaced by the full email address.
    %u replaced by the local part of the email address
    %d replaced by the domain part of the email address.

Example:

[sql]
driver = mysql
host = localhost
name = mail
user = user
pass = pass
user_query = SELECT address FROM users WHERE addr='%s'

The [ldap] section

Parameters in this section affect the ldap backend configuration.

  • host
    List of available LDAP hosts, separated by a semicolon. Set to localhost if LDAP server is on the same host as spmfilter.
  • binddn
    Bind DN of LDAP user
  • bindpw
    Password of LDAP user
  • base
    Base DN (distinguishing name) for the LDAP server.
  • scope
    LDAP search scope, either subtree, onelevel or base.
  • user_query
    If you store user information within a LDAP directory in your network infrastructure, you can configure spmfilter to query your LDAP directory to determine either a user exists in your system or not. This parameter supports the following '%' expansions:
    %s replaced by the full email address.
    %u replaced by the local part of the email address
    %d replaced by the domain part of the email address.

Example:

[ldap]
host = localhost
binddn = ou=users,dc=example,dc=org
bindpw = password
base =  ou=users,dc=example,dc=org
scope = subtree
user_query = (&(email=%s)(accountstatus=active))

Example

What follows is a sample configuration file:

[global]
engine = smtpd
debug = false
modules=clamav
module_fail = 3
nexthop = localhost:2525
max_size = 0
tls_enable = 1
backend = sql
backend_connection = balance

[sql]
driver = postgresql
host = 192.168.0.1;192.168.0.2
name = maildb
user = mail
pass = password
user_query = SELECT * FROM accounts WHERE email='%s'
Powered by SpaceNet