pmg-mail-filter.adoc

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