]>
Commit | Line | Data |
---|---|---|
1 | [[chapter_mailfilter]] | |
2 | Rule-Based Mail Filter | |
3 | ====================== | |
4 | ||
5 | {pmg} ships with a highly configurable mail filter. This provides an | |
6 | easy but powerful way to define filter rules by user, domain, time | |
7 | frame, content type, and resulting action. | |
8 | ||
9 | [thumbnail="screenshot/pmg-gui-mail-filter-rules.png", big=1] | |
10 | ||
11 | Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT', and | |
12 | 'ACTION'), and each category may contain several objects to match | |
13 | certain criteria: | |
14 | ||
15 | 'Who' - objects:: | |
16 | ||
17 | Who is the sender or recipient of the email? Those objects can be used | |
18 | for the 'TO' and/or 'FROM' category. | |
19 | + | |
20 | ==== | |
21 | Example: EMail-object - Who is the sender or recipient of the email? | |
22 | ==== | |
23 | ||
24 | 'What' - objects:: | |
25 | ||
26 | What is in the email? | |
27 | + | |
28 | ==== | |
29 | Example: Does the email contain spam? | |
30 | ==== | |
31 | ||
32 | 'When' - objects:: | |
33 | ||
34 | When is the email received by {pmg}? | |
35 | + | |
36 | ==== | |
37 | Example: Office Hours - Mail is received between 8:00 and 16:00. | |
38 | ==== | |
39 | ||
40 | 'Action' - objects:: | |
41 | ||
42 | Defines the final actions. | |
43 | + | |
44 | ==== | |
45 | Example: Mark email with “SPAM:” in the subject. | |
46 | ==== | |
47 | ||
48 | Rules are ordered by priority, so rules with higher priority are | |
49 | executed first. It is also possible to set a processing direction: | |
50 | ||
51 | 'In':: Rule applies to all incoming emails | |
52 | ||
53 | 'Out':: Rule applies to all outgoing emails | |
54 | ||
55 | 'In & Out':: Rule applies to both directions | |
56 | ||
57 | You can also disable a rule completely, which is mostly useful for | |
58 | testing and debugging. The 'Factory Defaults' button allows you to | |
59 | reset the filter rules. | |
60 | ||
61 | Application of Rules | |
62 | -------------------- | |
63 | ||
64 | When there is more than one object category or multiple objects configured | |
65 | within a single rule, the following logic is used to determine if the rule | |
66 | should be applied by default: | |
67 | ||
68 | * Within one category (WHAT/FROM/TO/WHEN), all objects are logical-or linked, | |
69 | meaning that only one object of any one object group from the same category | |
70 | has to match for the whole category to match. | |
71 | ||
72 | * FROM/TO/WHAT/WHEN category match results are logical-and linked, so all | |
73 | categories that have at least one object in them must match for the rule to | |
74 | match. | |
75 | ||
76 | When these conditions are met, all configured actions are executed. | |
77 | ||
78 | Alternatively, one can configure the 'mode' to 'any' (the default) or 'all' and | |
79 | set 'invert' (default off) per object group and per object category for each | |
80 | rule. | |
81 | ||
82 | When the mode is 'all' for a group, all objects within must match for the | |
83 | object group to count as a match. This can be helpful when one wants to match | |
84 | multiple conditions at the same time (e.g. file content-type and filename). | |
85 | ||
86 | When 'all' is set for a category of a rule, all object groups for that | |
87 | type must match for the type to match. | |
88 | ||
89 | When 'invert' is active on a group, the original result of the group will | |
90 | simply be inverted, so a match becomes a non-match and vice versa. | |
91 | ||
92 | The same is true for the object group types for rules. | |
93 | ||
94 | Special handling is done for WHAT matches that mark mail parts (e.g. filename) | |
95 | since that is not a simple yes/no match for the complete mail, but could be a | |
96 | match for each part of the e-mail (e.g. attachments, or parts of a multi-part | |
97 | e-mail). | |
98 | ||
99 | So for WHAT match object groups, the 'mode' and 'invert' is applied to | |
100 | the single parts of the e-mail, not the message as a whole. | |
101 | ||
102 | This means one has to be very careful with the 'invert' option, as previously | |
103 | not matching parts, will match when using 'invert' (e.g. an inverted filename | |
104 | matching will also mark non attachment parts of the mail). | |
105 | ||
106 | On the rule level, these marks of the parts will always be logical-or linked, | |
107 | this way even more scenarios can be represented. | |
108 | ||
109 | To make it a bit easier to understand, the options are combined to a single | |
110 | selection in the web ui: | |
111 | ||
112 | * Any must match => mode: 'any', invert: 'off' | |
113 | * All must match => mode: 'all', invert: 'off' | |
114 | * At least one must not match => mode: 'all', invert: 'on' | |
115 | * None must match => mode: 'any', invert: 'on' | |
116 | ||
117 | [[pmg_mailfilter_action]] | |
118 | 'Action' - objects | |
119 | ------------------ | |
120 | ||
121 | [thumbnail="screenshot/pmg-gui-mail-filter-actions.png", big=1] | |
122 | ||
123 | Please note that some actions stop further rule processing. We call | |
124 | such actions 'final'. | |
125 | ||
126 | Accept | |
127 | ~~~~~~ | |
128 | ||
129 | Accept mail for Delivery. This is a 'final' action. | |
130 | ||
131 | ||
132 | Block | |
133 | ~~~~~ | |
134 | ||
135 | Block mail. This is a 'final' action. | |
136 | ||
137 | ||
138 | Quarantine | |
139 | ~~~~~~~~~~ | |
140 | ||
141 | Move to quarantine (virus mails are moved to the “virus quarantine”; | |
142 | other mails are moved to “spam quarantine”). This is also a 'final' action. | |
143 | ||
144 | ||
145 | Notification | |
146 | ~~~~~~~~~~~~ | |
147 | ||
148 | Send notifications. Please note that object configuration can use | |
149 | xref:rule_system_macros[macros], so it is easy to include additional | |
150 | information. For example, the default 'Notify Admin' object sends the | |
151 | following information: | |
152 | ||
153 | .Sample notification action body: | |
154 | ---- | |
155 | Proxmox Notification: | |
156 | Sender: __SENDER__ | |
157 | Receiver: __RECEIVERS__ | |
158 | Targets: __TARGETS__ | |
159 | Subject: __SUBJECT__ | |
160 | Matching Rule: __RULE__ | |
161 | ||
162 | __RULE_INFO__ | |
163 | ||
164 | __VIRUS_INFO__ | |
165 | __SPAM_INFO__ | |
166 | ---- | |
167 | ||
168 | Notification can also include a copy of the original mail. | |
169 | ||
170 | ||
171 | Blind Carbon Copy (BCC) | |
172 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
173 | ||
174 | The BCC object simply sends a copy to another target. It is possible to | |
175 | send the original unmodified mail, or the processed result. Please | |
176 | note that this can be quite different, for instance, when a previous rule | |
177 | removed attachments. | |
178 | ||
179 | ||
180 | Header Attributes | |
181 | ~~~~~~~~~~~~~~~~~ | |
182 | ||
183 | This object is able to add or modify mail header attributes. As with | |
184 | Notifications above, you can use xref:rule_system_macros[macros], | |
185 | making this a very powerful object. For example, the 'Modify Spam | |
186 | Level' actions add detailed information about detected Spam | |
187 | characteristics to the `X-SPAM-LEVEL` header. | |
188 | ||
189 | .'Modify Spam Level' Header Attribute | |
190 | ---- | |
191 | Field: X-SPAM-LEVEL | |
192 | Value: __SPAM_INFO__ | |
193 | ---- | |
194 | ||
195 | Another prominent example is the 'Modify Spam Subject' action. This | |
196 | simply adds the 'SPAM:' prefix to the original mail subject: | |
197 | ||
198 | .'Modify Spam Subject' Header Attribute | |
199 | ---- | |
200 | Field: subject | |
201 | Value: SPAM: __SUBJECT__ | |
202 | ---- | |
203 | ||
204 | ||
205 | Remove attachments | |
206 | ~~~~~~~~~~~~~~~~~~ | |
207 | ||
208 | Remove attachments can either remove all attachments, or only those | |
209 | matched by the rule's 'What' - object. You can also specify the | |
210 | replacement text, if you want. | |
211 | ||
212 | You can optionally move these mails into the attachment quarantine, where | |
213 | the original mail with all attachments will be stored. The mail with the | |
214 | attachments removed will continue through the rule system. | |
215 | ||
216 | NOTE: The Attachment Quarantine lifetime is the same as for the Spam Quarantine. | |
217 | ||
218 | ||
219 | Disclaimer | |
220 | ~~~~~~~~~~ | |
221 | ||
222 | Add a Disclaimer. | |
223 | ||
224 | The disclaimer can contain HTML markup. It will be added to the first | |
225 | `text/html` and `text/plain` part of an email. A disclaimer only gets added if | |
226 | its text can be encoded in the mail's character encoding. | |
227 | ||
228 | By default it will be appended at the end of the selected part of the mail with | |
229 | `--` as a separator. The position (start or end of the selected part) and the | |
230 | existence of the separator can be configured with the `position` and | |
231 | `add-separator` options respectively. | |
232 | ||
233 | ||
234 | [[pmg_mailfilter_who]] | |
235 | 'Who' objects | |
236 | ------------- | |
237 | ||
238 | [thumbnail="screenshot/pmg-gui-mail-filter-who-objects.png", big=1] | |
239 | ||
240 | These types of objects can be used for the 'TO' and/or 'FROM' category, | |
241 | and match the sender or recipient of the email. A single object can | |
242 | combine multiple items, and the following item types are available: | |
243 | ||
244 | EMail:: | |
245 | ||
246 | Allows you to match a single mail address. | |
247 | ||
248 | Domain:: | |
249 | ||
250 | Only match the domain part of the mail address. | |
251 | ||
252 | Regular Expression:: | |
253 | ||
254 | This one uses a regular expression to match the whole mail address. | |
255 | ||
256 | IP Address or Network:: | |
257 | ||
258 | This can be used to match the senders IP address. | |
259 | ||
260 | LDAP User or Group:: | |
261 | ||
262 | Test if the mail address belongs to a specific LDAP user or group. | |
263 | ||
264 | We have two important 'Who' objects called 'Blacklist' and | |
265 | 'Whitelist'. These are used in the default ruleset to globally block | |
266 | or allow specific senders. | |
267 | ||
268 | ||
269 | [[pmg_mailfilter_what]] | |
270 | 'What' objects | |
271 | -------------- | |
272 | ||
273 | [thumbnail="screenshot/pmg-gui-mail-filter-what-objects.png", big=1] | |
274 | ||
275 | 'What' objects are used to classify the mail's content. A single | |
276 | object can combine multiple items, and the following item types are | |
277 | available: | |
278 | ||
279 | Spam Filter:: | |
280 | ||
281 | Matches if the detected spam level is greater than or equal to the | |
282 | configured value. | |
283 | ||
284 | Virus Filter:: | |
285 | ||
286 | Matches on infected mails. | |
287 | ||
288 | Match Field:: | |
289 | ||
290 | Match specified mail header fields (for example, `Subject:`, `From:`, ...) | |
291 | ||
292 | Content Type Filter:: | |
293 | ||
294 | Can be used to match specific content types. | |
295 | ||
296 | Match Filename:: | |
297 | ||
298 | Uses regular expressions to match attachment filenames. | |
299 | ||
300 | Archive Filter:: | |
301 | ||
302 | Can be used to match specific content types inside archives. | |
303 | This also matches the content-types of all regular (non-archived) attachments. | |
304 | ||
305 | Match Archive Filename:: | |
306 | ||
307 | Uses regular expressions to match attachment filenames inside archives. | |
308 | This also matches the filenames for all regular (non-archived) attachments. | |
309 | ||
310 | ||
311 | [[pmg_mailfilter_when]] | |
312 | 'When' objects | |
313 | -------------- | |
314 | ||
315 | [thumbnail="screenshot/pmg-gui-mail-filter-when-objects.png", big=1] | |
316 | ||
317 | 'When' objects are used to activate rules at specific times of the | |
318 | day. You can compose them from one or more time frame items. | |
319 | ||
320 | The default ruleset defines 'Office Hours', but this is not used by | |
321 | the default rules. | |
322 | ||
323 | ||
324 | [[pmg_mailfilter_regex]] | |
325 | Using regular expressions | |
326 | ------------------------- | |
327 | ||
328 | A regular expression is a string of characters which represents a list | |
329 | of text patterns which you would like to match. The following is a | |
330 | short introduction to the syntax of regular expressions used by some | |
331 | objects. If you are familiar with Perl, you will already know the | |
332 | syntax. | |
333 | ||
334 | Simple regular expressions | |
335 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
336 | ||
337 | In its simplest form, a regular expression is just a word or phrase to | |
338 | search for. `Mail` would match the string "Mail". The search is case | |
339 | sensitive so "MAIL", "Mail", "mail" would not be matched. | |
340 | ||
341 | Metacharacters | |
342 | ~~~~~~~~~~~~~~ | |
343 | ||
344 | Some characters have a special meaning. These characters are called | |
345 | metacharacters. The Period (`.`) is a commonly used metacharacter. It | |
346 | matches exactly one character, regardless of what the character is. | |
347 | `e.mail` would match either "e-mail" or "e2mail" but not | |
348 | "e-some-mail" or "email". | |
349 | ||
350 | The question mark (`?`) indicates that the character immediately | |
351 | preceding it shows up either zero or one time. `e?mail` would match | |
352 | either "email" or "mail" but not "e-mail". | |
353 | ||
354 | Another metacharacter is the asterisk (`*`). This indicates that the | |
355 | character immediately preceding it may be repeated any number of times, | |
356 | including zero. `e*mail` would match "email", "mail", and | |
357 | "eeemail". | |
358 | ||
359 | The plus (`+`) metacharacter indicates that the character immediately | |
360 | preceding it appears one or more times. So `e+mail` does not match | |
361 | "mail". | |
362 | ||
363 | Metacharacters can also be combined. A common combination includes the | |
364 | period and asterisk metacharacters (`.*`), with the asterisk | |
365 | immediately following the period. This is used to match an arbitrary | |
366 | string of any length, including the null string. For example: | |
367 | `.*company.*` matches "company@domain.com" or "company@domain.co.uk" | |
368 | or "department.company@domain.com". | |
369 | ||
370 | The book xref:Friedl97[] provides a more comprehensive introduction. |