aboutsummaryrefslogtreecommitdiff
path: root/bogom.8
blob: 5c4b11984013ba9b3db3791893e3e88356e13356 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
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