]>
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 | ||
61 | ||
4a08dffe | 62 | [[pmg_mailfilter_action]] |
a16d5544 DM |
63 | 'Action' - objects |
64 | ------------------ | |
c9d28a2b | 65 | |
a695a527 | 66 | [thumbnail="pmg-gui-mail-filter-actions.png", big=1] |
c9d28a2b | 67 | |
6994b407 | 68 | Please note that some actions stop further rule processing. We call |
c9d28a2b DM |
69 | such actions 'final'. |
70 | ||
71 | Accept | |
72 | ~~~~~~ | |
73 | ||
74 | Accept mail for Delivery. This is a 'final' action. | |
75 | ||
76 | ||
77 | Block | |
78 | ~~~~~ | |
79 | ||
80 | Block mail. This is a 'final' action. | |
81 | ||
82 | ||
83 | Quarantine | |
84 | ~~~~~~~~~~ | |
85 | ||
f86a08de | 86 | Move to quarantine (virus mails are moved to the “virus quarantine”; |
c9d28a2b DM |
87 | other mails are moved to “spam quarantine”). This is also a 'final' action. |
88 | ||
89 | ||
90 | Notification | |
91 | ~~~~~~~~~~~~ | |
92 | ||
93 | Send notifications. Please note that object configuration can use | |
94 | xref:rule_system_macros[macros], so it is easy to include additional | |
95 | information. For example, the default 'Notify Admin' object sends the | |
96 | following information: | |
97 | ||
98 | .Sample notification action body: | |
99 | ---- | |
100 | Proxmox Notification: | |
101 | Sender: __SENDER__ | |
102 | Receiver: __RECEIVERS__ | |
103 | Targets: __TARGETS__ | |
104 | Subject: __SUBJECT__ | |
105 | Matching Rule: __RULE__ | |
106 | ||
107 | __RULE_INFO__ | |
108 | ||
109 | __VIRUS_INFO__ | |
110 | __SPAM_INFO__ | |
111 | ---- | |
112 | ||
113 | Notification can also include a copy of the original mail. | |
114 | ||
115 | ||
116 | Blind Carbon Copy (BCC) | |
117 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
118 | ||
119 | The BCC object simply sends a copy to another target. It is possible to | |
120 | send the original unmodified mail, or the processed result. Please | |
f86a08de | 121 | note that this can be quite different, for instance, when a previous rule |
c9d28a2b DM |
122 | removed attachments. |
123 | ||
124 | ||
125 | Header Attributes | |
126 | ~~~~~~~~~~~~~~~~~ | |
127 | ||
f86a08de DW |
128 | This object is able to add or modify mail header attributes. As with |
129 | Notifications above, you can use xref:rule_system_macros[macros], | |
130 | making this a very powerful object. For example, the 'Modify Spam | |
131 | Level' actions add detailed information about detected Spam | |
132 | characteristics to the `X-SPAM-LEVEL` header. | |
c9d28a2b | 133 | |
733e5b36 | 134 | .'Modify Spam Level' Header Attribute |
c9d28a2b DM |
135 | ---- |
136 | Field: X-SPAM-LEVEL | |
137 | Value: __SPAM_INFO__ | |
138 | ---- | |
139 | ||
140 | Another prominent example is the 'Modify Spam Subject' action. This | |
141 | simply adds the 'SPAM:' prefix to the original mail subject: | |
142 | ||
733e5b36 | 143 | .'Modify Spam Subject' Header Attribute |
c9d28a2b DM |
144 | ---- |
145 | Field: subject | |
146 | Value: SPAM: __SUBJECT__ | |
147 | ---- | |
148 | ||
149 | ||
150 | Remove attachments | |
151 | ~~~~~~~~~~~~~~~~~~ | |
152 | ||
153 | Remove attachments can either remove all attachments, or only those | |
f86a08de DW |
154 | matched by the rule's 'What' - object. You can also specify the |
155 | replacement text, if you want. | |
c9d28a2b | 156 | |
f86a08de | 157 | You can optionally move these mails into the attachment quarantine, where |
f7d90c0a | 158 | the original mail with all attachments will be stored. The mail with the |
f86a08de | 159 | attachments removed will continue through the rule system. |
f7d90c0a | 160 | |
f86a08de | 161 | NOTE: The Attachment Quarantine lifetime is the same as for the Spam Quarantine. |
f7d90c0a | 162 | |
c9d28a2b DM |
163 | |
164 | Disclaimer | |
165 | ~~~~~~~~~~ | |
166 | ||
167 | Add a Disclaimer. | |
66b48b3a | 168 | |
7b56a71c TL |
169 | The disclaimer can contain HTML markup. It will be added to the first |
170 | `text/html` and `text/plain` part of an email. A disclaimer only gets added if | |
171 | its text can be encoded in the mail's character encoding. | |
9b18c05f | 172 | |
66b48b3a | 173 | |
4a08dffe | 174 | [[pmg_mailfilter_who]] |
f86a08de DW |
175 | 'Who' objects |
176 | ------------- | |
66b48b3a | 177 | |
a695a527 | 178 | [thumbnail="pmg-gui-mail-filter-who-objects.png", big=1] |
66b48b3a | 179 | |
f86a08de | 180 | These types of objects can be used for the 'TO' and/or 'FROM' category, |
6994b407 | 181 | and match the sender or recipient of the email. A single object can |
66b48b3a DM |
182 | combine multiple items, and the following item types are available: |
183 | ||
184 | EMail:: | |
185 | ||
186 | Allows you to match a single mail address. | |
187 | ||
188 | Domain:: | |
189 | ||
190 | Only match the domain part of the mail address. | |
191 | ||
192 | Regular Expression:: | |
193 | ||
194 | This one uses a regular expression to match the whole mail address. | |
195 | ||
196 | IP Address or Network:: | |
197 | ||
198 | This can be used to match the senders IP address. | |
199 | ||
200 | LDAP User or Group:: | |
201 | ||
6994b407 | 202 | Test if the mail address belongs to a specific LDAP user or group. |
66b48b3a | 203 | |
f86a08de | 204 | We have two important 'Who' objects called 'Blacklist' and |
6994b407 | 205 | 'Whitelist'. These are used in the default ruleset to globally block |
3228913a DM |
206 | or allow specific senders. |
207 | ||
40ed107a | 208 | |
4a08dffe | 209 | [[pmg_mailfilter_what]] |
f86a08de DW |
210 | 'What' objects |
211 | -------------- | |
40ed107a | 212 | |
a695a527 | 213 | [thumbnail="pmg-gui-mail-filter-what-objects.png", big=1] |
40ed107a | 214 | |
f86a08de | 215 | 'What' objects are used to classify the mail's content. A single |
a16d5544 | 216 | object can combine multiple items, and the following item types are |
40ed107a DM |
217 | available: |
218 | ||
219 | Spam Filter:: | |
220 | ||
f86a08de DW |
221 | Matches if the detected spam level is greater than or equal to the |
222 | configured value. | |
40ed107a DM |
223 | |
224 | Virus Filter:: | |
225 | ||
226 | Matches on infected mails. | |
227 | ||
fc900299 DM |
228 | Match Field:: |
229 | ||
f86a08de | 230 | Match specified mail header fields (for example, `Subject:`, `From:`, ...) |
fc900299 | 231 | |
40ed107a DM |
232 | Content Type Filter:: |
233 | ||
234 | Can be used to match specific content types. | |
235 | ||
236 | Match Filename:: | |
237 | ||
238 | Uses regular expressions to match attachment filenames. | |
239 | ||
240 | Archive Filter:: | |
241 | ||
242 | Can be used to match specific content types inside archives. | |
883ec2c4 | 243 | This also matches the content-types of all regular (non-archived) attachments. |
40ed107a | 244 | |
d5c0557a DC |
245 | Match Archive Filename:: |
246 | ||
247 | Uses regular expressions to match attachment filenames inside archives. | |
248 | This also matches the filenames for all regular (non-archived) attachments. | |
249 | ||
40ed107a | 250 | |
4a08dffe | 251 | [[pmg_mailfilter_when]] |
f86a08de DW |
252 | 'When' objects |
253 | -------------- | |
3228913a | 254 | |
a695a527 | 255 | [thumbnail="pmg-gui-mail-filter-when-objects.png", big=1] |
3228913a | 256 | |
f86a08de DW |
257 | 'When' objects are used to activate rules at specific times of the |
258 | day. You can compose them from one or more time frame items. | |
3228913a DM |
259 | |
260 | The default ruleset defines 'Office Hours', but this is not used by | |
261 | the default rules. | |
99fd4bd4 DM |
262 | |
263 | ||
4a08dffe | 264 | [[pmg_mailfilter_regex]] |
99fd4bd4 DM |
265 | Using regular expressions |
266 | ------------------------- | |
267 | ||
f86a08de DW |
268 | A regular expression is a string of characters which represents a list |
269 | of text patterns which you would like to match. The following is a | |
270 | short introduction to the syntax of regular expressions used by some | |
271 | objects. If you are familiar with Perl, you will already know the | |
272 | syntax. | |
99fd4bd4 DM |
273 | |
274 | Simple regular expressions | |
275 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
276 | ||
277 | In its simplest form, a regular expression is just a word or phrase to | |
278 | search for. `Mail` would match the string "Mail". The search is case | |
279 | sensitive so "MAIL", "Mail", "mail" would not be matched. | |
280 | ||
281 | Metacharacters | |
282 | ~~~~~~~~~~~~~~ | |
283 | ||
284 | Some characters have a special meaning. These characters are called | |
285 | metacharacters. The Period (`.`) is a commonly used metacharacter. It | |
286 | matches exactly one character, regardless of what the character is. | |
6994b407 OB |
287 | `e.mail` would match either "e-mail" or "e2mail" but not |
288 | "e-some-mail" or "email". | |
99fd4bd4 DM |
289 | |
290 | The question mark (`?`) indicates that the character immediately | |
6994b407 | 291 | preceding it shows up either zero or one time. `e?mail` would match |
99fd4bd4 DM |
292 | either "email" or "mail" but not "e-mail". |
293 | ||
f86a08de | 294 | Another metacharacter is the asterisk (`*`). This indicates that the |
6994b407 | 295 | character immediately preceding it may be repeated any number of times, |
f86a08de | 296 | including zero. `e*mail` would match "email", "mail", and |
99fd4bd4 DM |
297 | "eeemail". |
298 | ||
f86a08de DW |
299 | The plus (`+`) metacharacter indicates that the character immediately |
300 | preceding it appears one or more times. So `e+mail` does not match | |
301 | "mail". | |
99fd4bd4 | 302 | |
f86a08de DW |
303 | Metacharacters can also be combined. A common combination includes the |
304 | period and asterisk metacharacters (`.*`), with the asterisk | |
305 | immediately following the period. This is used to match an arbitrary | |
306 | string of any length, including the null string. For example: | |
307 | `.*company.*` matches "company@domain.com" or "company@domain.co.uk" | |
308 | or "department.company@domain.com". | |
0601bef2 | 309 | |
6994b407 | 310 | The book xref:Friedl97[] provides a more comprehensive introduction. |