1DSPAM(1) DSPAM DSPAM(1)
2
6 dspam - DSPAM Anti-Spam Agent
7
10 dspam [--mode=teft|toe|tum|notrain|unlearn] [--user user1
11 user2 ... userN] [--feature=noise|no,tb=N,whitelist|wh]
12 [--class=spam|innocent] [--source=error|corpus|inoculation] [--pro‐
13 file=PROFILE] [--deliver=spam,innocent|nonspam,summary,stdout] [--help]
14 [--version] [--process] [--classify] [--signature=signature] [--stdout]
15 [--debug] [--daemon] [--nofork]] [--client] [--rcpt-to recipi‐
16 ent-address(es)] [--mail-from=sender-address] [passthru-delivery-argu‐
17 ments]
18
21 The DSPAM agent provides a direct interface to mail servers for com‐
22 mand-line spam filtering. The agent can masquerade as the mail server's
23 local delivery agent and will process any email passed to it. The agent
24 will then call whatever delivery agent was specified at compile time or
25 quarantine/tag/drop messages identified as spam. The DSPAM agent can
26 function locally or as a proxy. It is also responsible for processing
27 classification errors so that DSPAM can learn from its mistakes.
28
31 --user user1 user2 ... userN
32 Specifies the destination users of the incoming message. In most
33 cases this is the local user on the system, however some imple‐
34 mentations may call for virtual usernames, specific to DSPAM, to
35 be assigned. The agent processes an incoming message once for
36 each user specified. If the message is to be delivered, the $u
37 (or %u) parameters of the argument string will be interpolated
38 for the current user being processed.
39 --mode=toe|tum|teft|notrain
42 Configures the training mode to be used for this process, over‐
43 riding any defaults in dspam.conf or the preference extension:
44 teft : Train-Everything. Trains on all messages processed. This
46 is a very thorough training approach and should be considered
47 the standard training approach for most users. TEFT may, how‐
48 ever, prove too volatile on installations with extremely high
49 per-user traffic, or prove not very scalable on systems with
50 extremely large user-bases. In the event that TEFT is proving
51 ineffective, one of the other modes is recommended.
52 toe : Train-on-Error. Trains only on a classification error,
54 once the user's metadata has matured to 2500 innocent messages.
55 This training mode is much less resource intensive, as only
56 occasional metadata writes are necessary. It is also far less
57 volatile than the TEFT mode of training. One drawback, however,
58 is that TOE only learns when DSPAM has made a mistake - which
59 means the data is sometimes too static, and unable to "ease
60 into" a different type of behavior.
61 tum : Train-until-Mature. This training mode is a hybrid between
63 the other two training modes and provides a great balance
64 between volatility and static metadata. TuM will train on a
65 per-token basis only tokens which have had fewer than 25 "hits"
66 on them, unless an error is being retrained in which case all
67 tokens are trained. This training mode provides a solid core of
68 stable tokens to keep accuracy consistent, but also allows for
69 dynamic adaptation to any new types of email behavior a user
70 might be experiencing.
71 notrain : No training. Do not train the user's data, and do not
73 keep totals. This should only be used in cases where you want to
74 process mail for a particular user (based on a group, for exam‐
75 ple), but don't want the user to accumulate any learning data.
76 unlearn : Unlearn original training. Use this if you wish to
78 unlearn a previously learned message. Be sure to specify
79 --source=error and --class to whatever the original classifica‐
80 tion the message was learned under. If not using TrainPristine,
81 this will require the original signature from training.
82 --feature=noise|no,whitelist|wh,tb=N
85 Specifies the features that should be activated for this filter
86 instance. The following features may be used individually or
87 combined using a comma as a delimiter:
88 (no)ise : Bayesian Noise Reduction (BNR). Bayesian Noise Reduc‐
90 tion kicks in at 2500 innocent messages and provides an advanced
91 progressive noise logic to reduce Bayesian Noise (wordlist
92 attacks) in spams. See http://www.zdziarski.com/papers/bnr.html
93 for more information.
94 (tb)=N : Sets the training loop buffering level. Training loop
96 buffering is the amount of statistical sedation performed to
97 water down statistics and avoid false positives during the
98 user's training loop. The training buffer sets the buffer sensi‐
99 tivity, and should be a number between 0 (no buffering whatso‐
100 ever) to 10 (heavy buffering). The default is 5, half of what
101 previous versions of DSPAM used. To avoid dulling down statis‐
102 tics at all during the training loop, set this to 0.
103 (wh)itelist : Automatic whitelisting. DSPAM will keep track of
105 the entire "From:" line for each message received per user, and
106 automatically whitelist messages from senders with more than 20
107 innocent messages and zero spams. Once the user reports a spam
108 from the sender, automatic whitelisting will automatically be
109 deactivated for that sender. Since DSPAM uses the entire "From:"
110 line, and not just the sender's email address, automatic
111 whitelisting is a very safe approach to improving accuracy espe‐
112 cially during initial training.
113 NOTE: : None of the present features are necessary when the
115 source is "error", because the original training data is used
116 from the signature to retrain, instantiating whatever features
117 (such as whitelisting) were active at the time of the initial
118 classification. Since BNR is only necessary when a message is
119 being classified, the --feature flag can be safely omitted from
120 error source calls.
121 --class=spam|innocent
124 Identifies the disposition (if any) of the message being pre‐
125 sented. This flag should be used when a misclassification has
126 occured, when the user is corpus-feeding a message, or when an
127 inoculation is being presented. This flag should not be used for
128 standard processing. This flag must be used in conjunction with
129 the --source flag. Omitting this flag causes DSPAM to determine
130 the disposition of the message on its own (the standard operat‐
131 ing mode).
132 --source=error|corpus|inoculation
135 Where --class is used, the source of the classification must
136 also be provided. The source tells dspam how to learn the mes‐
137 sage being presented:
138 error : The message being presented was a message previously
140 misclassified by DSPAM. When ´error´ is provided as a source,
141 DSPAM requires that the DSPAM signature be present in the mes‐
142 sage, and will use the signature to recall the original training
143 metadata. If the signature is not present, the message will be
144 rejected. In this source mode, DSPAM will also decrement each
145 token's previous classification's count as well as the user
146 totals.
147 You should use error only when DSPAM has made an error in clas‐
149 sifying the message, and should present the modified version of
150 the message with the DSPAM signature when doing so.
151 corpus : The message being presented is from a mail corpus, and
153 should be trained as a new message, rather than re-trained based
154 on a signature. The message's full headers and body will be ana‐
155 lyzed and the correct classification will be incremented, with‐
156 out its opposite being decremented.
157 You should use corpus only when feeding messages in from corpus.
159 inoculation : The message being presented is in pristine form,
161 and should be trained as an inoculation. Inoculations are a more
162 intense mode of training designed to cause DSPAM to train the
163 user's metadata repeatedly on previoulsy unknown tokens, in an
164 attempt to vaccinate the user from future messages similar to
165 the one being presented. You should use inoculation only on hon‐
166 eypots and the like.
167 --profile=PROFILE
170 Specify a storage profile from dspam.conf. The storage profile
171 selected will be used for all database connectivity. See
172 dspam.conf for more information.
173 --deliver=spam,innocent|nonspam,summary,stdout
176 Tells DSPAM to deliver the message if its result falls within
177 the criteria specified. For example, --deliver=innocent or
178 --deliver=nonspam will cause DSPAM to only deliver the message
179 if its classification has been determined as innocent. Providing
180 --deliver=innocent,spam or --deliver=nonspam,spam will cause
181 DSPAM to deliver the message regardless of its classification.
182 This flag provides a significant amount of flexibility for non‐
183 standard implementations, where false positives may not be
184 delivered but spam is, and etcetera.
185 summary : Deliver (to stdout) a summary indentical to the output
187 of message classification:
188 X-DSPAM-Result: User; result="Innocent"; class="Innocent"; prob‐
190 ability=0.0000; confidence=1.00; signa‐
191 ture=4b11c532158749980119923
192 stdout : Is a shortcut for for --deliver=innocent,spam --stdout
194 --stdout
197 If the message is indeed deemed "deliverable" by the --deliver
198 flag, this flag will cause DSPAM to deliver the message to std‐
199 out, rather than the configured delivery agent.
200 --process
203 Tells DSPAM to process the message. This is the default behav‐
204 ior, and the flag is implied unless --classify is used.
205 --classify
208 Tells DSPAM to only classify the message, and not perform any
209 writes to the user's data or attempt to deliver/quarantine the
210 message. The results of a classification are printed to stdout
211 in the following format:
212 X-DSPAM-Result: User; result="Spam"; probability=1.0000; confi‐
214 dence=0.80
215 NOTE : The output of the classification is specific to a user's
217 own data, and does not include the output of any groups they
218 might be affiliated with, so it is entirely possible that the
219 message would be caught as spam by a group the user belongs to,
220 and appear as innocent in the output of a classification. To get
221 the classification for the group , use the group name as the
222 user instead of an individual.
223 --signature=signature
226 If only the signature is available for training, and not the
227 entire message, the --signature flag may be used to feed the
228 signature into DSPAM and forego the reading of stdin. DSPAM will
229 process the signature with whatever commandline classification
230 was specified.
231 NOTE : This should only be used with --source=error
233 --debug
236 If DSPAM was compiled with --enable-debug then using --debug
237 will turn on debugging messages.
238 --daemon
241 If DSPAM was compiled with --enable-daemon then using --daemon
242 will cause DSPAM to enter daemon mode, where it will listen for
243 DSPAM clients to connect and actively service requests.
244 --nofork
247 If DSPAM was compiled with --enable-daemon then using --nofork
248 will cause DSPAM to not fork the daemon into backgound when
249 using --daemon switch.
250 --client
253 If DSPAM was compiled with --enable-daemon then using --client
254 will cause DSPAM to act as a client and attempt to connect to
255 the DSPAM server specified in the client's configuration within
256 dspam.conf. If client behavior is desired, this option must be
257 specified, otherwise the agent simply operate as self-contained
258 and processes the message on its own, eliminating any benefit of
259 using the daemon.
260 --rcpt-to recipient-address(es)
263 If DSPAM will be configured to deliver via LMTP or SMTP, this
264 flag may be used to define the RCPT TOs which will be used for
265 the delivery of each user specified with --user If no recipients
266 are provided, the RCPT TOs will match the username.
267 NOTE : The recipient list should always be balanced with the
269 user list, or empty. Specifying an unbalanced number of recipi‐
270 ents to users will result in undefined behavior.
271 --mail-from=sender-address
274 If DSPAM will be cofigured to deliver via LMTP or SMTP, this
275 flag will set the MAIL FROM sent on delivery of the message. The
276 default MAIL FROM depends on how the message was originally
277 relayed to DSPAM. If it was relayed via the commandline, an
278 empty MAIL FROM will be used. If it was relayed via LMTP, the
279 original MAIL FROM will be used.
280
283 0 Operation was successful.
284 other Operation resulted in an error. If the error involved an error
285 in calling the delivery agent, the exit value of the delivery
286 agent will be returned.
287
290 Copyright © 2002-2012 DSPAM Project
291 All rights reserved.
292 For more information, see http://dspam.sourceforge.net.
294
297 dspam_admin(1), dspam_clean(1), dspam_crc(1), dspam_dump(1),
298 dspam_logrotate(1), dspam_merge(1), dspam_stats(1), dspam_train(1)
299DSPAM Aug 14, 2010 DSPAM(1)