]>
Commit | Line | Data |
---|---|---|
62e86eb6 DM |
1 | Mail Filter |
2 | =========== | |
3 | ||
4 | {pmg} ships with a highly configurable mail filter. It’s an easy but | |
5 | powerful way to define filter rules by user, domains, time frame, | |
6 | content type and resulting action. | |
7 | ||
8 | image::images/screenshot/pmg-gui-mail-filter-rules.png[] | |
9 | ||
c9d28a2b DM |
10 | Every rule has 5 categories ('FROM', 'TO', 'WHEN', 'WHAT' and |
11 | 'ACTION'), and each category may contain several objects to match | |
12 | certain criteria: | |
62e86eb6 | 13 | |
a16d5544 | 14 | 'Who' - objects:: |
62e86eb6 | 15 | |
c9d28a2b | 16 | Who is the sender or receiver of the e-mail? Those objects can be used |
62e86eb6 DM |
17 | for the 'TO' and/or 'FROM' category. |
18 | + | |
19 | ==== | |
20 | Example: EMail-object - Who is the sender or receiver of the e-mail? | |
21 | ==== | |
22 | ||
a16d5544 | 23 | 'What' - objects:: |
62e86eb6 DM |
24 | |
25 | What is in the e-mail? | |
26 | + | |
27 | ==== | |
c9d28a2b | 28 | Example: Does the e-mail contain spam? |
62e86eb6 DM |
29 | ==== |
30 | ||
a16d5544 | 31 | 'When' - objects:: |
62e86eb6 DM |
32 | |
33 | When is the e-mail received by {pmg}? | |
34 | + | |
35 | ==== | |
36 | Example: Office Hours - Mail is received between 8:00 and 16:00. | |
37 | ==== | |
38 | ||
a16d5544 | 39 | 'Action' - objects:: |
62e86eb6 DM |
40 | |
41 | Defines the final actions. | |
42 | + | |
43 | ==== | |
44 | Example: Mark e-mail with “SPAM:” in the subject. | |
45 | ==== | |
c9d28a2b DM |
46 | |
47 | Rules are ordered by priority, so rules with higher priority are | |
48 | executed first. It is also possible to set a processing direction: | |
49 | ||
50 | 'In':: Rule applies for all incoming e-mails | |
51 | ||
52 | 'Out':: Rule applies for all outgoing e-mails | |
53 | ||
54 | 'In & Out':: Rule applies for both directions | |
55 | ||
56 | And you can also disable a rule completely, which is mostly useful for | |
57 | testing and debugging. The 'Factory Defaults' button alows you to | |
58 | reset the filter rules. | |
59 | ||
60 | ||
a16d5544 DM |
61 | 'Action' - objects |
62 | ------------------ | |
c9d28a2b DM |
63 | |
64 | image::images/screenshot/pmg-gui-mail-filter-actions.png[] | |
65 | ||
66 | Please note that some actions stops further rule precessing. We call | |
67 | such actions 'final'. | |
68 | ||
69 | Accept | |
70 | ~~~~~~ | |
71 | ||
72 | Accept mail for Delivery. This is a 'final' action. | |
73 | ||
74 | ||
75 | Block | |
76 | ~~~~~ | |
77 | ||
78 | Block mail. This is a 'final' action. | |
79 | ||
80 | ||
81 | Quarantine | |
82 | ~~~~~~~~~~ | |
83 | ||
84 | Move to quarantine (virus mails are moved to the “virus quarantine”, | |
85 | other mails are moved to “spam quarantine”). This is also a 'final' action. | |
86 | ||
87 | ||
88 | Notification | |
89 | ~~~~~~~~~~~~ | |
90 | ||
91 | Send notifications. Please note that object configuration can use | |
92 | xref:rule_system_macros[macros], so it is easy to include additional | |
93 | information. For example, the default 'Notify Admin' object sends the | |
94 | following information: | |
95 | ||
96 | .Sample notification action body: | |
97 | ---- | |
98 | Proxmox Notification: | |
99 | Sender: __SENDER__ | |
100 | Receiver: __RECEIVERS__ | |
101 | Targets: __TARGETS__ | |
102 | Subject: __SUBJECT__ | |
103 | Matching Rule: __RULE__ | |
104 | ||
105 | __RULE_INFO__ | |
106 | ||
107 | __VIRUS_INFO__ | |
108 | __SPAM_INFO__ | |
109 | ---- | |
110 | ||
111 | Notification can also include a copy of the original mail. | |
112 | ||
113 | ||
114 | Blind Carbon Copy (BCC) | |
115 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
116 | ||
117 | The BCC object simply sends a copy to another target. It is possible to | |
118 | send the original unmodified mail, or the processed result. Please | |
119 | note that this can be quite different, i.e. when a previous rule | |
120 | removed attachments. | |
121 | ||
122 | ||
123 | Header Attributes | |
124 | ~~~~~~~~~~~~~~~~~ | |
125 | ||
126 | This object is able to add or modify mail header attributes. As notice above, you can use xref:rule_system_macros[macros], making this a very powerful object. For example, the 'Modify Spam Level' actions adds detailed infomation about detected Spam characteristics to the ` X-SPAM-LEVEL` header. | |
127 | ||
733e5b36 | 128 | .'Modify Spam Level' Header Attribute |
c9d28a2b DM |
129 | ---- |
130 | Field: X-SPAM-LEVEL | |
131 | Value: __SPAM_INFO__ | |
132 | ---- | |
133 | ||
134 | Another prominent example is the 'Modify Spam Subject' action. This | |
135 | simply adds the 'SPAM:' prefix to the original mail subject: | |
136 | ||
733e5b36 | 137 | .'Modify Spam Subject' Header Attribute |
c9d28a2b DM |
138 | ---- |
139 | Field: subject | |
140 | Value: SPAM: __SUBJECT__ | |
141 | ---- | |
142 | ||
143 | ||
144 | Remove attachments | |
145 | ~~~~~~~~~~~~~~~~~~ | |
146 | ||
147 | Remove attachments can either remove all attachments, or only those | |
a16d5544 | 148 | matched by the rules 'What' - object. You can also specify the |
c9d28a2b DM |
149 | replacement text if you want. |
150 | ||
151 | ||
152 | Disclaimer | |
153 | ~~~~~~~~~~ | |
154 | ||
155 | Add a Disclaimer. | |
66b48b3a DM |
156 | |
157 | ||
a16d5544 DM |
158 | 'Who' - objects |
159 | --------------- | |
66b48b3a DM |
160 | |
161 | image::images/screenshot/pmg-gui-mail-filter-who-objects.png[] | |
162 | ||
163 | This type of objects can be used for the 'TO' and/or 'FROM' category, | |
164 | and macth the sender or receiver of the e-mail. A single object can | |
165 | combine multiple items, and the following item types are available: | |
166 | ||
167 | EMail:: | |
168 | ||
169 | Allows you to match a single mail address. | |
170 | ||
171 | Domain:: | |
172 | ||
173 | Only match the domain part of the mail address. | |
174 | ||
175 | Regular Expression:: | |
176 | ||
177 | This one uses a regular expression to match the whole mail address. | |
178 | ||
179 | IP Address or Network:: | |
180 | ||
181 | This can be used to match the senders IP address. | |
182 | ||
183 | LDAP User or Group:: | |
184 | ||
185 | Test if the mail address belong to a specific LDAP user or group. | |
186 | ||
a16d5544 | 187 | We have two important 'Who' - objects called 'Blacklist' and |
66b48b3a | 188 | 'Whitelist'. Those are used in the default ruleset to globally block |
3228913a DM |
189 | or allow specific senders. |
190 | ||
40ed107a | 191 | |
a16d5544 DM |
192 | 'What' - objects |
193 | ---------------- | |
40ed107a DM |
194 | |
195 | image::images/screenshot/pmg-gui-mail-filter-what-objects.png[] | |
196 | ||
a16d5544 DM |
197 | 'What' - objects are used to classify the mail content. A single |
198 | object can combine multiple items, and the following item types are | |
40ed107a DM |
199 | available: |
200 | ||
201 | Spam Filter:: | |
202 | ||
203 | Matches if configured value if greater than the detected spam level. | |
204 | ||
205 | Virus Filter:: | |
206 | ||
207 | Matches on infected mails. | |
208 | ||
fc900299 DM |
209 | Match Field:: |
210 | ||
211 | Match specified mail header fields (eg. `Subject:`, `From:`, ...) | |
212 | ||
40ed107a DM |
213 | Content Type Filter:: |
214 | ||
215 | Can be used to match specific content types. | |
216 | ||
217 | Match Filename:: | |
218 | ||
219 | Uses regular expressions to match attachment filenames. | |
220 | ||
221 | Archive Filter:: | |
222 | ||
223 | Can be used to match specific content types inside archives. | |
224 | ||
225 | ||
a16d5544 DM |
226 | 'When' - objects |
227 | ---------------- | |
3228913a DM |
228 | |
229 | image::images/screenshot/pmg-gui-mail-filter-when-objects.png[] | |
230 | ||
a16d5544 DM |
231 | 'When' - objects are use to activate rules at specific daytimes. You |
232 | can compose them of one or more time-frame items. | |
3228913a DM |
233 | |
234 | The default ruleset defines 'Office Hours', but this is not used by | |
235 | the default rules. | |
99fd4bd4 DM |
236 | |
237 | ||
238 | Using regular expressions | |
239 | ------------------------- | |
240 | ||
241 | A regular expression is a string of characters which tells us which | |
242 | string you are looking for. The following is a short introduction in | |
243 | the syntax of regular expressions used by some objects. If you are | |
244 | familiar with Perl, you already know the syntax. | |
245 | ||
246 | Simple regular expressions | |
247 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
248 | ||
249 | In its simplest form, a regular expression is just a word or phrase to | |
250 | search for. `Mail` would match the string "Mail". The search is case | |
251 | sensitive so "MAIL", "Mail", "mail" would not be matched. | |
252 | ||
253 | Metacharacters | |
254 | ~~~~~~~~~~~~~~ | |
255 | ||
256 | Some characters have a special meaning. These characters are called | |
257 | metacharacters. The Period (`.`) is a commonly used metacharacter. It | |
258 | matches exactly one character, regardless of what the character is. | |
259 | `e.mail` would match either "e-mail" or "e-mail" or "e2mail" but not | |
260 | "e-some-mail". | |
261 | ||
262 | The question mark (`?`) indicates that the character immediately | |
263 | preceding it either zero or one time. `e?mail` would match | |
264 | either "email" or "mail" but not "e-mail". | |
265 | ||
266 | Another metacharacter is the star (`*`). This indicates that the | |
267 | character immediately to its left may repeated any number of times, | |
268 | including zero. `e*mail` would match either "email" or "mail" or | |
269 | "eeemail". | |
270 | ||
271 | The plus (`+`) metacharacter does the same as the star (*) excluding | |
272 | zero. So `e+mail` does not match "mail". | |
273 | ||
274 | Metacharacters may be combined. A common combination includes the | |
275 | period and star metacharacters (`.*`), with the star immediately following | |
276 | the period. This is used to match an arbitrary string of any length, | |
277 | including the null string. For example: `.*company.*` matches | |
278 | "company@domain.com" or "company@domain.co.uk" or | |
279 | "department.company@domain.com". | |
0601bef2 DM |
280 | |
281 | The book xref:Friedl97[] provides a more comprehensive introduction. |