Installation and configuration

Getting spmfilter

  • Configuring is done using CMake (, version 2.6 is the minimum required version. This means there is no configure-script, but you need to run cmake. Use cmake to see all available settings.

System requirements

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

Basic Installation

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 install

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


By default, make install installs the package's commands under /usr/local/sbin, include files under /usr/local/include, etc. You can specify an installation prefix other than /usr/local by giving cmake the option -DPREFIX:STRING=/opt

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 the file "" in the source and define your configuration parameters there. Here is an example for "":

set(PREFIX /opt/spmfilter)


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.


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

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. 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.
    • 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.
  • modules
    Specifies the modules, which will be loaded at runtime. All modules will be process in the same order, as listed. Module names have to be separated by a colon.
  • module_fail
    If one module fails, there are 3 options:
    • 1 = proceed and ignore
    • 2 = cancel further processing and return permanet error
    • 3 = cancel further processing and return temporary error (default)
  • nexthop
    The nexthop 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.
  • queue_dir
    Path to queue directory
  • 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.
  • lookup_persistent If true, spmfilter will use persistent connections to sql or ldap server.
  • 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
  • pid_file
    The pid_file option sets the file to which the daemon records the process id.
  • bind_ip
    The IP addresses the daemon will bind to
  • bind_port
    Port to bind to
  • max_childs
    Maximum number of child processes allowed
  • spare_childs
    Unused children to always have available
  • listen_backlog
    The maximum length of the queue of pending connections
  • user/group
    Root privs are used to open a port, then privs are dropped down to the user/group specified here
  • syslog_facility The syslog facility of spmfilter logging

The [smptd] section

  • nexthop_fail_code
    The fail code is used as response code for the sending MTA, if delivery to nexthop fails (default 451)
  • nexthop_fail_msg
    If delivery to nexthop fails, this message will be reported to the sending MTA with fail code.

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:

500=Customized error message

The [sql] section

  • driver
    SQL database driver. Supported drivers are mysql, pgsql, sqlite.
  • host
    List of available database hosts, separated by a colon. Set to localhost if the database runs on the same host as the spmfilter.
  • port
    Database 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
  • max_connections
    Maximum number of connections to database server
  • user_query
    user_query setting contains the sql query to look up user information in your sql database.

    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.


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

The [ldap] section

  • host
    List of available LDAP hosts, separated by a colon. Set to localhost if the LDAP server runs on the same host as the spmfilter.
  • port
    LDAP Port
  • 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
    user_query setting contains the ldap query to look up user information in your directory.

    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.


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))

Sample configuration

What follows is a sample configuration file:

engine = smtpd
debug = false
module_fail = 3
nexthop = localhost:2525
max_size = 0
tls_enable = 1
backend = sql
backend_connection = balance
bind_ip =
bind_port = 10025
spare_childs = 5
max_childs = 15
pid_file = /var/run/
user = nobody
group = mail
driver = postgresql
host =;
name = maildb
user = mail
pass = password
user_query = SELECT * FROM accounts WHERE email='%s'
host =
port = 3310
add_header = true