| <@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 |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| 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>, 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<-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<#> are ignored. Any space-separated words are |
| 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: |
| |
| # spamc global configuration file |
| |
| # connect to "server.example.com", port 783 |
| -d server.example.com |
| -p 783 |
| |
| # max message size for scanning = 350k |
| -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 occurrs, 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 |
| |
| The SpamAssassin(tm) Project <https://spamassassin.apache.org/> |
| |
| =head1 COPYRIGHT |
| |
| SpamAssassin is distributed under the Apache License, Version 2.0, as |
| described in the file C<LICENSE> included with the distribution. |