Getting spmfilter
- Configuring is done using CMake (http://www.cmake.org), 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
make install
If you encounter problems with cmake, it may help to set these two environment variables:
CMAKE_INCLUDE_PATH
CMAKE_LIBRARY_PATH
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 "build.properties" in the source and define your configuration parameters there. Here is an example for "build.properties":
set(PREFIX /opt/spmfilter)
set(ENABLE_DEBUG TRUE)
set(WITHOUT_ZDB TRUE)
set(WITHOUT_DB4 TRUE)
set(WITHOUT_LDAP TRUE)
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.
Each Section may have parameters which are specified in the form "option = value", e.g.
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:
[smtpd]
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.
- name
Database name, or path to database if driver is set to sqlite.
- encoding
Encoding to match database/table encoding, e.g., latin1, utf8
- max_connections
Maximum number of connections to database server
Example:
[sql]
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.
- 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.
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))
Sample configuration
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
bind_ip = 127.0.0.1
bind_port = 10025
spare_childs = 5
max_childs = 15
pid_file = /var/run/spmfilter.pid
user = nobody
group = mail
[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'
[clamav]
host = 127.0.0.1
port = 3310
add_header = true