~ubuntu-branches/ubuntu/trusty/dovecot-antispam/trusty-proposed : revision 1

1

.TH ANTISPAM 7 "15 October 2007" "" ""

2

.SH NAME

3

antispam \- The dovecot antispam plugin.

4

5

.SH DESCRIPTION

6

The dovecot antispam plugin watches a defined spam folder (defaults to

7

"SPAM"). It works together with a spam system that classifies each

8

message as it is delivered. When the message is classified as spam, it

9

shall be delivered to the spam folder, otherwise via the regular

10

filtering file the user may have (maildrop, sieve, ...). Now the user

11

has everything classified as spam in the special spam folder, everything

12

else where it should be sorted to.

13

14

This is not enough because our spam scanner needs training. We'll

15

occasionally have false positives and false negatives. Now this is the

16

point where the dovecot antispam plugin comes into play. Instead of

17

moving mail into special folders or forwarding them to special mail

18

addresses for retraining, the plugin offers two actions for the user:

19

.IP " 1." 4

20

moving mail out of the SPAM folder and

21

.IP " 2." 4

22

moving mail into the SPAM folder.

23

24

.PP

25

The dovecot plugin watches these actions (and additionally prohibits

26

APPENDs to the SPAM folder, more for technical reasons than others) and

27

tells the spam classifier that it made an error and needs to re-classify

28

the message (as spam/not spam depending on which way it was moved.)

29

30

The advantage of this approach is that the mail ends up in the right

31

target folder directly and needs not be touched twice.

32

33

When other classifiers like crm114 that have an `unsure' state are used,

34

the plugin can also help, it supports an `unsure' folder feature. The

35

unsure folder cannot be written to, but moving out from there into a

36

folder that is considered a spam folder will learn as spam, any other

37

folder (except trashes) will cause learning as not-spam.

38

39

.SH INSTALLATION

40

41

First copy the `defconfig' file to `.config' and edit it as necessary.

42

You need to have the dovecot headers installed and possibly other things

43

depending on the backend you choose. Then, assuming you have configured

44

the INSTALLDIR correctly, simply run `make install'.

45

46

If you do not wish to use the install target, simply copy the plugin

47

(that is, the file lib90_antispam_plugin.so) to your dovecot imap plugin

48

directory; by default this is /usr/lib/dovecot/modules/imap/ or any dir

49

you have configured (look for the mail_plugin_dir configuration

50

directive.)

51

52

Open your dovecot configuration file (usually /etc/dovecot/dovecot.conf)

53

and add the antispam plugin to the imap protocol section:

54

55

.nf

56

protocol imap {

57

mail_plugins = antispam

58

# mail_plugin_dir = /usr/lib/dovecot/modules/imap

59

}

60

.fi

61

62

.SH BACKENDS

63

64

The plugin supports multiple backends, there are currently two working

65

backends included in the distribution:

66

67

.SS dspam executable backend (dspam specific)

68

69

This backend instantly retrains by calling dspam. There are some

70

problems with this approach including

71

(1) it can take a long time during which the IMAP session is blocked

72

(2) when many users retrain many messages at once server load may spike

73

74

.SS email sender backend (spam filter agnostic)

75

76

This backend sends mail to ham@example.com or spam@example.com

77

(actual addresses are configurable) for retraining. This backend can

78

be very fast to set up if you already have a working setup that uses

79

training addresses as recommended by many spam filter setups.

80

81

Since this backend simply pipes the message to a program (by default

82

sendmail) it can also be used for all kinds of other spam filters,

83

for example spamassassin (by calling sa-learn instead of sendmail.)

84

85

.SS crm114 executable backend (crm114 specific)

86

87

This backend instantly retrains by calling mailreaver.crm which

88

needs to be configured (defaulting to /bin/false!); the argument

89

--good or --spam is given depending on how mail is moved.

90

91

You need to use the unsure folder option (see below) together with

92

this plugin and deliver unsure mail into an unsure folder, spam mail

93

into a spam folder and other mail regularly.

94

95

Has the same drawbacks as the dspam-exec approach.

96

97

98

.SH CONFIGURATION

99

100

Aside from the build-configuration done in the `.config' file, you have

101

the following run-time options (shown along with the default):

