]>
Commit | Line | Data |
---|---|---|
4a08dffe | 1 | [[chapter_mailfilter]] |
af0f1800 SI |
2 | Rule-Based Mail Filter |
3 | ====================== | |
62e86eb6 | 4 | |
f86a08de DW |
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. | |
62e86eb6 | 8 | |
a695a527 | 9 | [thumbnail="pmg-gui-mail-filter-rules.png", big=1] |
62e86eb6 | 10 | |
f86a08de | 11 | Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT', and |
c9d28a2b DM |
12 | 'ACTION'), and each category may contain several objects to match |
13 | certain criteria: | |
62e86eb6 | 14 | |
a16d5544 | 15 | 'Who' - objects:: |
62e86eb6 | 16 | |
6994b407 | 17 | Who is the sender or recipient of the email? Those objects can be used |
62e86eb6 DM |
18 | for the 'TO' and/or 'FROM' category. |
19 | + | |
20 | ==== | |
6994b407 | 21 | Example: EMail-object - Who is the sender or recipient of the email? |
62e86eb6 DM |
22 | ==== |
23 | ||
a16d5544 | 24 | 'What' - objects:: |
62e86eb6 | 25 | |
6994b407 | 26 | What is in the email? |
62e86eb6 DM |
27 | + |
28 | ==== | |
6994b407 | 29 | Example: Does the email contain spam? |
62e86eb6 DM |
30 | ==== |
31 | ||
a16d5544 | 32 | 'When' - objects:: |
62e86eb6 | 33 | |
6994b407 | 34 | When is the email received by {pmg}? |
62e86eb6 DM |
35 | + |
36 | ==== | |
37 | Example: Office Hours - Mail is received between 8:00 and 16:00. | |
38 | ==== | |
39 | ||
a16d5544 | 40 | 'Action' - objects:: |
62e86eb6 DM |
41 | |
42 | Defines the final actions. | |
43 | + | |
44 | ==== | |
6994b407 | 45 | Example: Mark email with “SPAM:” in the subject. |
62e86eb6 | 46 | ==== |
c9d28a2b DM |
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 | ||
f86a08de | 51 | 'In':: Rule applies to all incoming emails |
c9d28a2b | 52 | |
f86a08de | 53 | 'Out':: Rule applies to all outgoing emails |
c9d28a2b | 54 | |
f86a08de | 55 | 'In & Out':: Rule applies to both directions |
c9d28a2b | 56 | |
f86a08de DW |
57 | You can also disable a rule completely, which is mostly useful for |
58 | testing and debugging. The 'Factory Defaults' button allows you to | |
c9d28a2b DM |
59 | reset the filter rules. |
60 | ||
e807e3f1 DC |
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 | |
dae08541 | 66 | should be applied by default: |
e807e3f1 DC |
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 | ||
dae08541 DC |
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' | |
c9d28a2b | 116 | |
4a08dffe | 117 | [[pmg_mailfilter_action]] |
a16d5544 DM |
118 | 'Action' - objects |
119 | ------------------ | |
c9d28a2b | 120 | |
a695a527 | 121 | [thumbnail="pmg-gui-mail-filter-actions.png", big=1] |
c9d28a2b | 122 | |
6994b407 | 123 | Please note that some actions stop further rule processing. We call |
c9d28a2b DM |
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 | ||
f86a08de | 141 | Move to quarantine (virus mails are moved to the “virus quarantine”; |
c9d28a2b DM |
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 | |
f86a08de | 176 | note that this can be quite different, for instance, when a previous rule |
c9d28a2b DM |
177 | removed attachments. |
178 | ||
179 | ||
180 | Header Attributes | |
181 | ~~~~~~~~~~~~~~~~~ | |
182 | ||
f86a08de DW |
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. | |
c9d28a2b | 188 | |
733e5b36 | 189 | .'Modify Spam Level' Header Attribute |
c9d28a2b DM |
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 | ||
733e5b36 | 198 | .'Modify Spam Subject' Header Attribute |
c9d28a2b DM |
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 | |
f86a08de DW |
209 | matched by the rule's 'What' - object. You can also specify the |
210 | replacement text, if you want. | |
c9d28a2b | 211 | |
f86a08de | 212 | You can optionally move these mails into the attachment quarantine, where |
f7d90c0a | 213 | the original mail with all attachments will be stored. The mail with the |
f86a08de | 214 | attachments removed will continue through the rule system. |
f7d90c0a | 215 | |
f86a08de | 216 | NOTE: The Attachment Quarantine lifetime is the same as for the Spam Quarantine. |
f7d90c0a | 217 | |
c9d28a2b DM |
218 | |
219 | Disclaimer | |
220 | ~~~~~~~~~~ | |
221 | ||
222 | Add a Disclaimer. | |
66b48b3a | 223 | |
7b56a71c TL |
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. | |
9b18c05f | 227 | |
024e41f5 DC |
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 | ||
66b48b3a | 233 | |
4a08dffe | 234 | [[pmg_mailfilter_who]] |
f86a08de DW |
235 | 'Who' objects |
236 | ------------- | |
66b48b3a | 237 | |
a695a527 | 238 | [thumbnail="pmg-gui-mail-filter-who-objects.png", big=1] |
66b48b3a | 239 | |
f86a08de | 240 | These types of objects can be used for the 'TO' and/or 'FROM' category, |
6994b407 | 241 | and match the sender or recipient of the email. A single object can |
66b48b3a DM |
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 | ||
6994b407 | 262 | Test if the mail address belongs to a specific LDAP user or group. |
66b48b3a | 263 | |
f86a08de | 264 | We have two important 'Who' objects called 'Blacklist' and |
6994b407 | 265 | 'Whitelist'. These are used in the default ruleset to globally block |
3228913a DM |
266 | or allow specific senders. |
267 | ||
40ed107a | 268 | |
4a08dffe | 269 | [[pmg_mailfilter_what]] |
f86a08de DW |
270 | 'What' objects |
271 | -------------- | |
40ed107a | 272 | |
a695a527 | 273 | [thumbnail="pmg-gui-mail-filter-what-objects.png", big=1] |
40ed107a | 274 | |
f86a08de | 275 | 'What' objects are used to classify the mail's content. A single |
a16d5544 | 276 | object can combine multiple items, and the following item types are |
40ed107a DM |
277 | available: |
278 | ||
279 | Spam Filter:: | |
280 | ||
f86a08de DW |
281 | Matches if the detected spam level is greater than or equal to the |
282 | configured value. | |
40ed107a DM |
283 | |
284 | Virus Filter:: | |
285 | ||
286 | Matches on infected mails. | |
287 | ||
fc900299 DM |
288 | Match Field:: |
289 | ||
f86a08de | 290 | Match specified mail header fields (for example, `Subject:`, `From:`, ...) |
fc900299 | 291 | |
40ed107a DM |
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. | |
883ec2c4 | 303 | This also matches the content-types of all regular (non-archived) attachments. |
40ed107a | 304 | |
d5c0557a DC |
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 | ||
40ed107a | 310 | |
4a08dffe | 311 | [[pmg_mailfilter_when]] |
f86a08de DW |
312 | 'When' objects |
313 | -------------- | |
3228913a | 314 | |
a695a527 | 315 | [thumbnail="pmg-gui-mail-filter-when-objects.png", big=1] |
3228913a | 316 | |
f86a08de DW |
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. | |
3228913a DM |
319 | |
320 | The default ruleset defines 'Office Hours', but this is not used by | |
321 | the default rules. | |
99fd4bd4 DM |
322 | |
323 | ||
4a08dffe | 324 | [[pmg_mailfilter_regex]] |
99fd4bd4 DM |
325 | Using regular expressions |
326 | ------------------------- | |
327 | ||
f86a08de DW |
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. | |
99fd4bd4 DM |
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. | |
6994b407 OB |
347 | `e.mail` would match either "e-mail" or "e2mail" but not |
348 | "e-some-mail" or "email". | |
99fd4bd4 DM |
349 | |
350 | The question mark (`?`) indicates that the character immediately | |
6994b407 | 351 | preceding it shows up either zero or one time. `e?mail` would match |
99fd4bd4 DM |
352 | either "email" or "mail" but not "e-mail". |
353 | ||
f86a08de | 354 | Another metacharacter is the asterisk (`*`). This indicates that the |
6994b407 | 355 | character immediately preceding it may be repeated any number of times, |
f86a08de | 356 | including zero. `e*mail` would match "email", "mail", and |
99fd4bd4 DM |
357 | "eeemail". |
358 | ||
f86a08de DW |
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". | |
99fd4bd4 | 362 | |
f86a08de DW |
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". | |
0601bef2 | 369 | |
6994b407 | 370 | The book xref:Friedl97[] provides a more comprehensive introduction. |