.\" $Id$ .\" .\" bogom, simple sendmail milter to interface bogofilter .\" Copyright (C) 2004-2007 Juan J. Martinez .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License Version 2 as .\" published by the Free Software Foundation. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; if not, write to the Free Software .\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. .\" .Dd December 25, 2004 .Dt BOGOM 8 .Os .Sh NAME .Nm bogom .Nd simple sendmail milter to interface bogofilter .Sh SYNOPSIS .Nm .Op Fl R | Fl D .Op Fl t .Op Fl v .Op Fl S .Op Fl u Ar user .Op Fl s Ar conn .Op Fl b Ar bogo_path .Op Fl x Ar exclude_string .Op Fl c Ar conf_file .Op Fl l Ar body_limit .Op Fl p Ar pidfile .Op Fl f Ar forward_spam .Op Fl q Ar quarantine_mdir .Op Fl d .Sh DESCRIPTION The .Nm plugin can be used with the milter API of .Xr sendmail 8 to filter mails using .Xr bogofilter 1 bayesian filter. .Pp .Nm is intended to be used with only one words database for the whole system. .Pp The options are as follows: .Bl -tag -width "-x exclude_string" .It Fl R Reject mail classified as spam .It Fl D Discard mail classified as spam .It Fl t Train bogofilter with the mail classified as spam/ham .It Fl v Verbose logging .It Fl S Use spamicity header. Read configuration file section for further details. .It Fl u Ar user User to run the milter. Default: bogofilter .It Fl s Ar conn Path to the pipe to connect sendmail. Default: .Pa unix:/var/spool/bogofilter/milter.sock .It Fl b Ar bogo_path Path to the .Xr bogofilter 1 binary. Default: .Pa /usr/local/bin/bogofilter .It Fl x Ar exclude_string If this string is found in the Subject of a message, it will be automatically accepted and no filtering operation will be done. .It Fl c Ar conf_file Path to the configuration file. Default: .Pa /etc/bogom.conf .It Fl l Ar body_limit Length limit in bytes to be processed from mail body. The rest of the body will be discarded and not analyzed by the filter. Default: .Pa no limit .It Fl p Ar pidfile Path to the file to store the pid of the milter. The pidfile is created after the milter drops privileges and the user to run the milter must have write permission to the specified file. Default: .Pa /var/spool/bogofilter/bogom.pid .It Fl f Ar forward_spam Set a recipient to forward any message classified as spam. Read configuration file section for further details. .It Fl q Ar quarantine_mdir Path to a directory to deliver a copy of any message classified as spam. The messages are stored in .Xr maildir 5 format. .It Fl d Enable debug messages (implies verbose logging) .El .Pp Default policy is to add the .Em X-Bogosity header (Yes, No, Unsure) and deliver the mail. This can be changed with .Cm -R or .Cm -D when bogofilter classifies the mail as spam. .Pp In bogofilter's configuration the .Em bogofilter_dir token should be set to the directory with system database, usually .Pa /var/spool/bogofilter , in bogofilter's configuration, or simply the words database of the unprivileged user running the milter can be used. .Pp .Nm uses a temporal file to store each individual message and forks a new process to scan it with bogofilter. This temporal file uses .Pa /tmp directory by default, it's owned by the user running the milter and has 0600 mode. When a directory is specified in .Em quarantine_mdir , the .Pa tmp subdirectory in that maildir is used as temporal directory. .Pp The option .Cm -t registers the mail after classifying it as spam or ham. This option can be dangerous because the filter may register errors, so you should read carefully bogofilter's manual regarding this point. .Sh SENDMAIL SETUP Milter support in sendmail binary can be verified with: .Pp .D1 # sendmail -d0.1 -bv root | grep MILTER .D1 Compiled with: DNSMAP LOG MAP_REGEX MATCHGECOS MILTER MIME7TO8 MIME8TO7 .Pp The milter can be added to sendmail's configuration by adding the following lines to the mc file: .Pp .D1 INPUT_MAIL_FILTER(`bogom', .D1 `S=unix:/var/spool/bogofilter/milter.sock, T=S:30s;R:1m') .Pp It assumes the default place for the communication socket. .Pp The cf file must be rebuilt and sendmail restarted. .Sh CONFIGURATION FILE Configuration file supports following tokens: .Bd -literal # line comment policy (pass|reject|discard) default: policy pass reject "" default: empty (sendmail default is "Command rejected") subject_tag "" default: empty verbose (0|1) default: verbose 0 spamicity_header (0|1) default: spamicity_header 0 bogofilter "" default: bogofilter "/usr/local/bin/bogofilter" training (0|1) default: training 0 body_limit default: no limit user "" default: user "bogofilter" connection ":" default: connection "unix:/var/spool/bogofilter/milter.sock" pidfile "" default: pidfile "/var/spool/bogofilter/bogom.pid" exclude_string "" default: empty forward_spam "" default: empty quarantine_mdir "" default: empty re_connection "" default: empty re_envfrom "" default: empty re_envrcpt "" default: empty .Ed .Pp Configuration takes precedence over command line. .Pp By default .Em X-Bogosity header will use 'Yes, tests=bogofilter', 'No, tests=bogofilter' and 'Unsure, tests=bogofilter'. With .Em spamicity_header activated, the classification of 'Ham', 'Spam' or 'Unsure' plus the value of spamicity will be used to tag the messages. .Pp .Em subject_tag string will be prepend to message subject when it is identified as spam and policy is pass. .Pp .Em body_limit specifies the amount of bytes (K suffix for Kilobytes and M for Megabytes) of message body that will be passed to bogofilter to be processed. This option should help busy servers but is incompatible with .Em quarantine_mdir feature. .Pp .Em forward_spam recipient will receive a copy of any message classified as spam when policy is pass. Notice that the original destination recipients won't be modified and general RELAY restrictions will apply. .Pp If a directory in .Em quarantine_mdir is specified, any message classified as spam will be delivered there in maildir format. Neither reject nor discard policy affect this delivery, but .Em body_limit option is ignored. When a message is delivered, necessary subdirectories are created (tmp and new only). Notice that tmp subdirectory in maildir is used as temporal directory for .Nm process when this option is active. .Pp The .Em re_* tokens allow to add items to .Em connection , .Em envfrom and .Em envrcpt white lists. Any message with client connection (both host and hostname, if available), sender address or destination address matching the case insensitive extended regular expression (explained in .Xr re_format 7 ) will be accepted and no filtering operation will be done. Those token can be used more than once and all the regular expressions will be checked. .Pp Quoted strings can use single and double quotes, using backslash to escape both characters. . .Sh LOGGING .Nm sends messages to .Xr syslogd 8 using facility daemon and levels err, notice, info and debug. .Pp By default only info and, when needed, err levels will be used. With .Cm -v option, extra information will be addressed with notice level plus the log facility provided in bofogilter. .Pp .Cm -d option enables debug level with very verbose logging. .Pp .Nm activity can be logged to a separate file with following lines in .Xr syslog.conf 5 : .Bd -literal !bogom *.* /var/log/bogom !bogofilter *.* /var/log/bogom .Ed .Sh FILES /etc/bogom.conf .Sh SEE ALSO .Xr sendmail 8 , .Xr bogofilter 1 , .Xr bogoutil 1 , .Xr syslog.conf 5 , .Xr syslogd 8 , .Xr re_format 7 , .Xr maildir 5 .Pp http://www.usebox.net/jjm/bogom/ .Sh CAVEATS By now SIGHUP is ignored. .Sh HISTORY The first version of .Nm was written in the end of 2004. .Sh AUTHORS Juan J. Martinez .Aq jjm@usebox.net