<
@LICENSE
>
Copyright 2004 Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the
"License"
);
you may not
use
this file except in compliance
with
the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an
"AS IS"
BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License
for
the specific language governing permissions and
limitations under the License.
</
@LICENSE
>
=head1 NAME
spamc - client
for
spamd
=head1 SYNOPSIS
=over
=item spamc [options] < message
=back
=head1 DESCRIPTION
Spamc is the client half of the spamc/spamd pair. It should be used in place
of C<spamassassin> in scripts to process mail. It will
read
the mail from
STDIN, and spool it to its connection to spamd, then
read
the result back and
print
it to STDOUT. Spamc
has
extremely low overhead in loading, so it should
be much faster to load than the whole spamassassin program.
See the F<README> file in the F<spamd> directory of the SpamAssassin
distribution
for
more details.
=head1 OPTIONS
All options detailed below can be passed as command line arguments, or be
contained in a configuration file, as described in the B<CONFIGURATION FILE>
section below.
Note that the long options, a la C<--long-options>, are new as of
SpamAssassin 3.2.0, and were not available in earlier versions.
=over
=item B<-B>, B<--bsmtp>
Assume input is a single BSMTP-formatted message. In other words, spamc will
pull out everything between the DATA line and the lone-dot line to feed to
spamd, and will place the spamd output back in the same envelope (thus, any
SIZE extension in your BSMTP file will cause many problems).
=item B<-c>, B<--check>
Just check
if
the message is spam or not. Set process exitcode to 1
if
message is spam, 0
if
not spam or processing failure occurs. Will
print
score/threshold to stdout (as ints) or 0/0
if
there was an error.
Combining B<-c> and B<-E> is a
no
-op, since B<-c> implies the behaviour
of B<-E>.
=item B<-d> I<host[,host2]>, B<--dest>=I<host[,host2]>
In TCP/IP mode,
connect
to spamd server on
given
host (
default
: localhost).
Several hosts can be specified
if
separated by commas.
If I<host> resolves to multiple addresses, then spamc will fail-over to the
other addresses,
if
the first one cannot be connected to. It will first
try
all addresses of one host
before
it tries the
next
one in the list.
Note that this fail-over behaviour is incompatible
with
B<-x>;
if
that
switch is used, fail-over will not occur.
=item B<-4>
Use IPv4 only
for
connecting to server. Restricts domain name resolution of
spamd server host(s) to address family AF_INET through the C<hints.ai_family>
flag in the call to getaddrinfo(3).
=item B<-6>
Use IPv6 only
for
connecting to server. Restricts domain name resolution of
spamd server host(s) to address family AF_INET6 through the C<hints.ai_family>
flag in the call to getaddrinfo(3).
=item B<-e> I<command> I<[args]>, B<--
pipe
-to> I<command> I<[args]>
Instead of writing to stdout,
pipe
the output to I<command>'s standard input.
Note that there is a very slight chance mail will be lost here, because
if
the
fork
-and-
exec
fails there's
no
place to put the mail message.
Note that this must be the LAST command line option, as everything
after
the
B<-e> is taken as arguments to the command (it's like I<rxvt> or I<xterm>).
This option is not supported on Win32 platforms.
=item B<-E>, B<--exitcode>
Filter according to the other options, but set the process exitcode to 1
if
message is spam, 0
if
not spam or processing failure occurs.
=item B<-F> I</path/to/file>, B<--config>=I<path>
Specify a configuration file to
read
additional command-line flags from.
See B<CONFIGURATION FILE> below.
=item B<-h>, B<--help>
Print this help message and terminate without action.
=item B<-H>, B<--randomize>
For TCP/IP sockets, randomize the IP addresses returned
for
the hosts
given
by the B<-d> switch. This provides
for
a simple kind of load balancing. It
will
try
only three
times
though.
=item B<-l>, B<--
log
-to-stderr>
Send
log
messages to stderr, instead of to the syslog.
=item B<-L> I<learn type>, B<--learntype>=I<type>
Send message to spamd
for
learning. The C<learn type> can be either spam,
ham or forget. The exitcode
for
spamc will be set to 5
if
the message
was learned, or 6
if
it was already learned, under a condition that
a B<--
no
-safe-fallback> option is selected too.
Note that the C<spamd> must run
with
the C<--allow-
tell
> option
for
this to work.
=item B<-C> I<report type>, B<--reporttype>=I<type>
Report or revoke a message to one of the configured collaborative filtering
databases. The C<report type> can be either report or revoke.
Note that the C<spamd> must run
with
the C<--allow-
tell
> option
for
this to work.
=item B<-p> I<port>, B<--port>=I<port>
In TCP/IP mode,
connect
to spamd server listening on
given
port
(
default
: 783).
=item B<-r>, B<--full-spam>
Just output the SpamAssassin report text to stdout,
if
the message is
spam. If the message is ham (non-spam), nothing will be printed. The
first line of the output is the message score and the threshold, in
this
format
:
score/threshold
=item B<-R>, B<--full>
Just output the SpamAssassin report text to stdout,
for
all messages.
See B<-r>
for
details of the output
format
used.
=item B<-s> I<max_size>, B<--max-size>=I<max_size>
Set the maximum message size which will be sent to spamd -- any bigger than
this threshold and the message will be returned unprocessed (
default
: 500 KB).
If spamc gets handed a message bigger than this, it won't be passed to spamd.
The maximum message size is 256 MB.
The size is specified in bytes, as a positive integer greater than 0.
For example, B<-s 500000>.
=item B<--
connect
-retries>=I<retries>
Retry connecting to spamd I<retries>
times
. The
default
is 3
times
.
=item B<--retry-
sleep
>=I<
sleep
>
Sleep
for
I<
sleep
> seconds between attempts to
connect
to spamd.
The
default
is 1 second.
=item B<--filter-retries>=I<retries>
Retry filtering I<retries>
times
if
the spamd process fails (usually
times
out). This differs from B<--
connect
-retries> in that it
times
out the
transaction
after
the TCP connection
has
been established successfully.
The
default
is 1
time
(ie. one attempt and
no
retries).
=item B<--filter-retry-
sleep
>=I<
sleep
>
Sleep
for
I<
sleep
> seconds between failed spamd filtering attempts.
The
default
is 1 second.
=item B<-S>, B<--ssl>
If spamc was built
with
support
for
SSL, encrypt data to and from the
spamd process
with
SSL; spamd must support SSL as well.
=item B<--ssl-cert>=I<certfile>
Authenticate to spamd server
with
a SSL client certificate. Specify the
certificate file to
use
.
=item B<--ssl-key>=I<keyfile>
Authenticate to spamd server
with
a SSL client certificate. Specify the
certificate key file to
use
.
=item B<--ssl-ca-file>=I<cafile>
Use the specified Certificate Authority certificate to verify the server
certificate. The server certificate must be signed by this certificate.
=item B<--ssl-ca-path>=I<capath>
Use the Certificate Authority certificate files in the specified set of
directories to verify the server certificate. The server certificate must
be signed by one of these Certificate Authorities. See the man page
for
B<IO::Socket::SSL>
for
additional details.
=item B<-t> I<timeout>, B<--timeout>=I<timeout>
Set the timeout
for
spamc-to-spamd communications (
default
: 600, 0 disables).
If spamd takes longer than this many seconds to reply to a message, spamc
will abort the connection and treat this as a failure to
connect
; in other
words the message will be returned unprocessed.
=item B<-n> I<timeout>, B<--
connect
-timeout>=I<timeout>
Set the timeout
for
spamc-to-spamd connection establishment (
default
: 600, 0
disables). If spamc takes longer than this many seconds to establish a
connection to spamd, spamc will abort the connection and treat this as a
failure to
connect
; in other words the message will be returned unprocessed.
=item B<-u> I<username>, B<--username>=I<username>
To have spamd
use
per-user-config files, run spamc as the user whose config
files spamd should load; by
default
the effective user-ID is sent to spamd. If
you're running spamc as some other user, though, (eg. root, mail, nobody,
cyrus, etc.) then you may
use
this flag to
override
the
default
.
=item B<-U> I<socketpath>, B<--
socket
>=I<path>
Connect to C<spamd> via UNIX domain
socket
I<socketpath> instead of a
TCP/IP connection.
This option is not supported on Win32 platforms.
=item B<-V>, B<--version>
Report the version of this C<spamc> client. If built
with
SSL support,
an additional line will be included noting this, like so:
SpamAssassin Client version 3.0.0-rc4
compiled
with
SSL support (OpenSSL 0.9.7d 17 Mar 2004)
=item B<-x>, B<--
no
-safe-fallback>
Disables the
'safe fallback'
error-recovery method, which passes through the
unaltered message
if
an error occurs. Instead,
exit
with
an error code, and
let the MTA queue up the mails
for
a retry later. See also L<
"EXIT CODES"
>.
This also disables the TCP fail-over behaviour from B<-d>.
=item B<-X>, B<--unavailable-tempfail>
When disabling
'safe fallback'
with
B<-x>, this option will turn EX_UNAVAILABLE
errors into EX_TEMPFAIL. This may allow your MTA to defer mails
with
a
temporary SMTP error instead of bouncing them
with
a permanent SMTP error.
See also L<
"EXIT CODES"
>.
=item B<-y>, B<--tests>
Just output the names of the tests hit to stdout, on one line, separated
by commas.
=item B<-K>
Perform a keep-alive check of spamd, instead of a full message check.
=item B<-z>
Use gzip compression to compress the mail message sent to C<spamd>. This is
useful
for
long-distance
use
of spamc over the internet. Note that this relies
on C<zlib> being installed on the C<spamc> client side, and the
C<Compress::Zlib> perl module on the server side; an error will be returned
otherwise.
=item B<--headers>
Perform a scan, but instead of allowing any part of the message (header and
body) to be rewritten, limit rewriting to only the message headers. This is
much more efficient in bandwidth usage, since the response message transmitted
back from the spamd server will not include the body.
Note that this only makes sense
if
you are using C<report_safe 0> in the
scanning configuration on the remote end;
with
C<report_safe 1>, it is
likely to result in corrupt messages.
=back
=head1 CONFIGURATION FILE
The above command-line switches can also be loaded from a configuration
file.
The
format
of the file is similar to the SpamAssassin rules files; blank lines
and lines beginning
with
C<
considered additions to the command line, and are prepended. Newlines are
treated as equivalent to spaces. Existing command line switches will
override
any settings in the configuration file.
If the B<-F> switch is specified, that file will be used. Otherwise,
C<spamc> will attempt to load spamc.conf in C<SYSCONFDIR> (
default
:
/etc/mail/spamassassin). If that file doesn't exist, and the B<-F>
switch is not specified,
no
configuration file will be
read
.
Example:
-d server.example.com
-p 783
-s 350000
=head1 EXIT CODES
By
default
, spamc will
use
the
'safe fallback'
error recovery method. That
means, it will always
exit
with
an
exit
code of C<0>, even
if
an error was
encountered. If any error occurs, it will simply pass through the unaltered
message.
The B<-c> and B<-E> options modify this; instead, spamc will
use
an
exit
code
of C<1>
if
the message is determined to be spam.
If one of the C<-x>, C<-L> or C<-C> options are specified,
'safe fallback'
will
be disabled, and certain error conditions related to communication between
spamc and spamd will result in an error code.
The
exit
codes used are as follows:
EX_USAGE 64 command line usage error
EX_DATAERR 65 data
format
error
EX_NOINPUT 66 cannot
open
input
EX_NOUSER 67 addressee unknown
EX_NOHOST 68 host name unknown
EX_UNAVAILABLE 69 service unavailable
EX_SOFTWARE 70 internal software error
EX_OSERR 71
system
error (e.g., can't
fork
)
EX_OSFILE 72 critical OS file missing
EX_CANTCREAT 73 can't create (user) output file
EX_IOERR 74 input/output error
EX_TEMPFAIL 75 temp failure; user is invited to retry
EX_PROTOCOL 76 remote error in protocol
EX_NOPERM 77 permission denied
EX_CONFIG 78 configuration error
* The EX_TOOBIG error level is never used. If spamc receives a message
that is too big, the
exit
code will be 0.
EX_TOOBIG 98 message was too big to process (see --max-size)
=head1 SEE ALSO
spamd(1)
spamassassin(1)
Mail::SpamAssassin(3)
=head1 PREREQUISITES
C<Mail::SpamAssassin>
=head1 AUTHORS
=head1 COPYRIGHT
SpamAssassin is distributed under the Apache License, Version 2.0, as
described in the file C<LICENSE> included
with
the distribution.