Table of Contents

Step by step ... or ... Quick Start

Beginning : step by step

  1. Compiling
  2. Installing / Upgrading
  3. Where things are installed
  4. Minimal configuration
  5. Creating databases
  6. Creating tables
  7. Logging
  8. Launching it for the first time
  9. Monitoring

Compiling

Unless you have a really good reason to not use default configuration options, the only thing you need to do is to download ze-filter tarball, uncompress it, configure it and compile it…

$ tar xzf ze-filter-1.11.0.tgz
$ cd ze-filter-1.11.0
$ ./configure
$ make

configure options

Installing and Upgrading

If you're installing it for the first time, the only thing to do is :

$ su
# make install

and everything will be installed and needed directories will be created with the right owner and rights. You can skip now to the configuration section.

If you're upgrading an existing installation, you'll probably need to update some configuration files. You MUST :

  1. read the ChangeLog file, to understand what changed since the last installed version
  2. read the README-X.YY file - since 1.11 version, this file contains main hints and changes
  3. take a look at /etc/ze-filter.cf.running file - this file shows how the new ze-filter binary understands your current configuration file, and can show some errors (new undefined or old removed options). If everything is right, or after some configuration changes, you'll probably change current configuration file by this one, as shown bellow :
$ su
# service sendmail stop
# service stop
# make install
# cp /etc/ze-filter/ze-filter.cf.running /etc/ze-filter/ze-filter.cf
# service ze-filter start
# service sendmail start

… and everything is done !

If you're upgrading an old version, it's better to use make upgrade instead of make install, as some data may need to be updated/upgraded. make upgrade will :
  • dump working databases in /var/ze-filter/wdb, using old binaries
  • install new release using make install
  • update some configuration files needing to be updated
  • restore contents of working databases using previously dumped data.

Where things are installed

Installation process create directories and put things in many places :

Minimal Configuration

ze-filter

If you do nothing, ze-filter will only handle messages without any filtering. This very minimal configuration is useful if what you want to do is only to monitor your mailserver : connections/messages/Mbytes handled a day, connection rates, …

The first thing to do is to define your known networks. This happens in ze-policy database.

You'll probably add some lines like these one : Put your the subnet of your local servers in LOCAL, we will give them better privilege (no greylisting, better rate limits). Then put your clients in DOMAIN and last, some friends server in FRIEND. The other SMTP clients will fall in UNKNOWN NetClass

# Our private local network
NetClass:10                LOCAL
# Our domain public IP addresses 
NetClass:199.180.10        DOMAIN
# Our MXs
NetClass:199.180.10.1      LOCAL
NetClass:199.180.10.2      LOCAL
# 
NetClass:128.12.12.33      FRIEND

You can use local or inet sockets to enable communications between ze-filter and sendmail. This is done by the following lines at /etc/ze-filter/ze-filter.cf file :

# SOCKET
#     Communication socket between sendmail and ze-filter
#  Syntax : inet:PORT@HOSTNAME | local:SOCKET_PATH
SOCKET                     local:/var/run/ze-filter/ze-filter.sock

For the first time, you must connect the filter to sendmail and let it run without any feature enabled to verify if it's stable. If this is the case, you can begin enabling each wanted feature.

sendmail

You must tell sendmail that he has to use ze-filter to filter incoming connections/messages. You can do that at sendmail.cf file.

Prefered way to do that is to add some lines to sendmail.mc file used to generate sendmail.cf file, but you really know what you do, you can add some other lines to sendmail.cf file.

smconfig directory inside ze-filter distribution directory tree contains two files : milter.mc and milter.cf with the content to be added to sendmail.mc or sendmail.cf file.

dnl
dnl Uncomment one of the following lines
INPUT_MAIL_FILTER(`ze-filter',`S=inet:2000@localhost, T=C:2m;S:20s;R:20s;E:5m')
dnl
dnl INPUT_MAIL_FILTER(`ze-filter',`S=local:/var/run/ze-filter/ze-filter.sock, T=C:2m;S:20s;R:20s;E:5m')
dnl
define(`confINPUT_MAIL_FILTERS',`ze-filter')
define(`confMILTER_LOG_LEVEL',`9')dnl  
dnl
dnl
define(`confMILTER_MACROS_CONNECT', confMILTER_MACROS_CONNECT``, v, {client_resolve}, {client_name}, {client_ptr}'')dnl
define(`confMILTER_MACROS_HELO',    confMILTER_MACROS_HELO)dnl
define(`confMILTER_MACROS_ENVFROM', confMILTER_MACROS_ENVFROM)dnl
define(`confMILTER_MACROS_ENVRCPT', confMILTER_MACROS_ENVRCPT``, {nrcpts}, {nbadrcpts}'')dnl
define(`confMILTER_MACROS_EOM',     confMILTER_MACROS_EOM``, {msg_id}'')dnl

Postfix

You can use ze-filter with postfix if you're running postfix version 2.4 and newers.

If you're still running postfix version 2.3.X, you can use ze-filter too, but not all features are available. Mainly, postfix versions older than 2.4 can't replace message body.
#
# main.cf configuration options
#
smtpd_milters = unix:/var/run/ze-filter/ze-filter.sock
milter_protocol = 6
 
milter_connect_macros = j {daemon_name} v {client_name} _ {client_addr} 
                        {client_ptr} {client_resolve} {daemon_addr} 
                        {daemon_name} {daemon_port} {if_addr} {if_name}
milter_data_macros = i {msg_id}
milter_end_of_data_macros = i {msg_id}
milter_helo_macros = {tls_version} {cipher} {cipher_bits} {cert_subject} 
                     {cert_issuer}
milter_macro_daemon_name = $myhostname
milter_macro_v = $mail_name $mail_version
milter_mail_macros = i {auth_type} {auth_authen} {auth_author} {mail_addr} 
                     {auth_ssf} {mail_addr} {mail_host} {mail_mailer}
milter_rcpt_macros = i {rcpt_addr} {nrcpts} {rcpt_host} {rcpt_mailer}
milter_unknown_command_macros =
 
milter_command_timeout = 30s
milter_connect_timeout = 30s
milter_content_timeout = 40s
 
milter_default_action = tempfail
non_smtpd_milters =

Creating constant databases - the first time

ze-filter needs four constant databases : ze-policy.db, ze-urlbl.db, ze-rcpt.db and ze-bayes.db. Even if you haven't configured ze-filter to use them, they must be there. ze-filter absolutely needs, at least, ze-policy.db.

When installing ze-filter for the first time, please check that these files exist and if not create them at least as empty files (you can use touch).

After creating these these four files, you have to launch a make inside /var/ze-filter/cdb directory to create the .db versions.

Creating tables - the first time

When you install ze-filter for the first time, this installation procedure will create default needed tables. You can then modify them to fit your needs.

Each time ze-filter will be upgraded, default tables will be installed with the extension .org.

Logging

Default ze-filter logging is done by syslog, using LOCAL5 facility.

You'll probably need to configure /etc/syslog.conf to do that in the good place.

local5.*                    -/var/log/ze-filter.log
Don't forget to setup some way to rotate ze-filter logs. ze-filter.log file may be rotated using logadm (Solaris), logrotate (Linux) or newsyslog (FreeBSD). Log files inside /var/ze-filter directory may be rotated using ze-rotate script.

Launching

Start up script is installed inside /usr/local/etc/rc.d under FreeBSD or inside /etc/init.d directories. Don't forget to create a symbolic link to it inside /etc/rc3.d. Under some Linux distributions (e.g., Fedora, RedHat, you can use /sbin/chkconfig to add it.

Monitoring

Have a look here