kmail/kmail.antispamrc-HOWTO

   1
   2 HOWTO for setting up a KMail antispam wizard configuration entry
   3 ================================================================
   4
   5 This is a HOWTO for setting up a KMail antispam wizard configuration
   6 entry. Since this possibly is more developer related, I put this as
   7 text file into the source SVN. Possibly some of this should go to the
   8 user documentation.
   9
  10 I gathered the information from several mails and comments by Andreas
  11 Gungl, the original developer of the antispam wizard for KMail, and
  12 Ingo Kloecker.
  13
  14 When you have questions do not hesitate to ask me, Martin Steigerwald,
  15 Andreas or Ingo.
  16
  17
  18 Basics
  19 ------
  20
  21 The configuration file for the KMail antispam wizard "kmail.antispamrc"
  22 consists of one entry for each spamfilter that the antispam wizard
  23 shall support.
  24
  25 At the beginning of the file in the section "General" the option "tools"
  26 specifies the count of configured spam filters. Increase that by one
  27 when you add a new entry:
  28
  29 [General]
  30 tools=11
  31
  32
  33 A spam filter configuration entry starts with a header like this:
  34
  35 [Spamtool #11]
  36
  37
  38 After this you place all the options for the spam filter. Please use
  39 an ordering that is similar to the other entries in the configuration
  40 file so that things are unified a bit.
  41
  42
  43 General options
  44 ---------------
  45
  46 - Ident: Specifies the internal identifier for the entry
  47
  48 - Version: Specifies the version of the entry (FIXME what is this for?)
  49
  50 - Priority: Specifies the priority of the filter. This value is used to
  51   place faster filters before the slower ones in the selection list. If the
  52   user chooses the top item, he gets the fastest filter. Provider sided
  53   "filters" (which produce headers tough) like the GMX filter have a prio
  54   at about 70, they are very fast as they don't consume time on the client
  55   side. Since CRM114 is almost as fast it gets 65 ;-).
  56
  57 - VisibleName: This is the name that is presented to the user
  58
  59 Or:
  60
  61 - HeadersOnly=yes: This is used for entries where KMail should just parse
  62   the mail headers for the spam score display (see Razor filter and below
  63   for spam score display details).
  64
  65
  66 Spam filter options
  67 -------------------
  68
  69 These specify details about the spamfilter.
  70
  71 - Executable: Specifies a test whether the executable of the spamfilter
  72   can be started. You should provide something which can be run on the
  73   command line and returns [ $? -eq 0 ], i.e. it doesn't wait for any input
  74   etc. It usually make sense to assume the program in the $PATH, so you
  75   should better avoid /usr/bin. Set executable to "echo" for provider based
  76   filters.
  77   Example: Executable=crm -v | grep "CRM114"
  78
  79 - URL: URL to the homepage of the filter
  80
  81 - PipeFilterName: Name of the pipe-through filter used to send mails to the
  82   spamfilter and get them back with added spam filter headers.
  83
  84 - PipeCmdDetect: Command used to pipe the mail into.
  85
  86 - ExecCmdSpam: Command used to mark a mail as spam.
  87
  88 - ExecCmdHam: Command used to mark a mail as ham.
  89
  90 - SupportsBayes: Set to 1 if you have a spam filter that can learn. Only
  91   in this case KMail uses ExecCmdSpam and ExecCmdHam to let the user mark
  92   mail as ham or spam.
  93
  94
  95 Spam detection options
  96 ----------------------
  97
  98 These specify how KMail shall detect whether a mail is spam, unsure or good.
  99
 100 - DetectionHeader: The name of the header where the spam filter puts the spam
 101   status of a mail into.
 102
 103 - DetectionPattern: The pattern the spam filter uses for marking a mail as
 104   spam.
 105
 106 - DetectionPattern2: The pattern the spam filter uses for marking a mail as
 107   unsure. Set "SupportsUnsure=1" when you use this.
 108
 109 - DetectionOnly: Don't pipe mails through the spam filter, but just use headers
 110   from outside, e.g. a provider based spam filter (See GMX).
 111
 112 - UseRegExp: Set to 1 if you need to use regular expressions in the detection
 113   patterns. KMail can operate faster when they are not required.
 114
 115 - SupportsUnsure: Set to 1 if you have a spam filter that supports
 116   classying mails as unsure to tell the user to train those.
 117
 118
 119 Spam score display
 120 ------------------
 121
 122 Those regular expressions are used to extract the actual "spamicity"
 123 score and the threshold (i.e. the upper bound for non-spam) from
 124 SpamAssassin's ScoreHeader. The score and the threshold are then used
 125 for showing the spam status in the message header, i.e. the small
 126 colorbar.
 127
 128 You need to specify the following values:
 129
 130 - ScoreName: The name that will be shown in the message header.
 131
 132 - ScoreHeader: The message header containing the score value.
 133
 134 - ScoreType: The type of the score, cf. below.
 135
 136 - ScoreValueRegexp: A regular expression for extracting the score from
 137   the ScoreHeader.
 138
 139 - ScoreThresholdRegexp: A regular expression for extracting the threshold
 140   from the ScoreHeader; only needed for Adjusted type. Please set to
 141   nothing (ScoreThresholdRegexp=) if not needed.
 142
 143
 144 KMail supports the following ScoreType values:
 145
 146 - Bool: Simple Yes or No (Razor)
 147
 148 - Decimal: For probability between 0.0 and 1.0 (BogoFilter)
 149
 150 - Percentage: For straight percentages between 0.0 and 100.0
 151
 152 - Adjusted: Use this when we need to compare against a threshold
 153   (SpamAssasssin)
 154