.\" $Id: relaydb.8,v 1.9 2003/11/20 18:41:34 dhartmei Exp $
.\"
.\" Copyright (c) 2003 Daniel Hartmeier.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd Jan 8, 2003
.Dt RELAYDB 8
.Os
.Sh NAME
.Nm relaydb
.Nd spam relay database
.Sh SYNOPSIS
.Nm relaydb
.Op Fl 46bdlnrvw
.Op Fl B Ar [+-]num
.Op Fl W Ar [+-]num
.Op Fl m Ar [+-]days
.Op Fl f Ar filename
.Op Fl i Ar filename
.Op Fl t Ar filename
.Sh DESCRIPTION
.Nm
is a mail header analyzer that builds a database of IP addresses either
known as legitimate senders or spammers.
.Pp
.Nm
doesn't itself classify mails as legitimate or spam, that decision needs
to be reached through other means.
Neither does
.Nm
block spam itself.
It merely provides a list of IP addresses to block through other means,
like
.Xr spamd 8
and
.Xr pf 4 .
.Pp
.Nm
reads a single mail from stdin, analyzes the Received: header lines and
updates blacklist and whitelist counters for each IP address.
.Pp
The options are as follows:
.Pp
.Bl -tag -width Ds
.It Fl 4
Use only IPv4 addresses, ignoring IPv6 addresses.
.It Fl 6
Use only IPv6 addresses, ignoring IPv4 addresses.
.It Fl b
Blacklist the sender of the mail.
.It Fl w
Whitelist the sender of the mail.
.It Fl B Ar [+-]num
Match addresses based on blacklist counter.
+num matches counters larger than num, -num matches
counters smaller than num, num matches counters equal
to num.
.It Fl W Ar [+-]num
Match addresses based on whitelist counter.
.It Fl d
Delete addresses from the database that match the criteria
imposed by flags
.Fl 46bwBWm .
.It Fl f Ar filename
Database file, defaults to $HOME/.relaydb if not specified.
.It Fl i Ar filename
Import a plain text file into the database.
The format must match that of
.Nm
.Fl vl
output, only the last field (last modification time) is
optional, defaulting to the current time.
.It Fl l
List the IP addresses of the database.
If 
.Fl b
is specified, only hosts considered spammers are listed.
If
.Fl w
is specified, only hosts considered non-spammers are listed.
Otherwise, all hosts are listed.
.It Fl m Ar [+-]num
Match addresses based on their last modification time.
The last modification time of an address is set to the
current time when the address is inserted and whenever
an address' counters are changed.
+num matches last modified more than num days ago,
-num matches less than num days ago, and num matches
exactly num days ago.
.It Fl n
Don't read past the first Received: header.
By default,
.Nm
will process all Received: headers as long as the previous header contained
an address of a host in the whitelist, trusting the previous host to not
have inserted a fake Received: header.
This is useful to blacklist senders that send spam through mailing list
servers (or other known-good relays), but allows an attacker to first
establish a new whitelist entry for a new host, then send spam from the
same address, faking further Received: headers, to cause relaydb to blacklist
those addresses, causing a denial of service for these addresses.
.It Fl r
Revert a previously made decision.
For instance, if a mail has been run through
.Nm
.Fl b
by mistake, running the same mail through
.Nm
.Fl rb
will correct the mistake.
This merely reverts the first run, it doesn't count the mail as the opposite
type.
To achieve this, the same mail has to be run through
.Nm
.Fl w
additionally.
.It Fl t Ar filename
Parse a spamd syslog file and increase the last modification time
of matching database entries to the time of the most recent spamd
connection.
The file is expected to have the following format, other lines
are ignored:
.Bd -literal
Nov 20 09:32:19 host spamd[123]: 12.24.56.78: connected (1)
.Ed
.It Fl v
Produce more verbose output.
.El
.Pp
Using
.Pa procmail
recipes like the following ones, each incoming mail can
be run through a spam classifier
.Pq SpamAssassin , for instance
which tags any detected spam with a X-Spam-Status: header.
After tagging, all mails are piped through
.Nm 
with either the
.Fl b
or
.Fl w
option, to update the database.
.Pp
.Bd -literal -offset indent -compact
  :0fw
  | /usr/local/bin/spamc
  :0c
  * ^X-Spam-Status: Yes
  | /usr/local/bin/relaydb -b
  :0:
  * ^X-Spam-Status: Yes
  in-x-spam
 
  :0c
  | /usr/local/bin/relaydb -w
.Ed
.Sh EXAMPLES
.Bd -literal
  analyze mail and increase sender's blacklist counter
  $ cat mail | relaydb -b

  undo mistaken blacklist counter increment
  $ cat mail | relaydb -rb

  list whitelist entries which have blacklist counters > 100
  $ relaydb -vlw -B +100

  update last modification times of hosts that connected to
  spamd recently
  $ relaydb -t /var/log/daemon

  delete all blacklist entries with zero whitelist counters
  that haven't been updated within a month
  $ relaydb -db -W 0 -m +30
.Ed
.Sh SEE ALSO
.Xr pf.conf 5 ,
.Xr pfctl 8 ,
.Xr spamd 8 ,
.Xr spamd-setup 8
.Sh HISTORY
The
.Nm
command appeared in
.Ox 3.3 .