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
  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, for instance, 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
 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.
 133
 134 .'Modify Spam Level' Header Attribute
 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
 143 .'Modify Spam Subject' Header Attribute
 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
 154 matched by the rule's 'What' - object. You can also specify the
 155 replacement text, if you want.
 156
 157 You can optionally move these mails into the attachment quarantine, where
 158 the original mail with all attachments will be stored. The mail with the
 159 attachments removed will continue through the rule system.
 160
 161 NOTE: The Attachment Quarantine lifetime is the same as for the Spam Quarantine.
 162
 163
 164 Disclaimer
 165 ~~~~~~~~~~
 166
 167 Add a Disclaimer.
 168
 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.
 172
 173
 174 [[pmg_mailfilter_who]]
 175 'Who' objects
 176 -------------
 177
 178 [thumbnail="pmg-gui-mail-filter-who-objects.png", big=1]
 179
 180 These types of objects can be used for the 'TO' and/or 'FROM' category,
 181 and match the sender or recipient of the email. A single object can
 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
 202 Test if the mail address belongs to a specific LDAP user or group.
 203
 204 We have two important 'Who' objects called 'Blacklist' and
 205 'Whitelist'. These are used in the default ruleset to globally block
 206 or allow specific senders.
 207
 208
 209 [[pmg_mailfilter_what]]
 210 'What' objects
 211 --------------
 212
 213 [thumbnail="pmg-gui-mail-filter-what-objects.png", big=1]
 214
 215 'What' objects are used to classify the mail's content. A single
 216 object can combine multiple items, and the following item types are
 217 available:
 218
 219 Spam Filter::
 220
 221 Matches if the detected spam level is greater than or equal to the
 222 configured value.
 223
 224 Virus Filter::
 225
 226 Matches on infected mails.
 227
 228 Match Field::
 229
 230 Match specified mail header fields (for example, `Subject:`, `From:`, ...)
 231
 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.
 243 This also matches the content-types of all regular (non-archived) attachments.
 244
 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
 250
 251 [[pmg_mailfilter_when]]
 252 'When' objects
 253 --------------
 254
 255 [thumbnail="pmg-gui-mail-filter-when-objects.png", big=1]
 256
 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.
 259
 260 The default ruleset defines 'Office Hours', but this is not used by
 261 the default rules.
 262
 263
 264 [[pmg_mailfilter_regex]]
 265 Using regular expressions
 266 -------------------------
 267
 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.
 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.
 287 `e.mail` would match either "e-mail" or "e2mail" but not
 288 "e-some-mail" or "email".
 289
 290 The question mark (`?`) indicates that the character immediately
 291 preceding it shows up either zero or one time. `e?mail` would match
 292 either "email" or "mail" but not "e-mail".
 293
 294 Another metacharacter is the asterisk (`*`). This indicates that the
 295 character immediately preceding it may be repeated any number of times,
 296 including zero. `e*mail` would match "email", "mail", and
 297 "eeemail".
 298
 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".
 302
 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".
 309
 310 The book xref:Friedl97[] provides a more comprehensive introduction.