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 ACTIONS - 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 Actions
  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 object
 198 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 Content Type Filter::
 210
 211 Can be used to match specific content types.
 212
 213 Match Filename::
 214
 215 Uses regular expressions to match attachment filenames.
 216
 217 Archive Filter::
 218
 219 Can be used to match specific content types inside archives.
 220
 221
 222 WHEN - objects
 223 --------------
 224
 225 image::images/screenshot/pmg-gui-mail-filter-when-objects.png[]
 226
 227 WHEN - objects are use to activate rules at specific daytimes. You can compose
 228 them of one or more time-frame items.
 229
 230 The default ruleset defines 'Office Hours', but this is not used by
 231 the default rules.