.TH opendkim-spam 1 "The Trusted Domain Project"
.SH NAME
.B opendkim-spam
\- DKIM filter spam correlation tool
.SH SYNOPSIS
.B opendkim-spam
[options]
.SH DESCRIPTION
.B opendkim-spam
accepts a regular format message (RFC5322) on standard input and uses it
to update a local SQL database being updated by
.I opendkim(8)
with an indiciation that a user believes the input message is spam or
otherwise abusive.  This feedback is important input toward developing
DKIM-based domain reputation systems.

The tool is intended to be used directly from within shell-based mail readers 
such as
.I alpine(1)
or
.I mutt(1)
using a "pipe" command, which feeds the message being read to the specified
program.

This tool is experimental.  If the experiment proves useful, the
feedback could be used as an input stream to a larger-scale collaborative
feedback system that can be used to identify sources of signed mail
that have good reputations.
.SH OPTIONS
.TP
.I -b backend
Specifies the style of backend database in use.  The default is
"yes".
.TP
.I -c file
Names a configuration file from which operating parameters will be read.
The configuration file contains entries of the form "key value", one per
line.  Empty lines or lines beginning with a hash ("#") character are
ignored.  Command line equivalents for the configuration file are available
as runtime overrides.
The default configuration file location is
.I /etc/opendkim-spam.conf.
See the CONFIGURATION FILE section for a list of known values.
.TP
.I -f
Run in the foreground rather than executing as a background process.
Intended mainly for debugging.
.TP
.I -d name
Indicates the name of the database to be accessed.  The default is
"opendkim".
.TP
.I -h host
Specifies the host where the database server is running.  The default
is "localhost".
.TP
.I -o file
Writes an update record to an OpenDKIM statistics file rather than directly
to a database.  There is no default.  Note that if this option is used,
all database-specific options are ignored.
.TP
.I -p password
Specifies the password to be used when authenticating to the database.
The default is "opendkim".
.TP
.I -P port
Specifies the port number where the database server is listening.  The
default depends on which backend is in use.
.TP
.I -r reporter
Provides the name of the site reporting the spam.  If not provided, an attempt
will be made to extract this information from the topmost Received header
field from the input message.
.TP
.I -s column
Names the database column whose value should be incremented as a result
of this user action.  The default is "spam".
.TP
.I -u user
Identifies the database user to be used when connecting to the database.
The default is "opendkim".
.TP
.I -v
Requests verbose output.  Can be specified multiple times for more and
more information.
.TP
.I -V
Print version number and exit.
.SH CONFIGURATION FILE
The configuration file used by
.B opendkim-spam(1)
is expected to be a text file.  Empty lines or lines starting with a
hash ("#") character are ignored.  All other lines should consist of a
parameter name followed by one or more whitespace characters, then followed
by its intended value.

Parameters generally match command line options (specified above), but when
present the command line options override the configuration file options.  The
list of configuration file parameters and their command line equivalents
are as follows; see above for descriptions:
.TP
.I Background
\-f (opposite meaning)
.TP
.I DatabaseBackend
\-b
.TP
.I DatabaseName
\-d
.TP
.I DatabaseHost
\-h
.TP
.I DatabasePassword
\-p
.TP
.I DatabasePort
\-P
.TP
.I DatabaseSpamColumn
\-s
.TP
.I DatabaseUser
\-u
.TP
.I ReporterID
\-r
.TP
.I SkipReceived
An integer that defines a number of Received fields that should be skipped
while searching for the one that was also seen by
.B opendkim(8)
so that this command refers to the same Received field.  Defaults to 0.
.TP
.I StatisticsFile
\-o
.SH NOTES
It is possible to compile this application without SQL support, in which
case only the
.I StatisticsFile
setting has any meaning (and, in fact, it is required in that case).
.SH VERSION
This man page covers the version of
.I opendkim-spam
that shipped with version 2.11.0 of
.I OpenDKIM.
.SH COPYRIGHT
Copyright (c) 2011, 2012, The Trusted Domain Project.  All rights reserved.
.SH SEE ALSO
.I alpine(1),
.I mutt(1),
.I opendkim(8)
.P
RFC6376 - DomainKeys Identified Mail