pmg-mail-filter.adoc

   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
  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:
  13
  14 'Who' - objects::
  15
  16 Who is the sender or receiver of the e-mail? Those objects can be used
  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
  23 'What' - objects::
  24
  25 What is in the e-mail?
  26 +
  27 ====
  28 Example: Does the e-mail contain spam?
  29 ====
  30
  31 'When' - objects::
  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
  39 'Action' - objects::
  40
  41 Defines the final actions.
  42 +
  43 ====
  44 Example: Mark e-mail with “SPAM:” in the subject.
  45 ====
  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
  61 'Action' - objects
  62 ------------------
  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
 128 .'Modify Spam Level' Header Attribute
 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
 137 .'Modify Spam Subject' Header Attribute
 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
 148 matched by the rules 'What' - object. You can also specify the
 149 replacement text if you want.
 150
 151
 152 Disclaimer
 153 ~~~~~~~~~~
 154
 155 Add a Disclaimer.
 156
 157
 158 'Who' - objects
 159 ---------------
 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
 187 We have two important 'Who' - objects called 'Blacklist' and
 188 'Whitelist'. Those are used in the default ruleset to globally block
 189 or allow specific senders.
 190
 191
 192 'What' - objects
 193 ----------------
 194
 195 image::images/screenshot/pmg-gui-mail-filter-what-objects.png[]
 196
 197 'What' - objects are used to classify the mail content. A single
 198 object can combine multiple items, and the following item types are
 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
 209 Match Field::
 210
 211 Match specified mail header fields (eg. `Subject:`, `From:`, ...)
 212
 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
 226 'When' - objects
 227 ----------------
 228
 229 image::images/screenshot/pmg-gui-mail-filter-when-objects.png[]
 230
 231 'When' - objects are use to activate rules at specific daytimes. You
 232 can compose them of one or more time-frame items.
 233
 234 The default ruleset defines 'Office Hours', but this is not used by
 235 the default rules.
 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".
 280
 281 The book xref:Friedl97[] provides a more comprehensive introduction.