From 335bd0d855dc2cd0b2b6c1f666fd7402afb591ca Mon Sep 17 00:00:00 2001 From: Dimitri Sokolyuk Date: Tue, 9 Mar 2010 16:37:48 +0000 Subject: bogom 1.9.2 import --- bogom.8 | 312 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 bogom.8 (limited to 'bogom.8') diff --git a/bogom.8 b/bogom.8 new file mode 100644 index 0000000..5c4b119 --- /dev/null +++ b/bogom.8 @@ -0,0 +1,312 @@ +.\" $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 -- cgit v1.2.3