.\" $Id: spamass-milter.1.in,v 1.21 2014/08/15 02:25:31 kovert Exp $
.Dd July 25, 2001
.Os
.Dt SPAMASS_MILTER 8
.Sh NAME
.Nm spamass-milter
.Nd sendmail milter for passing emails through SpamAssassin
.Sh SYNOPSIS
.Nm
.Fl p Ar socket
.Op Fl b Ns | Ns Fl B Ar spamaddress
.Op Fl C rejectcode
.Op Fl d Ar debugflags
.Op Fl D Ar host
.Op Fl e Ar defaultdomain
.Op Fl f
.Op Fl i Ar networks
.Op Fl m
.Op Fl M
.Op Fl P Ar pidfile
.Op Fl r Ar nn
.Op Fl r rejectmsg
.Op Fl u Ar defaultuser
.Op Fl x
.Op Fl S /path/to/sendmail
.Op Fl - Ar spamc flags ...
.Sh DESCRIPTION
The
.Nm
utility is a sendmail milter that checks and modifies incoming email
messages with SpamAssassin.
.Pp
The following options are available:
.Bl -tag -width "indent"
.It Fl p Ar socket
Specifies the pathname of a socket to create for communication with
.Nm sendmail .
If it is removed,
.Nm sendmail
will not be able to access the milter.
This may cause messages to bounce, queue, or be passed through
unmiltered, depending on the parameters in
.Nm sendmail Ns 's .cf file.
.It Fl b Ar spamaddress
Redirects tagged spam to the specified email address.
All envelope recipients are removed, and inserted into the message as
.Ql X-Spam-Orig-To:
headers.
.It Fl B Ar spamaddress
Same as
.Fl b ,
except the original recipients are retained.
Only one of
.Fl b
and
.Fl B
may be used.
.It Fl C Ar rejectcode
Mail that is rejected is rejected by default with a 5.7.1 code.  This option
allows that to be overridden.  See also, -R
.Fl S
option.
.It Fl d Ar debugflags
Enables logging. 
.Ar debugflags 
is a comma-separated list of tokens:
.Bl -tag -width "indent"
.It func
Entry and exit of internal functions.
.It misc
Other non-verbose logging.
.It net
Lookups of the ignored netblocks list.
.It poll
Low-level I/O to the child spamc process.
.It rcpt
Recipient processing.
.It spamc
High-level I/O to the child spamc process.
.It str
Calls to field lookup and string comparison functions.
.It uori
Calls to the update_or_insert function.
.It 1
(historical) Same as 
.Ar func,misc .
.It 2
(historical) Same as
.Ar func,misc,poll .
.It 3
(historical) Same as
.Ar func,misc,poll,str,uori .
.El
.It Fl D Ar host
Connects to a remote spamd server on 
.Ar host , 
instead of using one on localhost.
This option is deprecated; use 
.Fl - Fl d Ar host 
instead.
.It Fl e Ar defaultdomain
Pass the full user@domain address to spamc.
The default is to pass only the username part on the assumption that
all users are local.
This flag is useful if you are using an SQL (or other username) backend
with spamassassin and have listed the full address there.
If the recipient name has no domain part (if the recipient is on the
local machine for example),
.Ar defaultdomain 
is added.
Requires the
.Fl u
flag.
.It Fl f
Causes
.Nm
to fork into the background.
.It Fl i Ar networks
Ignores messages if the originating IP is in the network(s) listed.
The message will be passed through without calling SpamAssassin at all.
.Ar networks
is a comma-separated list, where each element can be either an IP address 
(nnn.nnn.nnn.nnn), a CIDR network (nnn.nnn.nnn.nnn/nn), or a network/netmask
pair (nnn.nnn.nnn.nnn/nnn.nnn.nnn.nnn).
Multiple
.Fl i
flags will append to the list.
For example, if you list all your internal networks, no outgoing emails
will be filtered.
.It Fl m
Disables modification of the 
.Ql Subject: 
and 
.Ql Content-Type: 
headers and
message body.
This is useful when SpamAssassin is configured with
.Ql "defang_mime 0"
and 
.Ql "report_header 1" ,
or when SA is simply used to add headers for postprocessing later.
Updating the body through the milter interface can be slow for large
messages.
.It Fl M
Like
.Fl m ,
but also disables creation of any SpamAssassin
.Ql X-Spam-* 
headers as well.
Both tagged and untagged mail gets passed through unchanged.
To be useful, this option should be used with the
.Fl r ,
.Fl b , 
or
.Fl B
flags.
If 
.Fl b
is used, the 
.Ql X-Spam-Orig-To:
headers will still be added.
.It Fl P Ar pidfile
Create the file
.Ar pidfile ,
containing the processid of the milter.
.It Fl r Ar nn
Reject scanned email if it greater than or equal to
.Ar nn .
If 
.Ar -1 ,
reject scanned email if SpamAssassin tags it as spam (useful if you
are also using the
.Fl u
flag, and users have changed their required_hits value).
.Pp
For example, if you usually use procmail to redirect tagged email into
a separate folder just in case of false positives, you can use
.Fl r Ar 15
and reject flagrant spam outright while still receiving low-scoring
messages.
.It Fl R Ar rejecttext
Mail that is rejected is rejected with the message "Blocked by SpamAssassin".
This option allows the user to call with a different message, instead.   See
also, the
.Fl C
option
.It Fl S Ar /path/to/sendmail
This option is used in conjunction with the -x option to specify a path
to sendmail if the default compiled in choice is not satisfactory.
.It Fl u Ar defaultuser
Pass the username part of the first recipient to spamc with the 
.Fl u 
flag.
This allows user preferences files to be used.
If the message is addressed to multiple recipients, the username
.Ar defaultuser
is passed instead.
.Pp
Note that 
.Nm
does not know whether an email is incoming or outgoing, so a message
from
.Aq user1@localdomain.com 
to 
.Aq user2@yahoo.com 
will make 
.Nm
pass 
.Fl u Ar user2
to spamc.
.It Fl x
Pass the recipient address through 
.Nm sendmail Fl bv ,
which will perform virtusertable and alias expansion.
The resulting username is then passed to spamc.
Requires the
.Fl u
flag.  The spamass-milter configuration process does its
best to find sendmail, but it is possible to override this compiled-in
setting via the
.It Fl - Ar spamc flags ...
Pass all remaining options to spamc. 
This allows you to connect to a remote spamd with
.Fl d
or 
.Fl p .
.El
.Sh FILES
.Bl -tag -width "indent"
.It Pa @SPAMC@
client interface to SpamAssassin
.El
.Sh SEE ALSO
.Xr spamassassin 1 ,
.Xr spamd 1
.Sh AUTHORS
.An "Georg C. F. Greve" Aq greve@gnu.org
.An "Dan Nelson" Aq dnelson@allantgroup.com
.An "Todd Kover" Aq kovert@omniscient.com