102

103

.nf

104

plugin {

105

##################

106

# GENERIC OPTIONS

107

108

# mail signature (used with any backend requiring a signature)

109

antispam_signature = X-DSPAM-Signature

110

111

# action to take on mails without signature

112

# (used with any backend requiring a signature)

113

# (we recommend only setting this to 'move' after verifying that the

114

# whole setup is working)

115

# antispam_signature_missing = move # move silently without training

116

antispam_signature_missing = error

117

118

# semicolon-separated list of Trash folders (default unset i.e. none)

119

# antispam_trash =

120

# antispam_trash = trash;Trash;Deleted Items

121

122

# semicolon-separated list of spam folders

123

antispam_spam = SPAM

124

125

# semicolon-separated list of unsure folders (default unset i.e. none)

126

# antispam_unsure =

127

128

# Whether to allow APPENDing to SPAM folders or not. Must be set to

129

# "yes" (case insensitive) to be activated. Before activating, please

130

# read the discussion below.

131

# antispam_allow_append_to_spam = no

132

133

###########################

134

# BACKEND SPECIFIC OPTIONS

135

#

136

137

#===================

138

# dspam-exec plugin

139

140

# dspam binary

141

antispam_dspam_binary = /usr/bin/dspam

142

143

# semicolon-separated list of extra arguments to dspam

144

# (default unset i.e. none)

145

# antispam_dspam_args =

146

# antispam_dspam_args = --deliver=;--user;%u # % expansion done by dovecot

147

# antispam_dspam_args = --mode=teft

148

149

# Ignore mails where the DSPAM result header contains any of the

150

# strings listed in the blacklist

151

# (default unset i.e. none)

152

# antispam_dspam_result_header = X-DSPAM-Result

153

# semicolon-separated list of blacklisted results, case insensitive

154

# antispam_dspam_result_blacklist = Virus

155

156

#=====================

157

# mail sending plugin

158

#

159

# Because of the way this plugin works, you can also use it

160

# to train via an arbitrary program that receives the message

161

# on standard input, in that case you can use the config

162

# options antispam_mail_spam and antispam_mail_notspam for

163

# the argument that distinguishes between ham and spam.

164

# For example:

165

# antispam_mail_sendmail = /path/to/mailtrain

166

# antispam_mail_sendmail_args = --for;%u

167

# antispam_mail_spam = --spam

168

# antispam_mail_notspam = --ham

169

# will call it, for example, like this:

170

# /path/to/mailtrain --for jberg --spam

171

172

# temporary directory

173

antispam_mail_tmpdir = /tmp

174

175

# spam/not-spam addresses (default unset which will give errors)

176

# antispam_mail_spam =

177

# antispam_mail_notspam =

178

179

# sendmail binary

180

antispam_mail_sendmail = /usr/sbin/sendmail

181

#antispam_mail_sendmail_args = -f;%u@example.com # % expansion done by dovecot

182

183

#===================

184

# crm114-exec plugin

185

186

# mailreaver binary

187

antispam_crm_binary = /bin/false

188

# antispam_crm_binary = /usr/share/crm114/mailreaver.crm

189

190

# semicolon-separated list of extra arguments to dspam

191

# (default unset i.e. none)

192

# antispam_crm_args =

193

# antispam_crm_args = --config=/path/to/config

194

195

# NOTE: you need to set the signature for this backend

196

antispam_signature = X-CRM114-CacheID

197

}

198

.fi

199

200

.SH ALLOWING APPENDS?

201

202

You should be careful with allowing APPENDs to SPAM folders. The reason

203

for possibly allowing it is to allow not-SPAM --> SPAM transitions to work

204

with offlineimap. However, because with APPEND the plugin cannot know the

205

source of the message, multiple bad scenarios can happen:

206

207

.IP " 1." 4

208

SPAM --> SPAM transitions cannot be recognised and are trained

209

210

.IP " 2." 4

211

the same holds for Trash --> SPAM transitions

212

213

.PP

214

Additionally, because we cannot recognise SPAM --> not-SPAM transitions,

215

training good messages will never work with APPEND.

216

217

.SH AUTHORS

218

219

Johannes Berg, Frank Cusack, Benedikt Boehm, Andreas Schneider