1Mail::SpamAssassin::PluUgsienr::CAoWnLt(r3i)buted Perl DMoaciulm:e:nStpaatmiAosnsassin::Plugin::AWL(3)
2
6 Mail::SpamAssassin::Plugin::AWL - Normalize scores via auto-welcomelist
7
9 To try this out, add this or uncomment this line in init.pre:
10 loadplugin Mail::SpamAssassin::Plugin::AWL
12 Use the supplied 60_awl.cf file (ie you don't have to do anything) or
14 add these lines to a .cf file:
15 header AWL eval:check_from_in_auto_welcomelist()
17 describe AWL From: address is in the auto welcome-list
18 tflags AWL userconf noautolearn
19 priority AWL 1000
20
22 This plugin module provides support for the auto-welcomelist. It keeps
23 track of the average SpamAssassin score for senders. Senders are
24 tracked using a combination of their From: address and their IP
25 address. It then uses that average score to reduce the variability in
26 scoring from message to message and modifies the final score by pushing
27 the result towards the historical average. This improves the accuracy
28 of filtering for most email.
29
31 This plugin module adds the following "tags" that can be used as
32 placeholders in certain options. See "Mail::SpamAssassin::Conf" for
33 more information on TEMPLATE TAGS.
34 _AWL_ AWL modifier
36 _AWLMEAN_ Mean score on which AWL modification is based
37 _AWLCOUNT_ Number of messages on which AWL modification is based
38 _AWLPRESCORE_ Score before AWL
39
41 The following options can be used in both site-wide ("local.cf") and
42 user-specific ("user_prefs") configuration files to customize how
43 SpamAssassin handles incoming email messages.
44 use_auto_welcomelist ( 0 | 1 ) (default: 1)
46 Previously use_auto_whitelist which will work interchangeably until
47 4.1.
48 Whether to use auto-welcomelists. Auto-welcomelists track the
50 long-term average score for each sender and then shift the score of
51 new messages toward that long-term average. This can increase or
52 decrease the score for messages, depending on the long-term
53 behavior of the particular correspondent.
54 For more information about the auto-welcomelist system, please look
56 at the "Automatic Welcomelist System" section of the README file.
57 The auto-welcomelist is not intended as a general-purpose
58 replacement for static welcomelist entries added to your config
59 files.
60 Note that certain tests are ignored when determining the final
62 message score:
63 - rules with tflags set to 'noautolearn'
65 auto_welcomelist_factor n (default: 0.5, range [0..1])
67 Previously auto_whitelist_factor which will work interchangeably
68 until 4.1.
69 How much towards the long-term mean for the sender to regress a
71 message. Basically, the algorithm is to track the long-term mean
72 score of messages for the sender ("mean"), and then once we have
73 otherwise fully calculated the score for this message ("score"), we
74 calculate the final score for the message as:
75 "finalscore" = "score" + ("mean" - "score") * "factor"
77 So if "factor" = 0.5, then we'll move to half way between the
79 calculated score and the mean. If "factor" = 0.3, then we'll move
80 about 1/3 of the way from the score toward the mean. "factor" = 1
81 means just use the long-term mean; "factor" = 0 mean just use the
82 calculated score.
83 auto_welcomelist_ipv4_mask_len n (default: 16, range [0..32])
85 Previously auto_whitelist_ipv4_mask_len which will work
86 interchangeably until 4.1.
87 The AWL database keeps only the specified number of most-
89 significant bits of an IPv4 address in its fields, so that
90 different individual IP addresses within a subnet belonging to the
91 same owner are managed under a single database record. As we have
92 no information available on the allocated address ranges of
93 senders, this CIDR mask length is only an approximation. The
94 default is 16 bits, corresponding to a former class B. Increase the
95 number if a finer granularity is desired, e.g. to 24 (class C) or
96 32. A value 0 is allowed but is not particularly useful, as it
97 would treat the whole internet as a single organization. The number
98 need not be a multiple of 8, any split is allowed.
99 auto_welcomelist_ipv6_mask_len n (default: 48, range [0..128])
101 Previously auto_whitelist_ipv6_mask_len which will work
102 interchangeably until 4.1.
103 The AWL database keeps only the specified number of most-
105 significant bits of an IPv6 address in its fields, so that
106 different individual IP addresses within a subnet belonging to the
107 same owner are managed under a single database record. As we have
108 no information available on the allocated address ranges of
109 senders, this CIDR mask length is only an approximation. The
110 default is 48 bits, corresponding to an address range commonly
111 allocated to individual (smaller) organizations. Increase the
112 number for a finer granularity, e.g. to 64 or 96 or 128, or
113 decrease for wider ranges, e.g. 32. A value 0 is allowed but is
114 not particularly useful, as it would treat the whole internet as a
115 single organization. The number need not be a multiple of 4, any
116 split is allowed.
117 user_awl_sql_override_username
119 Used by the SQLBasedAddrList storage implementation.
120 If this option is set the SQLBasedAddrList module will override the
122 set username with the value given. This can be useful for
123 implementing global or group based auto-welcomelist databases.
124 auto_welcomelist_distinguish_signed
126 Previously auto_whitelist_distinguish_signed which will work
127 interchangeably until 4.1.
128 Used by the SQLBasedAddrList storage implementation.
130 If this option is set the SQLBasedAddrList module will keep
132 separate database entries for DKIM-validated e-mail addresses and
133 for non-validated ones. A pre-requisite when setting this option is
134 that a field awl.signedby exists in a SQL table, otherwise SQL
135 operations will fail (which is why we need this option at all - for
136 compatibility with pre-3.3.0 database schema). A plugin DKIM
137 should also be enabled, as otherwise there is no benefit from
138 turning on this option.
139
141 These settings differ from the ones above, in that they are considered
142 'more privileged' -- even more than the ones in the PRIVILEGED SETTINGS
143 section. No matter what "allow_user_rules" is set to, these can never
144 be set from a user's "user_prefs" file.
145 auto_welcomelist_factory module (default:
147 Mail::SpamAssassin::DBBasedAddrList)
148 Previously auto_whitelist_factory which will work interchangeably
149 until 4.1.
150 Select alternative welcomelist factory module.
152 auto_welcomelist_path /path/filename (default:
154 ~/.spamassassin/auto-welcomelist)
155 Previously auto_whitelist_path which will work interchangeably
156 until 4.1.
157 This is the automatic-welcomelist directory and filename. By
159 default, each user has their own welcomelist database in their
160 "~/.spamassassin" directory with mode 0700. For system-wide
161 SpamAssassin use, you may want to share this across all users,
162 although that is not recommended.
163 auto_welcomelist_db_modules Module ... (default: see below)
165 Previously auto_whitelist_db_modules which will work
166 interchangeably until 4.1.
167 What database modules should be used for the auto-welcomelist
169 storage database file. The first named module that can be loaded
170 from the perl include path will be used. The format is:
171 PreferredModuleName SecondBest ThirdBest ...
173 ie. a space-separated list of perl module names. The default is:
175 DB_File GDBM_File SDBM_File
177 NDBM_File is no longer supported, since it appears to have bugs
179 that preclude its use for the AWL (see SpamAssassin bug 4353).
180 auto_welcomelist_file_mode (default: 0700)
182 Previously auto_whitelist_file_mode which will work interchangeably
183 until 4.1.
184 The file mode bits used for the automatic-welcomelist directory or
186 file.
187 Make sure you specify this using the 'x' mode bits set, as it may
189 also be used to create directories. However, if a file is created,
190 the resulting file will not have any execute bits set (the umask is
191 set to 0111).
192 user_awl_dsn DBI:databasetype:databasename:hostname:port
194 Used by the SQLBasedAddrList storage implementation.
195 This will set the DSN used to connect. Example:
197 "DBI:mysql:spamassassin:localhost"
198 user_awl_sql_username username
200 Used by the SQLBasedAddrList storage implementation.
201 The authorized username to connect to the above DSN.
203 user_awl_sql_password password
205 Used by the SQLBasedAddrList storage implementation.
206 The password for the database username, for the above DSN.
208 user_awl_sql_table tablename
210 Used by the SQLBasedAddrList storage implementation.
211 The table user auto-welcomelists are stored in, for the above DSN.
213perl v5.38.0 2023-07-22Mail::SpamAssassin::Plugin::AWL(3)