aboutsummaryrefslogtreecommitdiff
path: root/bogom.8
diff options
context:
space:
mode:
authorDimitri Sokolyuk <demon@dim13.org>2010-03-09 16:37:48 +0000
committerDimitri Sokolyuk <demon@dim13.org>2010-03-09 16:37:48 +0000
commit335bd0d855dc2cd0b2b6c1f666fd7402afb591ca (patch)
tree8535af5c9378ac29bd8a4ef18bd335cd65c7edeb /bogom.8
bogom 1.9.2 import
Diffstat (limited to 'bogom.8')
-rw-r--r--bogom.8312
1 files changed, 312 insertions, 0 deletions
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 <jjm*at*usebox*dot*net>
+.\"
+.\" 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 "<text for the SMTP reply>"
+ default: empty
+ (sendmail default is "Command rejected")
+
+ subject_tag "<text to tag the subject>"
+ default: empty
+
+ verbose (0|1)
+ default: verbose 0
+
+ spamicity_header (0|1)
+ default: spamicity_header 0
+
+ bogofilter "<path to bogofilter binary>"
+ default: bogofilter "/usr/local/bin/bogofilter"
+
+ training (0|1)
+ default: training 0
+
+ body_limit <length in bytes>
+ default: no limit
+
+ user "<username to run the milter>"
+ default: user "bogofilter"
+
+ connection "<type>:<location>"
+ default: connection "unix:/var/spool/bogofilter/milter.sock"
+
+ pidfile "<path to milter pidfile>"
+ default: pidfile "/var/spool/bogofilter/bogom.pid"
+
+ exclude_string "<subject exclude string>"
+ default: empty
+
+ forward_spam "<rcpt>"
+ default: empty
+
+ quarantine_mdir "<path to maildir directory>"
+ default: empty
+
+ re_connection "<case insensitive extended re>"
+ default: empty
+
+ re_envfrom "<case insensitive extended re>"
+ default: empty
+
+ re_envrcpt "<case insensitive extended re>"
+ 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