pmg-mail-filter.adoc

   1 [[chapter_mailfilter]]
   2 Rule-Based Mail Filter
   3 ======================
   4
   5 {pmg} ships with a highly configurable mail filter. It’s an easy but
   6 powerful way to define filter rules by user, domains, time frame,
   7 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 for all incoming emails
  52
  53 'Out':: Rule applies for all outgoing emails
  54
  55 'In & Out':: Rule applies for both directions
  56
  57 And you can also disable a rule completely, which is mostly useful for
  58 testing and debugging. The 'Factory Defaults' button alows you to
  59 reset the filter rules.
  60
  61
  62 [[pmg_mailfilter_action]]
  63 'Action' - objects
  64 ------------------
  65
  66 [thumbnail="pmg-gui-mail-filter-actions.png", big=1]
  67
  68 Please note that some actions stop further rule processing. We call
  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
  86 Move to quarantine (virus mails are moved to the “virus quarantine”,
  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
 121 note that this can be quite different, i.e. when a previous rule
 122 removed attachments.
 123
 124
 125 Header Attributes
 126 ~~~~~~~~~~~~~~~~~
 127
 128 This object is able to add or modify mail header attributes. As with notifications above, you can use xref:rule_system_macros[macros], making this a very powerful object. For example, the 'Modify Spam Level' actions adds detailed information about detected Spam characteristics to the `X-SPAM-LEVEL` header.
 129
 130 .'Modify Spam Level' Header Attribute
 131 ----
 132 Field: X-SPAM-LEVEL
 133 Value: __SPAM_INFO__
 134 ----
 135
 136 Another prominent example is the 'Modify Spam Subject' action. This
 137 simply adds the 'SPAM:' prefix to the original mail subject:
 138
 139 .'Modify Spam Subject' Header Attribute
 140 ----
 141 Field: subject
 142 Value: SPAM: __SUBJECT__
 143 ----
 144
 145
 146 Remove attachments
 147 ~~~~~~~~~~~~~~~~~~
 148
 149 Remove attachments can either remove all attachments, or only those
 150 matched by the rules 'What' - object. You can also specify the
 151 replacement text if you want.
 152
 153 You can optionally move those mails into the attachment quarantine, where
 154 the original mail with all attachments will be stored. The mail with the
 155 attachments removed will continue in the rule system.
 156
 157 NOTE: The Attachment Quarantine Lifetime is the same as for the Spam Quarantine.
 158
 159
 160 Disclaimer
 161 ~~~~~~~~~~
 162
 163 Add a Disclaimer.
 164
 165
 166 [[pmg_mailfilter_who]]
 167 'Who' - objects
 168 ---------------
 169
 170 [thumbnail="pmg-gui-mail-filter-who-objects.png", big=1]
 171
 172 This type of objects can be used for the 'TO' and/or 'FROM' category,
 173 and match the sender or recipient of the email. A single object can
 174 combine multiple items, and the following item types are available:
 175
 176 EMail::
 177
 178 Allows you to match a single mail address.
 179
 180 Domain::
 181
 182 Only match the domain part of the mail address.
 183
 184 Regular Expression::
 185
 186 This one uses a regular expression to match the whole mail address.
 187
 188 IP Address or Network::
 189
 190 This can be used to match the senders IP address.
 191
 192 LDAP User or Group::
 193
 194 Test if the mail address belongs to a specific LDAP user or group.
 195
 196 We have two important 'Who' - objects called 'Blacklist' and
 197 'Whitelist'. These are used in the default ruleset to globally block
 198 or allow specific senders.
 199
 200
 201 [[pmg_mailfilter_what]]
 202 'What' - objects
 203 ----------------
 204
 205 [thumbnail="pmg-gui-mail-filter-what-objects.png", big=1]
 206
 207 'What' - objects are used to classify the mail content. A single
 208 object can combine multiple items, and the following item types are
 209 available:
 210
 211 Spam Filter::
 212
 213 Matches if detected spam level is equal or greater than the configured value.
 214
 215 Virus Filter::
 216
 217 Matches on infected mails.
 218
 219 Match Field::
 220
 221 Match specified mail header fields (eg. `Subject:`, `From:`, ...)
 222
 223 Content Type Filter::
 224
 225 Can be used to match specific content types.
 226
 227 Match Filename::
 228
 229 Uses regular expressions to match attachment filenames.
 230
 231 Archive Filter::
 232
 233 Can be used to match specific content types inside archives.
 234 This also matches the content-types of all regular (non-archived) attachments.
 235
 236 Match Archive Filename::
 237
 238 Uses regular expressions to match attachment filenames inside archives.
 239 This also matches the filenames for all regular (non-archived) attachments.
 240
 241
 242 [[pmg_mailfilter_when]]
 243 'When' - objects
 244 ----------------
 245
 246 [thumbnail="pmg-gui-mail-filter-when-objects.png", big=1]
 247
 248 'When' - objects are use to activate rules at specific daytimes. You
 249 can compose them of one or more time frame items.
 250
 251 The default ruleset defines 'Office Hours', but this is not used by
 252 the default rules.
 253
 254
 255 [[pmg_mailfilter_regex]]
 256 Using regular expressions
 257 -------------------------
 258
 259 A regular expression is a string of characters which tells us which
 260 string you are looking for. The following is a short introduction in
 261 the syntax of regular expressions used by some objects. If you are
 262 familiar with Perl, you already know the syntax.
 263
 264 Simple regular expressions
 265 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 266
 267 In its simplest form, a regular expression is just a word or phrase to
 268 search for. `Mail` would match the string "Mail". The search is case
 269 sensitive so "MAIL", "Mail", "mail" would not be matched.
 270
 271 Metacharacters
 272 ~~~~~~~~~~~~~~
 273
 274 Some characters have a special meaning. These characters are called
 275 metacharacters.  The Period (`.`) is a commonly used metacharacter. It
 276 matches exactly one character, regardless of what the character is.
 277 `e.mail` would match either "e-mail" or "e2mail" but not
 278 "e-some-mail" or "email".
 279
 280 The question mark (`?`) indicates that the character immediately
 281 preceding it shows up either zero or one time. `e?mail` would match
 282 either "email" or "mail" but not "e-mail".
 283
 284 Another metacharacter is the star (`*`). This indicates that the
 285 character immediately preceding it may be repeated any number of times,
 286 including zero. `e*mail` would match either "email" or "mail" or
 287 "eeemail".
 288
 289 The plus (`+`) metacharacter does the same as the star (*) excluding
 290 zero. So `e+mail` does not match "mail".
 291
 292 Metacharacters may be combined. A common combination includes the
 293 period and star metacharacters (`.*`), with the star immediately following
 294 the period. This is used to match an arbitrary string of any length,
 295 including the null string. For example: `.*company.*` matches
 296 "company@domain.com" or "company@domain.co.uk" or
 297 "department.company@domain.com".
 298
 299 The book xref:Friedl97[] provides a more comprehensive introduction.